Features have several advantages over static class initializers (which also run during native image generation):
access parameter that allows callbacks into the native image
generator.
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:
required by another included feature.
Required features are added transitively, and initialization methods of required features are
called after invoking the constructor and isInConfiguration of the requiring features
(unless the feature dependencies are cyclic).
| Modifier and Type | Class and Description |
|---|---|
| public static interface | Feature.
Access methods available for |
| public static interface | Feature.
Access methods available for |
| public static interface | Feature.
Access methods available for |
| public static interface | Feature.
Access methods available for |
| public static interface | Feature.
Access methods available for |
| public static interface | Feature.
Access methods available for |
| public static interface | Feature.
Access methods available for |
| public static interface | Feature.
Access methods available for |
| public static interface | Feature.
Access methods available for |
| public static interface | Feature.
Access methods available for |
| public static interface | Feature.
Access methods available for |
| public static interface | Feature.
Access methods available for |
| public static interface | Feature.
Access methods that are available for all feature methods. |
| public static interface | Feature.
Access methods available for |
| public static interface | Feature.
Access methods available for |
| public static interface | Feature.
Access reachability methods available for |
| Modifier and Type | Method and Description |
|---|---|
| public default void | afterAnalysis(Feature.
The supported operations that the feature can perform at this time accessHandler for initializations after analysis and before universe creation. |
| public default void | afterCompilation(Feature.
The supported operations that the feature can perform at this time accessHandler for initializations after compilation, i.e., before the native image is written. |
| public default void | afterHeapLayout(Feature.
The supported operations that the feature can perform at this time accessHandler for initializations after the native image heap and code layout. |
| public default void | afterImageWrite(Feature.
The supported operations that the feature can perform at this time. accessHandler for altering the image (or shared object) that the linker command produced. |
| public default void | afterRegistration(Feature.
The supported operations that the feature can perform at this time accessHandler for initializations after all features have been registered and all options have been parsed; but before any initializations for the static analysis have happened. |
| public default void | beforeAnalysis(Feature.
The supported operations that the feature can perform at this time accessHandler for initializations before the static analysis. |
| public default void | beforeCompilation(Feature.
The supported operations that the feature can perform at this time accessHandler for initializations before compilation. |
| public default void | beforeImageWrite(Feature.
The supported operations that the feature can perform at this time. accessHandler for altering the linker command after the native image has been built and before it is written. |
| public default void | beforeUniverseBuilding(Feature.
The supported operations that the feature can perform at this time accessHandler for code that needs to run before universe building, but after hosted meta-access has been created. |
| public default void | |
| public default void | duringAnalysis(Feature.
The supported operations that the feature can perform at this time accessHandler for performing operations during the static analysis. |
| public default void | duringSetup(Feature.
The supported operations that the feature can perform at this time accessHandler for initializations at startup time. |
| public default String | |
| public default List | |
| public default String | |
| public default boolean | isInConfiguration(Feature.
The supported operations that the feature can perform at this time accessThis method is called immediately after the constructor, to check whether the feature is part of the configuration or not. |
| public default void | onAnalysisExit(Feature.
The supported operations that the feature can perform at this time accessHandler for code that needs to run after the analysis, even if an error has occurred, e.g., like reporting code. |
| afterAnalysis | back to summary |
|---|---|
| public default void afterAnalysis(Feature. Handler for initializations after analysis and before universe creation.
| |
| afterCompilation | back to summary |
|---|---|
| public default void afterCompilation(Feature. Handler for initializations after compilation, i.e., before the native image is written.
| |
| afterHeapLayout | back to summary |
|---|---|
| public default void afterHeapLayout(Feature. 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.
| |
| afterImageWrite | back to summary |
|---|---|
| public default void afterImageWrite(Feature. Handler for altering the image (or shared object) that the linker command produced.
| |
| afterRegistration | back to summary |
|---|---|
| public default void afterRegistration(Feature. 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.
| |
| beforeAnalysis | back to summary |
|---|---|
| public default void beforeAnalysis(Feature. Handler for initializations before the static analysis.
| |
| beforeCompilation | back to summary |
|---|---|
| public default void beforeCompilation(Feature. Handler for initializations before compilation.
| |
| beforeImageWrite | back to summary |
|---|---|
| public default void beforeImageWrite(Feature. Handler for altering the linker command after the native image has been built and before it is written.
| |
| beforeUniverseBuilding | back to summary |
|---|---|
| public default void beforeUniverseBuilding(Feature. Handler for code that needs to run before universe building, but after hosted meta-access has been created.
| |
| cleanup | back to summary |
|---|---|
| public 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
| |
| duringAnalysis | back to summary |
|---|---|
| public default void duringAnalysis(Feature. 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
| |
| duringSetup | back to summary |
|---|---|
| public default void duringSetup(Feature. Handler for initializations at startup time. It allows customization of the static analysis setup.
| |
| getDescription | back to summary |
|---|---|
| public 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.
| |
| getRequiredFeatures | back to summary |
|---|---|
| public default List 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.
| |
| getURL | back to summary |
|---|---|
| public 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).
| |
| isInConfiguration | back to summary |
|---|---|
| public default boolean isInConfiguration(Feature. 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
| |
| onAnalysisExit | back to summary |
|---|---|
| public default void onAnalysisExit(Feature. Handler for code that needs to run after the analysis, even if an error has occurred, e.g., like reporting code.
| |
Feature#afterAnalysis.
Feature#afterCompilation.
Feature#afterHeapLayout.
Feature#afterImageWrite.
| Modifier and Type | Method and Description |
|---|---|
| public Path | getImagePath()
Returns the path to the created native-image file (includes the native-image file name). |
| getImagePath | back to summary |
|---|---|
| public Path getImagePath() Returns the path to the created native-image file (includes the native-image file name).
| |
Feature#afterRegistration.
Feature#beforeAnalysis.
| Modifier and Type | Method and Description |
|---|---|
| public void | registerAsAccessed(Field field)
Registers the provided field as accesses, i.e., the static analysis assumes the field is used even if there are no explicit reads or writes in the bytecodes. |
| public void | registerAsInHeap(Class<?> type)
Registers the provided type as instantiated, i.e., the static analysis assumes that instances of this type exist at run time even if there is no explicit instantiation in the bytecodes. |
| public void | registerAsUnsafeAccessed(Field field)
Registers the provided field as written or read by |
| public void | registerAsUsed(Class<?> type)
Registers the provided type a used, i.e., metadata for the type is put into the native image. |
| public void | registerClassInitializerReachabilityHandler(Consumer<Feature.
Registers a callback that is invoked once |
| public void | registerFieldValueTransformer(Field field, FieldValueTransformer transformer)
Registers a field value transformer for the provided field. |
| public void | registerMethodOverrideReachabilityHandler(BiConsumer<Feature.
Registers a callback that is invoked once during analysis for each time a method that overrides the specified {param baseMethod} is determined to be reachable at run time. |
| public void | registerReachabilityHandler(Consumer<Feature.
Registers a callback that is invoked once |
| public void | registerSubtypeReachabilityHandler(BiConsumer<Feature.
Registers a callback that is invoked once |
| registerAsAccessed | back to summary |
|---|---|
| public void registerAsAccessed(Field field) Registers the provided field as accesses, i.e., the static analysis assumes the field is used even if there are no explicit reads or writes in the bytecodes.
| |
| registerAsInHeap | back to summary |
|---|---|
| public void registerAsInHeap(Class<?> type) Registers the provided type as instantiated, i.e., the static analysis assumes that instances of this type exist at run time even if there is no explicit instantiation in the bytecodes.
This implies that the type is also marked as
| |
| registerAsUnsafeAccessed | back to summary |
|---|---|
| public void registerAsUnsafeAccessed(Field field) Registers the provided field as written or read by
This implies that the field is also marked as
| |
| registerAsUsed | back to summary |
|---|---|
| public void registerAsUsed(Class<?> type) Registers the provided type a used, i.e., metadata for the type is put into the native image.
| |
| registerClassInitializerReachabilityHandler | back to summary |
|---|---|
| public void registerClassInitializerReachabilityHandler(Consumer<Feature. Registers a callback that is invoked once
| |
| registerFieldValueTransformer | back to summary |
|---|---|
| public void registerFieldValueTransformer(Field field, FieldValueTransformer transformer) Registers a field value transformer for the provided field. See the JavaDoc of
| |
| registerMethodOverrideReachabilityHandler | back to summary |
|---|---|
| public void registerMethodOverrideReachabilityHandler(BiConsumer<Feature. Registers a callback that is invoked once during analysis for each time a method that overrides the specified {param baseMethod} is determined to be reachable at run time. In addition, the handler will also get invoked once when the {param baseMethod} itself becomes reachable. The specific method that becomes reachable is passed to the handler as the second parameter. A method is considered reachable at run time if it can be executed, as determined via static analysis. Therefore, if a method can be statically bound (usually, that means it is final or private or static, but not abstract, or the declaring class is final), or it is a constructors, and it is the target of a reachable invoke, or it is inlined, then it is considered run time reachable. A virtual methods is considered run time reachable if its declaring-class or any of its subtypes is instantiated and the method is the target of a reachable invoke, or it is inlined. Even if the declaring type itself is not marked as instantiated the method can still be reachable via special invokes, e.g., `super` calls.
| |
| registerReachabilityHandler | back to summary |
|---|---|
| public void registerReachabilityHandler(Consumer<Feature. Registers a callback that is invoked once
| |
| registerSubtypeReachabilityHandler | back to summary |
|---|---|
| public void registerSubtypeReachabilityHandler(BiConsumer<Feature. Registers a callback that is invoked once
| |
Feature#beforeCompilation.
Feature#beforeImageWrite.
Feature#beforeUniverseBuilding.
Feature#beforeCompilation and
Feature#afterCompilation.
| Modifier and Type | Method and Description |
|---|---|
| public long | |
| public void | registerAsImmutable(Object object)
Hint to the native image generator that the given object is immutable at runtime, i.e., can be placed in a read-only section of the native image heap. |
| public void | registerAsImmutable(Object root, Predicate<Object> includeObject)
Register the object, and everything it transitively references, as immutable. |
| objectFieldOffset | back to summary |
|---|---|
| public long objectFieldOffset(Field field) Returns the field offset of the provided instance field.
| |
| registerAsImmutable | back to summary |
|---|---|
| public void registerAsImmutable(Object object) Hint to the native image generator that the given object is immutable at runtime, i.e., can be placed in a read-only section of the native image heap.
| |
| registerAsImmutable | back to summary |
|---|---|
| public void registerAsImmutable(Object root, Predicate<Object> includeObject) Register the object, and everything it transitively references, as immutable. When the provided predicate returns false for an object, the object is not marked as immutable and the transitive iteration is stopped.
| |
Feature#duringAnalysis.
| Modifier and Type | Method and Description |
|---|---|
| public void | requireAnalysisIteration()
Notifies the static analysis that changes are made that enforce a new iteration of the analysis. |
| requireAnalysisIteration | back to summary |
|---|---|
| public void requireAnalysisIteration() Notifies the static analysis that changes are made that enforce a new iteration of the analysis.
| |
Feature#duringSetup.
| Modifier and Type | Method and Description |
|---|---|
| public void | registerObjectReplacer(Function<Object, Object> replacer)
Registers the provided function to replace objects. |
| registerObjectReplacer | back to summary |
|---|---|
| public void registerObjectReplacer(Function<Object, Object> replacer) Registers the provided function to replace objects. The function checks if an object should be replaced. In such a case, the function creates the new object and returns it. The function must return the original object if the object should not be replaced.
| |
| Modifier and Type | Method and Description |
|---|---|
| public Class | |
| public ClassLoader | getApplicationClassLoader()
Returns the |
| public List | |
| public List |
| findClassByName | back to summary |
|---|---|
| public Class Returns a class if it is present on the classpath.
| |
| getApplicationClassLoader | back to summary |
|---|---|
| public ClassLoader getApplicationClassLoader() Returns the
| |
| getApplicationClassPath | back to summary |
|---|---|
| public List Returns the class path of the native image that is currently built. The returned list does not include the native image generator itself, and does not include the JDK.
| |
| getApplicationModulePath | back to summary |
|---|---|
| public List Returns the module path of the native image that is currently built. The returned list does not include the native image generator itself, and does not include the JDK.
| |
Feature#isInConfiguration.
Feature#onAnalysisExit.
Feature#afterAnalysis and
Feature#duringAnalysis.
| Modifier and Type | Method and Description |
|---|---|
| public boolean | isReachable(Class<?> clazz)
Returns true if the static analysis determined that the provided class is reachable at run time. |
| public boolean | isReachable(Field field)
Returns true if the static analysis determined that the provided field is reachable at run time. |
| public boolean | isReachable(Executable method)
Returns true if the static analysis determined that the provided method is reachable at run time. |
| public Set | reachableMethodOverrides(Executable baseMethod)
Returns all method overrides of the given {param baseMethod} that the static analysis determined to be reachable at run time (including the {param baseMethod} itself). |
| public Set | reachableSubtypes(Class<?> baseClass)
Returns all subtypes of the given {param baseClass} that the static analysis determined to be reachable at run time (including the {param baseClass} itself). |
| isReachable | back to summary |
|---|---|
| public boolean isReachable(Class<?> clazz) Returns true if the static analysis determined that the provided class is reachable at run time.
| |
| isReachable | back to summary |
|---|---|
| public boolean isReachable(Field field) Returns true if the static analysis determined that the provided field is reachable at run time.
| |
| isReachable | back to summary |
|---|---|
| public boolean isReachable(Executable method) Returns true if the static analysis determined that the provided method is reachable at run time.
| |
| reachableMethodOverrides | back to summary |
|---|---|
| public Set Returns all method overrides of the given {param baseMethod} that the static analysis determined to be reachable at run time (including the {param baseMethod} itself).
| |
| reachableSubtypes | back to summary |
|---|---|
| public Set Returns all subtypes of the given {param baseClass} that the static analysis determined to be reachable at run time (including the {param baseClass} itself).
| |