Class PipelineConfiguration
- java.lang.Object
-
- org.revapi.PipelineConfiguration
-
public final class PipelineConfiguration extends Object
This class represents the configuration of the Revapi analysis pipeline. This is different from the configuration of the individual extensions (which are part of the pipeline) as it provides the configuration of the pipeline itself. Namely, this class defines all the possible extensions that can be used during the analysis as well as the configuration of the "shape" of the pipeline - as of now only the transformation blocks can be defined.The analysis can be influenced by defining "transformation blocks". By default, each
DifferenceTransform
can transform a difference into another one. Each such newly created difference is then again examined by all difference transforms to see if it is also can be transformed again. This is sometimes not what the user intends with the configuration, because it might be useful to "group" certain transformations into "blocks" that happen "atomically" without the constituent transforms in the block influencing each others results.E.g., consider the following scenario:
There is a "reclassify" transform that is configured to "tune down" severity of certain differences. At the same time, there is another transformation, say a "policy transformation" that considers any potentially breaking change as breaking - the goal of the policy is to have a "clean" set of changes without any potentially breaking change in the release.
Without a transformation block, these two transformations cannot coexist together without causing an "infinite loop" (Revapi will interrupt the difference transformations after a certain number attempts).
In the outlined scenario, the intention of the user is to have the "reclassify" transform make some differences admissible for the release and the "policy" transform to make all other differences breaking. The problem with this is that, as described above, Revapi cannot guess this intention and just blindly applies all transforms on each and every difference found. This makes it impossible for the "policy" transform to "not see" the admissible differences that the "reclassify" transform tunes down.
Enter transformation blocks. Transformation blocks enable certain transformations to be applied in the defined order while considering the result of such series of transformations as potential input for other transformations outside of the block. This enables the user to say "first reclassify then apply policy", resulting her original intention being clear to Revapi.
As explained in the
AnalysisContext
, each transformation extension can be configured multiple times using different IDs. An ID is optional if there is only a single configuration of a single type of transformation. When trying to group the transformations into blocks, Revapi first tries to find a transformation with given ID and if it finds none, it tries to match the provided string with the name of the extension (internally called the extension ID).
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
PipelineConfiguration.Builder
-
Constructor Summary
Constructors Constructor Description PipelineConfiguration(Set<Class<? extends ApiAnalyzer<?>>> apiAnalyzerTypes, Set<Class<? extends Reporter>> reporterTypes, Set<Class<? extends DifferenceTransform<?>>> transformTypes, Set<Class<? extends TreeFilterProvider>> treeFilterTypes, Set<Class<? extends ElementMatcher>> matcherTypes, Set<List<String>> transformationBlocks, List<String> includedAnalyzerExtensionIds, List<String> excludedAnalyzerExtensionIds, List<String> includedReporterExtensionIds, List<String> excludedReporterExtensionIds, List<String> includedTransformExtensionIds, List<String> excludedTransformExtensionIds, List<String> includedFilterExtensionIds, List<String> excludedFilterExtensionIds, List<String> includedMatcherExtensionIds, List<String> excludedMatcherExtensionIds, Set<Criticality> criticalities, Map<DifferenceSeverity,Criticality> severityMapping)
-
Method Summary
-
-
-
Constructor Detail
-
PipelineConfiguration
public PipelineConfiguration(Set<Class<? extends ApiAnalyzer<?>>> apiAnalyzerTypes, Set<Class<? extends Reporter>> reporterTypes, Set<Class<? extends DifferenceTransform<?>>> transformTypes, Set<Class<? extends TreeFilterProvider>> treeFilterTypes, Set<Class<? extends ElementMatcher>> matcherTypes, Set<List<String>> transformationBlocks, List<String> includedAnalyzerExtensionIds, List<String> excludedAnalyzerExtensionIds, List<String> includedReporterExtensionIds, List<String> excludedReporterExtensionIds, List<String> includedTransformExtensionIds, List<String> excludedTransformExtensionIds, List<String> includedFilterExtensionIds, List<String> excludedFilterExtensionIds, List<String> includedMatcherExtensionIds, List<String> excludedMatcherExtensionIds, Set<Criticality> criticalities, Map<DifferenceSeverity,Criticality> severityMapping)
-
-
Method Detail
-
builder
public static PipelineConfiguration.Builder builder()
- Returns:
- a pipeline configuration builder instance
-
parse
@Deprecated public static PipelineConfiguration.Builder parse(org.jboss.dmr.ModelNode json)
Deprecated.use the Jackson-based variantParses the configuration node and provides a pipeline configuration without any extensions marked for loading. The configuration node is supposed to conform to the pipeline configuration JSON schema.The caller is supposed to use the methods from the builder to add/find extension classes that will be used in the analysis.
Note that the returned pipeline configuration might not contain all the extensions available in the classloader depending on the include/exclude filters in the configuration.
- Parameters:
json
- the configuration node- Returns:
- a pipeline configuration parsed from the configuration
- See Also:
PipelineConfiguration.Builder.build()
-
parse
public static PipelineConfiguration.Builder parse(com.fasterxml.jackson.databind.JsonNode json)
Parses the configuration node and provides a pipeline configuration without any extensions marked for loading. The configuration node is supposed to conform to the pipeline configuration JSON schema.The caller is supposed to use the methods from the builder to add/find extension classes that will be used in the analysis.
Note that the returned pipeline configuration might not contain all the extensions available in the classloader depending on the include/exclude filters in the configuration.
- Parameters:
json
- the configuration node- Returns:
- a pipeline configuration parsed from the configuration
- See Also:
PipelineConfiguration.Builder.build()
-
parse
@Deprecated public static PipelineConfiguration parse(org.jboss.dmr.ModelNode json, Collection<Class<? extends ApiAnalyzer>> analyzers, Collection<Class<? extends TreeFilterProvider>> filters, Collection<Class<? extends DifferenceTransform>> transforms, Collection<Class<? extends Reporter>> reporters, Collection<Class<? extends ElementMatcher>> matchers)
Deprecated.use the Jackson-based variantSimilar toparse(ModelNode)
but the extensions to use are provided by the caller straight away instead of letting the caller use the builder to finish up the configuration.Note that the returned pipeline configuration might not contain all the extensions available in the classloader depending on the include/exclude filters in the configuration.
- Parameters:
json
- the configuration nodeanalyzers
- the set of analyzers to choose fromfilters
- the set of filters to choose fromtransforms
- the set of transforms to choose fromreporters
- the set of reporters to choose from- Returns:
- pipeline configuration corresponding to the provided configuration node
- See Also:
PipelineConfiguration.Builder.build()
-
parse
public static PipelineConfiguration parse(com.fasterxml.jackson.databind.JsonNode json, Collection<Class<? extends ApiAnalyzer>> analyzers, Collection<Class<? extends TreeFilterProvider>> filters, Collection<Class<? extends DifferenceTransform>> transforms, Collection<Class<? extends Reporter>> reporters, Collection<Class<? extends ElementMatcher>> matchers)
Similar toparse(JsonNode)
but the extensions to use are provided by the caller straight away instead of letting the caller use the builder to finish up the configuration.Note that the returned pipeline configuration might not contain all the extensions available in the classloader depending on the include/exclude filters in the configuration.
- Parameters:
json
- the configuration nodeanalyzers
- the set of analyzers to choose fromfilters
- the set of filters to choose fromtransforms
- the set of transforms to choose fromreporters
- the set of reporters to choose from- Returns:
- pipeline configuration corresponding to the provided configuration node
- See Also:
PipelineConfiguration.Builder.build()
-
getApiAnalyzerTypes
public Set<Class<? extends ApiAnalyzer<?>>> getApiAnalyzerTypes()
-
getTransformTypes
public Set<Class<? extends DifferenceTransform<?>>> getTransformTypes()
-
getTreeFilterTypes
public Set<Class<? extends TreeFilterProvider>> getTreeFilterTypes()
-
getMatcherTypes
public Set<Class<? extends ElementMatcher>> getMatcherTypes()
-
getCriticalities
public Set<Criticality> getCriticalities()
-
getSeverityMapping
public Map<DifferenceSeverity,Criticality> getSeverityMapping()
-
-