Skip to main content

Framework provided markers

Not everything a Recipe may wish to know about an LST is contained in the LST itself. OpenRewrite attaches Markers to an LST to provide Recipes access to relevant metadata. This document provides Recipe authors a reference for what metadata is available and how to access it.

Accessing provided markers​

All markers described in this document are found on the root element of the LST. The root LST element varies by language, but they all implement the SourceFile interface. From anywhere in a Visitor the cursor can be used to access the markers on the root element like so:

class SomeVisitor extends JavaVisitor<ExecutionContext> {

    @Override
    public J.ClassDeclaration visitClassDeclaration(J.ClassDeclaration classDecl, ExecutionContext ctx) {

        // This snippet will retrieve the root element's markers in any language, from anywhere in a visitor
        Markers m = getCursor().firstEnclosing(SourceFile.class).getMarkers();

        // There is only one of each of these markers, so Markers.findFirst() is a convenient way to access them
        Optional<BuildTool> buildTool = m.findFirst(BuildTool.class);

        // Some markers are language-specific
        Optional<JavaProject> javaProject = m.findFirst(JavaProject.class);

        return classDecl;
    }
}

Build markers​

These markers are language-independent, appearing on source files of all formats.

BuildTool​

The BuildTool marker records the type and version of build tool which produced the LST. Available on all LSTs produced by one of our build tool plugins.

BuildEnvironment​

The subtypes of BuildEnvironment record information on the continuous integration environment from within which the LST was produced. Available on all LSTs produced from a supported CI environment.

Supported CI environments:

GitProvenance​

The GitProvenance marker records Git branch, origin, and change hash.
Available on all LSTs produced from a Git repository.

Generated​

The Generated marker indicates that a source file was produced by a code generator rather than written by hand. Recipes commonly check for it so that they leave generated code alone.

LstProvenance​

The LstProvenance marker records what built the LST — the build tool, its version, and the timestamp. Useful when a recipe needs to behave differently depending on how the LST was produced.

Markup​

Markup attaches a warning, error, info, or debug message to an LST element. Unlike most markers it is rendered when the LST is printed, as a comment. Markup.warn(tree, throwable) is the usual way for a recipe to surface a problem on a specific element rather than failing the whole run.

Java Markers​

NamedStyles​

NamedStyles is a named collection of styles representing code style/formatting and related configuration options. If not explicitly configured the code style a project uses will be auto-detected. It is available on Java source files.

Checkstyle​

The Checkstyle marker is a NamedStyles which records Checkstyle settings. It is available on Java source files in projects that configure checkstyle.

JavaProject​

JavaProject records the publication coordinates (groupId, artifactId, version) of the module which contains the sources. Available on all sources, not only Java sources, in projects where these publication coordinates are configured.

JavaSourceSet​

JavaSourceSet records the name (usually "main" or "test") of the source set containing the source file, and list of fully qualified type names present on the classpath. Available on all Java sources, as well as non-Java sources placed in a Java source set's resources directory.

JavaVersion​

JavaVersion records the version of Java used to compile the source, including source and target compatibility. Available on all Java sources.

Maven markers​

These markers are available on Maven pom.xml sources.

MavenResolutionResult​

MavenResolutionResult contains a rich data model of a pom.xml, including full dependency resolution information.

Gradle markers​

These are the Gradle counterparts to MavenResolutionResult. Any recipe that reads or edits Gradle dependencies, plugins, or repositories works through them.

GradleProject​

GradleProject contains a rich data model of a Gradle subproject: its group, name, version, and path; the plugins it applies; its declared Maven repositories; and a map of configuration name to GradleDependencyConfiguration, which carries full dependency resolution information. Available on build.gradle/build.gradle.kts sources.

GradleSettings​

GradleSettings records settings-level configuration: the plugins applied in settings.gradle, enabled feature previews, and the settings buildscript. Available on settings.gradle/settings.gradle.kts sources.