Getting Started

A JSP application is a web application archive (WAR) that a servlet container unpacks and runs. The container supplies the Servlet, Pages and Expression Language APIs and the JSP engine; the application brings its own classes, its views and, with Tomcat, the JSTL jars. Four pieces are therefore needed.

Tomcat’s own documentation states the support matrix: Tomcat 11.0.x implements Servlet 6.1, JSP 4.0, EL 6.0, WebSocket 2.2 and Authentication 3.1 (the versions required by the Jakarta EE 11 platform) and runs on Java 17 and later, while Tomcat 10.1.x implements Servlet 6.0 and JSP 3.1 on Java 11 and later, and Tomcat 9.0.x still implements the javax.* Servlet 4.0 and JSP 2.3 on Java 8 and later.

Source: Apache Tomcat Versions — Currently Supported Versions

Any Jakarta EE 11 servlet container runs the examples of this section. The three that matter in practice differ in what they are and how a JSP is supported.

Tomcat is the one the examples assume. Jetty and GlassFish are shown further down with the same WAR; a portability difference between them (records in EL) is listed in the pitfalls table. Issue #116 (IDE links) is referenced here in prose only: every IDE with Jakarta EE tooling can start Tomcat 11, Jetty 12 or GlassFish 8 from a run configuration and deploy the exploded project into it, so nothing in this section depends on a particular IDE; use one only if it can run a server whose Servlet level is 6.1.

Source: Eclipse Jetty Operations Guide — Java Server Pages

Source: Eclipse WaSP — the Jakarta Pages implementation of GlassFish

Source: Eclipse Expressly — the Jakarta Expression Language implementation of GlassFish

Source: Eclipse GlassFish Quick Start Guide (release 8)

Install a JDK (not only a JRE) of version 21: the servlet compiler, Maven and Tomcat’s startup scripts all use it. Distributions such as Eclipse Temurin (https://adoptium.net/) and the OpenJDK builds listed on https://openjdk.org/projects/jdk/21/ are interchangeable for this purpose. Tomcat’s RUNNING.txt states that Tomcat 11.0 requires a Java SE Runtime Environment version 17 or later and that a full JDK may be used instead of a JRE. Point JAVA_HOME at the JDK and check both the compiler and the runtime.

Maven prints the Java version it runs with, which is the quickest way to find a JAVA_HOME that points at the wrong JDK. Installing Maven itself is covered by the Maven project (https://maven.apache.org/install.html); the Java language and its tools are covered elsewhere on this site (Java Getting Started and Build & Tooling).

Source: Running The Apache Tomcat 11.0 Servlet/JSP Container (RUNNING.txt)

Source: Apache Maven — Installing Maven

Tomcat is a directory, not an installer: download the "Core" archive from the Tomcat 11 download page, verify it, unpack it and run its scripts. The download page publishes OpenPGP signatures and SHA-512 checksums for every file and asks users to check the integrity of what they download. The checksum file has the format hash *filename, which shasum reads directly.

(downloads.apache.org serves the checksum files of current releases and archive.apache.org keeps every older release; the download page links both. On Windows use the "Windows zip" distribution.)

Source: Tomcat 11 Software Downloads — Release Integrity

Both alternatives run the same WAR that the rest of this page builds, so the instructions are short. They are written after the WAR exists; the full runs are in the Maven plugins and GlassFish sections below. The differences to know in advance:

Source: Eclipse Jetty — Using the Jetty Maven Plugin

Source: Eclipse GlassFish Quick Start Guide — Deploying and Undeploying Applications

The smallest useful project has a pom.xml, a folder of Java classes, and a folder of web content. Everything under src/main/webapp becomes the root of the WAR, and WEB-INF inside it is the private part: nothing in it is served directly to a browser. Create the layout first, then fill the files in.

The folder names follow the usual Maven and Servlet conventions: src/main/java holds the classes, src/main/webapp the web content, WEB-INF/jsp the views that only a servlet may forward to, and WEB-INF/tags the tag files that Jasper discovers automatically when a page declares tagdir="/WEB-INF/tags". The later pages of this section add author, review and loan packages beside book, a tlds folder and a messages resource bundle.

Source: Tomcat 11 Application Developer’s Guide — Standard Directory Layout

Source: Jakarta Servlet 6.1 — Directory Structure

A servlet is a Java class that extends HttpServlet and turns a request into a response. With the @WebServlet annotation no registration is needed; the container finds the class while scanning the WAR. The first servlet answers with plain text and shows what the container reports about itself, which makes it a good smoke test for any new environment.

Build it, copy the WAR to webapps/ and request the URL. The three parts of the path are the container’s context path (/bookshelf, from the WAR’s file name), the servlet’s URL pattern (/hello) and nothing else, because the servlet has no extra path.

getServerInfo() names the container, getMajorVersion() and getMinorVersion() report the Servlet API level the container implements, and getContextPath() returns the path under which the application is mounted. The same WAR printed jetty/12.1.14 and Eclipse GlassFish 8.0.5 for the first line on those servers, with the same two other lines.

Source: Jakarta Servlet 6.1 Javadoc — WebServlet

Source: Jakarta EE Tutorial — Hello World Web Application Using Jakarta Servlet

A servlet is good at deciding and bad at producing markup. The Model 2 arrangement used throughout Part I therefore keeps both jobs apart: a servlet handles the request, puts the model in a request attribute and forwards to a JSP that renders it. The view lives under WEB-INF/jsp, so a browser cannot request it directly.

The fourth title contains markup characters on purpose: it proves, in the output below, that the view escapes what it prints.

Build and deploy, then ask for the catalogue and for a filtered one.

(The blank lines that the directives and tags leave in the real output were removed above.) The second request returns only the Neuromancer item and <p>1 book(s)</p>; a filter with no match prints No books match "zzz"., and a filter such as "><script> is echoed back as "><script>, because c:out escapes <, >, &, ' and ".

Read the page from top to bottom.

The model in the request travels from the servlet to the JSP through request.setAttribute("books", ...). The EL expression ${books} searches the page, request, session and application scopes in that order and finds it in the request scope.

Source: Jakarta Pages 4.0 — The page Directive

Source: Jakarta Standard Tag Library 3.0 — Tag library URIs and prefixes

Source: Jakarta EE Tutorial — Transferring Control to Another Web Component

Source: Jakarta Pages 4.0 — Objects and Scopes

The catalogue page used a handful of features without introducing them. Before moving on, the next page shows the smaller steps that an introduction to JSP normally takes: template text, EL, request parameters, a JavaBean, jsp:include, a session, and what a scriptlet looks like (for reading old code only).

Putting the pieces together shows what the container does for the request GET /bookshelf/books?filter=dune.

That is why the first request to a JSP is slower than the following ones, and why a syntax error in a JSP appears as an error page at request time and not at deployment time (Jasper can also precompile all JSPs at build time; Jasper Configuration & Precompilation explains how). By default, Tomcat’s JSP servlet runs in development mode: it checks the modification time of the JSP file at most every few seconds (the modificationTestInterval parameter, default 4) and recompiles a changed page on the next request. In the verification for this page, editing first-steps.jsp in the deployed directory changed the response within five seconds without a restart.

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

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

Source: Jakarta Pages 4.0 — JSP Page Implementation Class

(The META-INF/maven entries and the directory entries are omitted from some listings; the order depends on the plugin.) This is the contents a servlet container expects: the public files at the root, and under WEB-INF the descriptor, the classes in classes/, the jars in lib/, the private views and the tag files. The three provided APIs are absent from WEB-INF/lib, as intended. A mvn clean matters when files are renamed or moved: without it the old target/classes and target/<finalName> directories can leak a stale file into the WAR (a WEB-INF/views/catalogue.jsp left over from an earlier layout appeared in a build made for this page until clean was used).

Source: Jakarta Servlet 6.1 — Web Application Archive File

Source: Jakarta EE Tutorial — The Web Application Archive

For an edit-run loop, a Maven plugin that starts a container from the build is quicker than copying WARs. Two are in common use: the Jetty plugin, which embeds Jetty, and Cargo, which downloads and runs an installed container.

GlassFish needs no descriptor and no extra libraries for this WAR. The commands come from its Quick Start Guide: start the default domain, deploy with asadmin deploy, list, and stop.

(The check was made with the Web Profile distribution 8.0.5, in a domain created with asadmin create-domain --portbase 18500, so its ports differed from the defaults 8080 and 4848.) One thing differs from Tomcat and Jetty. On GlassFish 8.0.5 the catalogue page failed with jakarta.el.PropertyNotFoundException: The class 'org.example.bookshelf.book.Book' does not have the property 'title': the Book is a Java record, and EL there did not resolve record components, although the Pages 4.0 specification lists jakarta.el.RecordELResolver in the chain of resolvers and EL 6.0 says record support is enabled by default. The same WAR rendered on Tomcat 11.0.26 and on Jetty 12.1.14. Adding JavaBean-style getters to the record (getTitle(), getAuthor(), getYear(), getId()) made the page render on GlassFish too. If an application must run on several servers, give model types getters, or use ordinary classes, until the GlassFish behaviour is fixed.

Source: Eclipse GlassFish Quick Start Guide — To Deploy the Sample Application From the Command Line

Source: Jakarta Pages 4.0 — Resolution of Variables and their Properties

The official tomcat image on Docker Hub is a Tomcat install in /usr/local/tomcat; tags such as 11.0-jdk21-temurin pin the Tomcat line and the JDK. Two details matter for a WAR. First, the image’s webapps directory is empty: the default applications are kept in webapps.dist (verified: ls /usr/local/tomcat/webapps lists nothing, webapps.dist has ROOT, docs, examples, host-manager and manager), so a copied WAR is the only application. Second, a WAR named ROOT.war is deployed at the root context path, so the container answers at / and not at /bookshelf/.

A multi-stage build keeps Maven and the sources out of the final image: the first stage builds the WAR, the second copies it into a Tomcat image. Only these lines are specific to a WAR; the general mechanics (layers, caches, non-root users, health checks, scanning) are covered by the Docker pages of this site, for example Dockerfile Fundamentals, Build Cache and Multi-Stage Builds, Java and Spring Boot Images and Image Best Practices and Security.

The context path is empty because the WAR is ROOT.war, which is why every URL lost its /bookshelf prefix. The image built for this check was 533 MB; the official image runs Tomcat as root by default (verified with id -un), so a production image adds a non-root user as the Docker security page describes. If the application needs a database or other services, the Compose and Testcontainers pages of this site show how to start them beside the container.

Source: Docker Official Image — tomcat

Source: Docker — Multi-stage builds

The sections above are the explanation; this is the sequence a reader performs, with the check after each step. It uses only files shown on this page.

From here Part I takes the same project further: servlets as controllers with a service layer (MVC with Servlets & JSP), EL and the JSTL libraries in depth (Expression Language Basics, JSTL Core), tag files and tag libraries, forms with validation and sticky fields, internationalisation (JSTL i18n & Messages), security, error pages and a Spring MVC variant of the catalogue page. Part II then starts bookshelf-struts, a second WAR on the same Tomcat built on Apache Struts 7.4; its own Struts Getting Started page builds it by hand with the struts2-bom, because the Struts Maven archetypes stop at 6.0.0, and the two applications can run on one Tomcat side by side because each has its own context path.

Source: Apache Struts — Getting Started

Every row below was reproduced on Tomcat 11.0.26, Jetty 12.1.14 or GlassFish 8.0.5 unless the right-hand column cites the documentation instead.

Source: Tomcat 11 Host — Common Attributes

Source: Spring Boot Reference — JSP Limitations

Source: Apache Tomcat Versions

Source: Jakarta Servlet 6.1 — Changes Since Jakarta Servlet 6.0

Source: Jakarta Pages 4.0 — Changes between JSP 4.0 and JSP 3.1

Source: Jakarta Expression Language 6.0 — Changes between 6.0 and 5.0

Source: Jakarta EE Tutorial — Jakarta Pages

Source: Tomcat 11 Host — legacyAppBase and the other common attributes

Source: Apache Tomcat 11 vulnerabilities

Source: Migration Guide — Tomcat 9.0.x to 10.0.x, Specification APIs

Two of the section’s reference books cover this ground: Web Development with JavaServer Pages (2nd edition, JSP 1.2) for the first steps, how JSP works and deploying, and JSTL in Action (JSTL 1.0) for the tag libraries; the section bibliography lists them. Their opening chapters introduce what a servlet container, a servlet and a JSP are, and those concepts are unchanged, but the platform they were written for has changed beyond recognition:

Setup advice of the Tomcat 4 and 5 era has also changed, as Tomcat’s current guides show. Tomcat’s deployer guide says that Context elements used to be stored in server.xml and that this is now discouraged, in favour of a WAR in webapps/ or a context descriptor. The single manager role of early Tomcat versions was replaced from Tomcat 7 by four roles (manager-gui, manager-status, manager-script, manager-jmx), and the Manager is unusable until a user holds one of them. The <jsp-config> and <taglib> descriptor elements and the other web.xml details of the books' deployment chapters are covered by Servlet Fundamentals and Part I.

The code samples of chapters 2 to 4 of the JSP book contain typographic (curly) quotation marks that make them invalid if copied; every example on this page was typed from the official documentation and compiled. Later pages note the outdated details next to the concepts they touch, and What’s Changed & Migration collects them.

Source: Apache Tomcat Versions — Unsupported Version Details

Source: Tomcat 11 Deployer How-To — A word on Contexts

Source: Tomcat 11 Manager App How-To — Configuring Manager Application Access

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

Source: Manning — JSTL in Action