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" />
