org.graalvm.nativeimage

Class RuntimeClassInitialization

java.lang.Object

org.graalvm.nativeimage.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 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. But for some classes, it is necessary to execute the class initialization method at runtime, e.g., when the class initialization method loads shared libraries (System.loadLibrary), allocates native memory (ByteBuffer.allocateDirect), or starts threads.

This class provides two different registration methods: Classes registered via RuntimeClassInitialization.delayClassInitialization(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.rerunClassInitialization(java.lang.Class<?>...) are initialized during image generation, and again initialized at runtime, i.e., the class initializer is executed twice.

Registering a class automatically registers all subclasses too. It would violate the class initialization specification to have an uninitialized class that has an initialized subclass.

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:

1.0

Method Summary

Modifier and Type	Method and Description
static void	delayClassInitialization(Class<?>... classes) Registers the provided classes, and all of their subclasses, for class initialization at runtime.
static void	rerunClassInitialization(Class<?>... classes) Registers the provided classes, and all of their subclasses, for class re-initialization at runtime.

Methods inherited from class java.lang.Object

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

Method Detail

delayClassInitialization

public static void delayClassInitialization(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:

1.0

rerunClassInitialization

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

Registers the provided classes, and all of their subclasses, for class re-initialization at runtime. The classes are still initialized during image generation, i.e., the class initializers run twice.

Static fields of the registered classes start out with their default values at runtime, i.e., values assigned by class initializers (or for any other reason) to static fields are not available at runtime.

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

Since:

1.0