Writing a Java Refactoring Recipe

In this tutorial, we'll create a basic refactoring recipe that adds a method returning aString to a user-specified class. This SayHelloRecipe will take a class like this:
1
package com.yourorg;
2
​
3
class A {
4
​
5
}
Copied!
And refactor it into a class like this:
1
package com.yourorg;
2
​
3
class A {
4
    public String hello() {
5
        return "Hello from com.yourorg.A!";
6
    }
7
​
8
}
Copied!
This guide assumes you've already set up your Recipe Development Environment.
Defining SayHelloRecipe
Begin by creating a class that extends org.openrewrite.Recipe. This recipe should accept as a configuration parameter the fully qualified name of the class to add a hello() method to and it should validate that parameter is configured with a valid value.
1
package org.openrewrite.samples;
2
​
3
import com.fasterxml.jackson.annotation.JsonCreator;
4
import com.fasterxml.jackson.annotation.JsonProperty;
5
import org.openrewrite.ExecutionContext;
6
import org.openrewrite.Option;
7
import org.openrewrite.Recipe;
8
import org.openrewrite.internal.lang.NonNull;
9
import org.openrewrite.java.JavaIsoVisitor;
10
import org.openrewrite.java.JavaTemplate;
11
import org.openrewrite.java.tree.J;
12
​
13
public class SayHelloRecipe extends Recipe {
14
    // Making your recipe immutable helps make them idempotent and eliminates categories of possible bugs
15
    // Configuring your recipe in this way also guarantees that basic validation of parameters will be done for you by rewrite
16
    @Option(displayName = "Fully Qualified Class Name",
17
            description = "A fully-qualified class name indicating which class to add a hello() method.",
18
            example = "com.yourorg.FooBar")
19
    @NonNull
20
    private final String fullyQualifiedClassName;
21
    public String getFullyQualifiedClassName() {
22
        return fullyQualifiedClassName;
23
    }
24
​
25
    // Recipes must be serializable. This is verified by RecipeTest.assertChanged() and RecipeTest.assertUnchanged()
26
    @JsonCreator
27
    public SayHelloRecipe(@NonNull @JsonProperty("fullyQualifiedClassName") String fullyQualifiedClassName) {
28
        this.fullyQualifiedClassName = fullyQualifiedClassName;
29
    }
30
​
31
    @Override
32
    public String getDisplayName() {
33
        return "Say Hello";
34
    }
35
​
36
    @Override
37
    public String getDescription() {
38
        return "Adds a \"hello\" method to the specified class";
39
    }
40
​
41
    // TODO: Override getVisitor() to return a JavaIsoVisitor to perform the refactoring
42
}
Copied!
The "discover" feature of the Gradle and Maven plugins will display information from the @Option annotation to users of your Recipe.
So now we have a Recipe implementation that validates that a single parameter is filled in with a non-blank value. It doesn't have any actual refactoring behavior yet, so that's what we'll add next.
Implementing the Visitor
To actually refactor the code in question we override Recipe.getVisitor() to return a new JavaIsoVisitor<ExecutionContext> instance that will actually perform the refactoring.
1
package org.openrewrite.samples;
2
​
3
import com.fasterxml.jackson.annotation.JsonCreator;
4
import com.fasterxml.jackson.annotation.JsonProperty;
5
import org.openrewrite.ExecutionContext;
6
import org.openrewrite.Option;
7
import org.openrewrite.Recipe;
8
import org.openrewrite.internal.lang.NonNull;
9
import org.openrewrite.java.JavaIsoVisitor;
10
import org.openrewrite.java.JavaTemplate;
11
import org.openrewrite.java.tree.J;
12
​
13
public class SayHelloRecipe extends Recipe {
14
    // Making your recipe immutable helps make them idempotent and eliminates categories of possible bugs
15
    // Configuring your recipe in this way also guarantees that basic validation of parameters will be done for you by rewrite
16
    @Option(displayName = "Fully Qualified Class Name",
17
            description = "A fully-qualified class name indicating which class to add a hello() method.",
18
            example = "com.yourorg.FooBar")
19
    @NonNull
20
    private final String fullyQualifiedClassName;
21
    public String getFullyQualifiedClassName() {
22
        return fullyQualifiedClassName;
23
    }
24
​
25
    // Recipes must be serializable. This is verified by RecipeTest.assertChanged() and RecipeTest.assertUnchanged()
26
    @JsonCreator
27
    public SayHelloRecipe(@NonNull @JsonProperty("fullyQualifiedClassName") String fullyQualifiedClassName) {
28
        this.fullyQualifiedClassName = fullyQualifiedClassName;
29
    }
30
​
31
    @Override
32
    public String getDisplayName() {
33
        return "Say Hello";
34
    }
35
​
36
    @Override
37
    public String getDescription() {
38
        return "Adds a \"hello\" method to the specified class";
39
    }
40
​
41
    @Override
42
    protected JavaIsoVisitor<ExecutionContext> getVisitor() {
43
        // getVisitor() should always return a new instance of the visitor to avoid any state leaking between cycles
44
        return new SayHelloVisitor();
45
    }
46
​
47
    public class SayHelloVisitor extends JavaIsoVisitor<ExecutionContext> {
48
        private final JavaTemplate helloTemplate =
49
                JavaTemplate.builder(this::getCursor, "public String hello() { return \"Hello from #{}!\"; }")
50
                        .build();
51
​
52
        @Override
53
        public J.ClassDeclaration visitClassDeclaration(J.ClassDeclaration classDecl, ExecutionContext executionContext) {
54
            // TODO: Filter out classes that don't need refactoring, refactor those that do
55
            return classDecl;
56
        }
57
    }
58
}
Copied!
Here we override JavaIsoVisitor.visitClassDeclaration in preparation for returning a modified class declaration that includes our new hello() method. The first step in any refactoring visit method is to avoid refactoring any class which the visitor should not change. In this case, that means any class that isn't the one specified in the recipe, or any class that already has a hello() method. Adding this filtering to SayHelloRecipe.SayHelloVisitor.visitClassDeclaration() looks like this:
1
@Override
2
public J.ClassDeclaration visitClassDeclaration(J.ClassDeclaration classDecl, ExecutionContext executionContext) {
3
    // In any visit() method the call to super() is what causes sub-elements of to be visited
4
    J.ClassDeclaration cd = super.visitClassDeclaration(classDecl, executionContext);
5
​
6
    if (classDecl.getType() == null || !classDecl.getType().getFullyQualifiedName().equals(fullyQualifiedClassName)) {
7
        // We aren't looking at the specified class so return without making any modifications
8
        return cd;
9
    }
10
​
11
    // Check if the class already has a method named "hello" so we don't incorrectly add a second "hello" method
12
    boolean helloMethodExists = classDecl.getBody().getStatements().stream()
13
            .filter(statement -> statement instanceof J.MethodDeclaration)
14
            .map(J.MethodDeclaration.class::cast)
15
            .anyMatch(methodDeclaration -> methodDeclaration.getName().getSimpleName().equals("hello"));
16
    if (helloMethodExists) {
17
        return cd;
18
    }
19
​
20
    // TODO: Use JavaTemplate to say hello()
21
    return cd;
22
}
Copied!
Using JavaTemplate to say hello()
Templates are created using the JavaTemplate.builder() method. Within a template #{} is the signifier for positional parameter substitution. So to produce the hello() method add this to the visitor:
1
public class SayHelloVisitor extends JavaIsoVisitor<ExecutionContext> {
2
    private final JavaTemplate helloTemplate =
3
            JavaTemplate.builder(this::getCursor, "public String hello() { return \"Hello from #{}!\"; }")
4
                    .build();
5
    ...
6
}
Copied!
And use that template within SayHelloVisitor.visitClassDeclaration like so:
1
@Override
2
public J.ClassDeclaration visitClassDeclaration(J.ClassDeclaration classDecl, ExecutionContext executionContext) {
3
    // In any visit() method the call to super() is what causes sub-elements of to be visited
4
    J.ClassDeclaration cd = super.visitClassDeclaration(classDecl, executionContext);
5
​
6
    if (classDecl.getType() == null || !classDecl.getType().getFullyQualifiedName().equals(fullyQualifiedClassName)) {
7
        // We aren't looking at the specified class so return without making any modifications
8
        return cd;
9
    }
10
​
11
    // Check if the class already has a method named "hello" so we don't incorrectly add a second "hello" method
12
    boolean helloMethodExists = classDecl.getBody().getStatements().stream()
13
            .filter(statement -> statement instanceof J.MethodDeclaration)
14
            .map(J.MethodDeclaration.class::cast)
15
            .anyMatch(methodDeclaration -> methodDeclaration.getName().getSimpleName().equals("hello"));
16
    if (helloMethodExists) {
17
        return cd;
18
    }
19
​
20
    // Interpolate the fullyQualifiedClassName into the template and use the resulting AST to update the class body
21
    cd = cd.withBody(
22
            cd.getBody().withTemplate(
23
                    helloTemplate,
24
                    cd.getBody().getCoordinates().lastStatement(),
25
                    fullyQualifiedClassName
26
            ));
27
​
28
    return cd;
29
}
Copied!
Running this visitor on a class like A { } will now produce the desired result:
1
package com.yourorg;
2
​
3
class A {
4
    public String hello() {
5
        return "Hello from com.yourorg.A!";
6
    }
7
​
8
}
Copied!
So the complete SayHelloRecipe looks like this:
1
package org.openrewrite.samples;
2
​
3
import com.fasterxml.jackson.annotation.JsonCreator;
4
import com.fasterxml.jackson.annotation.JsonProperty;
5
import org.openrewrite.ExecutionContext;
6
import org.openrewrite.Option;
7
import org.openrewrite.Recipe;
8
import org.openrewrite.internal.lang.NonNull;
9
import org.openrewrite.java.JavaIsoVisitor;
10
import org.openrewrite.java.JavaTemplate;
11
import org.openrewrite.java.tree.J;
12
​
13
public class SayHelloRecipe extends Recipe {
14
    // Making your recipe immutable helps make them idempotent and eliminates categories of possible bugs
15
    // Configuring your recipe in this way also guarantees that basic validation of parameters will be done for you by rewrite
16
    @Option(displayName = "Fully Qualified Class Name",
17
            description = "A fully-qualified class name indicating which class to add a hello() method.",
18
            example = "com.yourorg.FooBar")
19
    @NonNull
20
    private final String fullyQualifiedClassName;
21
    public String getFullyQualifiedClassName() {
22
        return fullyQualifiedClassName;
23
    }
24
​
25
    // Recipes must be serializable. This is verified by RecipeTest.assertChanged() and RecipeTest.assertUnchanged()
26
    @JsonCreator
27
    public SayHelloRecipe(@NonNull @JsonProperty("fullyQualifiedClassName") String fullyQualifiedClassName) {
28
        this.fullyQualifiedClassName = fullyQualifiedClassName;
29
    }
30
​
31
    @Override
32
    public String getDisplayName() {
33
        return "Say Hello";
34
    }
35
​
36
    @Override
37
    public String getDescription() {
38
        return "Adds a \"hello\" method to the specified class";
39
    }
40
​
41
    @Override
42
    protected JavaIsoVisitor<ExecutionContext> getVisitor() {
43
        // getVisitor() should always return a new instance of the visitor to avoid any state leaking between cycles
44
        return new SayHelloVisitor();
45
    }
46
​
47
    public class SayHelloVisitor extends JavaIsoVisitor<ExecutionContext> {
48
        private final JavaTemplate helloTemplate =
49
                JavaTemplate.builder(this::getCursor, "public String hello() { return \"Hello from #{}!\"; }")
50
                        .build();
51
​
52
        @Override
53
        public J.ClassDeclaration visitClassDeclaration(J.ClassDeclaration classDecl, ExecutionContext executionContext) {
54
            // In any visit() method the call to super() is what causes sub-elements of to be visited
55
            J.ClassDeclaration cd = super.visitClassDeclaration(classDecl, executionContext);
56
​
57
            if (classDecl.getType() == null || !classDecl.getType().getFullyQualifiedName().equals(fullyQualifiedClassName)) {
58
                // We aren't looking at the specified class so return without making any modifications
59
                return cd;
60
            }
61
​
62
            // Check if the class already has a method named "hello" so we don't incorrectly add a second "hello" method
63
            boolean helloMethodExists = classDecl.getBody().getStatements().stream()
64
                    .filter(statement -> statement instanceof J.MethodDeclaration)
65
                    .map(J.MethodDeclaration.class::cast)
66
                    .anyMatch(methodDeclaration -> methodDeclaration.getName().getSimpleName().equals("hello"));
67
            if (helloMethodExists) {
68
                return cd;
69
            }
70
​
71
            // Interpolate the fullyQualifiedClassName into the template and use the resulting AST to update the class body
72
            cd = cd.withBody(
73
                    cd.getBody().withTemplate(
74
                            helloTemplate,
75
                            cd.getBody().getCoordinates().lastStatement(),
76
                            fullyQualifiedClassName
77
                    ));
78
​
79
            return cd;
80
        }
81
    }
82
}
Copied!
Testing
To create automated tests of this visitor we use the Kotlin language, mostly for convenient access to multi-line Strings, with JUnit 5 and using a fluent testing API that is provided by the rewrite-test module.
For SayHelloRecipe it is sensible to test:
That a class matching the configured fullyQualifiedClassName with no hello() method will have a hello() method added
That a class that already has a different hello() implementation will be left untouched
That a class not matching the configured fullyQualifiedClassName with no hello() method will be left untouched
The test for the recipe will implement the RewriteTest interface that provides the entry point to the testing infrastructure via the method variants of rewriteRun(). Our test will override the defaults(RecipeSpec)method and define both the recipe and the Java parser configuration that will be shared by all three of the tests.

Each test will define a Java SourceSpec that, at a minimum, will define the initial source code (the "before" state) for each test. If a second argument is excluded from a source specification, the testing infrastructure will assert that no changes are made to the given source file. If a second argument (the "after" state) is defined for a test, the testing infrastructure will assert that the source file has been transformed correctly after the recipe has been executed.
​
1
package org.openrewrite.samples
2
​
3
import org.junit.jupiter.api.Test
4
import org.openrewrite.java.JavaParser
5
import org.openrewrite.java.JavaRecipeTest
6
​
7
class SayHelloRecipeTest: RewriteTest {
8
​
9
    override fun defaults(spec: RecipeSpec) {
10
        spec
11
            .recipe(SayHelloRecipe("com.yourorg.A"))
12
    }
13
​
14
    @Test
15
    fun addsHelloToA() = rewriteRun(
16
        java(
17
            """
18
                package com.yourorg;
19
    
20
                class A {
21
                }
22
            """,
23
            """
24
                package com.yourorg;
25
    
26
                class A {
27
                    public String hello() {
28
                        return "Hello from com.yourorg.A!";
29
                    }
30
                }
31
            """
32
        )
33
    )
34
​
35
    @Test
36
    fun doesNotChangeExistingHello() = rewriteRun(
37
        java(
38
            """
39
                package com.yourorg;
40
    
41
                class A {
42
                    public String hello() { return ""; }
43
                }
44
            """
45
        )
46
    )
47
​
48
    @Test
49
    fun doesNotChangeOtherClass() = rewriteRun(
50
        java(
51
            """
52
                package com.yourorg;
53
    
54
                class B {
55
                }
56
            """
57
        )
58
    )
59
}
Copied!
Users of IntelliJ Idea benefit from Java syntax highlighting when authoring these tests.
Declarative YAML Usage
SayHelloRecipe is now ready to be used in code or declaratively from YAML.
YAML
1
---
2
type: specs.openrewrite.org/v1beta/recipe
3
name: com.yourorg.sayHelloA
4
recipeList:
5
  - org.openrewrite.samples.SayHelloRecipe:
6
      fullyQualifiedClassName: com.yourorg.A
Copied!
Tutorials & Guides - Previous
Use SLF4J Parameterized Logging
Next - Tutorials & Guides
Modifying Methods with JavaTemplate
Last modified 25d ago
Export as PDF
Copy link
Contents
Defining SayHelloRecipe
Implementing the Visitor
Using JavaTemplate to say hello()
Testing
Declarative YAML Usage