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

This guide uses a fork of spring-petclinic. Clone it by running:

git clone https://github.com/openrewrite/spring-petclinic-migration.git

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.

pom.xml
<plugin>
  <groupId>org.openrewrite.maven</groupId>
  <artifactId>rewrite-maven-plugin</artifactId>
  <version>4.0.0</version>
</plugin>

build.gradle
plugins {
    id("java")
    id("org.openrewrite.rewrite").version("4.0.0")
}
​
rewrite {
    // Will configure in subsequent steps
}

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. Until we add dependencies on recipe-providing modules 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, in this step 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:

pom.xml
<plugin>
  <groupId>org.openrewrite.maven</groupId>
  <artifactId>rewrite-maven-plugin</artifactId>
  <version>4.0.0</version>
  <configuration>
    <activeRecipes>
      <recipe>org.openrewrite.java.format.AutoFormat</recipe>
    </activeRecipes>
  </configuration>
</plugin>

build.gradle
plugins {
    id("java")
    id("org.openrewrite.rewrite").version("4.0.0")
}
​
rewrite {
    activeRecipe("org.openrewrite.java.format.AutoFormat")
}

With AutoFormat activated we can now apply it to the project. Run:

./mvnw rewrite:run

./gradlew rewriteRun

Run git diff, or use your preferred IDE's diff viewer, to inspect the changes.

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:
      oldFullyQualifiedPackageName: org.springframework.samples.petclinic.vet
      newFullyQualifiedPackageName: org.springframework.samples.petclinic.veterinary

This creates a new recipe called com.yourorg.VetToVeterinary. Now add it to the active recipe list:

pom.xml
<plugin>
  <groupId>org.openrewrite.maven</groupId>
  <artifactId>rewrite-maven-plugin</artifactId>
  <version>4.0.0</version>
  <configuration>
    <activeRecipes>
      <recipe>org.openrewrite.java.format.AutoFormat</recipe>
      <recipe>com.yourorg.VetToVeterinary</recipe>
    </activeRecipes>
  </configuration>
</plugin>

build.gradle
plugins {
    id("java")
    id("org.openrewrite.rewrite").version("4.0.0")
}
​
rewrite {
    activeRecipe(
        "org.openrewrite.java.format.AutoFormat",
        "com.yourorg.VetToVeterinary")
}

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.

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

To run recipes from a rewrite module that isn't part of the core rewrite libraries, add a plugin dependency on the module to your pom.xml. In this example we'll use rewrite-spring, a rewrite-provided module which contains spring, mockito, junit, and assertJ related refactoring recipes.

1. Add an appropriately scoped 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:

pom.xml
<plugin>
  <groupId>org.openrewrite.maven</groupId>
  <artifactId>rewrite-maven-plugin</artifactId>
  <version>4.0.0</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>
  <dependencies>
    <dependency>
      <groupId>org.openrewrite.recipe</groupId>
      <artifactId>rewrite-spring</artifactId>
      <version>4.0.2</version>
    </dependency>
  </dependencies>
</plugin>

build.gradle
plugins {
    id("java")
    id("org.openrewrite.rewrite").version("4.0.0")
}
​
rewrite {
    activeRecipe(
        "org.openrewrite.java.format.AutoFormat",
        "com.yourorg.VetToVeterinary",
        "org.openrewrite.java.spring.boot2.SpringBoot2JUnit4to5Migration")
}
​
dependencies {
    compileOnly("org.openrewrite.recipe:rewrite-spring:4.0.2")
​
    // 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. Rewrite does not yet support automatic update of Gradle dependencies. Gradle users will have to manually make the corresponding changes.

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​