1. Overview
Jakarta EE, formerly known as Java EE, allows us to write an enterprise web application that can be deployed within an application server or servlet container such as GlassFish, Payara, or Tomcat.
In this tutorial, we’ll explore common dependency configuration pitfalls when setting up Jakarta EE for Tomcat and demonstrate the correct pom.xml configuration.
2. Tomcat Server Support for Jakarta EE
Earlier versions of Java EE used the javax namespace. However, starting from Jakarta EE 9, all packages were renamed to use the jakarta namespace. This namespace change implies that applications using jakarta APIs must be deployed on servers that support Jakarta EE 10 or later.
Before Tomcat 10, applications deployed on Tomcat depended on libraries that used the javax namespace. This is in line with the Java EE specifications. Starting from Tomcat 10, the server adopted the jakarta namespace to align with Jakarta EE 9 and above specifications.
As a result, applications deployed on Tomcat 10 or newer versions must use dependencies based on the jakarta packages, while older versions of Tomcat still require the javax packages.
3. Common Configuration Pitfalls
When setting up a Jakarta EE web application on Tomcat 10 or newer versions, several configuration mistakes could cause deployment or runtime failures. These issues are often related to dependency mismatches. Let’s go through some of the most common ones.
3.1. Using javax Dependencies on Tomcat 10 and Newer Versions
A common mistake during configuration is to use older javax dependencies with Tomcat 10 or newer. For example:
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>javax.servlet-api</artifactId>
<version>4.0.1</version>
<scope>provided</scope>
</dependency>
The configuration above compiles successfully but fails when deployed on Tomcat 10 and the newer versions because these versions no longer support the javax namespace. The dependency would have worked correctly only for applications running on Tomcat 9 or earlier.
3.2. Missing the provided Scope
Another common issue is including Jakarta EE dependencies without marking them as provided:
<dependency>
<groupId>jakarta.servlet</groupId>
<artifactId>jakarta.servlet-api</artifactId>
<version>6.1.0</version>
</dependency>
Without the provided scope, the library above is packaged into the WAR file and deployed along with the application. However, Tomcat already provides this API at runtime. As a result, having duplicates in both Tomcat and the application can lead to classpath conflicts and unexpected runtime behavior.
3.3. Adding Tomcat Dependency Manually
Furthermore, it’s unnecessary to add Tomcat-specific dependencies directly to our project. Notably, Tomcat already provides the required servlet implementation at runtime. Adding Tomcat JARs manually may cause version mismatches or classloader conflicts.
We should avoid adding dependencies like this:
<dependency>
<groupId>org.apache.tomcat</groupId>
<artifactId>tomcat-servlet-api</artifactId>
<version>11.0.13</version>
</dependency>
Instead, we should solely rely on Jakarta EE API dependencies marked as provided. This ensures our application remains portable and compatible across servlet containers that support Jakarta EE.
The jakarta.jakartaee-api dependency provides the entire Jakarta EE platform, which includes APIs for technologies such as Servlet, JSP, JSF, CDI, EJB, and JPA:
<dependency>
<groupId>jakarta.platform</groupId>
<artifactId>jakarta.jakartaee-api</artifactId>
<version>11.0.0</version>
<scope>provided</scope>
</dependency>
However, Tomcat is only a servlet container, not a full Jakarta EE application server. It supports only a subset of these specifications, primarily the web-related ones.
While using the full jakarta.jarkataee-api dependency may compile, it includes APIs that Tomcat doesn’t support at runtime unless additional libraries are installed manually.
To ensure compatibility and keep the application lightweight, we should include only the Jakarta APIs that Tomcat natively supports.
The main ones we can add individually include jarkata.servlet-api, jakarta.servlet.jsp-api, jarkarta.el-api, jakarta.websocket-api:
<!-- Servlet API -->
<dependency>
<groupId>jakarta.servlet</groupId>
<artifactId>jakarta.servlet-api</artifactId>
<version>6.1.0</version>
<scope>provided</scope>
</dependency>
<!-- JSP API -->
<dependency>
<groupId>jakarta.servlet.jsp</groupId>
<artifactId>jakarta.servlet.jsp-api</artifactId>
<version>3.1.1</version>
<scope>provided</scope>
</dependency>
<!-- Expression Language (EL) API -->
<dependency>
<groupId>jakarta.el</groupId>
<artifactId>jakarta.el-api</artifactId>
<version>6.0.1</version>
<scope>provided</scope>
</dependency>
<!-- WebSocket API -->
<dependency>
<groupId>jakarta.websocket</groupId>
<artifactId>jakarta.websocket-api</artifactId>
<version>2.2.0</version>
<scope>provided</scope>
</dependency>
These dependencies represent the subset of Jakarta EE specifications that Tomcat supports out of the box. They cover servlet, JSP, and WebSocket-based applications.
Alternatively, we could use the Jakarta Web Profile dependency, which bundles these same specifications in a single dependency:
<dependency>
<groupId>jakarta.platform</groupId>
<artifactId>jakarta.jakartaee-web-api</artifactId>
<version>11.0.0</version>
<scope>provided</scope>
</dependency>
APIs like Jakarta Faces (JSF), Jakarta Persistence (JPA), etc. aren’t supported by Tomcat by default.
4. Correct Configuration
To properly configure Jakarta EE libraries for Tomcat 10 and above, let’s create a simple Java project and add the jakarta.servlet-api dependency to our pom.xml with the provided scope:
<dependency>
<groupId>jakarta.servlet</groupId>
<artifactId>jakarta.servlet-api</artifactId>
<version>11.0.0</version>
<scope>provided</scope>
</dependency>
The jakarta.servlet-api dependency includes Servlet API. Also, let’s instruct Maven to package the project as a WAR file instead of the default JAR file:
<packaging>war</packaging>
With the current setup, we can now create a Servlet.
5. Verifying the Configuration
Now that we have the correct dependency configuration, let’s create a simple servlet to verify that our setup works correctly.
First, let’s create a servlet named CurrentDateAndTime that displays the current date and time:
@WebServlet(name = "CurrentDateAndTime", urlPatterns = {"/date-time"})
class CurrentDateAndTime extends HttpServlet {
LocalDateTime currentDate = LocalDateTime.now();
protected void processRequest(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
response.setContentType("text/html;charset=UTF-8");
currentDate = LocalDateTime.now();
try (PrintWriter out = response.getWriter()) {
out.printf("""
<html>
<head> <title> Current Date And Time </title> </head>
<body> <h2> Servlet current date and time at %s </h2> <br/> Date and Time %s </body>
</html>
""", request.getContextPath(), currentDate
);
}
}
@Override
protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
processRequest(request, response);
}
}
In the code above, the CurrentDateAndTime extends the HttpServlet class, allowing it to handle HTTP requests and responses.
Next, we define a method named processRequest(), which generates an HTML response that displays the current date and time. When the servlet receives a request from Tomcat, the doGet() method is invoked, and the generated HTML is sent back to the client. Also, we use the @WebServlet annotation to declare the servlet’s name and URL mapping directly inside the code.
Finally, let’s package our application as a WAR file by running the following Maven command:
$ mvn package
The command above generates a WAR file in the target directory. Our application is now ready for deployment. Deploying the WAR file to Tomcat outputs the current date and time without an error:
6. Conclusion
In this article, we explored the common pitfalls developers face when configuring a Jakarta EE application for deployment on Tomcat. We examined the differences between javax and jakarta dependencies, discussed why the provided scope is essential, and clarified which Jakarta EE libraries Tomcat supports out of the box. Finally, we configured the correct dependencies in the pom.xml file and verified our setup by deploying a simple servlet to Tomcat.
As always, the source code for the examples is available over on GitHub.
