Java EE / Jakarta EE
Jakarta EE Architecture: Containers, Profiles and Application Servers
Beginner12 min readReviewed by Mariem Ouled on Updated
Jakarta EE is a set of specifications that an application server implements so your code can rely on managed services instead of wiring them itself. After reading this you will be able to explain the container model, name the specifications that make up Jakarta EE 10 and its profiles, understand what the move from javax.* to jakarta.* changed, package a WAR or EAR correctly and choose between GlassFish, WildFly, Open Liberty, Payara or a plain servlet container.
What you will learn
- Describe the multi-tier model and the role of the web and enterprise-bean containers
- List the main Jakarta EE 10 specifications and what the Platform, Web and Core profiles include
- Explain the history from J2EE to Jakarta EE and the javax.* to jakarta.* migration
- Package an application as a WAR or EAR and understand portable JNDI names
- Choose an application server or runtime for a new or existing project
Every non-trivial server application needs the same set of services: an HTTP front end, a way to talk to a database inside a transaction, a security model, a place to run background work, and some form of messaging. Jakarta EE is the standardised answer to that list for the Java platform. You write components against a set of published APIs; an application server implements those APIs and provides the runtime services, and in return your code contains very little infrastructure plumbing. Understanding this division of responsibility — what the container does for you and what it expects from you — is the foundation for everything else in this subject, and it also explains a good deal about how Spring and MicroProfile are designed.
From J2EE to Jakarta EE
The platform has been renamed twice, and the names still cause confusion, so it is worth fixing the timeline.
| Release | Year | Notable content |
|---|---|---|
| J2EE 1.2 – 1.4 | 1999 – 2003 | Servlets, JSP, EJB 1.x/2.x with home interfaces and XML descriptors, JMS, JTA, JAX-RPC |
| Java EE 5 | 2006 | Annotations replace most descriptors, EJB 3.0, the Java Persistence API (JPA) 1.0, JSF 1.2 |
| Java EE 6 | 2009 | CDI 1.0, EJB 3.1 (no-interface view, singletons), JAX-RS 1.1, Bean Validation, the Web Profile |
| Java EE 7 | 2013 | JMS 2.0 simplified API, WebSocket, JSON-P, Batch, Concurrency Utilities, JTA @Transactional |
| Java EE 8 | 2017 | JSON-B, the Java EE Security API 1.0, Servlet 4.0 with HTTP/2 push, JAX-RS 2.1 |
| Jakarta EE 8 | 2019 | Same APIs as Java EE 8, now governed by the Eclipse Foundation; javax.* packages |
| Jakarta EE 9 / 9.1 | 2020 / 2021 | Package namespace changed to jakarta.*; old pruned APIs removed; Java 11 support |
| Jakarta EE 10 | 2022 | First feature release under Eclipse: CDI 4.0 with CDI Lite, Core Profile, Servlet 6, Faces 4, Persistence 3.1, REST 3.1 |
| Jakarta EE 11 | 2025 | Java 17 baseline, Jakarta Data 1.0, further pruning of legacy APIs |
The rename happened because Oracle transferred the specifications and reference code to the Eclipse Foundation in 2017 but kept the Java trademark. The javax package prefix was part of that trademark, so the community had no choice but to rename every package. That is why Jakarta EE 9 is a breaking release with no new features: javax.servlet.http.HttpServletRequest became jakarta.servlet.http.HttpServletRequest, javax.persistence.Entity became jakarta.persistence.Entity, and so on for every specification. Deployment-descriptor XML namespaces changed at the same time, from http://xmlns.jcp.org/xml/ns/javaee to https://jakarta.ee/xml/ns/jakartaee.
This guide targets Jakarta EE 10 and uses jakarta.* throughout. When you read older material — and most enterprise Java code in production was written against Java EE 6, 7 or 8 — mentally substitute the prefix; the class and method names are otherwise the same.
The tier and container model
Jakarta EE describes an application as a set of components distributed over logical tiers. The tiers are conceptual; two of them often share one process, and in most modern deployments all server-side tiers live in a single application server instance.
- Client tier — a browser, a mobile app, another service calling a REST endpoint, or a Java desktop client. The platform still defines an application client container for the last case, but it is rarely used today.
- Web tier — servlets, Faces pages, Jakarta REST resources and WebSocket endpoints. These components receive requests, translate them into calls on the business tier and render the response.
- Business tier — enterprise beans and CDI beans that implement the use cases, run inside transactions and enforce security rules.
- Enterprise information system (EIS) tier — relational databases, message brokers, mainframes and other back ends reached through JDBC, JMS or connector (JCA) resource adapters.
What makes this more than a layered-architecture diagram is the container: the runtime that hosts a component type and sits between the component and the outside world. Because your servlet or bean is instantiated and invoked by the container, it can:
- inject dependencies (
@Inject,@EJB,@PersistenceContext,@Resource) before your code runs; - begin and commit a transaction around each business method;
- check that the caller holds a required role;
- pool instances, manage thread access and passivate idle state;
- apply interceptors and life-cycle callbacks (
@PostConstruct,@PreDestroy).
The web container hosts servlets, filters, listeners, JSP pages, Faces views, REST resources and WebSocket endpoints. The enterprise-bean container hosts session beans and message-driven beans. Both share the CDI container for dependency injection and contextual scopes, plus platform services such as JNDI naming, JTA transactions and the security subsystem. The practical consequence: never instantiate a managed component with new. A new OrderService() is a plain object with no injected fields, no transaction and no security context; only container-created instances get those.
What the server actually provides
An application server is the product that implements the specifications. Vendors compete on management tooling, clustering, performance and support, not on the APIs your code compiles against. The services every compliant server has to supply include:
| Service | Specification | What you use it for |
|---|---|---|
| Naming | JNDI (part of Java SE) | Look up data sources, JMS destinations and beans by name |
| Transactions | Jakarta Transactions | Declarative or programmatic ACID boundaries, including XA across several resources |
| Persistence | Jakarta Persistence | Object-relational mapping with a container-managed EntityManager |
| Messaging | Jakarta Messaging | Queues and topics, message-driven beans |
| Web | Servlet, Pages, Faces, REST, WebSocket | HTTP request handling and rendering |
| Injection and scopes | CDI, Dependency Injection | Wiring components, request/session/application scopes, events |
| Security | Jakarta Security, Authentication, Authorization | Authentication mechanisms, identity stores, role checks |
| Concurrency | Jakarta Concurrency | Managed executors and scheduled tasks that keep the container context |
| Integration | Connectors (JCA), Mail | Resource adapters for legacy systems, sending e-mail |
Resources such as data sources are configured in the server and exposed to your code through JNDI names, so the same WAR runs in test and production with different credentials and no rebuild. @DataSourceDefinition lets an application declare its own data source, which is convenient for demos but puts credentials in code.
import jakarta.annotation.Resource;
import jakarta.enterprise.context.ApplicationScoped;
import javax.sql.DataSource;
@ApplicationScoped
public class HealthCheck {
// The container resolves this JNDI name at injection time.
@Resource(lookup = "java:/jdbc/OrdersDS")
DataSource dataSource;
public boolean databaseReachable() {
try (var connection = dataSource.getConnection()) {
return connection.isValid(2);
} catch (Exception e) {
return false;
}
}
}
Profiles: Platform, Web and Core
Not every application needs all of that, and requiring a full-platform server for a small web app was one of the reasons Java EE lost ground to lighter stacks in the 2000s. Since Java EE 6 the platform defines profiles, and Jakarta EE 10 has three:
- Jakarta EE Platform — everything.
- Web Profile — the web tier plus what a typical web application needs behind it: Servlet, Pages, Expression Language, Faces, CDI, Bean Validation, Persistence, Transactions, REST, JSON-P/JSON-B, WebSocket, Security, Concurrency (added to the profile in EE 10) and EJB Lite: local session beans, container-managed transactions, interceptors, declarative security and non-persistent timers, but no remote interfaces, no message-driven beans and no JMS.
- Core Profile — new in EE 10 and aimed at microservice frameworks and ahead-of-time compilation: CDI Lite, REST, JSON-P, JSON-B, Annotations, Dependency Injection and Interceptors. MicroProfile builds on this profile.
The choice affects your Maven dependency. Compile against the API artifact for the profile you target and let the server provide it at runtime:
<dependency>
<groupId>jakarta.platform</groupId>
<artifactId>jakarta.jakartaee-web-api</artifactId> <!-- or jakarta.jakartaee-api for the full platform -->
<version>10.0.0</version>
<scope>provided</scope>
</dependency>
The provided scope matters. If you bundle the API classes — or worse, an implementation such as Hibernate — inside a WAR deployed to a server that already ships them, you get class-loading conflicts that are painful to diagnose.
Packaging and deployment
Jakarta EE applications are deployed as archives with a fixed internal layout, and the container reads both annotations and optional XML descriptors to discover components.
- WAR (web archive) —
WEB-INF/classesfor your classes,WEB-INF/libfor libraries,WEB-INF/web.xml(optional since Servlet 3.0),WEB-INF/beans.xml(optional in CDI 4, which discovers annotated beans by default),META-INF/persistence.xmlinsideclassesfor JPA. Since Java EE 6 a WAR may contain enterprise beans directly; this is by far the most common packaging today. - EJB JAR — enterprise beans only, with an optional
META-INF/ejb-jar.xml. - EAR (enterprise archive) — a wrapper containing WARs, EJB JARs, resource adapters (RAR) and shared libraries in
lib/, described byMETA-INF/application.xml. Use it only when you genuinely need several modules to share libraries and be deployed as one unit; it complicates class loading and most teams no longer need it.
The Servlet 6.0 web.xml header shows the current namespace and version:
<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
https://jakarta.ee/xml/ns/jakartaee/web-app_6_0.xsd"
version="6.0">
<session-config>
<session-timeout>30</session-timeout>
</session-config>
</web-app>
Descriptors override annotations, which is the intended way to change environment-specific settings — a security constraint, a servlet init parameter, a session timeout — without touching source.
Portable JNDI names
Since Java EE 6 every session bean gets standard JNDI names, so you can look one up from anywhere without vendor-specific syntax:
java:global/<app-name>/<module-name>/<bean-name>[!<fully-qualified-interface>]
java:app/<module-name>/<bean-name>
java:module/<bean-name>
For a bean OrderService in shop.war deployed standalone, the global name is java:global/shop/OrderService. The java:comp/env namespace holds the component's own environment entries (@Resource injection points), and java:comp/UserTransaction and java:comp/DefaultDataSource are standard entries that every server provides. Injection has made explicit lookups rare, but you will still meet them in older code and in remote clients.
Choosing a server or runtime
All Jakarta EE 10 compatible products pass the same Technology Compatibility Kit, so the API behaviour is the same; the differences are operational.
| Product | Profile | Notes |
|---|---|---|
| Eclipse GlassFish 7 | Platform | The compatible implementation used to ratify the specifications; good for learning, less common in production |
| WildFly (27+) | Platform | Red Hat's community server, basis of JBoss EAP; also offers a "preview" feature pack and a bootable-JAR packaging |
| Open Liberty | Platform | IBM's modular runtime; features are switched on per application, fast startup, basis of WebSphere Liberty |
| Payara Server / Micro | Platform | GlassFish-derived with commercial support; Payara Micro runs a WAR from the command line |
| Apache TomEE 10 | Web Profile / Platform variants | Tomcat plus OpenEJB, OpenJPA/Hibernate, ActiveMQ, CXF |
| Apache Tomcat 10.1 / Jetty 12 | Servlet, Pages, EL, WebSocket only | Not Jakarta EE servers; you bring the rest as libraries |
In practice the choice is decided by what your operations team already runs and patches, whether you need commercial support (JBoss EAP, WebSphere Liberty and Payara Enterprise are the supported editions of WildFly, Open Liberty and Payara), and how you deploy: all of these servers can be baked into a container image with the application, and WildFly's bootable JAR or Payara Micro produce a single executable much like a Spring Boot jar. If you only use servlets, JPA and REST, a Web Profile runtime — or Tomcat plus libraries — may be the pragmatic answer.
Where Spring and MicroProfile fit
Spring began in 2003 as a reaction to EJB 2.x, whose home interfaces, mandatory checked exceptions and XML descriptors made simple things laborious. Java EE 5 and 6 absorbed most of Spring's ideas — annotations, dependency injection, plain-object components — into EJB 3 and CDI. Today the relationship is symbiotic rather than competitive: Spring Framework 6 and Spring Boot 3 depend on Jakarta EE 9+ APIs for the servlet layer, JPA, Bean Validation, JMS and JTA, and simply provide their own container instead of relying on an application server. If you understand the specifications, you understand a large part of what Spring auto-configures; the Spring subject covers that side.
MicroProfile is a sibling set of Eclipse specifications that adds what cloud-native services need on top of the Core Profile — configuration, health, metrics, OpenAPI, a REST client, fault tolerance, JWT propagation — and is implemented by Open Liberty, Payara, WildFly, Quarkus and Helidon. Knowing CDI and Jakarta REST carries over to all of them.
Migrating javax to jakarta
Because the Jakarta EE 9 rename is mechanical, tooling can do most of it:
Upgrade the runtime and the API dependency
Move to a Jakarta EE 9.1+ server (or Tomcat 10.1+, Jetty 11+) and switch thejakarta.jakartaee-api(or per-specification) dependency to a 9.1 or 10 version.Rewrite imports and descriptors
Run the Eclipse Transformer or an OpenRewrite recipe over the source tree. They rewritejavax.*imports for the affected packages, XML namespaces and property names such asjavax.persistence.jdbc.url, while leaving Java SE packages likejavax.sqlandjavax.naminguntouched, since those never moved.Update every library that touches the APIs
Hibernate 6, Jersey 3, RESTEasy 6, Mojarra 4, EclipseLink 4 and Spring 6 are the Jakarta-namespace lines. A single transitive dependency still importingjavax.servletwill fail at runtime withNoClassDefFoundError, so scan the dependency tree.Check for removed APIs
Servlet 6.0 removed long-deprecated types such asSingleThreadModelandHttpSessionContext; Faces 4.0 removed@ManagedBeanand JSP views; Enterprise Beans 4.0 dropped EJB 2.x entity beans and JAX-RPC endpoints. Code using them must be rewritten, not just re-imported.
Tomcat's migration guide describes a variant of the same approach: Tomcat 10 can transform legacy WARs on the fly, which buys time but should not be the long-term plan.
Common mistakes
- Bundling an implementation the server already provides. Packaging
hibernate-coreor a Jakarta REST implementation inside a WAR for WildFly or Liberty produces two copies of the same classes in different class loaders and errors likeClassCastException: OrderEntity cannot be cast to OrderEntity. Useprovidedscope for APIs and let the server supply implementations, unless the server documents how to override its version. - Mixing
javaxandjakartaartifacts. A project half-migrated compiles and then fails at deployment. Grep the dependency tree, not just your own imports. - Treating tiers as physical. Splitting the web tier and business tier into separate servers connected by remote enterprise-bean calls was fashionable in the J2EE era and is almost always slower and harder to operate than one process. Keep them together unless you have a measured reason.
- Configuring resources in the application. Hard-coded connection URLs in
persistence.xmlor@DataSourceDefinitionwork on a laptop and then leak credentials into version control. Define data sources and JMS destinations in the server and reference them by JNDI name. - Using an EAR out of habit. One WAR is simpler to build, deploy and debug. Reach for an EAR only when you have several modules that must be versioned together.
Key takeaways
- Jakarta EE is a set of specifications; an application server implements them and runs your components inside containers that inject dependencies, manage transactions and enforce security.
- The lineage is J2EE, then Java EE 5–8, then Jakarta EE 8 (same APIs), 9 (
javax.*becomesjakarta.*, no new features), 10 (first feature release) and 11. - Jakarta EE 10 defines three profiles — Platform, Web and Core — so you can target only what you need; the Web Profile covers most web applications.
- Compile against the
jakarta.jakartaee-apiorjakarta.jakartaee-web-apiartifact withprovidedscope and let the server provide implementations. - Package as a WAR whenever possible; use portable
java:globalJNDI names and server-side resource definitions rather than hard-coded configuration. - GlassFish, WildFly, Open Liberty, Payara and TomEE are compatible implementations; Tomcat and Jetty implement only the servlet family.
- Spring and MicroProfile are built on the same specifications, so the knowledge transfers in both directions.
Sources and further reading
Frequently asked questions
- Is Jakarta EE the same thing as Java EE?
- It is the continuation of Java EE under the Eclipse Foundation. Jakarta EE 8 is functionally identical to Java EE 8 and still uses javax.* packages. From Jakarta EE 9 onwards the packages moved to jakarta.*, which is why libraries and servers written for Java EE 8 do not run unchanged on a Jakarta EE 9+ server.
- Do I need an application server, or is Tomcat enough?
- Tomcat and Jetty implement only the servlet, JSP, EL and WebSocket specifications. If you need CDI, JPA, JTA, JMS, enterprise beans or Jakarta REST from the container itself, use a Web Profile or full Platform server such as WildFly, Open Liberty, Payara, GlassFish or TomEE. Frameworks such as Spring Boot bring their own implementations of several of those specifications and so can run on Tomcat.
- What is the difference between the Web Profile and the full Platform?
- The Web Profile is a subset targeted at web applications: servlets, Faces, CDI, JPA, JTA, Bean Validation, Jakarta REST, JSON, WebSocket, Security, Concurrency and a reduced enterprise-bean feature set called EJB Lite. The full Platform adds messaging (JMS), connectors, mail, batch, remote and message-driven beans and more. The Core Profile, new in Jakarta EE 10, is even smaller and is aimed at microservice runtimes.
- Should new projects use Jakarta EE or Spring Boot?
- Both are viable. Jakarta EE gives you vendor-neutral standards, a managed runtime and less framework code in your application; Spring Boot gives you a larger ecosystem, faster release cadence and easier stand-alone packaging. Spring 6 itself is built on Jakarta EE 9+ APIs (Servlet, JPA, Bean Validation), so the specifications you learn here transfer directly.