JSP Lifecycle and Translation

The specification describes the life of a page as two phases. In the translation phase the container validates the page (and the tag files and tag libraries it uses) and determines the JSP page implementation class that corresponds to it. In the execution phase the container manages one or more instances of that class in response to requests and other events. The specification allows translation at any moment between the deployment of the page and the processing of the first client request, and deliberately leaves the choice open as a quality-of-service decision of the container. Tomcat translates lazily, on the first request, unless the page is declared with load-on-startup (shown below), and rebuilds the class when the source changes.

Source: Jakarta Pages 4.0 — 1.1.4 Translation and Execution Phases

Source: Apache Tomcat 11 — Jasper 2 JSP Engine How-To, Introduction

The same path as a diagram. The upper half runs once per page (and again whenever the source changes); the lower half runs once for every request.

The whole of this machinery is the container’s job: a JSP author writes the page and, at most, jspInit and jspDestroy. The class that results is an ordinary servlet, which is why everything on the Servlet Fundamentals page (one instance, many threads, filters, error pages, dispatchers, sessions) applies to a page unchanged.

Chapter 11 of the specification defines the contract between a JSP container and the class that implements a page. It corresponds to the Servlet interface, extended by two interfaces in jakarta.servlet.jsp: JspPage (generic) and HttpJspPage (the HTTP form every page uses). Of the three methods of the contract, only two can be written by the page author.

Three details of that table matter in practice:

By default the generated class extends a container-specific base class (org.apache.jasper.runtime.HttpJspBase in Tomcat), which implements HttpJspPage. The extends attribute of the page directive replaces that superclass; the author then guarantees that the replacement supports the contract. Almost nobody needs it, and it is covered with the other attributes on the Directives page of this section.

Source: Jakarta Pages 4.0 — 11.2.1 API Contracts

Source: Jakarta Pages 4.0 Javadoc — HttpJspPage

Source: Jakarta Pages 4.0 Javadoc — JspPage

Source: Jakarta Pages 4.0 — 1.1.6 Events in JSP Pages

All the examples below are files of one WAR, deployed as g3lifecycle.war (context path /g3lifecycle) on Tomcat 11.0.26, built with Maven from the same pom.xml shape as the Getting Started page of this section (Jakarta APIs with scope provided, plus the JSTL API and implementation). The page directory is the web root; WEB-INF/web.xml declares only one servlet, shown later.

The first page prints a list of titles and, to make the lifecycle visible, defines jspInit and jspDestroy in a declaration, counts its own hits in an instance field and reports the class, the superclass, the identity of the instance and the thread that ran the request.

Source: Jakarta Pages 4.0 — 1.12.1 Declarations

Requesting it twice returns the same instance on two different request threads, with the counter advancing (blank lines at the top of the real response come from the directives and declaration lines, which are template text; the trimDirectiveWhitespaces attribute is covered on the Directives page):

The container’s log (ServletContext.log goes to localhost.<date>.log in Tomcat’s logs/ directory) shows the other two events. jspInit ran once, during the first request, not at deployment; jspDestroy ran when the web application was removed (three requests had been served by the instance that was current at that time):

Source: Jakarta Pages 4.0 — 11.2.1 API Contracts

Jasper keeps the Java source it generates (keepgenerated defaults to true) in the web application’s scratch directory, $CATALINA_BASE/work/Catalina/<host>/<context>/. The source is the best documentation of what a page really does. For the page above the files are:

The class lives in the package org.apache.jsp, followed by the directory of the page; its name is the file name with _jsp appended. Characters that are illegal in a Java identifier are escaped (WEB-INF becomes WEB_002dINF, where 002d is the hexadecimal code of -), and the tag handler pool fields carry names such as _005fjspx_005ftagPool_005fc_005fforEach for the same reason. The file name, the package and these identifiers are implementation details of Tomcat and may differ in Jetty or GlassFish; the specification says so itself (section 9.1.3: an implementation need not perform the transformations literally), so a page must never depend on them.

The structure of a generated class follows specification Table JSP.9-1: optional imports, the superclass, the declaration section, then _jspService with the implicit-object section and the main section. This is the real source for lifecycle.jsp, with the repeated plumbing shortened where marked:

Source: Jakarta Pages 4.0 — 9.1 Overall Structure

Source: Apache Tomcat 11 — Jasper 2 JSP Engine How-To, Configuration (keepgenerated, mappedfile)

Reading it gives the rules that the other pages of this section rely on.

Source: Jakarta Pages 4.0 — 9.4 Main Section

Source: Jakarta Pages 4.0 — 9.2 Declarations Section

Source: Jakarta Pages 4.0 — 1.10.3 The include Directive

The translation of a static include and a dynamic include is visible side by side in composed.jsp, which has both:

Its generated source writes the footer as plain template text (out.write("<footer>Bookshelf, footer version one</footer>\n")) and calls JspRuntimeLibrary.include(...) for hello.jsp; the footer appears in _jspx_dependants with its last-modified time, which is how Jasper knows the page depends on it.

Source: Jakarta Pages 4.0 — 1.10.3 The include Directive

The generated class is a servlet and the container creates a single instance of it (specification section 2.2 of the Servlet specification: one instance per declaration unless the application is distributable), so every request to lifecycle.jsp runs _jspService on that same object, on a different thread. The consequences follow directly from the translation table above:

The example above increments hits inside synchronized (this). Forty parallel requests against it (twenty at a time, with xargs -P 20) leave the counter exactly where it should be, on one instance:

(hits=43 is the two earlier requests plus the forty parallel ones plus this last one.)

The old escape hatch for a page that was not thread safe, <%@ page isThreadSafe="false" %>, made the container serialise requests with the SingleThreadModel interface. That interface was deprecated for years and was removed in Servlet 6.0, and the attribute was deprecated in Pages 3.1 and removed in Pages 4.0. On Tomcat 11 it is a translation error:

The replacement is design, not configuration: keep state out of instance fields, or protect it.

Source: Jakarta Servlet 6.1 — 2.2 Number of Instances

Source: Jakarta Servlet 6.1 — 2.3.3.1 Multithreading Issues

Source: Jakarta Pages 4.0 — Appendix C.1, Changes between JSP 4.0 and JSP 3.1

By default Tomcat translates a page on the first request that reaches it (the first hit pays for translation and compilation; the instance created then serves all the others). A page can be moved to deployment time by declaring it as a servlet with <jsp-file> and <load-on-startup>, which also lets web.xml give it a name, initialisation parameters and its own URL mapping.

The generated file for warmup.jsp carries the header Generated at: 2026-10-08 11:02:36 UTC, the moment the application was deployed, while lifecycle_jsp.java, which was only requested later, carries 11:02:40: translation happened at deployment for the first and at request time for the second. Pages under WEB-INF (as here) cannot be requested directly by a client; only the mapping /warmup reaches this one, which is the right place for views. Two other things to know about the container’s page management:

Source: Jakarta Servlet 6.1 — 10.7 Web Application Deployment Descriptor (jsp-file, load-on-startup)

Source: Apache Tomcat 11 — Jasper 2 JSP Engine How-To, Configuration (jspIdleTimeout, maxLoadedJsps)

In development mode (the Jasper parameter development, default true) Tomcat checks a page for changes when it is requested, but not more often than modificationTestInterval seconds (default 4); a value of 0 checks on every access. When the source, or a file the page depends on, is newer than the compiled class, the page is translated and compiled again, the old instance is destroyed (jspDestroy) and a new instance of the new class is created (jspInit). The experiment below changes hello.jsp on disk, five seconds after the previous request:

The generated hello_jsp.java was rewritten (out.write("Hello version two\n")) and its Generated at header moved. Editing lifecycle.jsp the same way produced the log pair that shows what recompilation does to a page’s state: the old instance reported jspDestroy after 43 hits, the new instance reported jspInit, instance 157172844, and the counter on the page started again at hits=1. A page that keeps data in an instance field therefore loses it whenever the page is edited, a second reason (after concurrency) to keep state out of declarations.

Dependencies are tracked too. composed.jsp includes footer.jspf with the static include directive, and the footer is listed in _jspx_dependants. Editing only the footer (after the interval) made the next request to composed.jsp show footer version two: the including page was translated again, because a static include is part of its translation unit. Editing only hello.jsp, which composed.jsp includes with jsp:include, did not recompile composed.jsp at all; hello.jsp was rebuilt on its own the next time it was served.

Source: Apache Tomcat 11 — Jasper 2 JSP Engine How-To, Configuration (development, modificationTestInterval, recompileOnFail)

Source: Jakarta Pages 4.0 — 1.1.9 Compiling JSP Pages

Production changes the defaults. The Jasper HowTo recommends development=false (no checks on access, so a page is never retranslated unless the application is redeployed), genStringAsCharArray=true, a high modificationTestInterval if development mode cannot be switched off, and trimSpaces=single or extended; the Jasper checkInterval (seconds, default 0) enables background recompilation, when development is false, so that the previous class keeps serving requests until the new one has compiled. The full parameter list, JspC and the Maven and Ant integrations are the topic of the Jasper Configuration & Precompilation page of this section.

Source: Apache Tomcat 11 — Jasper 2 JSP Engine How-To, Production Configuration

Because translation and compilation happen on the first request, a mistake in a page is not reported at deployment but to the first client. The two kinds of failure look different, and both are mapped back to lines of the page.

A translation or compilation error is a JasperException with the heading Unable to compile class for JSP:

The message shows the JSP line and a few lines of context (displaySourceFragment, default true), not the generated Java. A request-time error is an exception thrown while _jspService runs. Here the page dereferences a request parameter that is absent:

Jasper says line 8 of the JSP, but the stack frame in the cause says line 130 of the generated Java. The two numbers are related by the SMAP, the line table that the Jakarta Debugging Support for Other Languages specification defines and that the Pages specification requires of every container (section 11.5): the class file gets a SourceDebugExtension attribute, with a stratum named JSP, mapping lines of the page to lines of the generated class. Tomcat uses it to turn the Java line into the page line in the message, and IDE debuggers use it to step through the page rather than the generated servlet. javap -v shows the table of runtimefail_jsp.class:

Each *L line reads "input lines a,b map to output starting at line n`": JSP line 8 is output lines 129 to 131, and the failing statement is at 130. The same table is why a debugger breakpoint on line 8 of a JSP works, and why a stack trace of the page in the server log needs the cause section, not the first frames. With `suppressSmap=true Tomcat leaves the table out, and the message falls back to Java line numbers. In development, keep mappedfile on and read the .java in work/ when a page misbehaves in a way the message cannot explain.

Source: Jakarta Pages 4.0 — 11.5 Debugging Requirements

Source: Jakarta Debugging Support for Other Languages 2.0

Source: Jakarta Pages 4.0 — 1.1.10 Debugging JSP Pages

The implicit object out is a jakarta.servlet.jsp.JspWriter, a buffered writer that sits between the generated code and the servlet response. Headers are not sent until the response is committed, which happens when the buffer is flushed or, with autoFlush="true", fills up. Until then the page can still change the status, set headers, redirect or call sendError; after that those calls no longer work, exactly as for any servlet. Two attributes of the page directive control it, and a third affects whether the page touches the session at all.

Source: Jakarta Pages 4.0 — 1.10.1 The page Directive

Four short pages show the behaviour on Tomcat 11.0.26.

The header was added after the first line of body had been written, yet it reaches the client, because the line was still in the buffer, and the response has a Content-Length (58), which a buffered page can compute. The Set-Cookie line is the default session="true" at work, on a page that never mentions a session.

Two thousand characters do not fit in 1024 bytes and, with autoFlush="false", the page fails instead of flushing. With the default autoFlush="true" the same page would flush at 1 KB, commit the response and send it chunked.

X-Too-Late is absent: after out.flush() the headers had gone, so setHeader did nothing and the response is chunked because its length was not known when it was committed. Finally, a redirect issued from a scriptlet after some output, while the response is still uncommitted, works and the buffered text is discarded:

The specification’s wording of this case (section 11.3) names the method response.redirect; the method is sendRedirect, as above. The thing that matters in design is that anything which must be decided before the first byte (status codes, redirects, cookies, content type, a forward) has to happen before the buffer is flushed, either explicitly or by overflowing; a larger buffer, or doing the work in a servlet before forwarding to the view, are the usual remedies. The Servlet response buffer, which is the layer below JspWriter, is discussed in the Servlet Fundamentals page.

Source: Jakarta Pages 4.0 — 11.3 Buffering

Source: Jakarta Pages 4.0 Javadoc — JspWriter

Source: Jakarta Servlet 6.1 — 5.1 Buffering

The specification gives containers a precompilation protocol (section 11.4). Request parameter names beginning with jsp are reserved; a request to a page with the parameter jsp_precompile is a precompilation request that must not be delivered to the page itself. The parameter may have no value, true or false; true or no value is a suggestion to translate and compile the page, which the container may ignore. Any other value is an error (HTTP 500). Tomcat honours the suggestion and returns an empty 200:

After the first call, hello_jsp.java and hello_jsp.class exist in work/ although the page body never ran; the second call produced jakarta.servlet.ServletException: Cannot have precompilation request parameter [jsp_precompile] set to [foo], as the specification requires. This is a way to warm up a deployed application page by page, with a script that requests each page with the parameter. A better one for production is to translate and compile every page during the build (JspC, the Ant <jasper> task, the Jetty JspC Maven plugin) and package the result, which removes the first-request delay and the need for a compiler on the server; the specification describes this in section 1.1.9 and in Appendix A, and the tooling is the subject of the Jasper configuration and precompilation page of this section. Precompilation does not work with every feature (the HowTo points out that jsp-property-group can make it impractical), which is why the production settings above still matter.

Source: Jakarta Pages 4.0 — 11.4.2 Precompilation Protocol

Source: Jakarta Pages 4.0 — 1.1.9 Compiling JSP Pages

Source: Apache Tomcat 11 — Jasper 2 JSP Engine How-To, Web Application Compilation

The lifecycle above is the specification’s; the generated source is Tomcat’s. Tomcat and Jetty implement Pages with Apache Jasper (Jetty names its JSP module apache-jsp), and GlassFish with Eclipse WaSP (eclipse-ee4j/wasp), which uses the Expressly EL implementation. The three produce differently shaped classes, so a page, a tag or a framework must not depend on the class name, the package, the superclass or the helper methods seen above; the supported seams are the HttpJspPage contract, the tag APIs, PageContext and the SMAP. File locations differ too: the work/ directory path shown here is Tomcat’s, so check the container’s own documentation for where it keeps generated sources.

Source: Eclipse WaSP (GlassFish Pages implementation)

Source: Eclipse Jetty documentation

Source: Jakarta Pages 4.0 — 1.1.4 Translation and Execution Phases

Source: Jakarta Pages 4.0 — Appendix C.1, Changes between JSP 4.0 and JSP 3.1

Source: Jakarta Pages 4.0 — Appendix C.2, Changes between JSP 3.1 and JSP 3.0

Source: Jakarta Pages 4.0 — Appendix C.3, Changes between JSP 3.0 and JSR 245

Source: Apache Tomcat 11 — Jasper 2 JSP Engine How-To

Web Development with JavaServer Pages (Manning, 2001, listed in the section bibliography) describes JSP 1.2 on Tomcat 4, and its chapter on how JSP works and its appendices (the JSP 1.1 to 1.2 changes, running Tomcat, the syntax and API references) are the origin of most of what developers still remember about the lifecycle. The model is intact: translation phase and request phase, a servlet underneath, jspInit, _jspService and jspDestroy, output buffering and recompilation on change. What differs is the platform around it.

Source: Jakarta Pages 4.0 — Appendix C.3, Changes between JSP 3.0 and JSR 245

Source: Manning — Web Development with JavaServer Pages, Second Edition