Refactoring with Declarative YAML Recipes

Not every refactoring operation requires a brand new imperative Recipe to be authored in code. With declarative YAML Recipes many powerful transformations can be achieved without writing any code. In this tutorial we'll use declarative YAML recipes to rename a package relocation and update downstream projects to reflect the updated package names.
In this tutorial we'll assume the existence of two projects, A and B, in different repositories:
Project A will contain the package we will rename from com.yourorg.foo to com.yourorg.bar
Project B will depend on A and use classes from the com.yourorg.foo package.
Renaming in Project A
First, apply a OpenRewrite build plugin per the Quickstart: Maven and Gradle.
With a OpenRewrite build plugin applied, create a rewrite.yml at the project root with these contents:
A/rewrite.yml
1
---
2
type: specs.openrewrite.org/v1beta/recipe
3
name: com.yourorg.FooToBar
4
recipeList:
5
  - org.openrewrite.java.ChangePackage:
6
      oldPackageName: com.yourorg.foo
7
      newPackageName: com.yourorg.bar
Copied!
Now that a recipe named "com.yourorg.FooToBar" has been created set that recipe as active in your build plugin's configuration:
Gradle
Maven
A/build.gradle
1
plugins {
2
    id("java")
3
    id("org.openrewrite.rewrite") version("5.22.2")
4
}
5
​
6
rewrite {
7
    activeRecipe("com.yourorg.FooToBar")
8
}
Copied!
A/pom.xml
1
<project>
2
  <build>
3
    <plugins>
4
      <plugin>
5
        <groupId>org.openrewrite.maven</groupId>
6
        <artifactId>rewrite-maven-plugin</artifactId>
7
        <version>4.25.0</version>
8
        <configuration>
9
          <activeRecipes>
10
            <recipe>com.yourorg.FooToBar</recipe>
11
          </activeRecipes>
12
        </configuration>
13
      </plugin>
14
    </plugins>
15
  </build>
16
</project>
Copied!
Run mvn rewrite:run or gradlew rewriteRun to apply the transformation to project A. Source files referencing the old package will be updated. Sources that were part of the com.yourorg.foo package will also be moved to directories corresponding to the new package name.
Updating Downstream Projects
A has been updated, but this is a breaking change to any projects that depend on A, such as project B. To help those projects adapt to this package relocation painlessly we can redistribute this recipe to them inside of the next release of A.
Begin by creating a YAML file inside of A/src/main/resources/META-INF/rewrite. The name of this file does not matter so long as its extension is "yml". We'll call it rewrite.yml for simplicity. It has the exact same contents as the rewrite.yml at the project root:
A/src/main/resources/META-INF/rewrite/rewrite.yml
1
---
2
type: specs.openrewrite.org/v1beta/recipe
3
name: com.yourorg.FooToBar
4
recipeList:
5
  - org.openrewrite.java.ChangePackage:
6
      oldPackageName: com.yourorg.foo
7
      newPackageName: com.yourorg.bar
Copied!
Now when the next version of A is published its jar will include this recipe. Assuming we've just published A version 2.0 with this recipe inside it, we can now use this recipe in project B.
Gradle
Maven
B/build.gradle
1
plugins {
2
    id("java")
3
    id("org.openrewrite.rewrite") version("5.22.2")
4
}
5
​
6
dependencies {
7
    implementation("com.yourorg:A:2.0")
8
}
9
​
10
rewrite {
11
    activeRecipe("com.yourorg.FooToBar")
12
}
Copied!
B/pom.xml
1
<project>
2
  <dependencies>
3
    <dependency>
4
      <groupId>com.yourorg</groupId>
5
      <artifactId>A</artifactId>
6
      <version>2.0</version>
7
    </dependency>
8
  </dependencies>
9
  <build>
10
    <plugins>
11
      <plugin>
12
        <groupId>org.openrewrite.maven</groupId>
13
        <artifactId>rewrite-maven-plugin</artifactId>
14
        <version>4.25.0</version>
15
        <configuration>
16
          <activeRecipes>
17
            <recipe>com.yourorg.FooToBar</recipe>
18
          </activeRecipes>
19
        </configuration>
20
      </plugin>
21
    </plugins>
22
  </build>
23
</project>
Copied!
Run mvn rewrite:run or gradlew rewriteRun to apply the transformation to project B. Note that we didn't have to create a rewrite.yml in project B because it found the recipe directly from its dependency on A version 2.0. So In only a few minutes, we've applied a refactoring operation to a project and its consumer and development on both can continue, effectively minimizing the pain and disruption brought by the breaking change.
Recipes will never be applied just because they exist on the classpath. A Recipe must be explicitly activated in the build plugin's configuration to be applied. This helps to avoid being surprised by unexpected changes to your source code.
Next Steps
​Declarative YAML Format​
​Writing a Java Refactoring Recipe​

Tutorials & Guides - Previous

Modifying Methods with JavaTemplate

Next - Tutorials & Guides

Automating Maven Dependency Management

Last modified 3d ago

Export as PDF

Copy link

Contents

Renaming in Project A

Updating Downstream Projects

Next Steps