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:
git clone https://github.com/openrewrite/spring-petclinic-migration.git
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
<plugin>
  <groupId>org.openrewrite.maven</groupId>
  <artifactId>rewrite-maven-plugin</artifactId>
  <version>4.31.1</version>
</plugin>
build.gradle
plugins {
    id("java")
    id("org.openrewrite.rewrite") version("5.26.1")
}
​
repositories {
  // The root project doesn't have to be a Java project, but this is necessary
  // to resolve recipe artifacts.
  mavenCentral()
}
​
rewrite {
    // Will configure in subsequent steps
}
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.
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
<plugin>
  <groupId>org.openrewrite.maven</groupId>
  <artifactId>rewrite-maven-plugin</artifactId>
  <version>4.31.1</version>
  <configuration>
    <activeRecipes>
      <recipe>org.openrewrite.java.format.AutoFormat</recipe>
    </activeRecipes>
  </configuration>
</plugin>
build.gradle
plugins {
    id("java")
    id("org.openrewrite.rewrite") version("5.26.1")
}
​
rewrite {
    activeRecipe("org.openrewrite.java.format.AutoFormat")
}
With AutoFormat activated we can now apply it to the project. Run:
Maven
Gradle
./mvnw rewrite:run
./gradlew rewriteRun
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
---
type: specs.openrewrite.org/v1beta/recipe
name: com.yourorg.VetToVeterinary
recipeList:
  - org.openrewrite.java.ChangePackage:
      oldPackageName: org.springframework.samples.petclinic.vet
      newPackageName: org.springframework.samples.petclinic.veterinary
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
<build>
  <plugins>
    <plugin>
      <groupId>org.openrewrite.maven</groupId>
      <artifactId>rewrite-maven-plugin</artifactId>
      <version>4.31.1</version>
      <configuration>
        <activeRecipes>
          <recipe>org.openrewrite.java.format.AutoFormat</recipe>
          <recipe>com.yourorg.VetToVeterinary</recipe>
        </activeRecipes>
      </configuration>
    </plugin>
  </plugins>
</build>
build.gradle
    plugins {
        id("java")
        id("org.openrewrite.rewrite") version("5.26.1")
    }
    
    rewrite {
        activeRecipe(
            "org.openrewrite.java.format.AutoFormat",
            "com.yourorg.VetToVeterinary")
    }
Run ./mvnw rewrite:run or ./gradlew rewriteRun to perform the package relocation. Afterward 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 that contains Spring, Mockito, JUnit, and AssertJ-related refactoring recipes.
1.Add the rewrite-recipe-bom to manage versions of various Rewrite artifacts
2.Add a rewrite dependency on rewrite-spring
3.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
<build>
  <plugins>
    <plugin>
      <groupId>org.openrewrite.maven</groupId>
      <artifactId>rewrite-maven-plugin</artifactId>
      <version>4.31.1</version>
      <configuration>
        <activeRecipes>
          <recipe>org.openrewrite.java.format.AutoFormat</recipe>
          <recipe>com.yourorg.VetToVeterinary</recipe>
          <recipe>org.openrewrite.java.spring.boot2.SpringBoot2JUnit4to5Migration</recipe>
        </activeRecipes>
      </configuration>
    <plugin>
  </plugins>
<build>
...
<dependencyManagement>
  <dependencies>
      <dependency>
          <groupId>org.openrewrite.recipe</groupId>
          <artifactId>rewrite-recipe-bom</artifactId>
          <version>1.4.0</version>
          <type>pom</type>
          <scope>import</scope>
      </dependency>
  </dependencies>
</dependencyManagement>
...
<dependencies>
  <dependency>
    <groupId>org.openrewrite.recipe</groupId>
    <artifactId>rewrite-spring</artifactId>
  </dependency>
</dependencies>
build.gradle
plugins {
    id("java")
    id("org.openrewrite.rewrite") version("5.26.1")
}
​
rewrite {
    activeRecipe(
        "org.openrewrite.java.format.AutoFormat",
        "com.yourorg.VetToVeterinary",
        "org.openrewrite.java.spring.boot2.SpringBoot2JUnit4to5Migration")
}
​
dependencies {
    implementation(platform("org.openrewrite.recipe:rewrite-recipe-bom:1.4.0"))
    rewrite("org.openrewrite.recipe:rewrite-spring")
​
    // Other project dependencies
}
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 2h ago

Export as PDF

Copy link

Outline

Step 1: Clone sample project

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

Step 3: Execute a Refactoring Recipe

Step 4: Execute a Recipe with Yaml Configuration

Step 5: Running Recipes from External Modules

Next Steps