User Guide: GraalVM/native-image chapter (#4802) * User Guide: GraalVM/native-image chapter Signed-off-by: Maxim Nesen <maxim.nesen@oracle.com>
diff --git a/docs/src/main/docbook/client.xml b/docs/src/main/docbook/client.xml index ffa4bde..4202fa7 100644 --- a/docs/src/main/docbook/client.xml +++ b/docs/src/main/docbook/client.xml
@@ -848,7 +848,7 @@ </example> <para> For more information see javadoc of &jersey.client.InjectionManagerClientProvider; - (and javadoc of &jersey.common.InjectionManagerProvider; which supports common JAX-RS components). + (and javadoc of &lit.jersey.common.InjectionManagerProvider; which supports common JAX-RS components). </para> </section>
diff --git a/docs/src/main/docbook/getting-started.xml b/docs/src/main/docbook/getting-started.xml index 8d4e1be..3680d60 100644 --- a/docs/src/main/docbook/getting-started.xml +++ b/docs/src/main/docbook/getting-started.xml
@@ -568,7 +568,7 @@ T E S T S ------------------------------------------------------- Running com.example.MyResourceTest - Jan 29, 2021 9:13:20 AM org.glassfish.jersey.test.grizzly.GrizzlyTestContainerFactory$GrizzlyTestContainer <init> + Jan 29, 2021 9:13:20 AM org.glassfish.jersey.test.grizzly.GrizzlyTestContainerFactory$GrizzlyTestContainer INFO: Creating GrizzlyTestContainer configured at the base URI http://localhost:9998/ Jan 29, 2021 9:13:20 AM org.glassfish.jersey.server.wadl.WadlFeature configure WARNING: JAXBContext implementation could not be found. WADL feature is disabled.
diff --git a/docs/src/main/docbook/graalvm-native-image.xml b/docs/src/main/docbook/graalvm-native-image.xml new file mode 100644 index 0000000..c64bbc3 --- /dev/null +++ b/docs/src/main/docbook/graalvm-native-image.xml
@@ -0,0 +1,110 @@ +<?xml version="1.0"?> +<!-- + + Copyright (c) 2021 Oracle and/or its affiliates. All rights reserved. + + This program and the accompanying materials are made available under the + terms of the Eclipse Public License v. 2.0, which is available at + http://www.eclipse.org/legal/epl-2.0. + + This Source Code may also be made available under the following Secondary + Licenses when the conditions for such availability set forth in the + Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + version 2 with the GNU Classpath Exception, which is available at + https://www.gnu.org/software/classpath/license.html. + + SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + +--> + +<!DOCTYPE chapter [<!ENTITY % ents SYSTEM "jersey.ent" > %ents; ]> +<chapter xmlns="http://docbook.org/ns/docbook" + version="5.0" + xml:lang="en" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:xi="http://www.w3.org/2001/XInclude" + xmlns:xlink="http://www.w3.org/1999/xlink" + xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd + http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd" + xml:id="graalvm-native-image"> + <title>GraalVM native-image generation</title> + <para> + This chapter describes Jersey's compatibility with GraalVM native image. This functionality is available since + Jersey 2.35 and is under development and configuration. For now Jersey provides native image configuration + basics for some modules and example on how to really generate native image for an existing application. + </para> + <section xml:id="supported_modules"> + <title>Modules with GraalVM native image support</title> + <para> + Currently Jersey provides basic support for native image generation within following modules: + <literal>jersey-common</literal>,<literal>jersey-server</literal>,<literal>jersey-client</literal>, + <literal>jersey-hk2</literal>. + + This support means that most of reflection and resource related settings are extracted into reflect-config + and resource-config JSON files to be used while generating a native image. Those files are included in + the native image generation process automatically (unless some tricky configuration is applied), so there is + no need to include those files manually and/or duplicate their contents in some custom configuration. + </para> + </section> + <section xml:id="native-image"> + <title>HelloWorld native image generation</title> + <para> + The example for the GraalVM native image generation is hidden under examples/helloworld example. + To generate native image there it's required to perform some preliminary steps: + <simplelist> + <member>Download GraalVM at least 20.3.2 version</member> + <member>Set JAVA_HOME to point to that [GraalVM_HOME]</member> + <member>Perform <markup>$JAVA_HOME/bin/gu install native-image</markup> because native-image tool is not bundled within GraalVM itself</member> + <member>Download Jersey examples source codes (preferable some released version like 2.35), + and go to [path_to_jersey_examples]/examples/helloworld</member> + <member>Run <markup>mvn -Pnative-image clean package -DskipTests</markup></member> + </simplelist> + </para> + <para> + If all was correctly performed from previous steps the native image shall be already generated inside the targed folder + of the helloworld example with the name helloworld-native and it's possible to run it by + <programlisting language="bash">target/./helloworld-native</programlisting> + After it's run, console should print our following output: + <screen linenumbering="unnumbered"> + "Hello World" Jersey Example App + May 27, 2021 1:37:49 PM org.glassfish.jersey.server.wadl.WadlFeature configure + WARNING: JAX-B API not found . WADL feature is disabled. + May 27, 2021 1:37:49 PM org.glassfish.grizzly.http.server.NetworkListener start + INFO: Started listener bound to [localhost:8080] + May 27, 2021 1:37:49 PM org.glassfish.grizzly.http.server.HttpServer start + INFO: [HttpServer] Started. + Application started. + Try out http://localhost:8080/base/helloworld + Stop the application using CTRL+C + </screen> + If you see this, you can open given link in browser and check how application actually works. + In general we are done here and you can use that example to generate native images for your own projects. + </para> + </section> + <section xml:id="undercover"> + <title>What's under the cover</title> + <para> + For the example above the following command line was used: + <programlisting language="bash"> + -H:EnableURLProtocols=http,https + --initialize-at-build-time=org.glassfish.jersey.client.internal.HttpUrlConnector + -H:+ReportExceptionStackTraces + --verbose + --no-fallback + --report-unsupported-elements-at-runtime + </programlisting> + This might be useful to generate another native image. It's possible to add another bunch of parameters to the command line + (and put those into the <literal>native-image.properties</literal> file inside of your project). Important parameter here is + --initialize-at-build-time (opposite to --initialize-at-run-time) and --no-fallback which says to the native + image to generate pure native image with everything bundled inside the image and not just fall back wrapper for JDK. + </para> + <para> + Another important aspect for generating the native image is the proper listing of reflection classes (classes that use reflection + in an application). For those needs, there is a native image agent which helps to generate those lists automatically. + In order to generate a list of reflection classes (and JNI classes and resources), it is required to run: + <programlisting language="bash">$JAVA_HOME/bin/java -agentlib:native-image-agent=config-output-dir=[output_location] -jar [app_name].jar</programlisting> + And afterwords, the [output_location] directory will be created with generated lists (in JSON format). Those files can be + included as is into native image generation, but it's very preferable to edit them manually to reduce possible ambiguous classes listings. + </para> + </section> +</chapter> \ No newline at end of file
diff --git a/docs/src/main/docbook/user-guide.xml b/docs/src/main/docbook/user-guide.xml index bddbfac..799478d 100644 --- a/docs/src/main/docbook/user-guide.xml +++ b/docs/src/main/docbook/user-guide.xml
@@ -1,7 +1,7 @@ <?xml version="1.0"?> <!-- - Copyright (c) 2010, 2020 Oracle and/or its affiliates. All rights reserved. + Copyright (c) 2010, 2021 Oracle and/or its affiliates. All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v. 2.0, which is available at @@ -116,6 +116,7 @@ <xi:include href="custom-di.xml" /> <xi:include href="cdi.xml" /> <xi:include href="spring.xml" /> + <xi:include href="graalvm-native-image.xml" /> <xi:include href="test-framework.xml" /> <xi:include href="how-to-build.xml" /> <xi:include href="migration.xml" />