Markers

Markers are used to annotate AST elements with metadata. Visitors can attach any type implementing the Marker interface to any AST element. When an AST is printed back to source code Markers are not printed. Markers are used during OpenRewrite execution to communicate between Recipes and to represent search results.
Usage
Example Marker Implementations
Within rewrite itself Markers are used for a wide variety of purposes. Examples include:
​IntelliJ - Represents the IntelliJ IDE's Java source code style/formatting configuration options. 
​GitProvenance - Keeps track of Git metadata associated with a particular Java project
​Pom - Rich data model of a pom.xml, including full dependency resolution information
​RecipeSearchResult - Marks an AST element with the Recipe that found it
Adding Markers to an AST Element
All AST elements implement the Markable interface which provides two methods to add Markers. AST elements are immutable, and that includes their metadata, so these methods return a copy of the AST element with the specified Markers.
Markable.java
1
// Returns the existing Markers
2
Markers getMarkers();
3
​
4
// Fully replaces any existing Markers
5
<M extends Markable> M withMarkers(Markers markers);
6
​
7
// Add or replace the specified markers
8
<M extends Markable> M withMarker(Marker... add)
Copied!
Reading Markers from an AST Element
Markable.getMarkers() returns the Markers on a given AST element. The Markers class provides several convenience methods.
Markers.java
1
// Returns the first Marker of the specified type.
2
<M extends Marker> Optional<M> findFirst(Class<M> markerType)
3
​
4
// Returns all Markers of the specified type
5
<M extends Marker> List<M> findAll(Class<M> markerType)
6
​
7
// Add a new marker or update some existing marker via the remappingFunction
8
// The existence of "identity" is determined based on equality
9
<M extends Marker> Markers compute(M identity, BinaryOperator<M> remappingFunction)
10
​
11
// Add a new marker or update some existing marker via the remappingFunction
12
// The existence of "identity" is determined based on type equality
13
<M extends Marker> Markers computeByType(M identity, BinaryOperator<M> remappingFunction)
Copied!
RecipeSearchResult
The most common form of Marker in a typical Recipe is a RecipeSearchResult. Any Recipe which adds RecipeSearchResult markers to an AST can be described as a search recipe. RecipeSearchResults include which specific recipe instance created it. So recipes are able to differentiate between search results left by an instance of the search visitor they're interested in and results left by a different instance of the same type of visitor. RecipeSearchResults can optionally include a text description.
Adding a Search Result to an AST
In this example the search recipe FindAnnotations adds a RecipeSearchResult indicating that it found a matching Annotation.
FindAnnotations.java
1
public J.Annotation visitAnnotation(J.Annotation annotation, ExecutionContext ctx) {
2
    J.Annotation a = super.visitAnnotation(annotation, ctx);
3
    if (annotationMatcher.matches(annotation)) {
4
        a = a.withMarker(new RecipeSearchResult(FindAnnotations.this));
5
    }
6
    return a;
7
}
Copied!
Search Result Printers
While Markers are never written back to source code, they can be made visible in a textual representation of source code via a Search Result Printer. To create a custom search result printer use the SearchResult.printer() method. SearchResult.printer() accepts two arguments:
markerText - the text to print when a RecipeSearchResult has no description
markerTextWithDescription - the text to print when a RecipeSearchResult has a description. Use the "%s" format specifier within this String to indicate where the description should be interpolated in.
This is the printer used by default in tests of Java Search visitors:
1
SearchResult.printer("/*~~>*/", "/*~~(%s)~~>*/");
Copied!
So for example if the FindMethods("A singleArg(String)") recipe were applied to this Java source file:
1
class Test {
2
    void test() {
3
        new java.util.ArrayList<String>().forEach(new A()::singleArg);
4
    }
5
}
Copied!
The search result would be visualized like so:
1
class Test {
2
    void test() {
3
        new java.util.ArrayList<String>().forEach(new A()::/*~~>*/singleArg);
4
    }
5
}
Copied!

Concepts & Explanations - Previous

Environment

Next - Concepts & Explanations

JavaTemplate

Last modified 2mo ago

Export as PDF

Copy link

Contents

Usage

Example Marker Implementations

Adding Markers to an AST Element

Reading Markers from an AST Element

RecipeSearchResult

Adding a Search Result to an AST

Search Result Printers