Merge pull request #3 from wkorando/main

Adding instructions for using jlink for Youtube video

Author: wkorando

intro-to-jlink/LICENSE.txt

@@ -0,0 +1,35 @@
+Copyright (c) 2023 Oracle and/or its affiliates.
+
+The Universal Permissive License (UPL), Version 1.0
+
+Subject to the condition set forth below, permission is hereby granted to any
+person obtaining a copy of this software, associated documentation and/or data
+(collectively the "Software"), free of charge and under any and all copyright
+rights in the Software, and any and all patent rights owned or freely
+licensable by each licensor hereunder covering either (i) the unmodified
+Software as contributed to or provided by such licensor, or (ii) the Larger
+Works (as defined below), to deal in both
+
+(a) the Software, and
+(b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+one is included with the Software (each a "Larger Work" to which the Software
+is contributed by such licensors),
+
+without restriction, including without limitation the rights to copy, create
+derivative works of, display, perform, and distribute the Software and make,
+use, sell, offer for sale, import, export, have made, and have sold the
+Software and the Larger Work(s), and to sublicense the foregoing rights on
+either these or other terms.
+
+This license is subject to the following condition:
+The above copyright notice and either this complete permission notice or at
+a minimum a reference to the UPL must be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

intro-to-jlink/README.md

@@ -0,0 +1,26 @@
+# Intro to JLink
+
+This repo provides an introduction to using some of the key functionality of `jlink` to create custom runtime images for running a Java application.
+
+Be sure to check out the YouTube video for additional details: https://youtu.be/mJKlxqQQeyI
+
+The repo is divided into five distinct parts;  
+
+## Step 1 Hello World with JLink
+We start by using the most basic functionality jlink, by creating a runtime image for a "Hello World!" program. [Link](step-1-hello-world-with-jlink)
+
+## Step 2 Using JDeps
+Step 2 covers how to use JDeps to find the dependent modules for an application, and build a runtime image with those modules. [Link](step-2-using-jdeps)
+
+## Step 3 Adding Non-JDK Modules to an Image
+In this step we look at how to add non-JDK modules, in this `org.apache.commons.lang3` to a runtime image. [Link](step-3-adding-non-jdk-modules)
+
+## Step 4 Adding Explicit Modules to an Image
+During this step we walk-through the process of creating our own explicit module and adding it to a runtime image. [Link](step-4-adding-explicit-modules) 
+
+## Step 5 Creating a Launcher
+We create a launcher for our runtime image, which can be used to streamline the process of running an application. [Link](step-5-creating-a-launcher)
+
+## Step 6 Additional Customization Options
+We look at a couple of the customization options; generating a CDS archive, and compressing the runtime image, `jlink` provides. [Link](step-6-additional-customization)
+

intro-to-jlink/step-1-hello-world-with-jlink/README.md

@@ -0,0 +1,47 @@
+# Hello World with JLink
+
+In this exercise we will create a simple custom runtime image with JLink that cna be used to run a Hello World program.
+
+## The Program
+
+The program is a standard "Hello World!", it is located in the `foo` package. 
+
+```java
+package foo;
+
+public class HelloWorld{
+        public static void main(String[] args){
+                System.out.println("Hello JLink!");
+        }
+}
+```
+
+## Creating a Runtime Image with JLink
+
+To create a runtime image with jlink that can run `HelloWorld` we will run the following command:
+
+```
+$ jlink --add-modules java.base --output hello-jlink-image
+```
+
+In the above command:
+
+*  `--add-modules`: defines the modules to be added to the image. `java.base` all the classes needed to execute `HelloWorld`
+
+* `--output`: is the name of the resulting image produced by `jlink`. This can be arbitrary, but should be descriptive. 
+
+## Running an Application with a JLink Image
+
+Running an application with a jlink image would be no different than with the JDK, just reference the `java` command located in the bin directory.
+
+```
+$ ./hello-jlink-image/bin/java foo.HelloWorld
+```
+
+Which should return:
+
+```
+Hello JLink!
+```
+
+[In the next exercise](../step-2-using-jdeps) we will look at using JDeps to find out which modules to include in an image.

intro-to-jlink/step-1-hello-world-with-jlink/foo/HelloWorld.class

@@ -0,0 +1,7 @@
+package foo;
+
+public class HelloWorld{
+	public static void main(String[] args){
+		System.out.println("Hello JLink!");
+	}
+}

intro-to-jlink/step-1-hello-world-with-jlink/foo/HelloWorld.java

@@ -0,0 +1,84 @@
+# Using JDeps
+
+In this exercise, we will using the `jdeps` tool to resolve the modules we need to include in a runtime.
+
+## The Program
+
+This program is designed to call a url endpoint and print to the JDK logger the response it receives. 
+
+```java
+package foo;
+
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.net.http.HttpResponse.BodyHandlers;
+import java.time.Duration;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
+public class GetWebsite {
+
+  private static final Logger LOGGER = Logger.getLogger(GetWebsite.class.getName());
+  public static void main(String... args) throws InterruptedException {
+    String url = args[0];
+    try (HttpClient client = HttpClient.newHttpClient();) {
+      LOGGER.log(Level.INFO, "Calling: " + url);
+      HttpRequest request = HttpRequest.newBuilder(URI.create(url)).GET().build();
+      client.sendAsync(request, BodyHandlers.ofString())
+        .thenApply(HttpResponse::body).thenAccept(r -> LOGGER.log(Level.INFO, r));
+      client.awaitTermination(Duration.ofMillis(1000L));
+    }
+  }
+}
+```
+
+## Resolving Module Dependencies with JDeps	
+Attempting to run `GetWebsite` with the runtime we created in the previous exercise will fail, throwing `ClassNotFound` exceptions. This is because some of the classes referenced in `GetWebsite` are located outside the `java.base` module. 
+
+The `jdeps` tool can be used to find which modules `GetWebsite` depends upon, which can be done with:
+
+```
+$jdeps GetWebsite.class
+```
+
+Which will return this table:
+
+```
+jdeps GetWebsite.class
+GetWebsite.class -> java.base
+GetWebsite.class -> java.logging
+GetWebsite.class -> java.net.http
+   foo                                                -> java.lang                                          java.base
+   foo                                                -> java.lang.invoke                                   java.base
+   foo                                                -> java.net                                           java.base
+   foo                                                -> java.net.http                                      java.net.http
+   foo                                                -> java.time                                          java.base
+   foo                                                -> java.util.concurrent                               java.base
+   foo                                                -> java.util.function                                 java.base
+   foo                                                -> java.util.logging                                  java.logging
+```
+
+The top of the table describes the modules the class depends on, the bottom portion shows how those values were calculated. 
+
+JDeps can also be configured to provide a more user friendly output with the option `--print-module-deps` which will return a comma-separated list of the modules:
+
+```
+$ jdeps --print-module-deps GetWebsite.class
+java.base,java.logging,java.net.http
+```
+
+This can then be copied into jlink to build runtime that can run `GetWebsite` like in this command:
+
+```
+$ jlink --add-modules java.base,java.logging,java.net.http --output get-website-image
+```
+
+This runtime can be used to successfully execute `GetWebsite`
+
+```
+$ ./get-website-image/bin/java GetWebsite http://localhost:8000
+```
+
+[In the next exercise](../step-3-adding-non-jdk-modules) we will look at how to add non-JDK modules to a runtime image created with JLink. 

intro-to-jlink/step-2-using-jdeps/README.md

@@ -0,0 +1,25 @@
+package foo;
+
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.net.http.HttpResponse.BodyHandlers;
+import java.time.Duration;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
+public class GetWebsite {
+
+  private static final Logger LOGGER = Logger.getLogger(GetWebsite.class.getName());
+  public static void main(String... args) throws InterruptedException {
+    String url = args[0];
+    try (HttpClient client = HttpClient.newHttpClient();) {
+      LOGGER.log(Level.INFO, "Calling: " + url);
+      HttpRequest request = HttpRequest.newBuilder(URI.create(url)).GET().build();
+      client.sendAsync(request, BodyHandlers.ofString())
+	.thenApply(HttpResponse::body).thenAccept(r -> LOGGER.log(Level.INFO, r));
+      client.awaitTermination(Duration.ofMillis(1000L));
+    }
+  }
+}

intro-to-jlink/step-2-using-jdeps/foo/GetWebsite.class

@@ -0,0 +1,58 @@
+# Adding Non-JDK Modules to a Runtime
+In this excerise we will walk through steps of adding a Non-JDK module to a runtime image built with JLink.
+
+## The Program
+
+This is a simple program that's using the `StringUtils.reverse()` located in the [apache commons lang3 library](https://mvnrepository.com/artifact/org.apache.commons/commons-lang3) to reverse a user-provided value. 
+
+💡 **Note:** You will need to download the library from maven central and place it in the `/libs` directory to complete this exercise.
+
+```java
+package foo;
+
+import org.apache.commons.lang3.StringUtils;
+
+public class ReverseString{
+        public static void main(String... args){
+                String reversedString = StringUtils.reverse(args[0]);
+                System.out.println(reversedString);
+        }
+}
+```
+
+## Using JDeps to Resolve external JDK Modules 
+
+While we already know that we need to bring in the `org.apache.commons.lang3` module, understanding how to look up this information is important. 
+
+Using `jdeps` we will need to use the `--module-path` option, and pass it the location of where the `apache-commons-lang3.jar` is located, which sould be the `libs` directory.
+
+```
+$ jdeps --module-path libs --multi-release 21  foo/ReverseString.class
+```
+
+This will return a table, like in the previous excerise.
+
+```
+ReverseString.class -> java.base
+ReverseString.class -> org.apache.commons.lang3
+   foo                                                -> java.io                                            java.base
+   foo                                                -> java.lang                                          java.base
+   foo                                                -> org.apache.commons.lang3                           org.apache.commons.lang3
+```
+
+## Building a Runtime with a Non-JDK Module
+
+Building a runtime with a Non-JDK module is similar to building a runtime like we have done in the previous exercise, we just need to include the path to where the additional modules are located, in this case `libs` like we did in the previous step using `jdeps`:
+
+```
+$ jlink --module-path libs --add-modules java.base,org.apache.commons.lang3 --output reverse-string-image
+```
+
+We can use this runtime, like in the previous exercises to run the `ReserveString` program:
+
+```
+$ ./reverse-string-image/bin/java foo.ReverseString Java
+avaJ
+```
+
+[In the next exercise](../step-4-adding-explicit-modules) we will walk through the steps of creating our own module and adding it to a runtime image.

intro-to-jlink/step-2-using-jdeps/foo/GetWebsite.java

@@ -0,0 +1,10 @@
+package foo;
+
+import org.apache.commons.lang3.StringUtils;
+
+public class ReverseString{
+	public static void main(String... args){
+		String reversedString = StringUtils.reverse(args[0]);
+		System.out.println(reversedString);
+	}
+}

intro-to-jlink/step-3-adding-non-jdk-modules/README.md

@@ -0,0 +1,34 @@
+# Creating and Adding a Module to a Runtime
+Adding modules to a runtime image isn't restricted to JDK or other pre-existing modules, we can create our own! We will walk through those steps in this exercise.
+
+## Creating a Module
+To create a module we will need to provide a `module-info.java`. `module-info.java` is a special type of Java file used for defining a module. In this file we will provide a name, and the modules our module depends on.
+
+```java
+module foo {
+        requires org.apache.commons.lang3;
+}
+```
+
+💡 **Note:** `java.base` is implicitly required by allow modules, so does not need to be defined. 
+
+Next we can create a module, using the `jmod` tool with this command:
+
+```
+$ jmod create --class-path .  mods/foo.jmod
+```
+
+After a few moments the module will be created, we can add it to a runtime image, just like we did in the previous exercise, just make sure to update `--module-path` to include `mods`. 
+
+```
+$ jlink --module-path libs:mods --add-modules java.base,org.apache.commons.lang3,foo --output reverse-string-image 
+```
+
+We can run the program like we did in the previous exercise:
+
+```
+$ ./reverse-string-image/bin/java foo.ReverseString Java
+avaJ
+```
+
+[In the next exercise](../step-5-creating-a-launcher) we will use JLink to create a launcher to streamline the process of running an application packaged a jlink artifact.  

intro-to-jlink/step-3-adding-non-jdk-modules/foo/ReverseString.class

@@ -0,0 +1,10 @@
+package foo;
+
+import org.apache.commons.lang3.StringUtils;
+
+public class ReverseString{
+	public static void main(String... args){
+		String reversedString = StringUtils.reverse(args[0]);
+		System.out.println(reversedString);
+	}
+}

intro-to-jlink/step-3-adding-non-jdk-modules/foo/ReverseString.java

@@ -0,0 +1,4 @@
+module foo {
+	requires org.apache.commons.lang3;
+}
+

intro-to-jlink/step-4-adding-explicit-modules/README.md

@@ -0,0 +1,19 @@
+# Creating a Launcher with JLink
+For Java developers distributing an artifact to clients, streamlining the process of starting a running the application has many benefits. JLink provides the ability to include a launcher which can provide a mapping to the main class with a JLink image. 
+
+## Adding a Launcher to a JLink Image
+
+The process of adding a launcher is simple. Just include the `--launcher` option and provide a name, and the module and fully qualified class-path to the main class like in this command:
+
+```
+$ jlink --add-modules java.base,foo,org.apache.commons.lang3 --module-path mods:libs --launcher app=foo/foo.ReverseString --output reverse-string-image
+```
+
+With the launcher added, we can simply reference the launcher `app` instead of main class:
+
+```
+$ ./reverse-string-image/bin/app Java
+avaJ
+```
+
+[In the next exercise](../step-6-additional-customization) we will look at a couple of options JLink provides for customizing a runtime.

intro-to-jlink/step-4-adding-explicit-modules/foo/ReverseString.class

@@ -0,0 +1,10 @@
+package foo;
+
+import org.apache.commons.lang3.StringUtils;
+
+public class ReverseString{
+	public static void main(String... args){
+		String reversedString = StringUtils.reverse(args[0]);
+		System.out.println(reversedString);
+	}
+}

intro-to-jlink/step-4-adding-explicit-modules/foo/ReverseString.java

@@ -0,0 +1,4 @@
+module foo {
+	requires org.apache.commons.lang3;
+}
+