| <?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> |