Migrating from Java EE to Jakarta EE in a Liferay Environment

By the transition of Java EE (Enterprise Edition) to Eclipse Foundation as Jakarta EE, we need to adapt the jakarta.* namespace, and we all are needed who uses Liferay or any java frameworks to migrate our application from java.* to jakarta.* package namespace.

Also, Liferay officially announced to migrate Java EE to Jakarta EE from the Liferay DXP 7.4 2025.Q3 and later releases and we also need to adapt Jakarta when we migrate or create projects on Liferay DXP 7.4 2025.Q3 or later release versions.

So, let’s understand what is Jakarta EE, why we need to migrate Java EE to Jakarta EE, challenges on migrations and advantages of migrations in detail through this blog.

We are all familiar with the Java EE but have little confusion about Jakarta. Let’s understand first about the difference between Java EE and Jakarta EE.

What is Jakarta EE and How Is It Different from Java EE?

Java EE is the standard platform for building enterprise Java applications, and it’s managed by Oracle. In 2017, Oracle handed over ownership to the Eclipse Foundation, where it became Jakarta EE. After this transition, Eclipse used jakarta.* instead of the javax.* due to trademark restrictions. 

Why is Liferay moving Java to Jakarta EE 10? 

1. For supporting the latest application servers like Tomcat 10.1, JBoss EAP 8.0

2. Jakarta EE provides the following benefits:

3. Enhanced features

4. Performance improvements

5. Updated security features

6. Better stability

Why do we need to migrate our projects from Java EE to Jakarta EE? 

If you are using Liferay and you have custom portlet, modules or hooks for extending functionalities, then you need to migrate your modules for the following reasons:

1. Use javax.* packages on your custom code

2. Support or connect with Third-party libraries

3. Compatibility with upcoming Liferay releases

4. Security and maintainability of your platform

Common challenges in the migration of Jakarta EE to a Liferay Environment

The following challenges are generally faced in a migration process

1. Namespace Changes

2. Face difficulty in identifying javax.* dependencies

3. Complex refactoring of legacy code

4. Compatibility issues with third-party libraries

5. Lake of knowledge about Jakarta EE

6. Testing and Validation

How to Upgrade to Jakarta

For the upgrading to Jakarta, it is an easy and straightforward process as Liferay provide the tools (Blade command) to assist you. A Liferay workspace and Blade is used to upgrade your projects to Jakarta. 

There are three steps to upgrade your Liferay project to Jakarta: 

1. Update Workspace and Dependencies  

2. Run Liferay Jakarta upgrade tool on Liferay project 

3. Handle third-party dependencies with Jakarta

Update Workspace and Dependencies

As the first step we need to update our supported workspace version on the settings.gradle file. As per the Liferay need to define minimum 14.0.0 version of our project workspace.

By using the following link, we can find out the correct versions of Liferay workspace.

 
dependencies { 
  classpath group: "com.liferay", name: "com.liferay.gradle.plugins.workspace", version: "14.0.0" 
} 

We can also define the latest.release as a version of the Liferay workspace, like:

 
dependencies { 
  classpath group: "com.liferay", name: "com.liferay.gradle.plugins.workspace", version: "latest.release" 
}

Note: If you define latest.release as a version of Liferay workspace, by this probably sometimes happen some issues when new releases will come. This is because the workspace will automatically pick up the latest release.

Now open the gradle.properties file and define liferay.workspace.target.platform.version.

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

Note: It is recommended to use liferay.workspace.target.platform.version=2025.q3.0 or higher version. The first step is completed, now run the upgrade Jakarta tool.

Run Liferay Jakarta upgrade tool on Liferay project

Liferay provide the blade command for the upgrade project code from javax.* to jakarta.*

• Go to root path of your project’s directory
• Open the terminal
• Run the following command for Jakarta upgrade tool

blade gw upgradeJakarta

You might see the warnings and exceptions like:

 
WARNING: Setting property "java.parser.enabled" to "false" may prevent certain Java/JSP checks 
from working properly. 

java.util.concurrent.ExecutionException: java.util.concurrent.ExecutionException: java.lang.RuntimeException: Unable to format /home/st28062405/Projects/LR-upgrade/git/Jakarta-LR/modules/jakarta-test/bnd.bnd

        at java.util.concurrent.FutureTask.report(FutureTask.java:122) 
        at java.util.concurrent.FutureTask.get(FutureTask.java:192) 
        at com.liferay.source.formatter.SourceFormatter.format(SourceFormatter.java:418) 
        at com.liferay.source.formatter.SourceFormatter.main(SourceFormatter.java:303) 
  

Don’t worry, this is not an issue. This exception is related to the Source Formatter. If you haven’t configured the Source Formatter, then you may get these exceptions. To avoid it, simply configure the Source Formatter in your Liferay workspace, or you can ignore it.

After completing the process of this upgrade tool, it’s replaced javax reference find in Gradle, bnd.bnd, Java, and language.properties files with the appropriate jakarta reference everywhere in your project.

import jakarta.portlet.Portlet;
import org.osgi.service.component.annotations.Component;

@Component(
    property = {
        "com.liferay.portlet.display-category=category.sample",
        "com.liferay.portlet.header-portlet-css=/css/main.css",
        "com.liferay.portlet.instanceable=true",
        "jakarta.portlet.display-name=JakartaTest",
        "jakarta.portlet.init-param.template-path=/",
        "jakarta.portlet.init-param.view-template=/view.jsp",
        "jakarta.portlet.name=" + JakartaTestPortletKeys.JAKARTATEST,
        "jakarta.portlet.resource-bundle=content.Language",
        "jakarta.portlet.security-role-ref=power-user,user"
    },
    service = Portlet.class
)
public class JakartaTestPortlet extends MVCPortlet {
}

Bundle-Name: jakarta-test
Bundle-SymbolicName: com.stpl.lr.upgrade.jakarta.web
Bundle-Version: 1.0.0
Export-Package: com.stpl.lr.upgrade.jakarta.web.constants
Provide-Capability:\
    liferay.language.resources;\
    resource.bundle.base.name="content.Language"

jakarta.portlet.title.com_stpl_lr_upgrade_jakarta_web_JakartaTestPortlet=JakartaTest
jakartatest.caption=Hello from JakartaTest!

When we run this tool, then it also upgrades our portlet code from Portlet 3.0 to Jakarta Portlet 4.0

Let’s looks around the which changes are done on the portlet classes by the running this tool:

If you don't want to use Jakarta Upgrade Tool for the upgrade of your project and prefer to do it manually then take care of the above changes in the portlet.

Handle third-party dependencies with Jakarta

If you are using any third-party dependencies in your project, then you also need to upgrade those dependencies.

We have two approaches to replacing third-party dependencies in your project:

• Find out the Jakarta-compatible dependency
• Use Eclipse Transformer

Let’s look at both approaches and understand which is better for us

Find out the Jakarta-compatible dependency

Identify and replace the existing dependency with the Jakarta-compatible version of the dependency.

For Example:

Let’s consider the popular Log4j dependency and when we are upgrading our project in Jakarta then also, we need to replace this dependency which supported with Jakarta. We are using the following dependency when we use javax version.

    
runtimeOnly "org.apache.logging.log4j:log4j-web"

To upgrade to it on the jakarta version, we need to use following dependency:

    
runtimeOnly "org.apache.logging.log4j:log4j-jakarta-web"

After replacing this dependency, verify the imports and functionality are working properly.

This approach is the best and recommended way. If in case, you are not able to find the relevant dependency then you can find another similar dependency which provide the same functionality with Jakarta.

Use Eclipse Transformer

You can use Eclipse Transformer to modify the binary .jar file to support Jakarta. You can choose this option as a last way. This way is not a recommended way, and we are not sure by using this, that .jar will work correctly or not. If you don't have any other ways, then you can just try using the Eclipse Transformer.

For Eclipse Transformer, you must use to two properties files which provided by Liferay:

1. https://github.com/liferay/liferay-portal/blob/master/modules/liferay-jakarta-renames.properties
2. https://github.com/liferay/liferay-portal/blob/master/modules/liferay-jakarta-versions.properties

Download these two files and below steps to use Eclipse Transformer:

• Download the Eclipse Transformer.
• The Transformer is shipped as a .jar file you must unzip to use. Unzip the .jar file to its own folder.
• Download the two properties files above to the same folder.
• Copy the .jar file which you want to transform into the same folder.
• Go to this folder and open the terminal.
• Run the following command, make sure you replace [name] for the name of the .jar file you’re transforming

    
    java -jar org.eclipse.transformer.cli-1.0.0.jar --renames ./liferay-jakarta-renames.properties 
    --versions ./liferay-jakarta-versions.properties ./[name].jar ./[name]-transformer.jar
    

Note: Liferay does not support applications which we use JAR files that have been transformed this way.

I will share here more updates, once the Liferay officially launch the Liferay 2025.q3 server with Jakarta support

Conclusion

At Surekha Technologies, we bring years of experience working with Liferay DXP and Java Ecosystem including Java EE. With this experience on hand, we help teams to plan and get ready for the Jakarta EE shift for their Liferay DXP.

After Oracle transferred ownership to the Eclipse Foundation, the namespace was shifted from javax.* to jakarta.* due to trademark restrictions. With the Liferay DXP 7.4 2025.Q3 release, Liferay has also adopted Jakarta EE. Transitioning from Java EE to Jakarta EE in Liferay brings several advantages, such as improved performance, stronger security, access to the latest features, and better compatibility with third-party libraries.

To make this migration easier, Liferay offers the Jakarta Upgrade Tool, which streamlines the process of updating projects to Jakarta EE. However, if the Liferay Source Formatter is not configured, you may encounter formatting-related exceptions during the upgrade. This can be resolved by either configuring the source formatter or simply ignoring those exceptions if they do not affect your implementation.