[GR-40198] Provide public API for feature-based JNI / Resource / Proxy / Serialization registration.

[graalvmbot]

This PR adds the missing APIs that will allow our users to not rely on our svm-internal APIs anymore.

[jerboaa]

@olpaw Thanks for adding me to this. Is this work being planned for 22.3? As this would be related to #4792 do you have some details on what exactly is svm-internal API and, thus, will allow us to determine what will move?

[fniephaus]

Is this work being planned for 22.3?

Yes. If you can help make sure that everything you need is in the first batch, that would speed up the overall migration process for all of us. :)

As this would be related to #4792 do you have some details on what exactly is svm-internal API and, thus, will allow us to determine what will move?

The migration should happen in a backward compatible way, so we don't plan to move anything just yet. This PR adds a new API to the Native Image part of the GraalVM SDK that frameworks are supposed to use in the future. Everything in com.oracle.svm is considered internal, while org.graalvm.nativeimage is the public API. So essentiall, we need to make sure, grep -R "com.oracle.svm" /the/quarkus/codebase does not return any results. :)

[olpaw]

@olpaw Thanks for adding me to this. Is this work being planned for 22.3?

Yes

As this would be related to #4792 do you have some details on what exactly is svm-internal API

Everything that is part of our SVM codebase that currently requires a --add-exports when the image-builder is running on module path (with GraalVM 22.2) (i.e. when the USE_NATIVE_IMAGE_JAVA_PLATFORM_MODULE_SYSTEM=false workaround is NOT used) is considered internal API. See add-exports in https://github.com/oracle/graal/blob/master/java-benchmarks/mx.java-benchmarks/mx_java_benchmarks.py#L374..L380

and, thus, will allow us to determine what will move?

As you can see this PR only adds API but does not remove anything. To be on the safe side projects that currently use svm-internal API should switch to using public API only (for example instead of using com.oracle.svm.core.jni.JNIRuntimeAccess.register use org.graalvm.nativeimage.hosted.RuntimeJNIAccess.register). Users that will continue using non-public API are at risk of experiencing breaking changes as we might modify non-public API as we see fit.

[zakkak]

Hello Paul, thanks for initiating this refactoring.

One major package that I see missing from this batch is com.oracle.svm.core.annotate, not sure if you plan to make it public API in a different PR.

Other than the annotations, Quarkus is currently using the following internal APIs:

1. com.oracle.svm.core.jdk.UnsupportedFeatureError to report a more quarkus-friendly error
2. com.oracle.svm.core.jdk.Resources#registerResource
3. com.oracle.svm.util.ReflectionUtil#lookupMethod
4. com.oracle.svm.core.jni.JNIRuntimeAccess#register
5. com.oracle.svm.core.jdk.proxy.DynamicProxyRegistry#addProxyClass
6. com.oracle.svm.core.jdk.localization.LocalizationFeature#prepareBundle
7. com.oracle.svm.core.configure.ResourcesRegistry#ignoreResources
8. com.oracle.svm.core.configure.ResourcesRegistry#addResources
9. com.oracle.svm.hosted.reflect.serialize.SerializationFeature, this is added as a required feature in one of the quarkus features.

From the above 1, 3, 6 and 9 seem not covered by this PR.

[olpaw]

One major package that I see missing from this batch is com.oracle.svm.core.annotate, not sure if you plan to make it public API in a different PR.

@zakkak, yes making the annotations available as public API is a different PR: #4683

[olpaw]

3. com.oracle.svm.util.ReflectionUtil#lookupMethod

Here I suggest to just copy our implementation (as a starting point). This is a simple helper-method that itself only depends on JDK code. Thus you are better off having your own variant of it in your codebase (i.e. you might want to use such a method in places that otherwise do not require native-image at all).

[olpaw]

9. com.oracle.svm.hosted.reflect.serialize.SerializationFeature, this is added as a required feature in one of the quarkus features.

Here we should make sure that all SVM internal feature handlers have priority (i.e. are executed before) any user-provided feature handler (e.g. Quarkus features). This way your code that specifies SerializationFeature as a required feature becomes obsolete and can be removed. cc @christianwimmer

[olpaw]

6. com.oracle.svm.core.jdk.localization.LocalizationFeature#prepareBundle

No need to use the internal prepareBundle. Use org.graalvm.nativeimage.hosted.RuntimeResourceAccess#addResourceBundles instead.

[olpaw]

1. com.oracle.svm.core.jdk.UnsupportedFeatureError to report a more quarkus-friendly error

I agree. We should discuss a custom solution for this use of com.oracle.svm.core.jdk.UnsupportedFeatureError in quarkus.

BTW, thanks for the detailed list above @zakkak !

[olpaw]

9. com.oracle.svm.hosted.reflect.serialize.SerializationFeature, this is added as a required feature in one of the quarkus features.

@zakkak if you stop using @AutomaticFeature (by using --features <list of FQNs of quarkus features> instead) you should be able to get rid of requiring your feature to specify depending on SerializationFeature because @AutomaticFeatures are always registered before non-automatic ones and thus their hooks are always executed before the ones from user provided features.

[christianwimmer]

9. com.oracle.svm.hosted.reflect.serialize.SerializationFeature, this is added as a required feature in one of the quarkus features.

@zakkak I'm quite curious why you need this feature dependency at all.

[kristofdho]

@olpaw Do I need to create a new issue with these remaining usages?

[olpaw]

@olpaw Do I need to create a new issue with these remaining usages?

That would be a good idea. Then it's easier to keep track of what is still open.