Adding the experimental option -H:Preserve

The `-H:Preserve` flag preserves all metadata from module, class-path entry, or a package in the image. This will allow users to more easily support third-party libraries and get more user-friendly experience with Native Image.
The flag can be used in following ways:

1. -H:Preserve=all preserves all elements from the JDK and from the classpath
2. -H:Preserve=module=<module>preserves all elements from a given module
3. -H:Preserve=module=ALL-UNNAMEDpreserves all elements from the class-path entry
4. -H:Preserve=package=<package>preserves all elements from a given package
5. -H:Preserve=path=<cp-entry>preserves all elements from a given class-path entry
6. A combination of any of the previous uses, for example, -H:Preserve=path=<cp-entry>,module<module>

Author: vjovanov

sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/hosted/RuntimeReflection.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2017, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2017, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -231,7 +231,7 @@ public static void registerAllFields(Class<?> declaringClass) {
      * @since 23.0
      */
     public static void registerAllDeclaredFields(Class<?> declaringClass) {
-        ImageSingletons.lookup(RuntimeReflectionSupport.class).registerAllDeclaredFieldsQuery(ConfigurationCondition.alwaysTrue(), declaringClass);
+        ImageSingletons.lookup(RuntimeReflectionSupport.class).registerAllDeclaredFields(ConfigurationCondition.alwaysTrue(), declaringClass);
     }
 
     /**

sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/impl/RuntimeReflectionSupport.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2017, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2017, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -48,7 +48,7 @@ public interface RuntimeReflectionSupport extends ReflectionRegistry {
 
     void registerAllFieldsQuery(ConfigurationCondition condition, Class<?> clazz);
 
-    void registerAllDeclaredFieldsQuery(ConfigurationCondition condition, Class<?> clazz);
+    void registerAllDeclaredFields(ConfigurationCondition condition, Class<?> clazz);
 
     void registerAllConstructorsQuery(ConfigurationCondition condition, boolean queriedOnly, Class<?> clazz);
 

substratevm/CHANGELOG.md

@@ -9,6 +9,17 @@ This changelog summarizes major changes to GraalVM Native Image.
 * (GR-59864) Added JVM version check to the Native Image agent. The agent will abort execution if the JVM major version does not match the version it was built with, and warn if the full JVM version is different.
 * (GR-59135) Verify if hosted options passed to `native-image` exist prior to starting the builder. Provide suggestions how to fix unknown options early on.
 * (GR-61492) The experimental JDWP option is now present in standard GraalVM builds.
+* (GR-54953) Add the experimental option `-H:Preserve` that preserves all metadata from module, class-path entry, or a package in the image. This will allow users to more easily support third-party libraries and get more user-friendly experience with Native Image.
+
+    The flag can be used in following ways:
+        1. `-H:Preserve=all` preserves all elements from the JDK and from the classpath
+        2. `-H:Preserve=module=<module>`preserves all elements from a given module
+        3. `-H:Preserve=module=ALL-UNNAMED`preserves all elements from the class-path entry
+        4. `-H:Preserve=package=<package>`preserves all elements from a given package
+        5. `-H:Preserve=path=<cp-entry>`preserves all elements from a given class-path entry
+        6.  A combination of any of the previous uses, for example, `-H:Preserve=path=<cp-entry>,module<module>`
+
+    The `-H:Preserve` options are forbidden in the `native-image.property` entries on the classpath.
 
 ## GraalVM for JDK 24 (Internal Version 24.2.0)
 * (GR-59717) Added `DuringSetupAccess.registerObjectReachabilityHandler` to allow registering a callback that is executed when an object of a specified type is marked as reachable during heap scanning.

substratevm/src/com.oracle.graal.pointsto/src/com/oracle/graal/pointsto/ClassInclusionPolicy.java

@@ -56,12 +56,28 @@ public void setBigBang(BigBang bb) {
         this.bb = bb;
     }
 
+    public static boolean isClassIncludedBase(Class<?> cls) {
+        if (Feature.class.isAssignableFrom(cls)) {
+            return false;
+        }
+
+        if (AnnotationAccess.isAnnotationPresent(cls, TargetClass.class)) {
+            return false;
+        }
+        try {
+            Class<?> enclosingClass = cls.getEnclosingClass();
+            return enclosingClass == null || isClassIncludedBase(enclosingClass);
+        } catch (LinkageError e) {
+            return true;
+        }
+    }
+
     /**
      * Determine if the given class needs to be included in the image according to the policy.
      */
     public boolean isClassIncluded(Class<?> cls) {
         Class<?> enclosingClass = cls.getEnclosingClass();
-        return !Feature.class.isAssignableFrom(cls) && !AnnotationAccess.isAnnotationPresent(cls, TargetClass.class) && (enclosingClass == null || isClassIncluded(enclosingClass));
+        return isClassIncludedBase(cls) && (enclosingClass == null || isClassIncluded(enclosingClass));
     }
 
     /**

substratevm/src/com.oracle.graal.pointsto/src/com/oracle/graal/pointsto/PointsToAnalysis.java

@@ -666,7 +666,7 @@ public void onTypeInstantiated(AnalysisType type) {
         /* Register the type as instantiated with all its super types. */
 
         assert type.isInstantiated() : type;
-        AnalysisError.guarantee(type.isArray() || (type.isInstanceClass() && !type.isAbstract()));
+        AnalysisError.guarantee(type.isArray() || (type.isInstanceClass() && !type.isAbstract()), "Type %s must be either an array, or a non abstract instance class", type.getName());
 
         TypeState typeState = TypeState.forExactType(this, type, true);
         TypeState typeStateNonNull = TypeState.forExactType(this, type, false);

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/IncludeExtendedOption.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2025, 2025, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package com.oracle.svm.core;
+
+public record IncludeExtendedOption(String key, String value) {
+
+    public static final String PACKAGE_OPTION = "package";
+    public static final String MODULE_OPTION = "module";
+    public static final String PATH_OPTION = "path";
+
+    public static IncludeExtendedOption parse(String option) {
+        String[] optionParts = SubstrateUtil.split(option, "=", 2);
+        if (optionParts.length == 2) {
+            return new IncludeExtendedOption(optionParts[0], optionParts[1]);
+        } else {
+            return new IncludeExtendedOption(option, null);
+        }
+    }
+}

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/SubstrateOptions.java

@@ -35,9 +35,14 @@
 import java.nio.file.InvalidPathException;
 import java.nio.file.Path;
 import java.nio.file.Paths;
+import java.util.Arrays;
+import java.util.HashSet;
 import java.util.List;
+import java.util.Set;
 import java.util.UUID;
 import java.util.function.Predicate;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
 
 import org.graalvm.collections.EconomicMap;
 import org.graalvm.collections.UnmodifiableEconomicMap;
@@ -57,6 +62,7 @@
 import com.oracle.svm.core.option.GCOptionValue;
 import com.oracle.svm.core.option.HostedOptionKey;
 import com.oracle.svm.core.option.HostedOptionValues;
+import com.oracle.svm.core.option.LocatableMultiOptionValue;
 import com.oracle.svm.core.option.OptionMigrationMessage;
 import com.oracle.svm.core.option.ReplacingLocatableMultiOptionValue;
 import com.oracle.svm.core.option.RuntimeOptionKey;
@@ -1326,6 +1332,73 @@ public enum ReportingMode {
     @Option(help = "Include all classes, methods, fields, and resources from the class path", type = OptionType.Debug) //
     public static final HostedOptionKey<Boolean> IncludeAllFromClassPath = new HostedOptionKey<>(false);
 
+    @Option(help = "Preserve classes, methods, fields, and resources in the image.")//
+    public static final HostedOptionKey<AccumulatingLocatableMultiOptionValue.Strings> Preserve = new HostedOptionKey<>(AccumulatingLocatableMultiOptionValue.Strings.build());
+
+    public record IncludeEntry(String value, OptionKey<?> option, String optionValue, String optionOrigin) {
+    }
+
+    public static final Set<IncludeEntry> PRESERVED_MODULES = new HashSet<>();
+    public static final Set<IncludeEntry> PRESERVED_PACKAGES = new HashSet<>();
+    public static final Set<IncludeEntry> PRESERVED_CLASSPATH_ENTRIES = new HashSet<>();
+    public static boolean preserveAll;
+
+    public static final String PRESERVE_ALL = "all";
+    public static final String PRESERVE_NONE = "none";
+
+    public static final String PRESERVE_POSSIBLE_OPTIONS;
+    static {
+        String msg = "[" + PRESERVE_ALL + ", " + PRESERVE_NONE + ", ";
+        msg += Stream.of(IncludeExtendedOption.MODULE_OPTION, IncludeExtendedOption.PACKAGE_OPTION, IncludeExtendedOption.PATH_OPTION)
+                        .map(option -> option + "=" + "<" + option + ">")
+                        .collect(Collectors.joining(", "));
+        msg += "]";
+        PRESERVE_POSSIBLE_OPTIONS = msg;
+    }
+
+    public static void parsePreserveOption(EconomicMap<OptionKey<?>, Object> hostedValues) {
+        AccumulatingLocatableMultiOptionValue.Strings preserve = Preserve.getValue(new OptionValues(hostedValues));
+        Stream<LocatableMultiOptionValue.ValueWithOrigin<String>> valuesWithOrigins = preserve.getValuesWithOrigins();
+        valuesWithOrigins.forEach(valueWithOrigin -> {
+            String optionValue = valueWithOrigin.value();
+            String optionOrigin = valueWithOrigin.origin().toString();
+
+            var extendedOptions = Arrays.stream(valueWithOrigin.value().split(",")).toList();
+            for (String extendedOption : extendedOptions) {
+                UserError.guarantee(!extendedOption.isEmpty(), "Option %s from %s cannot be passed an empty string. The possible options are: %s",
+                                SubstrateOptionsParser.commandArgument(Preserve, optionValue), optionOrigin, PRESERVE_POSSIBLE_OPTIONS);
+                if (extendedOption.equals(PRESERVE_ALL)) {
+                    preserveAll = true;
+                } else if (extendedOption.equals(PRESERVE_NONE)) {
+                    preserveAll = false;
+                } else {
+                    IncludeExtendedOption subOption = IncludeExtendedOption.parse(extendedOption);
+                    final IncludeEntry preservedEntry = new IncludeEntry(subOption.value(), Preserve, optionValue, optionOrigin);
+                    switch (subOption.key()) {
+                        case IncludeExtendedOption.MODULE_OPTION -> {
+                            UserError.guarantee(subOption.value() != null, "Option %s in %s from %s requires a module name argument, e.g., %s=module-name.", subOption.key(), optionValue, optionOrigin,
+                                            subOption.key());
+                            SubstrateOptions.PRESERVED_MODULES.add(preservedEntry);
+                        }
+                        case IncludeExtendedOption.PACKAGE_OPTION -> {
+                            UserError.guarantee(subOption.value() != null, "Option %s in %s from %s requires a package name argument, e.g., %s=package-name.", subOption.key(), optionValue,
+                                            optionOrigin, subOption.key());
+                            SubstrateOptions.PRESERVED_PACKAGES.add(preservedEntry);
+                        }
+                        case IncludeExtendedOption.PATH_OPTION -> {
+                            UserError.guarantee(subOption.value() != null, "Option %s in %s from %s requires a class-path entry, e.g., %s=path/to/jar-file.", subOption.key(), optionValue,
+                                            optionOrigin, subOption.key());
+                            SubstrateOptions.PRESERVED_CLASSPATH_ENTRIES.add(preservedEntry);
+                        }
+
+                        default -> throw UserError.abort("Unknown option %s used on %s. The possible options are: %s", subOption.key(), optionOrigin, PRESERVE_POSSIBLE_OPTIONS);
+                    }
+                }
+
+            }
+        });
+    }
+
     public static boolean includeAll() {
         return IncludeAllFromModule.hasBeenSet() || IncludeAllFromPath.hasBeenSet() || IncludeAllFromPackage.hasBeenSet() || IncludeAllFromClassPath.hasBeenSet();
     }

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/hub/ClassForNameSupport.java

@@ -26,6 +26,7 @@
 
 import static com.oracle.svm.core.MissingRegistrationUtils.throwMissingRegistrationErrors;
 
+import java.lang.reflect.Modifier;
 import java.util.EnumSet;
 import java.util.Objects;
 
@@ -159,7 +160,7 @@ public void registerNegativeQuery(ConfigurationCondition condition, String class
 
     @Platforms(Platform.HOSTED_ONLY.class)
     public void registerUnsafeAllocated(ConfigurationCondition condition, Class<?> clazz) {
-        if (!clazz.isArray()) {
+        if (!clazz.isArray() && !clazz.isInterface() && !Modifier.isAbstract(clazz.getModifiers())) {
             var conditionSet = unsafeInstantiatedClasses.putIfAbsent(clazz, RuntimeConditionSet.createHosted(condition));
             if (conditionSet != null) {
                 conditionSet.addCondition(condition);

substratevm/src/com.oracle.svm.driver/src/com/oracle/svm/driver/CmdLineOptionHandler.java

@@ -36,8 +36,7 @@
 import com.oracle.svm.core.option.OptionOrigin;
 import com.oracle.svm.core.util.ExitStatus;
 import com.oracle.svm.driver.NativeImage.ArgumentQueue;
-import com.oracle.svm.hosted.imagelayer.LayerArchiveSupport;
-import com.oracle.svm.hosted.imagelayer.LayerOptionsSupport.ExtendedOption;
+import com.oracle.svm.core.IncludeExtendedOption;
 import com.oracle.svm.hosted.imagelayer.LayerOptionsSupport.LayerOption;
 import com.oracle.svm.util.LogUtils;
 
@@ -146,9 +145,9 @@ private boolean consume(ArgumentQueue args, String headArg) {
             String layerCreateValue = headArg.substring(SubstrateOptions.LAYER_CREATE_OPTION.length());
             if (!layerCreateValue.isEmpty()) {
                 LayerOption layerOption = LayerOption.parse(layerCreateValue);
-                for (ExtendedOption option : layerOption.extendedOptions()) {
+                for (IncludeExtendedOption option : layerOption.extendedOptions()) {
                     switch (option.key()) {
-                        case LayerArchiveSupport.PACKAGE_OPTION -> {
+                        case IncludeExtendedOption.PACKAGE_OPTION -> {
                             String packageName = option.value();
                             String moduleName = nativeImage.systemPackagesToModules.get(packageName);
                             if (moduleName != null) {

substratevm/src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/ClassLoaderSupportImpl.java

@@ -116,7 +116,8 @@ public void collectResources(ResourceCollector resourceCollector) {
 
         /* Collect remaining resources from classpath */
         classLoaderSupport.classpath().stream().parallel().forEach(classpathFile -> {
-            boolean includeCurrent = classLoaderSupport.getJavaPathsToInclude().contains(classpathFile) || classLoaderSupport.includeAllFromClassPath();
+            boolean includeCurrent = classLoaderSupport.getPathsToInclude().contains(classpathFile) || classLoaderSupport.includeAllFromClassPath() ||
+                            classLoaderSupport.getClassPathEntriesToPreserve().contains(classpathFile) || classLoaderSupport.isEnabledDynamicAccess();
             try {
                 if (Files.isDirectory(classpathFile)) {
                     scanDirectory(classpathFile, resourceCollector, includeCurrent);
@@ -132,7 +133,8 @@ public void collectResources(ResourceCollector resourceCollector) {
     private void collectResourceFromModule(ResourceCollector resourceCollector, ResourceLookupInfo info) {
         ModuleReference moduleReference = info.resolvedModule.reference();
         try (ModuleReader moduleReader = moduleReference.open()) {
-            boolean includeCurrent = classLoaderSupport.getJavaModuleNamesToInclude().contains(info.resolvedModule().name());
+            boolean includeCurrent = classLoaderSupport.getModuleNamesToInclude().contains(info.resolvedModule().name()) ||
+                            classLoaderSupport.getModuleNamesToPreserve().contains(info.resolvedModule().name());
             List<ConditionalResource> resourcesFound = new ArrayList<>();
             moduleReader.list().forEach(resourceName -> {
                 var conditionsWithOrigins = shouldIncludeEntry(info.module, resourceCollector, resourceName, moduleReference.location().orElse(null), includeCurrent);