[GR-37608] Provide a demo for Accessing Resources in Native Images doc

olyagpl · olyagpl · commit a57ec4bb1cd3 · 2022-03-29T08:09:12.000Z
PullRequest: graal/11406
diff --git a/docs/getting-started/graalvm-enterprise/container-images/graalvm-ee-container-images.md b/docs/getting-started/graalvm-enterprise/container-images/graalvm-ee-container-images.md
@@ -13,10 +13,10 @@ The following images are available:
 
 | Image Name      | Description                                        
 ------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|
-| [**jdk-ee**](https://container-registry.oracle.com/ords/ocr/ba/graalvm/jdk-ee)          | A compact image containing the GraalVM Enterprise JDK. |
-| [**native-image-ee**](https://container-registry.oracle.com/ords/ocr/ba/graalvm/native-image-ee) | A compact image which includes the GraalVM Enterprise `native-image` utility and JDK |
-| [**enterprise**](https://container-registry.oracle.com/ords/ocr/ba/graalvm/enterprise)      | Provides the GraalVM Enterprise JDK along with the `gu` (Graal Updater) utility to enable installation of additional features. |
-| [**nodejs-ee**](https://container-registry.oracle.com/ords/ocr/ba/graalvm/nodejs-ee)       | Includes the Node.js runtime and the GraalVM Enterprise JDK. |
+| **jdk-ee**          | A compact image containing the GraalVM Enterprise JDK. |
+| **native-image-ee** | A compact image which includes the GraalVM Enterprise `native-image` utility and JDK |
+| **enterprise**      | Provides the GraalVM Enterprise JDK along with the `gu` (Graal Updater) utility to enable installation of additional features. |
+| **nodejs-ee**       | Includes the Node.js runtime and the GraalVM Enterprise JDK. |
 
 ## Images Tagging Structure and Availability
 
diff --git a/docs/reference-manual/embedding/embed-languages.md b/docs/reference-manual/embedding/embed-languages.md
@@ -19,7 +19,6 @@ permalink: /reference-manual/embed-languages/
 * [Embed languages in Guest Languages](#embed-languages-in-guest-languages)
 * [Build a Shell for Many Languages](#build-a-shell-for-many-languages)
 * [Step Through with Execution Listeners](#step-through-with-execution-listeners)
-* [Enterprise Sandbox Resource Limits](#enterprise-sandbox-resource-limits)
 * [Dependency setup](#dependency-setup)
 
 The GraalVM Polyglot API lets you embed and run code from guest languages in JVM-based host applications.
@@ -492,7 +491,7 @@ public class Main {
 }
 ```
 
-In this code: 
+In this code:
 - `import org.graalvm.polyglot.*` imports the base API for the Polyglot API.
 - `Engine.create()` creates a new engine instance with the default configuration.
 - `Source.create()` creates a source object for the expression “21 + 21”
@@ -532,7 +531,7 @@ public class Main {
 }
 ```
 
-In this code: 
+In this code:
 - `Context.newBuilder().allowAllAccess(true).build()` builds a new outer context with all privileges.
 - `outer.eval` evaluates a JavaScript snippet in the outer context.
 - `inner = Java.type('org.graalvm.polyglot.Context').create()` the first JS script line looks up the Java host type Context and creates a new inner context instance with no privileges (default).
@@ -610,9 +609,6 @@ In this code:
 - The `context.eval()` call evaluates a specified snippet of guest language code.
 - The `listener.close()` closes a listener earlier, however execution listeners are automatically closed with the engine.
 
-<!-- Enterprise Sandbox Resource Limits -->
-{% include_relative sandbox-options.md %}
-
 ## Polyglot Isolates
 
 On GraalVM Enterprise, a Polyglot engine can be configured to run in a dedicated native image isolate.
diff --git a/docs/reference-manual/native-image/Resources.md b/docs/reference-manual/native-image/Resources.md
@@ -6,8 +6,9 @@ permalink: /reference-manual/native-image/Resources/
 ---
 # Accessing Resources in Native Images
 
-By default, the native image builder will not integrate any of the resources which are on the classpath during the generation into the final image.
-To make calls such as `Class.getResource()` or `Class.getResourceAsStream()` (or the corresponding ClassLoader methods) return specific resources (instead of null), the resources that should be accessible at image run time need to be explicitly specified. This can be done via a configuration file such as the following:
+By default, the `native-image` tool will not integrate any of the resources which are on the classpath during the generation into the final image.
+To make calls such as `Class.getResource()` or `Class.getResourceAsStream()` (or their corresponding `ClassLoader` methods) return specific resources (instead of `null`), you must specify the resources that should be accessible at run time. 
+This can be achieved using a configuration file with the following content:
 
 ```json
 {
@@ -30,11 +31,11 @@ The configuration file's path must be provided to `native-image` with `-H:Resour
 Alternatively, individual resource paths can also be specified directly to `native-image`:
 
 ```shell
-native-image -H:IncludeResources=<Java regexp that matches resources to be included in the image> -H:ExcludeResources=<Java regexp that matches resources to be excluded from the image> ...
+native-image -H:IncludeResources="<Java regexp that matches resources to be included in the image>" -H:ExcludeResources="<Java regexp that matches resources to be excluded from the image>" ...
 ```
 The `-H:IncludeResources` and `-H:ExcludeResources` options can be passed several times to define more than one regexp to match or exclude resources, respectively.
 
-To see which resources get ultimately included into the image, you can enable the related logging info with `-H:Log=registerResource:`.
+To see which resources are included in the native executable, use the option `-H:Log=registerResource:<log level>`. The `<log level>` must be in the range from `1` to `5`, from least detailed to most detailed.
 
 ### Example Usage
 
@@ -52,11 +53,73 @@ my-app-root
 ```
 Then:
 
-*  All resources can be loaded with `.*/Resource.*txt$`, specified as `{"pattern":".*/Resource.*txt$"}` in a configuration file, or `-H:IncludeResources='.*/Resource.*txt$'` on the command line.
+*  All resources can be loaded with `".*/Resource.*txt$"`, specified as `{"pattern":".*/Resource.*txt$"}` in a configuration file, or `-H:IncludeResources=".*/Resource.*txt$"` on the command line.
 *  `Resource0.txt` can be loaded with `.*/Resource0.txt$`.
 *  `Resource0.txt` and `Resource1.txt` can be loaded with `.*/Resource0.txt$` and `.*/Resource1.txt$`
    (or alternatively with a single `.*/(Resource0|Resource1).txt$`).
-*  Also, if we want to include everything except the `Resource2.txt` file, we can simply exclude it with `-H:IncludeResources='.*/Resource.*txt$'` followed by `-H:ExcludeResources='.*/Resource2.txt$'`.
+*  Also, if we want to include everything except the `Resource2.txt` file, we can simply exclude it with `-H:IncludeResources=".*/Resource.*txt$"` followed by `-H:ExcludeResources=".*/Resource2.txt$"`.
+
+The following demo illustrates how to include a resource into a native executable. The application `fortune` simulates the traditional `fortune` Unix program (for more information, see [fortune](https://en.wikipedia.org/wiki/Fortune_(Unix)).
+
+1. Save the following Java code into the _Fortune.java_ file:
+
+    ```java
+    import java.io.BufferedReader;
+    import java.io.InputStreamReader;
+    import java.util.ArrayList;
+    import java.util.Random;
+    import java.util.Scanner;
+
+    public class Fortune {
+
+        private static final String SEPARATOR = "%";
+        private static final Random RANDOM = new Random();
+        private ArrayList<String> fortunes = new ArrayList<>();
+
+        public Fortune(String path) {
+            // Scan the file into the array of fortunes
+            Scanner s = new Scanner(new BufferedReader(new InputStreamReader(this.getClass().getResourceAsStream(path))));
+            s.useDelimiter(SEPARATOR);
+            while (s.hasNext()) {
+                fortunes.add(s.next());
+            }        
+        }
+        
+        private void printRandomFortune() throws InterruptedException {
+            int r = RANDOM.nextInt(fortunes.size()); //Pick a random number
+            String f = fortunes.get(r);  //Use the random number to pick a random fortune
+            for (char c: f.toCharArray()) {  // Print out the fortune
+              System.out.print(c);
+                Thread.sleep(100);   
+            }
+        }
+      
+        public static void main(String[] args) throws InterruptedException {
+            Fortune fortune = new Fortune("/fortunes.u8");
+            fortune.printRandomFortune();
+        }
+    }
+    ```
+
+2. Open the [_fortunes.u8_](assets/fortunes.u8) resource file and save it in the same directory as _Fortune.java_.
+
+3. Compile:
+
+    ```shell
+    $JAVA_HOME/bin/javac Fortune.java
+    ```
+
+4. Build a native executable by specifying the resource path:
+
+    ```shell
+    $JAVA_HOME/bin/native-image Fortune -H:IncludeResources=".*u8$"
+    ```
+
+5. Run the executable image: 
+
+    ```shell
+    ./fortune
+    ```
 
 See also the [guide on assisted configuration of Java resources and other dynamic features](BuildConfiguration.md#assisted-configuration-of-native-image-builds).
 
@@ -94,7 +157,7 @@ Alternatively, bundles can be specified directly as options to `native-image` as
 native-image -H:IncludeResourceBundles=your.pgk.Bundle,another.pkg.Resource,etc.Bundle ...
 ```
 By default, the requested bundles are included for all requested locales.
-In order to optimize this, it is possible to use ``IncludeResourceBundles`` with locale specific substring, for example ``-H:+IncludeResourceBundles=com.company.bundles.MyBundle_fr-FR`` will include the bundle only in French.
+In order to optimize this, it is possible to use `IncludeResourceBundles` with locale specific substring, for example `-H:+IncludeResourceBundles=com.company.bundles.MyBundle_fr-FR` will include the bundle only in French.
 
 ### Resources in Java modules
 
@@ -124,6 +187,6 @@ will always work as expected for resources registered as described above (even i
 ### JVM Mode of Localization
 
 Resource Bundle lookup is a complex and dynamic mechanism which utilizes a lot of the infrastructure of JVM.
-As a result of that, it causes image size increase for smaller applications such as Hello World.
+As a result of that, it causes the size of the executable to increase for smaller applications such as `HelloWorld`.
 Therefore, an optimized mode is set by default in which this lookup is simplified utilizing the fact the all bundles are known ahead of time.
 In case you would like to use the original JVM lookup, use the `-H:-LocalizationOptimizedMode` option.
diff --git a/docs/reference-manual/native-image/assets/fortunes.u8 b/docs/reference-manual/native-image/assets/fortunes.u8
