[GR-62940] API for dynamic-access registration based on access conditions

[graalvmbot]

Motivation

The current API for dynamic-access registration supports conditional registrations only through reachability handlers. This means that the program semantics (i.e., if something is registered or not) depends on the results of static analysis.

Since static analysis are not deterministic (affected by the classpath, compiler optimizations, usage layers or not) and not available in regular Java execution, we want to move away from the analysis results as the driver of semantics.

In addition, the current dynamic-access registration API was built for fine-grained reflection which is unnecessarily complex. Take, for example, the code needed to register all metadata for a single type:

        RuntimeReflection.registerAllDeclaredFields(clazz);
        RuntimeReflection.registerAllFields(clazz);
        RuntimeReflection.registerAllDeclaredMethods(clazz);
        RuntimeReflection.registerAllMethods(clazz);
        RuntimeReflection.registerAllDeclaredConstructors(clazz);
        RuntimeReflection.registerAllConstructors(clazz);
        RuntimeReflection.registerAllClasses(clazz);
        RuntimeReflection.registerAllRecordComponents(clazz);
        RuntimeReflection.registerAllPermittedSubclasses(clazz);
        RuntimeReflection.registerAllNestMembers(clazz);
        RuntimeReflection.registerAllSigners(clazz);

The revised API

This PR introduces a simplified API for metadata registration based on conditions, that has similar semantics as reachability-metadata.json. The key differences of the revised API are:

1. Each method in the new API takes a AccessCondition as its first argument. Conditions for programmatic metadata registration are explained in the Access Condition documentation.

2. The API should be independent of Native Image as we want to be able to use it in Crema. Therefore, it can be used only during Feature#afterRegistration as this phase of the Feature API is Native Image agnostic. Any attempt to register metadata after Feature#afterRegistration throws an error.

3. The users acquire an instance of the revised API via getter methods on Feature#AfterRegistrationAccess. This guides the users to use the feature during Feature#afterRegistration.

4. Similarly to reachability-metadata.json, the all reflection registrations of individual elements (e.g., methods and fields) also register the declaring class metadata.

Naming decisions

1. Ideally we want to avoid binding the name to the build-time paradigm and the hosted vs non-hosted distinction, thus we are proposing to move the revised API from the hosted to the new dynamicaccess package.
2. Unified the names for APIs to end with Access: ReflectiveAccess, ResourceAccess, ForeignAccess, JNIAccess.
3. The name of the API that represents access conditions is AccessCondition, as they guard access at run time.
4. Factory method for creating the always satisfiedAccessCondition is unconditional.

Examples

 // Current API
 RuntimeReflection.register(Foo.class);
 RuntimeReflection.registerAllClasses(Foo.class);
 RuntimeReflection.registerAllDeclaredClasses(Foo.class);
 RuntimeReflection.registerAllMethods(Foo.class);
 RuntimeReflection.registerAllFields(Foo.class);

 // New API
 public void afterRegistration(AfterRegistrationAccess access) {
     var reflection = access.getReflectiveAccess();
     reflection.register(AccessCondition.typeReached(Bar.class), Foo.class);
 }

An example of Micronaut internal feature adapted to the new API

Deprecation of current API

The existing API (e.g, RuntimeReflection, RuntimeResourceAccess, RuntimeSerialization, etc.) for metadata registration will remain available during a transition to the revised API. Therefore we are introducing an optional flag TrackDeprecatedRegistationUsage that emits runtime warnings when the legacy API is invoked, enabling developers to identify and remove deprecated usage.