Quickstart: Maven and Gradle

Following this guide you will learn:
How to apply the rewrite-maven-plugin to a Maven project
How to apply the rewrite-gradle-plugin to a Gradle project
How to configure, run, and inspect the results of built-in and external refactoring recipes
Step 1: Clone sample project
The sample spring-petclinic project is based on an older version of project that requires a JDK version 1.8 to build. Newer JDK versions will not work. Get OpenJDK 8 here if you do not already have one.
This guide uses a fork of spring-petclinic. Clone it by running:
1
git clone https://github.com/openrewrite/spring-petclinic-migration.git
Copied!
The steps in this guide are applicable to any Java project built with Maven or Gradle. Feel free to use your own project instead.
Step 2: Apply rewrite-maven-plugin or rewrite-gradle-plugin
In the pom.xml or build.gradle, add this entry to the plugins section to apply the rewrite plugin to the project.
Maven
Gradle
pom.xml
1
<plugin>
2
  <groupId>org.openrewrite.maven</groupId>
3
  <artifactId>rewrite-maven-plugin</artifactId>
4
  <version>4.23.0</version>
5
</plugin>
Copied!
build.gradle
1
plugins {
2
    id("java")
3
    
4
    id("org.openrewrite.rewrite") version("5.20.0")
5
}
6
​
7
repositories {
8
  // The root project doesn't have to be a Java project, but this is necessary
9
  // to resolve recipe artifacts.
10
  mavenCentral()
11
}
12
​
13
rewrite {
14
    // Will configure in subsequent steps
15
}
Copied!
When applied to a multi-project build, behavior differs depending on whether the plugin is applied to the root project or to a sub-project. Applied to the root project, the plugin will parse and refactor all sources from all projects. Applied to any project other than the root project, the plugin will parse and refactor only sources from that project.
Running on JDK 16 and newer
OpenRewrite requires access to Java compiler internals to function. JDK 16 and newer require explicit opt-in to access these internals via --add-exports. The are a few options for to setting explicit exports for packages used by rewrite's java parser.
Gradle
Maven opts
Maven Exec plugin
Maven Java Settings
In a gradle.properties file at the root of your project, add or update org.gradle.jvmargs to include this content:
gradle.properties
1
org.gradle.jvmargs= \
2
    --add-exports jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED \
3
    --add-exports jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED \
4
    --add-exports jdk.compiler/com.sun.tools.javac.comp=ALL-UNNAMED \
5
    --add-exports jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED \
6
    --add-exports jdk.compiler/com.sun.tools.javac.main=ALL-UNNAMED \
7
    --add-exports jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED
Copied!
Use the MAVEN_OPTS environment variable for passing the necessary exports to the jvm.
1
MAVEN_OPTS="--add-exports jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.comp=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.jvm=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.main=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.model=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.processing=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED"
Copied!
Use the Exec Maven Plugin to avoid setting the MAVEN_OPTS environment variable by executing rewrite in a separate process with a configured set of environment variables.
pom.xml
1
<plugin>
2
    <groupId>org.codehaus.mojo</groupId>
3
    <artifactId>exec-maven-plugin</artifactId>
4
    <version>3.0.0</version>
5
    <executions>
6
        <execution>
7
            <goals>
8
                <goal>exec</goal>
9
            </goals>
10
        </execution>
11
    </executions>
12
    <configuration>
13
        <executable>mvn</executable>
14
        <arguments>
15
            <argument>rewrite:run</argument>
16
        </arguments>
17
        <environmentVariables>
18
            <MAVEN_OPTS> --add-exports jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.comp=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.jvm=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.main=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.model=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.processing=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED</MAVEN_OPTS>
19
        </environmentVariables>
20
    </configuration>
21
</plugin>
Copied!
Define the exports in the ** _.mvn/jvm.config**_ file.
.mvn/jvm.config
1
--add-exports jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED
2
--add-exports jdk.compiler/com.sun.tools.javac.comp=ALL-UNNAMED
3
--add-exports jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED
4
--add-exports jdk.compiler/com.sun.tools.javac.jvm=ALL-UNNAMED
5
--add-exports jdk.compiler/com.sun.tools.javac.main=ALL-UNNAMED
6
--add-exports jdk.compiler/com.sun.tools.javac.model=ALL-UNNAMED
7
--add-exports jdk.compiler/com.sun.tools.javac.processing=ALL-UNNAMED
8
--add-exports jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED
9
--add-exports jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED
Copied!
At this point, you're able to run any of the Maven goals or Gradle tasks provided by the plugins. See Maven Plugin Configuration and Gradle Plugin Configuration for the full set of options. Try running ./mvnw rewrite:discover or ./gradlew rewriteDiscover to see a listing of all the recipes available for execution. Initially this will list only the recipes built-in to OpenRewrite.
Step 3: Execute a Refactoring Recipe
Before any recipe will be executed it must be listed as "active" in the plugin configuration. For the sake of example, we will activate the included org.openrewrite.java.format.AutoFormat recipe. This recipe will format the source code in the project according to the styles specified in the rewrite.yml file, or according to Jetbrains IntelliJ's default Java style if no other style is specified.
To configure this recipe to be active add this configuration to the plugin in the pom.xml or build.gradle:
Maven
Gradle
pom.xml
1
<plugin>
2
  <groupId>org.openrewrite.maven</groupId>
3
  <artifactId>rewrite-maven-plugin</artifactId>
4
  <version>4.23.0</version>
5
  <configuration>
6
    <activeRecipes>
7
      <recipe>org.openrewrite.java.format.AutoFormat</recipe>
8
    </activeRecipes>
9
  </configuration>
10
</plugin>
Copied!
build.gradle
1
plugins {
2
    id("java")
3
    id("org.openrewrite.rewrite") version("5.20.0")
4
}
5
​
6
rewrite {
7
    activeRecipe("org.openrewrite.java.format.AutoFormat")
8
}
Copied!
With AutoFormat activated we can now apply it to the project. Run:
Maven
Gradle
1
./mvnw rewrite:run
Copied!
1
./gradlew rewriteRun
Copied!
Console output from running ./mvnw rewrite:run with AutoFormat set as an active recipe on spring-petclinic-migration
Run git diff, or use your preferred IDE's diff viewer, to inspect the changes.
Sample of formatting changes made to spring-petclinic-migration by AutoFormat
That's all you need to do to run zero-configuration recipes like AutoFormat. But some recipes require you to tell them what you want them to do.
Step 4: Execute a Recipe with Yaml Configuration
The built-in recipe org.openrewrite.java.ChangePackage will move Java classes between package names you specify and update references and imports accordingly. To rename the org.springframework.samples.petclinic.vet package to org.springframework.samples.petclinic.veterinary, create a rewrite.yml file at the project root and give it these contents:
rewrite.yml
1
---
2
type: specs.openrewrite.org/v1beta/recipe
3
name: com.yourorg.VetToVeterinary
4
recipeList:
5
  - org.openrewrite.java.ChangePackage:
6
      oldPackageName: org.springframework.samples.petclinic.vet
7
      newPackageName: org.springframework.samples.petclinic.veterinary
Copied!
Yaml files are very sensitive to indentation. If you find a recipe you've configured in yaml not producing the expected result, double-check that its arguments are indented as shown here.
This creates a new recipe called com.yourorg.VetToVeterinary. Now add it to the active recipe list:
Maven
Gradle
pom.xml
1
<plugin>
2
  <groupId>org.openrewrite.maven</groupId>
3
  <artifactId>rewrite-maven-plugin</artifactId>
4
  <version>4.23.0</version>
5
  <configuration>
6
    <activeRecipes>
7
      <recipe>org.openrewrite.java.format.AutoFormat</recipe>
8
      <recipe>com.yourorg.VetToVeterinary</recipe>
9
    </activeRecipes>
10
  </configuration>
11
</plugin>
Copied!
build.gradle
1
plugins {
2
    id("java")
3
    id("org.openrewrite.rewrite") version("5.20.0")
4
}
5
​
6
rewrite {
7
    activeRecipe(
8
        "org.openrewrite.java.format.AutoFormat",
9
        "com.yourorg.VetToVeterinary")
10
}
Copied!
Run ./mvnw rewrite:run or ./gradlew rewriteRun to perform the package relocation. Afterwards you'll see both that the sources in the vet package have been moved to the new directory, and references such as import statements have been updated accordingly.
Git diff showing updated import statements
You can test that spring-petclinic-migrations still builds & passes its tests by running ./mvnw clean install or ./gradlew build. At this point you know how to configure and run any recipe included in rewrite itself.
Step 5: Running Recipes from External Modules
Not all rewrite recipes are bundled into the core libraries. In this example we'll use rewrite-spring, a rewrite-maintained module which contains spring, mockito, junit, and assertJ related refactoring recipes.
1.Add a rewrite dependency on rewrite-spring
2.Set the org.openrewrite.java.spring.boot2.SpringBoot2JUnit4to5Migration recipe as active.
After applying these steps, the relevant portions of your build file will look like this:
Maven
Gradle
pom.xml
1
<plugin>
2
  <groupId>org.openrewrite.maven</groupId>
3
  <artifactId>rewrite-maven-plugin</artifactId>
4
  <version>4.23.0</version>
5
  <configuration>
6
    <activeRecipes>
7
      <recipe>org.openrewrite.java.format.AutoFormat</recipe>
8
      <recipe>com.yourorg.VetToVeterinary</recipe>
9
      <recipe>org.openrewrite.java.spring.boot2.SpringBoot2JUnit4to5Migration</recipe>
10
    </activeRecipes>
11
  </configuration>
12
  <dependencies>
13
    <dependency>
14
      <groupId>org.openrewrite.recipe</groupId>
15
      <artifactId>rewrite-spring</artifactId>
16
      <version>4.19.3</version>
17
    </dependency>
18
  </dependencies>
19
</plugin>
Copied!
build.gradle
1
plugins {
2
    id("java")
3
    id("org.openrewrite.rewrite") version("5.20.0")
4
}
5
​
6
rewrite {
7
    activeRecipe(
8
        "org.openrewrite.java.format.AutoFormat",
9
        "com.yourorg.VetToVeterinary",
10
        "org.openrewrite.java.spring.boot2.SpringBoot2JUnit4to5Migration")
11
}
12
​
13
dependencies {
14
    rewrite("org.openrewrite.recipe:rewrite-spring:4.19.3")
15
​
16
    // Other project dependencies
17
}
Copied!
Run ./mvnw rewrite:run or ./gradlew rewriteRun and observe that the project has been upgraded to Spring Boot 2 and the test classes are all updated to be JUnit 5 tests. If you're using Maven, the pom.xml will also have had the Spring dependencies updated, the Junit 4 dependency removed and Junit 5 dependencies added. OpenRewrite does not yet support automatic update of Gradle dependencies. Gradle users will have to manually make the corresponding changes.
If you want to know when dependency management for Gradle will be added to rewrite, follow this issue on our roadmap.
Next Steps
Now that you're up and running with the rewrite-maven-plugin, you may be interested in these topics:
​Writing a Java Refactoring Recipe​
​Maven Plugin Configuration​
​Gradle Plugin Configuration​
​Declarative YAML Format​

Introduction to OpenRewrite

Next - Getting Started

Recipe Development Environment

Last modified 28d ago

Export as PDF

Copy link

Contents

Step 1: Clone sample project

Step 2: Apply rewrite-maven-plugin or rewrite-gradle-plugin

Running on JDK 16 and newer

Step 3: Execute a Refactoring Recipe

Step 4: Execute a Recipe with Yaml Configuration

Step 5: Running Recipes from External Modules

Next Steps