Provide FieldValueTransformer API

Author: Christian Wimmer

sdk/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 This changelog summarizes major changes between GraalVM SDK versions. The main focus is on APIs exported by GraalVM SDK.
 
+## Version 22.3.0
+* (GR-39852) Native Image API: Added FieldValueTransformer API
+
 ## Version 22.2.0
 * (GR-38925) Added `Value.hasMetaParents() and Value.getMetaParents()` that allow lookup of the hierarchy of parents for meta objects (e.g. super class or implemented interface of Java classes).
 * (GR-38351) Added [FileSystem#allowLanguageHomeAccess](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/io/FileSystem.html#allowLanguageHomeAccess-org.graalvm.polyglot.io.FileSystem-) returning a `FileSystem` that forwards access to files in the language home to the default file system.

sdk/src/org.graalvm.nativeimage/snapshot.sigtest

@@ -922,6 +922,7 @@ meth public abstract void registerAsUsed(java.lang.Class<?>)
 meth public abstract void registerClassInitializerReachabilityHandler(java.util.function.Consumer<org.graalvm.nativeimage.hosted.Feature$DuringAnalysisAccess>,java.lang.Class<?>)
 meth public abstract void registerMethodOverrideReachabilityHandler(java.util.function.BiConsumer<org.graalvm.nativeimage.hosted.Feature$DuringAnalysisAccess,java.lang.reflect.Executable>,java.lang.reflect.Executable)
 meth public abstract void registerSubtypeReachabilityHandler(java.util.function.BiConsumer<org.graalvm.nativeimage.hosted.Feature$DuringAnalysisAccess,java.lang.Class<?>>,java.lang.Class<?>)
+meth public abstract void registerFieldValueTransformer(java.lang.reflect.Field,org.graalvm.nativeimage.hosted.FieldValueTransformer)
 
 CLSS public abstract interface static org.graalvm.nativeimage.hosted.Feature$BeforeCompilationAccess
  outer org.graalvm.nativeimage.hosted.Feature
@@ -1024,3 +1025,5 @@ meth public abstract boolean equals(java.lang.Object)
  anno 0 java.lang.Deprecated(boolean forRemoval=false, java.lang.String since="")
 meth public abstract long rawValue()
 
+CLSS public abstract interface org.graalvm.nativeimage.hosted.FieldValueTransformer
+meth public abstract java.lang.Object transform(java.lang.Object,java.lang.Object)

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

@@ -296,6 +296,14 @@ interface BeforeAnalysisAccess extends FeatureAccess {
          * @since 21.0
          */
         void registerClassInitializerReachabilityHandler(Consumer<DuringAnalysisAccess> callback, Class<?> clazz);
+
+        /**
+         * Registers a field value transformer for the provided field. See the JavaDoc of
+         * {@link FieldValueTransformer} for details.
+         * 
+         * @since 22.3
+         */
+        void registerFieldValueTransformer(Field field, FieldValueTransformer transformer);
     }
 
     /**

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

@@ -0,0 +1,86 @@
+/*
+ * Copyright (c) 2022, 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
+ *
+ * Subject to the condition set forth below, permission is hereby granted to any
+ * person obtaining a copy of this software, associated documentation and/or
+ * data (collectively the "Software"), free of charge and under any and all
+ * copyright rights in the Software, and any and all patent rights owned or
+ * freely licensable by each licensor hereunder covering either (i) the
+ * unmodified Software as contributed to or provided by such licensor, or (ii)
+ * the Larger Works (as defined below), to deal in both
+ *
+ * (a) the Software, and
+ *
+ * (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+ * one is included with the Software each a "Larger Work" to which the Software
+ * is contributed by such licensors),
+ *
+ * without restriction, including without limitation the rights to copy, create
+ * derivative works of, display, perform, and distribute the Software and make,
+ * use, sell, offer for sale, import, export, have made, and have sold the
+ * Software and the Larger Work(s), and to sublicense the foregoing rights on
+ * either these or other terms.
+ *
+ * This license is subject to the following condition:
+ *
+ * The above copyright notice and either this complete permission notice or at a
+ * minimum a reference to the UPL must be included in all copies or substantial
+ * portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package org.graalvm.nativeimage.hosted;
+
+import org.graalvm.nativeimage.Platform;
+import org.graalvm.nativeimage.Platforms;
+import org.graalvm.nativeimage.hosted.Feature.BeforeAnalysisAccess;
+
+/**
+ * A transformer for a field value that can be registered using
+ * {@link BeforeAnalysisAccess#registerFieldValueTransformer}.
+ * <p>
+ * At image build time, the field value transformer provides the value of the field for the image
+ * heap. Without a transformer, the value of the field in the image heap is the same as the hosted
+ * value in the image generator. A field value transformer allows to intercept the value. A field
+ * value transformer can, for example, reset a field to the default null/0 value, replace a filled
+ * collection with a new empty collection, or provide any kind of new value for a field.
+ * <p>
+ * Only one field value transformer can be registered for each field.
+ * <p>
+ * A field value transformer can be registered for fields of classes that are initialized at image
+ * run time. That allows constant folding of final fields even though the declaring class is not
+ * initialized at image build time.
+ * <p>
+ * A field value transformer must be registered before the field is seen as reachable by the static
+ * analysis. It is generally safe to register a transformer in {@link Feature#beforeAnalysis} before
+ * the static analysis is started, in a {@link BeforeAnalysisAccess#registerReachabilityHandler type
+ * reachability handler} for the declaring class of the field, or a
+ * {@link BeforeAnalysisAccess#registerSubtypeReachabilityHandler subtype reachability handler} for
+ * a super-type of the declaring class of the field.
+ *
+ * @since 22.3
+ */
+@Platforms(Platform.HOSTED_ONLY.class)
+public interface FieldValueTransformer {
+
+    /**
+     * Transforms the field value for the provided receiver. The receiver is null for static fields.
+     * The original value of the field, i.e., the hosted value of the field in the image generator,
+     * is also provided as an argument.
+     * <p>
+     * The type of the returned object must be assignable to the declared type of the field. If the
+     * field has a primitive type, the return value must be a boxed value, and must not be null.
+     * 
+     * @since 22.3
+     */
+    Object transform(Object receiver, Object originalValue);
+}

substratevm/src/com.oracle.svm.core.windows/src/com/oracle/svm/core/windows/WindowsUtils.java

@@ -36,14 +36,14 @@
 import org.graalvm.nativeimage.c.type.CCharPointer;
 import org.graalvm.nativeimage.c.type.CIntPointer;
 import org.graalvm.nativeimage.c.type.CLongPointer;
+import org.graalvm.nativeimage.hosted.FieldValueTransformer;
 import org.graalvm.word.PointerBase;
 import org.graalvm.word.UnsignedWord;
 import org.graalvm.word.WordFactory;
 
 import com.oracle.svm.core.SubstrateUtil;
 import com.oracle.svm.core.annotate.Alias;
 import com.oracle.svm.core.annotate.RecomputeFieldValue;
-import com.oracle.svm.core.annotate.RecomputeFieldValue.CustomFieldValueComputer;
 import com.oracle.svm.core.annotate.TargetClass;
 import com.oracle.svm.core.annotate.Uninterruptible;
 import com.oracle.svm.core.c.function.CEntryPointActions;
@@ -52,9 +52,6 @@
 import com.oracle.svm.core.windows.headers.WinBase;
 import com.oracle.svm.core.windows.headers.WinBase.HMODULE;
 
-import jdk.vm.ci.meta.MetaAccessProvider;
-import jdk.vm.ci.meta.ResolvedJavaField;
-
 public class WindowsUtils {
 
     @TargetClass(className = "java.lang.ProcessImpl")
@@ -70,14 +67,9 @@ public static int getpid(java.lang.Process process) {
     @TargetClass(java.io.FileDescriptor.class)
     private static final class Target_java_io_FileDescriptor {
         /** Invalidates the standard FileDescriptors, which are allowed in the image heap. */
-        static class InvalidHandleValueComputer implements CustomFieldValueComputer {
-            @Override
-            public RecomputeFieldValue.ValueAvailability valueAvailability() {
-                return RecomputeFieldValue.ValueAvailability.BeforeAnalysis;
-            }
-
+        static class InvalidHandleValueComputer implements FieldValueTransformer {
             @Override
-            public Object compute(MetaAccessProvider metaAccess, ResolvedJavaField original, ResolvedJavaField annotated, Object receiver) {
+            public Object transform(Object receiver, Object originalValue) {
                 return -1L;
             }
         }

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/annotate/Alias.java

@@ -24,14 +24,14 @@
  */
 package com.oracle.svm.core.annotate;
 
-import org.graalvm.nativeimage.Platform;
-import org.graalvm.nativeimage.Platforms;
-
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.graalvm.nativeimage.Platform;
+import org.graalvm.nativeimage.Platforms;
+
 /**
  * Mechanism for referring to fields and methods otherwise inaccessible due to Java language access
  * control rules. This enables VM code to directly access a private field or invoke a private method
@@ -40,10 +40,12 @@
  * <p>
  * The idiom for using {@link Alias} is somewhat related to the {@link Substitute} annotation, but
  * reversed; both are often used in combination. In both cases a separate class is used to declare
- * the aliased or substituted methods. In the substitution case occurrences of {@code this} actually
- * refer to the instance of the class being substituted. In the aliased case we pretend that the
- * class declaring the aliased method is an instance of the aliasee in order to access its fields or
- * invoke its methods.
+ * the aliased and/or substituted methods. In the substitution case occurrences of {@code this}
+ * actually refer to the instance of the class being substituted. In the aliased case we pretend
+ * that the class declaring the aliased method or field is an instance of the aliasee in order to
+ * access its fields or invoke its methods. An alias is always called (method alias) or accessed
+ * (field alias), whereas a substitution method is only implemented (usually not called directly).
+ * In the body of a substitution method, aliases are often called or accessed.
  * <p>
  * The element can also be annotated with {@link TargetElement} to specify additional properties.
  * See {@link TargetClass} for an overview of the annotation system.

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/annotate/AutomaticFeature.java

@@ -24,15 +24,19 @@
  */
 package com.oracle.svm.core.annotate;
 
-import org.graalvm.nativeimage.Platform;
-import org.graalvm.nativeimage.Platforms;
-
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.graalvm.nativeimage.Platform;
+import org.graalvm.nativeimage.Platforms;
+
 /**
+ * Supported API is available to replace this non-API annotation: Instead of using this annotation,
+ * use {@code "--features <fqn.of.FeatureClass>"} in the {@code Args} of a
+ * {@code native-image.properties} file to ensure a user-provided feature gets processed.
+ *
  * Feature classes can use this annotation are unconditionally added when they are reachable on the
  * class path.
  */

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/annotate/Inject.java

@@ -24,20 +24,20 @@
  */
 package com.oracle.svm.core.annotate;
 
-import org.graalvm.nativeimage.Platform;
-import org.graalvm.nativeimage.Platforms;
-
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.graalvm.nativeimage.Platform;
+import org.graalvm.nativeimage.Platforms;
+
 /**
  * Injects the annotated field into the {@link TargetClass}.
  *
- * The field must not be declared static. If instances of the target class are in the native image
- * heap, the field also needs to be annotated with {@link RecomputeFieldValue} to provide a value
- * for the native image objects.
+ * The field must not be declared static. If instances of the target class are in the image heap,
+ * the field also needs to be annotated with {@link RecomputeFieldValue} to provide a value for the
+ * injected field.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.FIELD})

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/annotate/KeepOriginal.java

@@ -24,23 +24,25 @@
  */
 package com.oracle.svm.core.annotate;
 
-import org.graalvm.nativeimage.Platform;
-import org.graalvm.nativeimage.Platforms;
-
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.graalvm.nativeimage.Platform;
+import org.graalvm.nativeimage.Platforms;
+
 /**
- * In a {@link Substitute substituted} type, keep the original definition of this method. The
- * default behavior is that all non-substituted methods are implicitly treated as {@link Delete
- * deleted}. Unless this annotation is applied to the {@link Substitute substituted} type itself,
- * then the original definition of all methods and fields in the target type are kept by default.
+ * If a class annotated with {@link TargetClass} is also annotated with {@link Substitute}, all
+ * non-substituted methods in that class are by default treated as {@link Delete deleted}. This
+ * annotation changes the behavior: A method annotated with {@link KeepOriginal} keeps the original
+ * definition of the method.
+ * <p>
+ * If this annotation is used to the {@link Substitute * substituted} type itself, then the original
+ * definition of all methods and fields in the target type are kept by default.
  * <p>
  * The element can also be annotated with {@link TargetElement} to specify additional properties.
  * See {@link TargetClass} for an overview of the annotation system.
- * </p>
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.METHOD, ElementType.TYPE})