1+ <?xml version =" 1.0"
2+ <!--
3+
4+ Copyright (c) 2021 Oracle and/or its affiliates. All rights reserved.
5+
6+ This program and the accompanying materials are made available under the
7+ terms of the Eclipse Public License v. 2.0, which is available at
8+ http://www.eclipse.org/legal/epl-2.0.
9+
10+ This Source Code may also be made available under the following Secondary
11+ Licenses when the conditions for such availability set forth in the
12+ Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
13+ version 2 with the GNU Classpath Exception, which is available at
14+ https://www.gnu.org/software/classpath/license.html.
15+
16+ SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
17+
18+ -->
19+
20+ <!DOCTYPE chapter [<!ENTITY % ents SYSTEM " jersey.ent" %ents; ]>
21+ <chapter xmlns =" http://docbook.org/ns/docbook"
22+ version =" 5.0"
23+ xml : lang =" en"
24+ xmlns : xsi =" http://www.w3.org/2001/XMLSchema-instance"
25+ xmlns : xi =" http://www.w3.org/2001/XInclude"
26+ xmlns : xlink =" http://www.w3.org/1999/xlink"
27+ xsi : schemaLocation =" http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd
28+ http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd"
29+ xml : id =" graalvm-native-image"
30+ <title >GraalVM native-image generation</title >
31+ <para >
32+ This chapter describes Jersey's compatibility with GraalVM native image. This functionality is available since
33+ Jersey 2.35 and is under development and configuration. For now Jersey provides native image configuration
34+ basics for some modules and example on how to really generate native image for an existing application.
35+ </para >
36+ <section xml : id =" supported_modules"
37+ <title >Modules with GraalVM native image support</title >
38+ <para >
39+ Currently Jersey provides basic support for native image generation within following modules:
40+ <literal >jersey-common</literal >,<literal >jersey-server</literal >,<literal >jersey-client</literal >,
41+ <literal >jersey-hk2</literal >.
42+
43+ This support means that most of reflection and resource related settings are extracted into reflect-config
44+ and resource-config JSON files to be used while generating a native image. Those files are included in
45+ the native image generation process automatically (unless some tricky configuration is applied), so there is
46+ no need to include those files manually and/or duplicate their contents in some custom configuration.
47+ </para >
48+ </section >
49+ <section xml : id =" native-image"
50+ <title >HelloWorld native image generation</title >
51+ <para >
52+ The example for the GraalVM native image generation is hidden under examples/helloworld example.
53+ To generate native image there it's required to perform some preliminary steps:
54+ <simplelist >
55+ <member >Download GraalVM at least 20.3.2 version</member >
56+ <member >Set JAVA_HOME to point to that [GraalVM_HOME]</member >
57+ <member >Perform <markup >$JAVA_HOME/bin/gu install native-image</markup > because native-image tool is not bundled within GraalVM itself</member >
58+ <member >Download Jersey examples source codes (preferable some released version like 2.35),
59+ and go to [path_to_jersey_examples]/examples/helloworld</member >
60+ <member >Run <markup >mvn -Pnative-image clean package -DskipTests</markup ></member >
61+ </simplelist >
62+ </para >
63+ <para >
64+ If all was correctly performed from previous steps the native image shall be already generated inside the targed folder
65+ of the helloworld example with the name helloworld-native and it's possible to run it by
66+ <programlisting language =" bash" programlisting >
67+ After it's run, console should print our following output:
68+ <screen linenumbering =" unnumbered"
69+ "Hello World" Jersey Example App
70+ May 27, 2021 1:37:49 PM org.glassfish.jersey.server.wadl.WadlFeature configure
71+ WARNING: JAX-B API not found . WADL feature is disabled.
72+ May 27, 2021 1:37:49 PM org.glassfish.grizzly.http.server.NetworkListener start
73+ INFO: Started listener bound to [localhost:8080]
74+ May 27, 2021 1:37:49 PM org.glassfish.grizzly.http.server.HttpServer start
75+ INFO: [HttpServer] Started.
76+ Application started.
77+ Try out http://localhost:8080/base/helloworld
78+ Stop the application using CTRL+C
79+ </screen >
80+ If you see this, you can open given link in browser and check how application actually works.
81+ In general we are done here and you can use that example to generate native images for your own projects.
82+ </para >
83+ </section >
84+ <section xml : id =" undercover"
85+ <title >What's under the cover</title >
86+ <para >
87+ For the example above the following command line was used:
88+ <programlisting language =" bash"
89+ -H:EnableURLProtocols=http,https
90+ --initialize-at-build-time=org.glassfish.jersey.client.internal.HttpUrlConnector
91+ -H:+ReportExceptionStackTraces
92+ --verbose
93+ --no-fallback
94+ --report-unsupported-elements-at-runtime
95+ </programlisting >
96+ This might be useful to generate another native image. It's possible to add another bunch of parameters to the command line
97+ (and put those into the <literal >native-image.properties</literal > file inside of your project). Important parameter here is
98+ --initialize-at-build-time (opposite to --initialize-at-run-time) and --no-fallback which says to the native
99+ image to generate pure native image with everything bundled inside the image and not just fall back wrapper for JDK.
100+ </para >
101+ <para >
102+ Another important aspect for generating the native image is the proper listing of reflection classes (classes that use reflection
103+ in an application). For those needs, there is a native image agent which helps to generate those lists automatically.
104+ In order to generate a list of reflection classes (and JNI classes and resources), it is required to run:
105+ <programlisting language =" bash" programlisting >
106+ And afterwords, the [output_location] directory will be created with generated lists (in JSON format). Those files can be
107+ included as is into native image generation, but it's very preferable to edit them manually to reduce possible ambiguous classes listings.
108+ </para >
109+ </section >
110+ </chapter >
0 commit comments