Environment

Discovers, configures, and instantiates recipes to apply to a set of source files

OpenRewrite's Environment abstraction provides discovery, activation, and configuration facilities for Recipes and Styles. It can be helpful to look at the common runtime contexts in which OpenRewrite operates to better understand how the environment is established:
Context
Integrations
Rewrite Maven/Gradle plugins
Scans the compile and provided scope classpath of the project and looks for any available recipes.
Scans the compile and provided scope classpath and looks for META-INF/rewrite/*.yml which contain declarative definitions of recipes and styles.
Adds the resources in the YML file referred to by the plugin's configLocation configuration.
Activates recipes and styles based on the plugin's activeRecipes and activeStyles config
Command line utilities
Might have some command-line flags indicating which recipes and styles to activate and a pre-defined set of visitors and recipes to add to the environment.
Mass-refactoring microservice
Adds visitors and recipes to an environment based on post body inputs to the service. If the service is operating off of a data store of pre-published ASTs, there is no need for any style configuration because the styles should already be stored with the ASTs this service is designed to operate on.
The code below demonstrates how to manually construct an Environment and seed it with a variety of different resource loaders.
File rewriteYml = ...;
try(InputStream rewriteInputStream = new FileInputStream(rewriteYml)) {
  ResourceLoader rewriteYmlLoader = new YamlResourceLoader(
    rewriteInputStream,
    // wouldn't have to exist on disk necessarily (just used in logging)
    rewriteYml.toURI(),
    System.getProperties()
  );
​
  Iterable<Path> classpath = ...
​
  // any manually built visitors
  Iterable<? extends RefactorVisitor<?>> visitors = ...
​
  Environment env = Environment.builder()
    .load(rewriteYmlLoader) // can be called more than once for multiple files
    .scanClasspath(classpath) // classpath scans for META-INF/rewrite/*.yml
    .scanUserHome() // looks for `~/.rewrite/rewrite.yml
    .build();
}
Once an instance of the Environment has been created, it can be interrogated to list all available recipes and styes. There are also facilities for retrieving the recipe descriptions which provides a description of the recipe and its available options.

Context	Integrations
Rewrite Maven/Gradle plugins	Scans the compile and provided scope classpath of the project and looks for any available recipes. Scans the compile and provided scope classpath and looks for `META-INF/rewrite/*.yml` which contain declarative definitions of recipes and styles. Adds the resources in the YML file referred to by the plugin's `configLocation` configuration. Activates recipes and styles based on the plugin's `activeRecipes` and `activeStyles` config
Command line utilities	Might have some command-line flags indicating which recipes and styles to activate and a pre-defined set of visitors and recipes to add to the environment.
Mass-refactoring microservice	Adds visitors and recipes to an environment based on post body inputs to the service. If the service is operating off of a data store of pre-published ASTs, there is no need for any style configuration because the styles should already be stored with the ASTs this service is designed to operate on.

Concepts & Explanations - Previous

Styles

Next - Concepts & Explanations

Markers

Last modified 1yr ago