[GR-54193] Documentation for the exact reachability metadata.

PullRequest: graal/18574

docs/reference-manual/embedding/embed-languages.md

@@ -565,7 +565,7 @@ The language home options remain functional for compatibility reasons but may be
 ### Configuring Native Host Reflection
 
 Accessing host Java code from the guest application requires Java reflection in order to work.
-When reflection is used within a native executable, the [reflection configuration file](../native-image/Reflection.md) is required.
+When reflection is used within a native executable, the [reflection configuration file](../native-image/ReachabilityMetadata.md#reflection) is required.
 
 For this example we use JavaScript to show host access with native executables.
 Copy the following code in a new file named `AccessJavaFromJS.java`.
@@ -601,13 +601,18 @@ public class AccessJavaFromJS {
 }
 ```
 
-Copy the following code into `reflect.json`:
+Copy the following code into `reachability-metadata.json`:
+```json
+{
+  "reflection": [
+     { "type": "AccessJavaFromJS$MyClass", "allPublicFields": true },
+     { "type": "java.util.concurrent.Callable", "allPublicMethods": true }
+  ]
+}
+```
 
-{% highlight java %}
-{% include embed/access_java_from_reflection_config.json %}
-{% endhighlight %}
 
-Now, you can create a native executable that supports host access and add the additional `-H:ReflectionConfigurationFiles=reflect.json` build-time option.
+Now, you can add `reachability-metadata.json` to `META-INF/native-image/<group-id>/` of your project.
 
 ## Code Caching Across Multiple Contexts
 

docs/reference-manual/native-image/AutomaticMetadataCollection.md

@@ -58,7 +58,7 @@ It is advisable to manually review the generated configuration files.
 Because the agent observes only executed code, the application input should cover as many code paths as possible.
 
 The generated configuration files can be supplied to the `native-image` tool by placing them in a `META-INF/native-image/` directory on the class path. 
-This directory (or any of its subdirectories) is searched for files with the names `jni-config.json`, `reflect-config.json`, `proxy-config.json`, `resource-config.json`, `predefined-classes-config.json`, `serialization-config.json` which are then automatically included in the build process. 
+This directory (or any of its subdirectories) is searched for the file named _reachability-metadata.json_ that is then automatically included in the build process. 
 Not all of those files must be present. 
 When multiple files with the same name are found, all of them are considered.
 
@@ -134,7 +134,7 @@ The option can be specified more than once to add multiple filter files and can
 ### Specify Configuration Files as Arguments
 
 A directory containing configuration files that is not part of the class path can be specified to `native-image` via `-H:ConfigurationFileDirectories=/path/to/config-dir/`.
-This directory must directly contain all files: `jni-config.json`, `reflect-config.json`, `proxy-config.json` and `resource-config.json`.
+This directory must directly contain _reachability-metadata.json_ or the formerly-used individual metadata files (_jni-config.json_, _reflect-config.json_, _proxy-config.json_, _serialization-config.json_, and _resource-config.json_).
 A directory with the same metadata files that is on the class path, but not in `META-INF/native-image/`, can be provided via `-H:ConfigurationResourceRoots=path/to/resources/`.
 Both `-H:ConfigurationFileDirectories` and `-H:ConfigurationResourceRoots` can also take a comma-separated list of directories.
 

docs/reference-manual/native-image/DynamicFeatures.md

@@ -15,10 +15,9 @@ Thus, some dynamic Java features may require special "treatment" such as a comma
 
 The reference information here explains how Native Image handles some dynamic features of Java:
 
-- [Accessing Resources](Resources.md)
+- [Accessing Resources](ReachabilityMetadata.md#resources)
 - [Certificate Management](CertificateManagement.md)
-- [Dynamic Proxy](DynamicProxy.md)
-- [Java Native Interface (JNI)](JNI.md)
+- [Java Native Interface (JNI)](ReachabilityMetadata.md#java-native-interface)
 - [JCA Security Services](JCASecurityServices.md)
-- [Reflection](Reflection.md)
+- [Reflection](ReachabilityMetadata.md#reflection)
 - [URL Protocols](URLProtocols.md)

docs/reference-manual/native-image/JNI.md

@@ -43,22 +43,13 @@ This requires keeping the necessary metadata for these lookups around.
 The `native-image` builder must know beforehand which items will be looked up in case they might not be reachable otherwise and therefore would not be included in a native image.
 Moreover, `native-image` must generate wrapper code ahead-of-time for any method that can be called via JNI.
 Therefore, specifying a concise list of items that need to be accessible via JNI guarantees their availability and allows for a smaller footprint.
-Such a list can be specified with the following image build argument:
-```shell
--H:JNIConfigurationFiles=/path/to/jni-config.json
-```
-Here, _jni-config.json_ is a JSON configuration file.
-Check the JSON schema for specifying JNI metadata [here](ReachabilityMetadata.md#specifying-metadata-with-json).
-
-The `native-image` builder generates JNI reflection metadata for all classes, methods, and fields referenced in the configuration file.
-More than one JNI configuration can be used by specifying multiple paths for `JNIConfigurationFiles` and separating them with `,`.
-Also, `-H:JNIConfigurationResources` can be specified to load one or several configuration files from the image build's class path, such as from a JAR file.
+Such a list should be specified in the [_reachability-metadata.json_ file](ReachabilityMetadata.md#java-native-interface).
 
 The JNI configuration can be collected automatically using the [Tracing Agent](AutomaticMetadataCollection.md) from the GraalVM JDK. 
 The agent tracks all usages of dynamic features during application execution on a regular Java VM. 
 When the application completes and the JVM exits, the agent writes configuration to JSON files in the specified output directory.
 If you move the generated configuration files from that output directory to _META-INF/native-image/_ on the class path, they are then automatically used at build time. 
-The `native-image` builder searches for _META-INF/native-image/_ and its subdirectories for files named _jni-config.json_, _reflect-config.json_, and others.
+The `native-image` builder searches for _META-INF/native-image/_ and its subdirectories for file named _reachability-metadata.json_, or legacy files such as _reflect-config.json_ and others.
 
 Alternatively, a custom `Feature` implementation can register program elements before and during the analysis phase of the image build using the `JNIRuntimeAccess` class. For example:
 ```java
@@ -84,7 +75,7 @@ To activate the custom feature, pass `--features=<fully qualified name of JNIReg
 
 The JNI functions `FromReflectedMethod` and `ToReflectedMethod` can be used to obtain the corresponding `jmethodID` to a `java.lang.reflect.Method`, or to a `java.lang.reflect.Constructor` object, and vice versa.
 The functions `FromReflectedField` and `ToReflectedField` convert between `jfieldID` and `java.lang.reflect.Field`.
-In order to use these functions, [reflection support](Reflection.md) must be enabled and the methods and fields in question must be included in the reflection configuration, which is specified with `-H:ReflectionConfigurationFiles=`.
+In order to use these functions, [reflection support](ReachabilityMetadata.md#reflection) must be enabled and the methods and fields in question must be included in the reflection metadata.
 
 ## Object Handles