Javax to Jakarta Migration: Finest Practices

By 2 months ago

Upgrading to Jakarta EE 9 or newer from an older model of Jakarta EE or Java EE generally is a bit tough with the javax to jakarta prefix change. Some libraries could also be nonetheless utilizing the javax bundle, which might trigger conflicts when attempting to run your purposes on a Jakarta EE server like Eclipse GlassFish 7. You’ll probably encounter the identical points when upgrading to Spring Framework 6 or Spring Boot 3, Quarkus 3, and newer variations of many different frameworks, which now rely on Jakarta EE 9 APIs.

However don’t fear, I’ve obtained you coated! On this put up, I’ll clarify the whole lot that you must know to improve to Jakarta EE 9+ efficiently and in nearly no time. By Jakarta EE 9+, I imply both Jakarta EE 9 or 10, which is presently the most recent model of Jakarta EE.

Current Instruments To Automate Improve Steps

Happily, most of the challenges will be automated utilizing free and open-source instruments like Openrewrite, WindUp, and Eclipse Transformer. Openrewrite is a robust software that may mechanically make modifications to your software’s supply code, corresponding to updating all references to the outdated javax packages with the brand new jakarta prefix.

Eclipse Transformer can do the identical job, however it could actually additionally rework the ultimate JAR, WAR, or EAR binary information in case your undertaking shouldn’t be prepared for supply code transformation but. That is helpful in case you simply need to strive working your older software on a Jakarta EE 9+ runtime.

All these instruments can prevent effort and time when upgrading to Jakarta EE 9+, permitting you to give attention to different necessary points of your software’s improvement. Nonetheless, it is nonetheless necessary to assessment and check the modifications made by these instruments to make sure that they do not introduce any unintended penalties.

Remodel Functions With Eclipse Transformer

I like to recommend beginning each migration with Eclipse Transformer so that you could rapidly confirm whether or not your software will be migrated to a Jakarta EE 10 runtime with out modifications or establish potential issues for the migration. Utilizing Eclipse Transformer may additionally be important within the later levels of your migration, particularly in case your software depends on dependencies that aren’t but suitable with Jakarta EE 9+ or if it’s dangerous to improve them to a suitable model. In the long run, reworking your software with Eclipse Transformer earlier than you deploy it to a Jakarta EE 9+ runtime can work as a security internet, detecting and reworking any remaining courses and information that rely on older API packages. You possibly can maintain utilizing Eclipse Reworked till you’re completely positive the whole lot in your software has been migrated.

To exhibit the convenience of utilizing Eclipse Transformer, we at OmniFish have ready a pattern software undertaking at javax-jakarta-transform-whole-war. This undertaking showcases find out how to apply Eclipse Transformer to the construct of a Maven undertaking.

The important thing ingredient to making use of the transformation in a Maven undertaking is the Maven plugin transformer-maven-plugin. This plugin will be put in as an extension, after which it could actually hook into the usual Maven construct mechanism and modify the ultimate construct artifact.  

The Maven plugin gives two targets:

  1. jar – this aim transforms software packages, like JAR, WAR, and EAR information. It could both modify them in place or create their reworked model in a separate file
  2. rework – this aim transforms directories (earlier than they’re packed into JAR, WAR, or different software packages). It may be used on exploded directories earlier than they’re deployed to an app server

The instance software makes use of each plugin targets. The jar aim is used to rework the ultimate artifact file, which is required to deploy the file later or deploy it to a Maven repository. The rework aim is optionally available and is used to rework the exploded listing, which is commonly used throughout improvement by numerous IDEs to deploy the appliance. Utilizing the rework aim is optionally available however makes it simpler to develop the appliance and deploy it simply out of your IDE till it’s absolutely migrated to Jakarta EE 9 and Eclipse Transformer is required no extra.

Apart from utilizing it as a Maven plugin, Eclipse Transformer will be additionally used on the command line and thus with any undertaking or a steady integration system. 

To run Eclipse Transformer on the command line, first obtain the org.eclipse.transformer.cli distribution JAR file from Maven Central. Then, unpack this JAR, for instance, right into a folder named transformer. Then you possibly can rework your software file, for instance, jakarta-ee-8-app.struggle, into a brand new software file jakarta-ee-10-app-transformed.struggle with the next command:

java -jar transformer/org.eclipse.transformer.cli-0.5.0.jar jakarta-ee-8-app.struggle jakarta-ee-10-app-transformed.struggle

The file to rework does not should be a WAR file. It may be a listing, WAR, JAR, and plenty of different bundle varieties that the Eclipse Transformer helps.

You’ll find extra info on find out how to use Eclipse Transformer on the command line on the Github project. Nonetheless, generally, you wouldn’t want the rest; the software does an excellent job, even with the default choices.

Remodel Dependencies Incompatible With jakarta Prefix

Now, you may have to improve or rework particular person libraries utilized by your software. This solves two issues. First, it improves the construct time of your software throughout improvement by eradicating the step to rework the ultimate binary after every construct. Second, it solves compilation issues you possibly can face with some libraries after you modify the supply code of your software for Jakarta EE 9.

Libraries which have a model suitable with Jakarta EE 9 will be merely up to date to this model. Many of the libraries extensively utilized in enterprise initiatives already help Jakarta EE 9. Nonetheless, some libraries keep help for each Jakarta EE 9+ and older Jakarta EE and Java EE variations. These libraries have two variants for a similar library model. You will want to decide on the variant that helps Jakarta EE 9+. In case you use Maven, then, generally, you may want to make use of the jakarta classifier like this:

<dependency>
  <groupId>org.primefaces</groupId>
  <artifactId>primefaces</artifactId>
  <model>13.0.0</model>
  <classifier>jakarta</classifier>
</dependency>

Nevertheless it’s not the case for each library. Some libraries present the Jakarta EE 9 suitable Maven artifact beneath fully completely different coordinates, and you will want to perform a little research to search out them. 

When it’s not doable to improve a library, you possibly can rework particular person libraries with the Eclipse Transformer utilizing an identical method to remodeling the entire software WAR, which we defined in a earlier article. You should utilize the Eclipse Transformer additionally on particular person library JARs after which use the reworked JARs in the course of the construct. Nonetheless, in fashionable Maven or Gradle-based initiatives, this isn’t simple due to transitive dependencies. There’s presently no tooling that might correctly rework all of the transitive dependencies mechanically and set up them accurately to a neighborhood repository. However you need to use a trick – you possibly can merge all JARs that should be reworked right into a single JAR (Uber JAR) with all of the transitive dependencies, then rework it, after which set up this single JAR right into a Maven repository. Then, you’ll solely want to vary the appliance POM file to rely on this single artifact as an alternative of relying on all the person artifacts that had been reworked.

You’ll have to create a brand new Maven undertaking, e.g., transform-depenendencies, subsequent to our current undertaking. Then transfer all of the dependencies that you must rework into this new undertaking. Then take away all these dependencies from the unique undertaking and substitute them with a single dependency on the brand new transform-depenendencies undertaking.

Within the last WAR file, as an alternative of getting every JAR file individually within the WAR, like this:

  • WEB-INF
    • courses
      • jasperreports.jar
      • quartz.jar

We’ll find yourself with a single reworked JAR like this:

  • WEB-INF
    • courses
      • transform-dependencies.jar

This transform-dependencies.jar file will comprise all of the artifacts merged into it – it would comprise all courses and information from all of the artifacts. 

So as to obtain this, we will use the Maven Shade plugin, which merges a number of JAR information right into a single artifact produced by the undertaking:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-shade-plugin</artifactId>
  <model>3.5.0</model>
  <executions>
    <execution>
      <section>bundle</section>
      <targets>
        <aim>shade</aim>
      </targets>
      <configuration>
        <shadedClassifierName>jakarta</shadedClassifierName>
        <shadedArtifactAttached>true</shadedArtifactAttached>
        <transformers>
          <transformer implementation="org.apache.maven.plugins.shade.useful resource.ServicesResourceTransformer"/>
          <transformer implementation="org.apache.maven.plugins.shade.useful resource.ManifestResourceTransformer"/>
        </transformers>
      </configuration>
    </execution>
  </executions>
</plugin>

This plugin takes all of the dependencies outlined within the undertaking, merges them right into a single Uber JAR, and attaches the JAR to the undertaking as an artifact with the jakarta classifier. 

Now we add the Transformer plugin to rework the Uber JAR to make it suitable with Jakarta EE 9+. We have to configure the Transformer plugin with the next:

  • execute the aim “jar”
  • use the “jakartaDefaults” rule to use transformations for Jakarta EE 9
  • outline artifact with the classfier “jakarta” produced by the shade maven plugin. This may have the identical groupId, artifactId and model as the present undertaking

You will have to construct the transform-dependencies undertaking solely as soon as with mvn set up to rework the dependencies right into a single artifact in your native Maven repository. Once you construct the unique software undertaking, it would use the reworked Uber JAR and add it to the ultimate WAR as an alternative of all particular person (untransformed) JARs. After all, this can probably introduce compilation failures as a result of your supply code nonetheless makes use of the Javax prefix. There’s a straightforward answer to repair that, which I am going to describe within the subsequent part.

Remodel Utility Supply Code

Sure, you can repair the compilation errors in your supply code manually or with some easy find-and-replace mechanism. However I do not advocate that. Not all packages with the “javax.” prefix ought to be reworked; useful resource information like XML descriptors additionally should be reworked, and so forth. It is a lot simpler and extra bulletproof to make use of automation instruments designed to rework code for Jakarta EE 9. 

There are two free instruments that may assist us right here:

  1. Eclipse Transformer – we used it earlier to rework the ultimate software, nevertheless it’s additionally able to reworking Java supply information and assets
  2. Openrewrite – a software that may mechanically make modifications to your software’s supply code primarily based on specified guidelines. It incorporates guidelines for Jakarta EE 9.

I like to recommend utilizing Eclipse Transformer additionally for this step as a result of it has a extra full set of transformation guidelines for Jakarta EE 9 than Openrewrite and might rework some useful resource information that Openrewrite ignores. Nonetheless, the tip outcome may be very related even with Openrewrite. You’ll simply have to make a couple of extra handbook modifications to the supply code in case you use it as an alternative. I’ll describe find out how to use each of those instruments so that you could select which ones you’d like to make use of.

For a single software, you’ll want to rework the supply code solely as soon as. It’s not price altering the undertaking configuration only for this single step. Due to this fact we’ll describe find out how to use Eclipse Transformer on the command line to do that with out including any Maven plugin or configuration to your undertaking. This additionally means you could apply this process in case you use another construct software aside from Maven, e.g., Gradle. 

Observe these steps to rework the supply code of your software:

  1. Obtain Eclipse Transformer CLI distribution artifact from Maven Central. Obtain the distribution.jar file of the most recent model, not the plain jar file. For the model 0.5.0, right here’s the direct obtain hyperlink: org.eclipse.transformer.cli-0.5.0-distribution.jar 
  2. Unpack the JAR file into some listing, e.g. /path/to/transformer
  3. Go to your software’s undertaking listing.
  4. Run the next to rework the src listing (with supply code, assets, check code and assets, and so forth…) to output_src listing: java -jar /path/to/transformer/org.eclipse.transformer.cli-0.5.0.jar src
  5. Transfer the contents of the output_src listing into src (overwrite information). On Linux and Mac OS, you need to use RSync command line software: rsync -a output_src/* src
  6. Edit pom.xmlmanually as a result of the Eclipse Transformer does not do that:
    • Enhance the Jakarta EE model to 9.0.0 or 10.0.0, in order that your undertaking depends upon the next dependency (or an equal Net Profile or Core Profile dependency):
      • <dependency>
        <groupId>jakarta.platform</groupId>
        <artifactId>jakarta.jakartaee-api</artifactId>
        <model>10.0.0</model>
        <scope>supplied</scope>
        </dependency>

As an alternative choice to utilizing Eclipse Transformer, you need to use Openrewrite to rework your software supply code to be suitable with Jakarta EE 9. 

Making use of OpenRewrite may be very simple. If you have already got Maven put in, you possibly can simply use it as a Maven plugin configured on the command line (word that your undertaking does not should be Maven-based, Maven is barely required to run the transformation):

  1. Go to the appliance’s undertaking listing
  2. Execute the next command:
    • mvn -U org.openrewrite.maven:rewrite-maven-plugin:run
      -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-migrate-java:LATEST
      -Drewrite.activeRecipes=org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakarta

This may modify your software in place. Theoretically, it ought to be doable to construct it now, and all ought to work as anticipated. However, primarily based on my expertise, I needed to apply a couple of fixes in a Maven-based WAR undertaking in pom.xml, internet.xml, and Java annotations, which I did not have to do after utilizing the Eclipse Transformer.

Conclusion

After performing these steps, your software ought to be fully suitable with Jakarta EE 9. You possibly can take away the transformation of your last software to avoid wasting construct time if all of the non-transformed dependencies are suitable with Jakarta EE 9.

We wanted to do these three steps:

  1. (optionally available step) Remodel the ultimate software utilizing Eclipse Transformer and check if it runs with Jakarta EE 9+ server or framework.
  2. Improve dependencies to variations suitable with Jakarta EE 9.
  3. Remodel dependencies utilizing Eclipse Transformer if they can not be upgraded to Jakarta EE 9.
  4. Remodel the appliance supply code utilizing Eclipse Transformer or OpenRewrite.
  5. (optionally available step) Take away transformation of the ultimate software.

In spite of everything these steps are finished, it is best to be capable to construct your software now. It ought to compile efficiently and work nicely in case you deploy it on a Jakarta EE 9+ server or run it together with your framework of selection. Your undertaking is absolutely reworked into Jakarta EE 9+, and you’ll proceed engaged on it as earlier than, as if it was designed for Jakarta EE 9+ because the starting.

Tags: , , ,