Replace XML parser with Scanner

Bernard Horan · olyagpl · commit 2bfaf5503d59 · 2024-06-26T15:32:02.000+03:00
diff --git a/docs/reference-manual/native-image/guides/specify-class-initialization.md b/docs/reference-manual/native-image/guides/specify-class-initialization.md
@@ -1,14 +1,14 @@
 ---
 layout: ni-docs
 toc_group: how-to-guides
-link_title: Specify Class Initialization
+link_title: Specify Class Initialization Explicitly
 permalink: /reference-manual/native-image/guides/specify-class-initialization/
 ---
 
 # Specify Class Initialization Explicitly
 
 By default, Native Image initializes application classes at runtime, except for the classes that Native Image proves "safe" for initialization at build time. 
-However, you can influence the default behavior by specifying the classes to be build-time or run-time initialized explicitly.
+However, you can influence the default behavior by explicitly specifying the classes to be initialized at build-time or runtime.
 For that, there are two command-line options: `--initialize-at-build-time` and `--initialize-at-run-time`.
 You can use these options to specify whole packages or individual classes.
 For example, if you have the classes `p.C1`, `p.C2`, … ,`p.Cn`, you can specify that all the classes in the package `p` are to be initialized at build time by passing the following option to `native-image`:
@@ -20,100 +20,62 @@ If you want only class `C1` in package `p` to be initialized at runtime, use:
 --initialize-at-run-time=p.C1
 ```
 
-You can also programmatically specify Class initialization using the [`RuntimeClassInitialization` class](https://github.com/oracle/graal/blob/master/sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/hosted/RuntimeClassInitialization.java) from the [Native Image Feature interface](https://github.com/oracle/graal/blob/master/sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/hosted/Feature.java).
+You can also programmatically specify class initialization using the [`RuntimeClassInitialization`] class (https://github.com/oracle/graal/blob/master/sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/hosted/RuntimeClassInitialization.java) from the [Native Image Feature interface](https://github.com/oracle/graal/blob/master/sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/hosted/Feature.java).
 
 This guide demonstrates how to build a native executable by running the class initializer at runtime (default behavior), and then at build time, and compares the two approaches. 
 
 ### Prerequisite 
 Make sure you have installed a GraalVM JDK.
 The easiest way to get started is with [SDKMAN!](https://sdkman.io/jdks#graal).
-For other installation options, visit the [Downloads section](https://www.graalvm.org/downloads/).
+For other installation options, visit the [Downloads](https://www.graalvm.org/downloads/) section.
 
 ## Run a Demo
 
-For the demo part, you will run a simple Java application that uses an XML parser to list some Java talks from 2023.
-The parser create records from the XML data and store them in a `List<Talk>` collection.
-This approach removes the dependency on the DOM API for storing and manipulating the parsed data.
+For the demo, run a simple Java application that parses some Java talks from 2023.
+The parser creates records and adds them to a `List<Talk>` collection.
 
-1. Save the following Java source code in a file named _XMLParser.java_:
+1. Save the following Java source code in a file named _TalkParser.java_:
     ```java
-    import java.io.IOException;
-    import java.io.StringReader;
     import java.util.ArrayList;
     import java.util.List;
-
-    import javax.xml.parsers.DocumentBuilder;
-    import javax.xml.parsers.DocumentBuilderFactory;
-    import javax.xml.parsers.ParserConfigurationException;
-
-    import org.w3c.dom.Document;
-    import org.w3c.dom.NamedNodeMap;
-    import org.w3c.dom.NodeList;
-    import org.xml.sax.InputSource;
-    import org.xml.sax.SAXException;
-
-    public class XMLParser {
-
-        private static final List<Talk> talks = parseXML("""
-                        <?xml version="1.0" encoding="UTF-8"?>
-                        <talks>
-                            <talk name="Asynchronous Programming in Java: Options to Choose from by Venkat Subramaniam"></talk>
-                            <talk name="Anatomy of a Spring Boot App with Clean Architecture by Steve Pember"></talk>
-                            <talk name="Java in the Cloud with GraalVM by Alina Yurenko"></talk>
-                            <talk name="Bootiful Spring Boot 3 by Josh Long"></talk>
-                        </talks>
-                        """);
-
-        private static List<Talk> parseXML(String xmlContents) {
-            List<Talk> talkList = new ArrayList<>();
-            try {
-                DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
-                DocumentBuilder builder = factory.newDocumentBuilder();
-                Document document = builder.parse(new InputSource(new StringReader(xmlContents)));
-
-                NodeList nodeList = document.getElementsByTagName("talk");
-                for (int i = 0; i < nodeList.getLength(); i++) {
-                    NamedNodeMap attributes = nodeList.item(i).getAttributes();
-                    String name = attributes.getNamedItem("name").getTextContent();
-                    talkList.add(new Talk(name));
-                }
-            } catch (ParserConfigurationException | IOException | SAXException e) {
-                throw new RuntimeException(e);
-            }
-            return talkList;
+    import java.util.Scanner;
+
+    public class TalkParser {
+      private static final List<Talk> TALKS = new ArrayList<>();
+      static {
+        Scanner s = new Scanner("""
+            Asynchronous Programming in Java: Options to Choose from by Venkat Subramaniam
+            Anatomy of a Spring Boot App with Clean Architecture by Steve Pember
+            Java in the Cloud with GraalVM by Alina Yurenko
+            Bootiful Spring Boot 3 by Josh Long
+            """);
+        while (s.hasNextLine()) {
+          TALKS.add(new Talk(s.nextLine()));
         }
+        s.close();
+      }
 
-        public static void main(String[] args) {
-            System.out.println("Talks loaded via XML:");
-            for (Talk talk : talks) {
-                System.out.println("- " + talk.getName());
-            }
+      public static void main(String[] args) {
+        System.out.println("Talks loaded using scanner:");
+        for (Talk talk : TALKS) {
+            System.out.println("- " + talk.name());
         }
+      }
     }
 
-    class Talk {
-        private final String name;
-
-        public Talk(String name) {
-            this.name = name;
-        }
-
-        public String getName() {
-            return name;
-        }
-    }
+    record Talk (String name) {}
     ```
 
 2. Compile the application:
     ```bash
-    javac XMLParser.java
+    javac TalkParser.java
     ```
   
 3. Build a native executable, explicitly running the class initializer at runtime:
     ```bash
-    native-image --initialize-at-run-time=XMLParser,Talk -o runtime-parser XMLParser
+    native-image --initialize-at-run-time=TalkParser,Talk -o runtime-parser TalkParser
     ```
-    You can leave out the `--initialize-at-run-time=XMLParser,Talk` option in this example because these classes are marked for initialization at run time by default.
+    You can omit the `--initialize-at-run-time=TalkParser,Talk` option in this example because these classes are marked for initialization at run time by default.
     The `-o` option specifies the name of the output file.
 
 4. Run and `time` the native application:
@@ -122,56 +84,54 @@ This approach removes the dependency on the DOM API for storing and manipulating
     ```
     On a machine with 16 GB of memory and 8 cores, you should see a result similar to:
     ```
-    Talks loaded via XML:
+    Talks loaded using scanner:
     - Asynchronous Programming in Java: Options to Choose from by Venkat Subramaniam
     - Anatomy of a Spring Boot App with Clean Architecture by Steve Pember
     - Java in the Cloud with GraalVM by Alina Yurenko
     - Bootiful Spring Boot 3 by Josh Long
     ./runtime-parser  0.00s user 0.00s system 52% cpu 0.010 total
     ```
-    The application parses the XML data at runtime.
+    The application parses the text block at runtime.
 
-    Check the file size which should be around 19M:
+    Check the file size which should be around 13M:
     ```
     du -sh runtime-parser
     ```
 
-5.  Next, build a native executable initializing `XMLParser` at build time, and providing a different name for the output file to differentiate it from the previous build. The `Talk` class has to be initialized explicitly too, so the objects of this type will be persisted in the image heap.
+5.  Next, build a native executable initializing `TalkParser` at build time, and providing a different name for the output file to differentiate it from the previous build. The `Talk` record has to be initialized explicitly too, so the objects of this type will be persisted in the executable heap.
     ```bash
-    native-image --initialize-at-build-time=XMLParser,Talk -o buildtime-parser XMLParser
+    native-image --initialize-at-build-time=TalkParser,Talk -o buildtime-parser TalkParser
     ```
 
-    If your application adds additional types to the image heap, each type (or the corresponding package) needs to be marked for build-time initialization explicitly to fullfil the requirements of `--strict-image-heap`. 
+    If your application adds additional types to the executable heap, each type (or the corresponding package) needs to be marked for build-time initialization explicitly to fulfill the requirements of `--strict-image-heap`. 
     An appropriate actionable error message will guide you through the process.
 
-    Note that in this example, the static analysis optimizes `org.w3c.dom.Document` away.
-
 6. Run and `time` the second executable for comparison:
     ```bash
     time ./buildtime-parser
     ```
     This time you should see something similar to this:
     ```
-    Talks loaded via XML:
+    Talks loaded using scanner:
     - Asynchronous Programming in Java: Options to Choose from by Venkat Subramaniam
     - Anatomy of a Spring Boot App with Clean Architecture by Steve Pember
     - Java in the Cloud with GraalVM by Alina Yurenko
     - Bootiful Spring Boot 3 by Josh Long
     ./buildtime-parser  0.00s user 0.00s system 53% cpu 0.016 total
     ```
-    Check the file size which should decrease to around 5.9M!
+    Check the file size which should decrease to around 6.4M!
     ```
     du -sh buildtime-parser
     ```
-    The file size change is because Native Image runs the static initializer at build time, parsing the XML data, and persisting only the `Talks` objects in the executable.
-    As a result, the majority of the XML parsing infrastructure does not become reachable when Native Image statically analyzes the application and is, therefore, not included in the executable.
+    The file size change is because Native Image runs the static initializer at build time, parsing the text block, and persisting only the `Talk` records in the executable.
+    As a result, the majority of the scanning infrastructure does not become reachable when Native Image statically analyzes the application and is, therefore, not included in the executable.
 
 Another valuable criterion for profiling applications more accurately is the number of instructions, which can be obtained using the [Linux `perf` profiler](../PerfProfiling.md).
 
 For example, for this demo application, the number of instructions decreased by almost 30% (from 11.8M to 8.6M) in the case of build-time class initialization:
 ```bash
 perf stat ./runtime-parser 
-Talks loaded via XML:
+Talks loaded using scanner:
 - Asynchronous Programming in Java: Options to Choose from by Venkat Subramaniam
 (...)
  Performance counter stats for './runtime-parser':
@@ -187,7 +147,7 @@ Talks loaded via XML:
 ```
 ```bash
 perf stat ./buildtime-parser 
-Talks loaded via XML:
+Talks loaded using scanner:
 - Asynchronous Programming in Java: Options to Choose from by Venkat Subramaniam
 (...)
  Performance counter stats for './buildtime-parser':
@@ -202,15 +162,15 @@ Talks loaded via XML:
        0.002226000 seconds sys 
 ```
 
-This demonstrates how Native Image can shift work from runtime to build time: when the class is initialized at build time, the XML data is parsed when the executable is being built and only the parsed objects are included.
-This not only makes the executable smaller in file size, but also faster to run: when the executable runs, the `Talk` objects already exists and only need to be printed.
+This demonstrates how Native Image can shift work from runtime to build time: when the class is initialized at build time, the text block is parsed when the executable is being built and only the parsed objects are included.
+This not only makes the executable smaller in file size, but also faster to run: when the executable runs, the `Talk` records already exist and only need to be printed.
 
 To ensure native executables built with Native Image are as compatible as possible with the HotSpot behavior, application classes that cannot be safely initialized at build time, are initialized at runtime.
 You as a user, or a framework that you use, must explicitly request build-time initialization for certain classes to benefit from smaller file sizes and faster times to run.
 Include the right data structures to avoid the image size blowing up instead.
-We also recommend to use `--initialize-at-build-time` with single classes only. 
+We also recommend using `--initialize-at-build-time` with single classes only. 
 It may be that you need to add a lot of `--initialize-at-build-time` entries. 
-Note that incorrect build-time initialization can lead from dysfunctional behavior to including sensitive data such as passwords or encryption keys, problems that are to be avoided in production settings.
+Note that incorrect build-time initialization can lead to problems that are to be avoided in production settings such as dysfunctional behavior or including sensitive data such as passwords or encryption keys.
 
 ### Conclusion
 
