org.graalvm.nativeimage.hosted

Class RuntimeClassInitialization

java.lang.Object

org.graalvm.nativeimage.hosted.RuntimeClassInitialization

public final class RuntimeClassInitialization
extends Object

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 RuntimeClassInitialization.initializeAtRunTime(java.lang.Class<?>...) 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 RuntimeClassInitialization.initializeAtBuildTime(java.lang.Class<?>...) will be initialized during image building. It is also possible define initialization for whole packages with RuntimeClassInitialization.initializeAtRunTime(String[]) and RuntimeClassInitialization.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.

Since:

19.0

Method Summary

Modifier and Type	Method and Description
static void	initializeAtBuildTime(Class<?>... classes) Registers the provided classes as eagerly initialized during image-build time.
static void	initializeAtBuildTime(String... packages) Registers all classes in provided packages as eagerly initialized during image-build time.
static void	initializeAtRunTime(Class<?>... classes) Registers the provided classes, and all of their subclasses, for class initialization at runtime.
static void	initializeAtRunTime(String... packages) Registers all classes in provided packages, and all of their subclasses, for class initialization at runtime.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

initializeAtRunTime

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

initializeAtBuildTime

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 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

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

initializeAtBuildTime

public static void initializeAtBuildTime(String... packages)

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

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