Java EE to Jakarta EE Migration in Liferay: What You Need to Know

Introduction

The enterprise Java landscape just shifted in a way that changes how every Liferay user company should think about their digital experience platform. With Liferay DXP 2025.Q3 already live on Jakarta EE 10 and Liferay Portal CE 2026.Q1 following the same path, running on the legacy javax.* namespace is no longer a long-term option.

This is not a routine update. It is a foundational re-platforming that touches your application server, Java runtime, and every line of custom code that uses enterprise APIs. Companies that plan it well come out faster, more secure, and architecturally cleaner. Companies that defer it inherit a steeper bill and growing security exposure.

What Is Jakarta EE, and Why the Rename

Java EE was governed by Oracle for two decades. In 2017, stewardship moved to the Eclipse Foundation. Because Oracle retained the Java trademark, every package had to be renamed from javax.* to jakarta.*. The wider ecosystem, including Tomcat, WildFly, JBoss EAP, Hibernate, and Spring, has already made the jump. Liferay is now aligning with that reality.

Why Liferay Is Moving to Jakarta EE 10

Three forces made this transition inevitable :

• Application server alignment : Tomcat 10.1, WildFly 26 and 30, and JBoss EAP 8 only run on Jakarta EE. Staying on legacy app servers means staying on shrinking patch windows.
• Java 21 as the strategic runtime : Liferay recommends JDK 21 for its performance gains, which translate directly into smaller cloud instances and lower hosting costs.
• Vendor support timelines : Liferay 2025.Q1 is the last LTS release on Java EE. After its support window closes, legacy deployments enter a much higher risk profile.

Who This Affects

• SaaS customers are largely insulated, especially when customizations use Liferay Objects or Client Extensions.
• PaaS and self-hosted customers carry the full weight. Any custom OSGi modules, portlets, hooks, themes, and third-party libraries using javax.* need a structured Liferay version migration.

What Actually Changes

The migration touches several layers at once :

• Namespace shift : Every javax.* reference becomes jakarta.*. The Portlet spec moves from 3.0 to Jakarta Portlet 4.0.
• Dependency updates : Hibernate, Jackson, Log4j, and other libraries need Jakarta-compatible versions.
• Application server migration : Tomcat 9 to Tomcat 10.1, JBoss EAP 7 to EAP 8, with config and clustering review.
• Database and config references : The Liferay upgrade process handles internal references, but custom templates and scripts need manual attention.
• Frameworks needing manual care : JSF and Spring Portlet code is not fully covered by the automated tooling.

Common Challenges

A useful portal migration strategy plans for these upfront :

1. Hidden javax.* dependencies, especially reflection-based references that fail only at runtime.
2. Third-party libraries with no Jakarta release.
3. Source Formatter exceptions during the upgrade tool run, which are informational rather than blockers.
4. Regression risk across SSO, ERP, CRM, and analytics integrations.
5. Operations lag while new app server environments are provisioned and certified.

How to Upgrade Your Liferay Project

Liferay ships an official upgrade tool through Blade CLI that handles most of the work in three steps.

Step 1 : Update Workspace and Dependencies

In settings.gradle, set the workspace plugin to 14.0.0 or higher.

1dependencies {
2    classpath group: "com.liferay",
3              name: "com.liferay.gradle.plugins.workspace",
4              version: "14.0.0"
5}

In gradle.properties, set the target platform.

liferay.workspace.target.platform.version=2025.q3.0

Step 2 : Run the Liferay Jakarta Upgrade Tool

From the project root :

blade gw upgradeJakarta

The tool scans Gradle scripts, bnd.bnd, Java sources, JSPs, and language.properties, replacing javax with jakarta and upgrading portlets to Jakarta Portlet 4.0. The table below summarizes the key changes.

Step 3 : Handle Third-Party Dependencies

The recommended approach is to replace each library with its Jakarta version. For example :

1// Old
2runtimeOnly "org.apache.logging.log4j:log4j-web"

1// New
2runtimeOnly "org.apache.logging.log4j:log4j-jakarta-web"

When no Jakarta release exists, the Eclipse Transformer can rewrite an existing JAR. Liferay does not support production deployments that rely on transformer-rewritten libraries, so use this only as a last resort.

A DXP Migration Checklist

The most successful Liferay migration services treat this as four phases :

• Discovery and assessment : Inventory custom modules, audit javax.* usage, catalogue third-party libraries, document app server configuration, and scope any Liferay content migration needs across Web Content, Documents and Media, and custom Asset types.
• Strategy and planning : Pick the target version, choose between in-place and side-by-side migration, set a code freeze window, and build a deployment-layer rollback plan.
• Execution : Run the upgrade tool, refactor what it cannot handle, swap dependencies, migrate the app server, and run the database upgrade.
• Validation and optimization : Full regression testing, performance baseline on Java 21, integration validation, and opportunistic refactoring into Liferay Objects and Client Extensions.

Liferay Upgrade ROI

Framing the work as cost alone misses the bigger picture. The real return shows up in four areas :

• Security posture : Modern app servers and JDK 21 close CVE gaps and reduce audit overhead.
• Cloud economics : Java 21 efficiency translates into smaller instances and lower monthly spend.
• Talent access : Modern frameworks attract and retain stronger developers.
• Roadmap optionality : Jakarta EE 10 unlocks Liferay Objects, Client Extensions, and headless APIs, making every future Liferay platform upgrade cheaper than the last.

A well-scoped migration typically pays back in 18 to 24 months.

When to Bring in a Liferay Upgrade Consultant

External help is usually justified when you have ten or more custom modules, your team has not done a major Liferay platform upgrade in three years, you rely heavily on JSF or Spring Portlet, or your environment has strict SLAs. A seasoned Liferay upgrade consultant sequences the work, defends the budget, and identifies where Liferay Objects and Client Extensions can replace fragile custom code.

Looking Ahead

The shift from Java EE to Jakarta EE separates organizations that treat Liferay as a long-term strategic asset from those that treat it as a static system. The technical work is real, the timeline is finite, and the modernization opportunity is too valuable to defer. Companies that approach this with structured enterprise migration planning will be ready for Java 21, headless architectures, and the next wave of AI-enabled experiences. The question is not whether to migrate. It is how to make this migration the moment that future-proofs your platform for the decade ahead.

Planning your Liferay Jakarta EE migration? Start with a complete assessment of your custom modules, third-party dependencies, and integration footprint, then build a phased roadmap that aligns the technical work with measurable business outcomes.