Interface Feature

public interface Feature
Features allow clients to intercept the native image generation and run custom initialization code at various stages. All code within feature classes is executed during native image generation, and never at run time.

Features have several advantages over static class initializers (which also run during native image generation):

  • The different feature methods are called at different stages during native image generation, which gives clients control over when code is executed.
  • Feature methods have an access parameter that allows callbacks into the native image generator.
  • Feature methods run when the ImageSingletons is already set up, which allows features to prepare data structures that are then used at run time by querying the ImageSingletons .

Implementation classes must have a no-argument constructor, which is used to instantiate a singleton instance for each feature using reflection. The following features are included during native image generation:

  • Features explicitly specified on the command line.
  • Features referenced as required by another included feature. Required features are added transitively, and initialization methods of required features are called after invoking the constructor and isInConfiguration(Feature.IsInConfigurationAccess) of the requiring features (unless the feature dependencies are cyclic).
Since:
19.0

  • Method Details

    • getURL

      default String getURL()
      A URL to documentation or the sources of the feature. The URL will be used as a link for the feature in the build output (if supported by the user's terminal).
      Since:
      22.2

    • getDescription

      default String getDescription()
      A short description of the feature (e.g., "Enables Truffle support"). The description is displayed to users as part of the build output.
      Since:
      22.2

    • isInConfiguration

      default boolean isInConfiguration(Feature.IsInConfigurationAccess access)
      This method is called immediately after the constructor, to check whether the feature is part of the configuration or not. If this method returns false, the feature is not included in the list of features and no other methods are called (in particular, the required features are not processed).
      Parameters:
      access - The supported operations that the feature can perform at this time
      Since:
      19.0

    • getRequiredFeatures

      default List<Class<? extends Feature>> getRequiredFeatures()
      Returns the list of features that this feature depends on. As long as the dependency chain is non-cyclic, all required features are processed before this feature.
      Since:
      19.0

    • afterRegistration

      default void afterRegistration(Feature.AfterRegistrationAccess access)
      Handler for initializations after all features have been registered and all options have been parsed; but before any initializations for the static analysis have happened.
      Parameters:
      access - The supported operations that the feature can perform at this time
      Since:
      19.0

    • duringSetup

      default void duringSetup(Feature.DuringSetupAccess access)
      Handler for initializations at startup time. It allows customization of the static analysis setup.
      Parameters:
      access - The supported operations that the feature can perform at this time
      Since:
      19.0

    • beforeAnalysis

      default void beforeAnalysis(Feature.BeforeAnalysisAccess access)
      Handler for initializations before the static analysis.
      Parameters:
      access - The supported operations that the feature can perform at this time
      Since:
      19.0

    • duringAnalysis

      default void duringAnalysis(Feature.DuringAnalysisAccess access)
      Handler for performing operations during the static analysis. This handler is called after analysis is complete. So all analysis meta data is available. If the handler performs changes, e.g., makes new types or methods reachable, it needs to call Feature.DuringAnalysisAccess.requireAnalysisIteration(). This triggers a new iteration: analysis is performed again and the handler is called again.
      Parameters:
      access - The supported operations that the feature can perform at this time
      Since:
      19.0

    • afterAnalysis

      default void afterAnalysis(Feature.AfterAnalysisAccess access)
      Handler for initializations after analysis and before universe creation.
      Parameters:
      access - The supported operations that the feature can perform at this time
      Since:
      19.0

    • onAnalysisExit

      default void onAnalysisExit(Feature.OnAnalysisExitAccess access)
      Handler for code that needs to run after the analysis, even if an error has occurred, e.g., like reporting code.
      Parameters:
      access - The supported operations that the feature can perform at this time
      Since:
      19.0

    • beforeUniverseBuilding

      default void beforeUniverseBuilding(Feature.BeforeUniverseBuildingAccess access)
      Handler for code that needs to run before universe building, but after hosted meta-access has been created.
      Parameters:
      access - The supported operations that the feature can perform at this time
      Since:
      21.1

    • beforeCompilation

      default void beforeCompilation(Feature.BeforeCompilationAccess access)
      Handler for initializations before compilation.
      Parameters:
      access - The supported operations that the feature can perform at this time
      Since:
      19.0

    • afterCompilation

      default void afterCompilation(Feature.AfterCompilationAccess access)
      Handler for initializations after compilation, i.e., before the native image is written.
      Parameters:
      access - The supported operations that the feature can perform at this time
      Since:
      19.0

    • beforeHeapLayout

      default void beforeHeapLayout(Feature.BeforeHeapLayoutAccess access)
      Handler for initializations before the native image heap and code layout.
      Parameters:
      access - The supported operations that the feature can perform at this time
      Since:
      23.2

    • afterHeapLayout

      default void afterHeapLayout(Feature.AfterHeapLayoutAccess access)
      Handler for initializations after the native image heap and code layout. Objects and methods have their offsets assigned. At this point, no additional objects must be added to the native image heap, i.e., modifying object fields of native image objects that are part of the native image heap is not allowed at this point.
      Parameters:
      access - The supported operations that the feature can perform at this time
      Since:
      19.0

    • beforeImageWrite

      default void beforeImageWrite(Feature.BeforeImageWriteAccess access)
      Handler for altering the linker command after the native image has been built and before it is written.
      Parameters:
      access - The supported operations that the feature can perform at this time.
      Since:
      19.0

    • afterImageWrite

      default void afterImageWrite(Feature.AfterImageWriteAccess access)
      Handler for altering the image (or shared object) that the linker command produced.
      Parameters:
      access - The supported operations that the feature can perform at this time.
      Since:
      19.0

    • cleanup

      default void cleanup()
      Handler for cleanup. Can be used to cleanup static data. This can avoid memory leaks if native image generation is done many times, e.g. during unit tests.

      Usually, overriding this method can be avoided by putting a configuration object into the ImageSingletons.

      Since:
      19.0