Package 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 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 initializeAtBuildTime(java.lang.Class<?>...) 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.
    Since:
    19.0

    • Method Details

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

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

        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