01Before you start
What you need first
For what recipes do and where they stop, read OpenRewrite recipes for Java 21 and Spring Boot 3.
- A Git branch with a clean working tree, so the recipe diff is the sole change.
- A build that compiles and passes tests today. If it does not, fix that first; you cannot tell recipe damage from old damage.
- A JDK that can run the plugin. The plugin runs on the JDK your build uses, so the target JDK may need to be installed separately.
02Maven
Set up the OpenRewrite Maven plugin
You can skip editing the pom for a one-off try. Pass everything on the command line: mvn -U org.openrewrite.maven:rewrite-maven-plugin:dryRun -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-migrate-java:RELEASE -Drewrite.activeRecipes=org.openrewrite.java.migrate.UpgradeToJava21. Swap dryRun for run to apply it. RELEASE floats to the latest version, so use it for a trial, not a repeatable run.
Pin the plugin and module versions in the pom for any run you want to repeat. A moving version changes the recipe, and a recipe that changes between runs is no longer reproducible.
- 01
Add the plugin
In pom.xml, under build/plugins, add groupId
org.openrewrite.maven, artifactIdrewrite-maven-plugin, with a pinned version. - 02
Name the recipe
Inside the plugin configuration, add an activeRecipes list with one recipe:
<recipe>org.openrewrite.java.migrate.UpgradeToJava21</recipe>. - 03
Add the recipe module
Under the plugin's dependencies, add
org.openrewrite.recipe:rewrite-migrate-java. Recipes live in separate modules, not in the plugin. - 04
Run a dry run
Command:
mvn rewrite:dryRun. It changes no files and writes a patch totarget/rewrite/rewrite.patch. - 05
Run it for real
Command:
mvn rewrite:run. This edits source files in place.
03Gradle
Set up the OpenRewrite Gradle plugin
Task and file names are as of the current plugin documentation. Check the OpenRewrite docs for the version you use.
- 01
Apply the plugin
In build.gradle.kts:
id("org.openrewrite.rewrite") version "<latest>". Look up the current version on the Gradle plugin portal. - 02
Add the recipe module
In dependencies:
rewrite("org.openrewrite.recipe:rewrite-migrate-java:<version>"). Addrepositories { mavenCentral() }if missing. - 03
Name the recipe
Add
rewrite { activeRecipe("org.openrewrite.java.migrate.UpgradeToJava21") }. - 04
Dry run
Command:
./gradlew rewriteDryRun. The patch lands underbuild/reports/rewrite/. - 05
Run it for real
Command:
./gradlew rewriteRun.
04Versions
Why the recipe BOM matters
Recipe modules depend on each other and on the core engine. If you pin each module by hand, versions drift apart and you get odd errors. The rewrite-recipe-bom (org.openrewrite.recipe:rewrite-recipe-bom) is a bill of materials that fixes compatible versions together.
In Maven, import it in dependencyManagement as a pom with scope import, then add recipe modules without versions. In Gradle, add rewrite(platform("org.openrewrite.recipe:rewrite-recipe-bom:<version>")) and omit versions on the module lines. Update the BOM version as one change, and review the recipe diff again.
05Recipes
Run the Java 21 and Spring Boot 3 recipes
Run one recipe at a time on a Java 8 or 11 application: first the Java upgrade, build and test, then Spring Boot 3, build and test again. Spring Boot 3 requires Java 17 or later, so the order matters. Several recipes in one run give you one large diff and no way to tell which one broke the build.
See Spring Boot 3 migration and javax to jakarta for what the recipes leave behind.
| Goal | Recipe | Module |
|---|---|---|
| Java 21 migration | org.openrewrite.java.migrate.UpgradeToJava21 | rewrite-migrate-java |
| Spring Boot 3.3 | org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_3 | rewrite-spring |
| javax to jakarta | org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakarta | rewrite-migrate-java |
06Review
How to review the diff
- Read the patch from dryRun before you run anything. Check that it touches the files you expect and nothing more.
- After run, use git diff and look for changes to build files, properties and resource files, not just Java.
- Compile, then run the full test suite. Record failures; do not hide them with edits to the tests.
- Look for comment markers or TODO text a recipe may leave where it could not decide.
- Check behavior the tests do not cover: serialization formats, date handling, security configuration, startup flags.
- Commit the recipe output as its own commit, separate from your manual fixes, so a reviewer can see what the tool did.
07Next step
How Ace8 helps
Ace8 is the AI-assisted application modernization practice of AceMQ. We run these recipes first, then AI-assisted tools on what remains, then tests and engineer review. We are running the recipes above on an open-source Java 8, Spring Boot 2 and javax application and will publish the run log, including failures, on the OpenRewrite page. For a client estate, the assessment tells you which applications suit this approach.