Subversion Repositories Integrator Subversion

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
771 blopes 1 
<!DOCTYPE html SYSTEM "about:legacy-compat">
2 
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="./images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Apache Tomcat 9 (9.0.112) - Ahead of Time compilation support</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="./images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="./images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tomcat 9</h1><div class="versionInfo">
3 
            Version 9.0.112,
4 
            <time datetime="2025-11-06">Nov 6 2025</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="index.html">Docs Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li></ul></div><div><h2>User Guide</h2><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="host-manager-howto.html">6) Host Manager</a></li><li><a href="realm-howto.html">7) Realms and AAA</a></li><li><a href="security-manager-howto.html">8) Security Manager</a></li><li><a href="jndi-resources-howto.html">9) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">10) JDBC DataSources</a></li><li><a href="class-loader-howto.html">11) Classloading</a></li><li><a href="jasper-howto.html">12) JSPs</a></li><li><a href="ssl-howto.html">13) SSL/TLS</a></li><li><a href="ssi-howto.html">14) SSI</a></li><li><a href="cgi-howto.html">15) CGI</a></li><li><a href="proxy-howto.html">16) Proxy Support</a></li><li><a href="mbeans-descriptors-howto.html">17) MBeans Descriptors</a></li><li><a href="default-servlet.html">18) Default Servlet</a></li><li><a href="cluster-howto.html">19) Clustering</a></li><li><a href="balancer-howto.html">20) Load Balancer</a></li><li><a href="connectors.html">21) Connectors</a></li><li><a href="monitoring.html">22) Monitoring and Management</a></li><li><a href="logging.html">23) Logging</a></li><li><a href="apr.html">24) APR/Native</a></li><li><a href="virtual-hosting-howto.html">25) Virtual Hosting</a></li><li><a href="aio.html">26) Advanced IO</a></li><li><a href="maven-jars.html">27) Mavenized</a></li><li><a href="security-howto.html">28) Security Considerations</a></li><li><a href="windows-service-howto.html">29) Windows Service</a></li><li><a href="windows-auth-howto.html">30) Windows Authentication</a></li><li><a href="jdbc-pool.html">31) Tomcat's JDBC Pool</a></li><li><a href="web-socket-howto.html">32) WebSocket</a></li><li><a href="rewrite.html">33) Rewrite</a></li><li><a href="cdi.html">34) CDI 2 and JAX-RS</a></li><li><a href="graal.html">35) AOT/GraalVM Support</a></li></ul></div><div><h2>Reference</h2><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Tomcat Javadocs</a></li><li><a href="servletapi/index.html">Servlet 4.0 Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.3 Javadocs</a></li><li><a href="elapi/index.html">EL 3.0 Javadocs</a></li><li><a href="websocketapi/index.html">WebSocket 1.1 Javadocs</a></li><li><a href="jaspicapi/index.html">JASPIC 1.1 Javadocs</a></li><li><a href="annotationapi/index.html">Common Annotations 1.3 Javadocs</a></li><li><a href="https://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul></div><div><h2>Apache Tomcat Development</h2><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/Tomcat+Versions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="tribes/introduction.html">Tribes</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>Ahead of Time compilation support</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
5 
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Setup">Setup</a></li><li><a href="#Packaging_and_Building">Packaging and Building</a></li><li><a href="#Native_image_configuration">Native image configuration</a></li><li><a href="#Building_the_native_image">Building the native image</a></li><li><a href="#Compatibility">Compatibility</a></li></ul>
6 
</div><h3 id="Introduction">Introduction</h3><div class="text">
7 
 
8 
  <p>
9 
    Tomcat supports using the GraalVM/Mandrel Native Image tool to produce
10 
    a native binary including the container. This documentation page
11 
    describes the build process of such an image.
12 
  </p>
13 
 
14 
  </div><h3 id="Setup">Setup</h3><div class="text">
15 
 
16 
  <p>
17 
    The native image tool is much easier to use with single JARs, as a result
18 
    the process will use the Maven shade plugin JAR packaging. The
19 
    idea is to produce a single JAR that contains all necessary classes from
20 
    Tomcat, the webapps and all additional dependencies. Although Tomcat has
21 
    received compatibility fixes to support native images, other libraries
22 
    may not be compatible and may require replacement code (the GraalVM
23 
    documentation has more details about this).
24 
  </p>
25 
 
26 
  <p>
27 
    Download and install GraalVM or Mandrel.
28 
  </p>
29 
 
30 
  <p>
31 
    Download the Tomcat Stuffed module from
32 
    <code>https://github.com/apache/tomcat/tree/10.1.x/modules/stuffed</code>.
33 
    For convenience, an env property can be set:
34 
    <div class="codeBox"><pre><code>export TOMCAT_STUFFED=/absolute...path...to/stuffed</code></pre></div>
35 
    The build process now requires both Apache Ant and Maven.
36 
  </p>
37 
 
38 
  </div><h3 id="Packaging_and_Building">Packaging and Building</h3><div class="text">
39 
 
40 
  <p>
41 
    Inside the <code>$TOMCAT_STUFFED</code> folder, the directory structure
42 
    is the same as for regular Tomcat. The main configuration files
43 
    are placed in the <code>conf</code> folder, and if using the default
44 
    <code>server.xml</code> the webapps are placed in the <code>webapps</code>
45 
    folder.
46 
  </p>
47 
 
48 
  <p>
49 
    All the webapp classes need to be made available to the Maven shade plugin
50 
    as well as the compiler during the JSP precompilation step.
51 
    Any JARs that are present in <code>/WEB-INF/lib</code>
52 
    need to be made available as Maven dependencies.
53 
    The <code>webapp-jspc.ant.xml</code> script will copy classes from the
54 
    <code>/WEB-INF/classes</code> folder of the webapp
55 
    to the <code>target/classes</code> path that Maven uses as the compilation
56 
    target, but if any of the JSP sources use them, then they need to be
57 
    packaged as JARs instead.
58 
  </p>
59 
 
60 
  <p>
61 
    The first step is to build the shaded Tomcat JAR with all dependencies.
62 
    Any JSP in the webapp must all be precompiled and packaged (assuming
63 
    that the <code>webapps</code> contains a <code>$WEBAPPNAME</code> webapp):
64 
    <div class="codeBox"><pre><code>cd $TOMCAT_STUFFED
65 
mvn package
66 
ant -Dwebapp.name=$WEBAPPNAME -f webapp-jspc.ant.xml</code></pre></div>
67 
    Dependencies for the webapp should now be added to the main
68 
    <code>$TOMCAT_STUFFED/pom.xml</code>,
69 
    following by building the shaded JAR:
70 
    <div class="codeBox"><pre><code>mvn package</code></pre></div>
71 
  </p>
72 
 
73 
  <p>
74 
    As it is best to avoid using reflection whenever possible with Ahead of
75 
    Time compilation, it can be a good idea to generate and compile Tomcat
76 
    Embedded code out of the main server.xml configuration as well as the
77 
    context.xml files used to configure the contexts.
78 
    <div class="codeBox"><pre><code>$JAVA_HOME/bin/java\
79 
        -Dcatalina.base=. -Djava.util.logging.config.file=conf/logging.properties\
80 
        -jar target/tomcat-stuffed-1.0.jar --catalina -generateCode src/main/java</code></pre></div>
81 
    Then stop Tomcat and use the following command to include the generated
82 
    embedded code:
83 
    <div class="codeBox"><pre><code>mvn package</code></pre></div>
84 
    The rest of the process described here will assume this step was done and
85 
    the <code>--catalina -useGeneratedCode</code> arguments are added to the
86 
    command lines. If this was not the case, they should be removed.
87 
  </p>
88 
 
89 
  </div><h3 id="Native_image_configuration">Native image configuration</h3><div class="text">
90 
 
91 
  <p>
92 
    Native images do not support any form of dynamic classloading or
93 
    reflection unless it is defined explicitly in descriptors. Generating
94 
    them uses a tracing agent from the GraalVM, and needs additional manual
95 
    configuration in some cases.
96 
  </p>
97 
 
98 
  <p>
99 
    Run Tomcat using the GraalVM substrate VM and its trace agent:
100 
    <div class="codeBox"><pre><code>$JAVA_HOME/bin/java\
101 
        -agentlib:native-image-agent=config-output-dir=$TOMCAT_STUFFED/target/\
102 
        -Dorg.graalvm.nativeimage.imagecode=agent\
103 
        -Dcatalina.base=. -Djava.util.logging.config.file=conf/logging.properties\
104 
        -jar target/tomcat-stuffed-1.0.jar --catalina -useGeneratedCode</code></pre></div>
105 
  </p>
106 
 
107 
  <p>
108 
    Now all paths from the webapp that lead to dynamic classloading
109 
    (ex: Servlet access, websockets, etc) need to be accessed using a script
110 
    that will exercise the webapp. Servlets may be loaded on startup
111 
    instead of needing an actual access. Listeners may also be used to load
112 
    additional classes on startup. When that is done, Tomcat can be stopped.
113 
  </p>
114 
 
115 
  <p>
116 
    The descriptors have now been generated in the agent output directory.
117 
    At this point, further configuration must be made to add items that are
118 
    not traced, including: base interfaces, resource bundles, BeanInfo based
119 
    reflection, etc. Please refer to the Graal documentation for more
120 
    information on this process.
121 
  </p>
122 
 
123 
  <p>
124 
    Even though all classes that are used have to be complied AOT into the
125 
    native image, webapps must still be left unchanged, and continue including
126 
    all needed classes and JARs in the <code>WEB-INF</code> folder. Although
127 
    these classes will not actually be run or loaded, access to them is
128 
    required.
129 
  </p>
130 
 
131 
  </div><h3 id="Building_the_native_image">Building the native image</h3><div class="text">
132 
 
133 
  <p>
134 
    If everything has been done properly, the native image can now be built
135 
    using the native-image tool.
136 
    <div class="codeBox"><pre><code>$JAVA_HOME/bin/native-image --report-unsupported-elements-at-runtime\
137 
        --enable-http --enable-https --enable-url-protocols=http,https,jar,jrt\
138 
        --initialize-at-build-time=org.eclipse.jdt,org.apache.el.parser.SimpleNode,javax.servlet.jsp.JspFactory,org.apache.jasper.servlet.JasperInitializer,org.apache.jasper.runtime.JspFactoryImpl\
139 
        -H:+UnlockExperimentalVMOptions\
140 
        -H:+JNI -H:+ReportExceptionStackTraces\
141 
        -H:ConfigurationFileDirectories=$TOMCAT_STUFFED/target/\
142 
        -H:ReflectionConfigurationFiles=$TOMCAT_STUFFED/tomcat-reflection.json\
143 
        -H:ResourceConfigurationFiles=$TOMCAT_STUFFED/tomcat-resource.json\
144 
        -H:JNIConfigurationFiles=$TOMCAT_STUFFED/tomcat-jni.json\
145 
        -jar $TOMCAT_STUFFED/target/tomcat-stuffed-1.0.jar</code></pre></div>
146 
    The additional <code>--static</code> parameter enables static linking of
147 
    glibc, zlib and libstd++ in the generated binary.
148 
  </p>
149 
 
150 
  <p>
151 
    Running the native image is then:
152 
    <div class="codeBox"><pre><code>./tomcat-stuffed-1.0 -Dcatalina.base=. -Djava.util.logging.config.file=conf/logging.properties --catalina -useGeneratedCode</code></pre></div>
153 
  </p>
154 
 
155 
  </div><h3 id="Compatibility">Compatibility</h3><div class="text">
156 
 
157 
  <p>
158 
    Servlets, JSPs, EL, websockets, the Tomcat container, tomcat-native, HTTP/2
159 
    are all supported out of the box in a native image.
160 
  </p>
161 
 
162 
  <p>
163 
    At the time of writing this documentation, JULI is not supported as the
164 
    log manager configuration property is not supported by Graal, in addition
165 
    to some static initializer problems, and the regular java.util.logging
166 
    loggers and implementation should be used instead.
167 
  </p>
168 
 
169 
  <p>
170 
    If using the default server.xml file, some Server listeners have
171 
    to be removed from the configuration as they are not compatible with native
172 
    images, such as a JMX listener (JMX is unsupported) and leak prevention
173 
    listeners (use of internal code that does not exist in Graal).
174 
  </p>
175 
 
176 
  <p>
177 
    Missing items for better Tomcat functionality:
178 
    <ul>
179 
      <li>java.util.logging LogManager: Configuration through a system property
180 
        is not implemented, so standard java.util.logging must be used instead
181 
        of JULI</li>
182 
      <li>Static linking configuration: tomcat-native cannot be statically
183 
        linked</li>
184 
    </ul>
185 
  </p>
186 
 
187 
  </div></div></div></div></div><footer><div id="footer">
188 
    Copyright &copy; 1999-2025, The Apache Software Foundation
189 
    <br>
190 
    Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo
191 
    are either registered trademarks or trademarks of the Apache Software
192 
    Foundation.
193 
    </div></footer></div></body></html>