Introduction

On March 18th, 2025, Liferay sent an email to clients and partners outlining the roadmap for migrating from Java EE to Jakarta EE that is coming in the 2025.Q3 release. It’s a necessary step Liferay has to take to be compatible with the latest versions of the supported application servers, and there’s lots of benefits that will come with this change…

I’m not going into those advantages here; this post is all about planning for the changes… For that info, I’d suggest the following:

• https://liferay.dev/blogs/-/blogs/java-evolution-is-here

• https://liferay.dev/blogs/-/blogs/liferay-s-java-roadmap-for-2025

The biggest impact that you’ll face is the namespace changes, namely switching from javax.* over to jakarta.*. The challenge, of course, is going to be finding all of the places where this change will need to take place.

The change itself is going to be pretty straightforward. Classes like javax.servlet.http.HttpServletRequest have been moved to jakarta.servlet.http.HttpServletRequest.

Liferay is in negotiations to migrate the Java Portlet specification to Jakarta. If this happens, portlets will move from javax.portlet.* to jakarta.portlet.*, requiring code updates across existing implementations.

When you update dependencies, obviously your Java compiles will point to locations where you need to make some package changes and those will be easy to resolve.

Other changes are not going to be so obvious and will take some searching on your part to find and resolve references.

For example, say for some reason you have a line of code like:

Object obj = Class.forName(“javax.portlet.GenericPortlet”);

The compiler is not going to flag this as an error, but at runtime you’ll face a ClassNotFoundException.

Same kind of deal for, say, portlet war files and their corresponding XML files. Or your logging configuration overrides where you’re hoping to get output from system packages. Or your JSP files that have import declarations on classes that were moved, or the new URLs for the TLD (Tag Library Descriptor) files that change. Or your FreeMarker templates and Groovy scripts that reference old names. Or having to rebuild ServiceBuilder and RESTBuilder services…

I hope by now you see that this change is going to be very important, but it’s also going to be a challenge and Liferay is already labeling it as a Breaking Change.

The major packages that are changing that will affect you are:

• Portlets
• Servlets
• JSPs
• JSP Tag Libraries
• JSTL
• JSF
• JPA Persistence
• Expression Language (EL)
• JAX-RS
• JAXB
• CDI
• Security
• Web Sockets
• JSON & JSON Binding
• JMS
• Mail
• Batch
• Concurrency
• Transactions

And what are the javax.* packages that aren’t changing?

• java.sql and javax.sql
• javax.naming
• javax.crypto
• javax.inject

Note that some of these, like javax.inject are from CDI, and most CDI packages are changing, but not this one. Same kind of deal with javax.crypto from Security.

My Proposed Plan for Jakarta Handling

So, first of all, this is going to be a Breaking Change, so you will need to treat this like a project. Have a project plan, have resources assigned, consider (if possible) a code freeze before you start the project (so you don’t have dual maintenance going on).

Next, wait. Really, you shouldn’t do anything now. It’s too early and we don’t know what kind of tooling Liferay may have to help you deal with the changes, so anything you do now might not be necessary when the time comes. So wait for the official 2025.Q3 release and any relevant tools, documentation, and maybe even blogs before you start your project.

Plan your production launch for 2026.Q1. That is the LTS release of Liferay that will have the full Jakarta support, and that also gives Liferay the 2025.Q3 and 2025.Q4 releases (the ones that only offer 1 year of support) time to fix bugs, upgrade processes, refine tools and documentation.

Use the 2025.Q3 release to start your upgrade project. You don’t want to be launching production on 2025.Q3, but you should use it to start doing your own upgrade of your database, your code, etc. The primary reason to start with 2025.Q3 is it allows you to open bugs with Liferay support and gives Liferay time to fix them so, when the 2026.Q1 LTS release comes out, you know that your issues will have been resolved.

My Proposal for JBoss Users

So I know many of you are concerned that JBoss 7.4 is EOL in June and there won’t be any support available for it. You really want this Liferay release so you can move onto JBoss 8 and continue your support contracts…

My recommendation though is really to follow the proposal I just laid out above.

Will you go without official JBoss support for some months? Yes. But ask yourselves how much this affects you? I mean, have you been keeping up with every JBoss 7.4 dot release? Applying all security patches and fixes? Are you regularly opening JBoss support tickets and getting fixes from them? Are you facing compliance requirements preventing the use of the EOL JBoss?

If you’re not saying yes to at least one of these questions, the EOL doesn’t matter because you haven’t been taking advantage of the support while it’s been available.

And if you have said yes, you’re in a tough spot. You need the JBoss 8 upgrade, but Liferay won’t be ready until the 2025.Q3 release, and that’s going to be the very first release with the Jakarta support. I know Liferay’s going to put a lot of time, effort and resources into testing the heck out of the release, but there will still be risk associated with the first release.

And, on top of that, you still have your own customizations and portlets and stuff to upgrade and test, and that too will take some time.

My guess is that, even if Liferay gets you an early cut of 2025.Q3 and you push really hard to upgrade, maybe you’re ready to launch production on 2025.Q4 (which historically has come out in December) and you then have 1 year from the release date to upgrade yet again (likely to the 2026.Q1 LTS release anyway).

So my recommendation is to just go with 2026.Q1 LTS also. It’s just a bit more time on the EOL JBoss 7.4, but then a single upgrade to 2026.Q1 LTS with time to get your upgrade done, tested and ready for the LTS release. It will save you money, time and resources.

My Proposal for Folks that Don't Want to Deal With This

If you just don't want to deal with this and you're on DXP, my recommendation is to stay on 2025.Q1 LTS. That will give you years of premium and extended support. If you update to 2025.Q2, you only get 1 year of support, so this can force you to upgrade whether you're ready to or not.

This may give you the time you need to properly assess and complete the upgrade while still getting production support for your 2025.Q1 LTS environment.

If you're a CE user, well you're going to want to stop at the Q2 release for CE. That will have the latest available fixes for you, but you won't be able to go further without addressing the jakarta namespace changes.

Conclusion

Well, that’s all I have for now. When I get a cut of the 2025.Q3 version, I’ll attempt some upgrades of projects I have and see if there is some additional guidance that might help, but I won’t be able to do that until I get my hands on it.

Until then, just know that this change is coming and remember it’s never too early to start planning…