Graal Sdk 24.1.2 · org.graalvm.nativeimage.hosted.RuntimeClassInitialization

This class provides methods that can be called during native-image building to configure class initialization behavior. By default, all JDK classes that are seen as reachable for a native image are initialized during image building, i.e. the class initialization method is executed during image building and is not seen as a reachable method at runtime. Application classes, on the other hand, are initialized during image building if they can be proven safe. Unsafe classes, e.g. ones that create threads, will be initialized at image run time. For classes that can't be proven safe, it is sometimes beneficial to ensure initialization during image building, and for some that are safe, it is still necessary to initialize at runtime (e.g., the order of initializer execution matters).

This class provides two different registration methods: Classes registered via initializeAtRunTime are not initialized at all during image generation, and only initialized at runtime, i.e., the class initializer is executed once at runtime. Classes registered via initializeAtBuildTime will be initialized during image building. It is also possible define initialization for whole packages with initializeAtRunTime(String[]) and initializeAtBuildTime(String[]). The rules for packages can be further refined by using methods for individual classes. Initializing classes at runtime comes with some costs and restrictions:

The class initialization status must be checked before a static field access, static method call, and object allocation of such classes. This has an impact on performance.
Instances of such classes are not allowed on the image heap, i.e., on the initial heap that is part of the native executable. Otherwise instances would exist before the class is initialized, which violates the class initialization specification.

Constructor Summary

Access	Constructor and Description
private	RuntimeClassInitialization()

Method Summary

Modifier and Type	Method and Description
private static String	classReason(StackTraceElement[] stacktrace, String simpleName)
private static String	getCaller(StackTraceElement[] stackTrace)
private static String	getUnqualifiedName(Class<?> aClass) Alternative to `Class#getSimpleName` that does not probe the enclosing class or method which fails when they are not yet loaded.
public static void	initializeAtBuildTime(Class<?>... classes) Registers the provided classes as eagerly initialized during image-build time.
public static void	initializeAtBuildTime(String... packages) Registers all classes in provided packages as eagerly initialized during image-build time.
public static void	initializeAtRunTime(Class<?>... classes) Registers the provided classes, and all of their subclasses, for class initialization at runtime.
public static void	initializeAtRunTime(String... packages) Registers all classes in provided packages, and all of their subclasses, for class initialization at runtime.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Constructor Detail

RuntimeClassInitialization	back to summary
private RuntimeClassInitialization()

Method Detail

classReason	back to summary
private static String classReason(StackTraceElement[] stacktrace, String simpleName)

getCaller	back to summary
private static String getCaller(StackTraceElement[] stackTrace)

getUnqualifiedName	back to summary
private static String getUnqualifiedName(Class<?> aClass) Alternative to `Class#getSimpleName` that does not probe the enclosing class or method which fails when they are not yet loaded. Duplicated from `ClassUtil.getUnqualifiedName` which is not reachable here.

initializeAtBuildTime back to summary

initializeAtBuildTime	back to summary
public static void initializeAtBuildTime(Class<?>... classes) Registers the provided classes as eagerly initialized during image-build time. All static initializers of `classes` will be executed immediately at image-build time and static fields that are assigned values will be available at runtime. `static final` fields will be considered as constant. It is up to the user to ensure that this behavior makes sense and does not lead to wrong application behavior. After this method returns, all listed classes are initialized in the VM that runs the image generator. Therefore, this method can be used to resolve deadlocks and cycles in class initializer by starting initialization with a known-good entry class. All superclasses and superinterfaces that are initialized before any of the listed classes are registered for initialization at build time too. Please look at the Java specification for the exact rules, especially regarding interfaces that declare default methods. Since 19.0

public static void initializeAtBuildTime(Class<?>... classes)

Registers the provided classes as eagerly initialized during image-build time.

All static initializers of classes will be executed immediately at image-build time and static fields that are assigned values will be available at runtime. static final fields will be considered as constant.

It is up to the user to ensure that this behavior makes sense and does not lead to wrong application behavior.

After this method returns, all listed classes are initialized in the VM that runs the image generator. Therefore, this method can be used to resolve deadlocks and cycles in class initializer by starting initialization with a known-good entry class.

All superclasses and superinterfaces that are initialized before any of the listed classes are registered for initialization at build time too. Please look at the Java specification for the exact rules, especially regarding interfaces that declare default methods.

Since: 19.0

initializeAtBuildTime back to summary

initializeAtBuildTime	back to summary
public static void initializeAtBuildTime(String... packages) Registers all classes in provided packages as eagerly initialized during image-build time. Passing `""` as a package, registers all packages and classes for initialization at build time. This might have unintended side-effects and should thus be used with great caution. All static initializers of `classes` will be executed during image-build time and static fields that are assigned values will be available at runtime. `static final` fields will be considered as constant. It is up to the user to ensure that this behavior makes sense and does not lead to wrong application behavior. Since 19.0

public static void initializeAtBuildTime(String... packages)

Registers all classes in provided packages as eagerly initialized during image-build time.

Passing "" as a package, registers all packages and classes for initialization at build time. This might have unintended side-effects and should thus be used with great caution.

All static initializers of classes will be executed during image-build time and static fields that are assigned values will be available at runtime. static final fields will be considered as constant.

It is up to the user to ensure that this behavior makes sense and does not lead to wrong application behavior.

Since: 19.0

initializeAtRunTime	back to summary
public static void initializeAtRunTime(Class<?>... classes) Registers the provided classes, and all of their subclasses, for class initialization at runtime. The classes are not initialized automatically during image generation, and also must not be initialized manually by the user during image generation. Unfortunately, classes are initialized for many reasons, and it is not possible to intercept class initialization and report an error at this time. If a registered class gets initialized, an error can be reported only later and the user must manually debug the reason for class initialization. This can be done by, e.g., setting a breakpoint in the class initializer or adding debug printing (print the stack trace) in the class initializer. Since 19.0

initializeAtRunTime

back to summary

public static void initializeAtRunTime(Class<?>... classes)

Registers the provided classes, and all of their subclasses, for class initialization at runtime. The classes are not initialized automatically during image generation, and also must not be initialized manually by the user during image generation.

Unfortunately, classes are initialized for many reasons, and it is not possible to intercept class initialization and report an error at this time. If a registered class gets initialized, an error can be reported only later and the user must manually debug the reason for class initialization. This can be done by, e.g., setting a breakpoint in the class initializer or adding debug printing (print the stack trace) in the class initializer.

Since: 19.0

initializeAtRunTime	back to summary
public static void initializeAtRunTime(String... packages) Registers all classes in provided packages, and all of their subclasses, for class initialization at runtime. The classes are not initialized automatically during image generation, and also must not be initialized manually by the user during image generation. Unfortunately, classes are initialized for many reasons, and it is not possible to intercept class initialization and report an error at this time. If a registered class gets initialized, an error can be reported only later and the user must manually debug the reason for class initialization. This can be done by, e.g., setting a breakpoint in the class initializer or adding debug printing (print the stack trace) in the class initializer. Since 19.0

initializeAtRunTime

back to summary

public static void initializeAtRunTime(String... packages)

Registers all classes in provided packages, and all of their subclasses, for class initialization at runtime. The classes are not initialized automatically during image generation, and also must not be initialized manually by the user during image generation.

Since: 19.0

public final Class RuntimeClassInitialization

Constructor Summary

Method Summary

Constructor Detail

Method Detail