Javax to Jakarta migration (was Re: [VOTE] Apache TomEE 9.0.0)

Moving this to the user list so other users can benefit.

> On Jan 5, 2023, at 1:02 AM, Alex The Rocker <[email protected]> wrote:
> 
> Le mer. 4 janv. 2023 à 21:28, Jean-Louis Monteiro
> <[email protected]> a écrit :
>> 
>> Hi Alexandre,
>> 
>> After some experiments, this tool is so limited that we decided to neither
>> advise nor support it. It's then not embedded in TomEE.
>> I wrote some notes here https://tomee.apache.org/javax-to-jakarta.html
>> 
>> Hope it helps
>> 
> Thanks Jean-Louis for your answer,
> 
> So it looks like https://github.com/apache/tomcat-jakartaee-migration
> is the recommended to migrate an EE 8 war archive into an Jakarta EE 8
> equivalent.
> Is that correct ?
> 
> if so then i'll try it to see if TomEE 9.0.0 works with our web apps

Here’s the approach I’d recommend:

 - migrate the source code for anything under your control
 - upgrade libraries to jakarta.* versions where they exist
 - use bytecode transformation as a last resort for libraries where no jakarta.* alternative exists (expect it won’t always work)

The big issue with bytecode transformation tools is 1) there is always logic and text references they cannot handle, and 2) the input and output is binary so when they don’t work, you can’t see why and you’re basically stuck with no visibility on how to move forward.

If you’d like to see some of the edge cases we hit in TomEE when we did our bytecode transformation approach, here’s a list of the 144 javax references that remained in code after several weeks of working with bytecode transformation tools:

 - https://github.com/dblevins/tomee-analysis/blob/ba5fb8caa917a4030e789f881e69d8079aa1df79/README.adoc

There was also another 5883 references in plain text (non-class files).  All of these had to be manually investigated and resolved on a case-by-case basis.  We ended up creating the TomEE Patch Plugin so we could patch the source code of individual files to resolve the  hardest edge cases.

We spent a little over a year going down the 100% bytecode transformation approach until we ultimately abandoned it and spent another year going down the source code approach with bytecode transformation used only by exception.  If I had to do it all over again, I’d skip trying to go 100% bytecode transformed and save that year.

Hindsight.

If people want to copy the bytecode approach we took, here’s where you’d look:

 - https://github.com/apache/tomee/tree/main/deps

Essentially, we created a module in our build where we could have a pom.xml for each individual jar that needed to be transformed because there was no jakarta version.  Each uses the Eclipse Transformer and some of those have patched sources being applied afterwards by the TomEE Patch Plugin.  We’re not very happy with having that module there as it dramatically increase the build time, it messes with IDEs and the Eclipse Transformer’s heavy debug output makes running maven with -X almost unusable.  But, it’s the best of the worst options.

Hope some of this helpful.


-David