Interface ForeignAccess

public interface ForeignAccess
This interface is used to register classes, methods, and fields for foreign access at run time. An instance of this interface is acquired via Feature.AfterRegistrationAccess.getForeignAccess().

All methods in ForeignAccess require a AccessCondition as their first parameter. Registration for foreign access will happen only if the specified condition is satisfied.

How to use

ForeignAccess should only be used during Feature.afterRegistration(Feature.AfterRegistrationAccess). Any attempt to register metadata in any other phase will result in an error.

Example: 

@Override
public void afterRegistration(AfterRegistrationAccess access) {
    ForeignAccess foreignAccess = access.getForeignAccess();
    AccessCondition condition = AccessCondition.typeReached(ConditionType.class);
    foreignAccess.registerForDowncall(condition, java.lang.foreign.ValueLayout.JAVA_INT);
}
Since:
25.0.1

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    registerForDirectUpcall(AccessCondition condition, MethodHandle target, Object desc, Object... options)
    Registers a specific static method (denoted by a method handle) as a fast upcall target, if the condition is satisfied.
    void
    registerForDowncall(AccessCondition condition, Object desc, Object... options)
    Registers the provided function descriptor and options pair at image build time for downcalls into foreign code, if the condition is satisfied.
    void
    registerForUpcall(AccessCondition condition, Object desc, Object... options)
    Registers the provided function descriptor and options pair at image build time for upcalls from foreign code, if the condition is satisfied.

  • Method Details

    • registerForDowncall

      void registerForDowncall(AccessCondition condition, Object desc, Object... options)
      Registers the provided function descriptor and options pair at image build time for downcalls into foreign code, if the condition is satisfied. Required to get a downcall method handle using Linker.downcallHandle(MemorySegment, FunctionDescriptor, Linker.Option...)RESTRICTED for the same descriptor and options at run time.

      Even though this method is weakly typed for compatibility reasons, run-time checks will be performed to ensure that the arguments have the expected type. It will be deprecated in favor of strongly typed variant as soon as possible.

      Parameters:
      condition - represents the condition that needs to be satisfied in order to access target resources.
      desc - A FunctionDescriptor to register for downcalls.
      options - An array of Linker.Option used for the downcalls.
      Since:
      25.0.1

    • registerForUpcall

      void registerForUpcall(AccessCondition condition, Object desc, Object... options)
      Registers the provided function descriptor and options pair at image build time for upcalls from foreign code, if the condition is satisfied. Required to get an upcall stub function pointer using Linker.upcallStub(MethodHandle, FunctionDescriptor, Arena, Linker.Option...)RESTRICTED for the same descriptor and options at run time.

      Even though this method is weakly typed for compatibility reasons, run-time checks will be performed to ensure that the arguments have the expected type. It will be deprecated in favor of strongly typed variant as soon as possible.

      Parameters:
      condition - represents the condition that needs to be satisfied in order to access target resources.
      desc - A FunctionDescriptor to register for upcalls.
      options - An array of Linker.Option used for the upcalls.
      Since:
      25.0.1

    • registerForDirectUpcall

      void registerForDirectUpcall(AccessCondition condition, MethodHandle target, Object desc, Object... options)
      Registers a specific static method (denoted by a method handle) as a fast upcall target, if the condition is satisfied. This will create a specialized upcall stub that will invoke only the specified method, which is much faster than using registerForUpcall(AccessCondition, Object, Object...)).

      The provided method handle must be a direct method handle. Those are most commonly created using MethodHandles.Lookup.findStatic(Class, String, MethodType). However, a strict requirement is that it must be possible to create a non-empty descriptor for the method handle using MethodHandle.describeConstable(). The denoted static method will also be registered for reflective access since run-time code will also create a method handle to denoted static method.

      Even though this method is weakly typed for compatibility reasons, run-time checks will be performed to ensure that the arguments have the expected type. It will be deprecated in favor of strongly typed variant as soon as possible.

      Parameters:
      condition - represents the condition that needs to be satisfied in order to access target resources.
      target - A direct method handle denoting a static method.
      desc - A FunctionDescriptor to register for upcalls.
      options - An array of Linker.Option used for the upcalls.
      Since:
      25.0.1