Package org.openrewrite

Class Recipe

java.lang.Object
org.openrewrite.Recipe
All Implemented Interfaces:
Cloneable
Direct Known Subclasses:
ChangeText, CompositeRecipe, DeclarativeRecipe, DeleteSourceFiles, EndOfLineAtEndOfFile, Find, FindAndReplace, FindBuildMetadata, FindDeserializationErrors, FindMultiselect, FindParseFailures, FindParseToPrintInequality, FindQuarks, FindSourceFiles, IsInRepository, RenameFile, ScanningRecipe, SetFilePermissions
public abstract class Recipe extends Object implements Cloneable
Provides a formalized link list data structure of recipes and a run(LargeSourceSet, ExecutionContext) method which will apply each recipes visitor visit method to a list of sourceFiles

Requires a name, visitor. Optionally a subsequent Recipe can be linked via getRecipeList()}

An ExecutionContext controls parallel execution and lifecycle while providing a message bus for sharing state between recipes and their visitors

returns a list of results for each modified SourceFile

  • Field Details

  • Constructor Details

    • Recipe

      public Recipe()

  • Method Details

    • getJacksonPolymorphicTypeTag

      public String getJacksonPolymorphicTypeTag()

    • noop

      public static Recipe noop()

    • maxCycles

      @Incubating(since="8.0.0") public int maxCycles()
      Returns:
      The maximum number of cycles this recipe is allowed to make changes in a recipe run.

    • getDisplayName

      @Language("markdown") public abstract String getDisplayName()
      A human-readable display name for the recipe, initial capped with no period. For example, "Find text". The display name can be assumed to be rendered in documentation and other places where markdown is understood, so it is possible to use stylistic markers like backticks to indicate types. For example, "Find uses of `java.util.List`".
      Returns:
      The display name.

    • getInstanceName

      @Incubating(since="8.12.0") @Language("markdown") public String getInstanceName()
      A human-readable display name for this recipe instance, including some descriptive text about the recipe options that are supplied, if any. The name must be initial capped with no period. For example, "Find text 'hello world'".
      For recipes with no options, by default this is equal to getDisplayName(). For recipes with options, the default implementation does its best to summarize those options in a way that fits in a reasonable amount of characters.
      For consistency, when surrounding option descriptive text in quotes to visually differentiate it from the text before it, use single ``.
      Override to provide meaningful recipe instance names for recipes with complex sets of options.
      Returns:
      A name that describes this recipe instance.

    • getInstanceNameSuffix

      public String getInstanceNameSuffix()
      Since most instance names will be constructed with getDisplayName() followed by some further descriptive text about the recipe's options, this method provides a convenient way to just specify the option descriptive text. When getInstanceName() is overridden, this method has no effect. Generally either override this method or getInstanceName() if you want to customize the instance name text.
      Returns:
      A suffix to append to the display name of a recipe.

    • getDescription

      @Language("markdown") public abstract String getDescription()
      A human-readable description for the recipe, consisting of one or more full sentences ending with a period.

      "Find methods by pattern." is an example. The description can be assumed to be rendered in documentation and other places where markdown is understood, so it is possible to use stylistic markers like backticks to indicate types. For example, "Find uses of `java.util.List`.".

      Returns:
      The display name.

    • getTags

      public Set<String> getTags()
      A set of strings used for categorizing related recipes. For example "testing", "junit", "spring". Any individual tag should consist of a single word, all lowercase.
      Returns:
      The tags.

    • getEstimatedEffortPerOccurrence

      @Nullable public @Nullable Duration getEstimatedEffortPerOccurrence()
      Returns:
      An estimated effort were a developer to fix manually instead of using this recipe.

    • getDescriptor

      public final RecipeDescriptor getDescriptor()

    • createRecipeDescriptor

      protected RecipeDescriptor createRecipeDescriptor()

    • getDataTableDescriptors

      public List<DataTableDescriptor> getDataTableDescriptors()

    • getMaintainers

      public List<Maintainer> getMaintainers()
      Returns:
      a list of the organization(s) responsible for maintaining this recipe.

    • getContributors

      public List<Contributor> getContributors()

    • getExamples

      public List<RecipeExample> getExamples()

    • causesAnotherCycle

      public boolean causesAnotherCycle()
      Returns:
      Determines if another cycle is run when this recipe makes a change. In some cases, like changing method declaration names, a further cycle is needed to update method invocations of that declaration that were visited prior to the declaration change. But other visitors never need to cause another cycle, such as those that format whitespace or add search markers. Note that even when this is false, the recipe will still run on another cycle if any other recipe causes another cycle to run. But if every recipe reports no need to run another cycle (or if there are no changes made in a cycle), then another will not run.

    • getRecipeList

      public List<Recipe> getRecipeList()
      A list of recipes that run, source file by source file, after this recipe. This method is guaranteed to be called only once per cycle.

      When creating a recipe with a fixed recipe list, either override this method or buildRecipeList(RecipeList) but ideally not both, as their default implementations are interconnected.

      Returns:
      The list of recipes to run.

    • buildRecipeList

      public void buildRecipeList(RecipeList list)
      Used to build up a recipe list programmatically. Using the methods on RecipeList, the appearance of a recipe that chains other recipes with options will be not strikingly different from defining it in a recipe.yml.

      Building, or at least starting to build, recipes for complex migrations with this method is more amenable to AI coding assistants since these assistants are primarily optimized for providing completion assistance in a single file.

      When creating a recipe with a fixed recipe list, either override this method or getRecipeList() but ideally not both, as their default implementations are interconnected.

      Parameters:
      list - A recipe list used to build up a series of recipes in code in a way that looks fairly declarative and therefore is more amenable to AI code completion.

    • getVisitor

      public TreeVisitor<?,ExecutionContext> getVisitor()
      A recipe can optionally encapsulate a visitor that performs operations on a set of source files. Subclasses of the recipe may override this method to provide an instance of a visitor that will be used when the recipe is executed.
      Returns:
      A tree visitor that will perform operations associated with the recipe.

    • addDataTable

      public void addDataTable(DataTable<?> dataTable)

    • run

      public final RecipeRun run(LargeSourceSet before, ExecutionContext ctx)

    • run

      public final RecipeRun run(LargeSourceSet before, ExecutionContext ctx, int maxCycles)

    • run

      public final RecipeRun run(LargeSourceSet before, ExecutionContext ctx, int maxCycles, int minCycles)

    • validate

      public Validated<Object> validate(ExecutionContext ctx)

    • validate

      public Validated<Object> validate()
      The default implementation of validate on the recipe will look for package and field level annotations that indicate a field is not-null. The annotations must have run-time retention and the simple name of the annotation must match one of the common names defined in NullUtils
      Returns:
      A validated instance based using non-null/nullable annotations to determine which fields of the recipe are required.

    • validateAll

      public final Collection<Validated<Object>> validateAll()

    • validateAll

      public Collection<Validated<Object>> validateAll(ExecutionContext ctx, Collection<Validated<Object>> acc)

    • getName

      public String getName()

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • clone

      public Object clone()
      Overrides:
      clone in class Object

    • builder

      @Incubating(since="8.31.0") public static Recipe.Builder builder(@Language("markdown") String displayName, @Language("markdown") String description)
      Returns:
      A new recipe builder.