E
- the type of the element expected in the transform
method. Note that you need to be careful about
this type because the types of the elements passed to tryTransform
depend on the differences that
the transform is interested in. Thus you may end up with ClassCastException
s if you're not
careful. This type needs to be cast-able to the type of all possible elements that the handled differences
can apply to. If in doubt, just keep the type generic.public interface DifferenceTransform<E extends Element<?>> extends AutoCloseable, Configurable
The AutoCloseable.close()
is not called if there is no prior call to Configurable.initialize(AnalysisContext)
. Do all your
resource acquisition in initialize, not during the construction of the object.
NOTE: for more complex transformations that require contextual knowledge about the traversal (like when you need to employ an element matcher during the transformation), you may want to re-implement the default methods for the element-pair tree traversal of the elements. The traversal happens prior to any transformations.
Modifier and Type | Interface and Description |
---|---|
static interface |
DifferenceTransform.TraversalTracker<E extends Element<E>>
Some more sophisticated transforms may need to track the traversal of the element forest.
|
Modifier and Type | Method and Description |
---|---|
default void |
endTraversal(DifferenceTransform.TraversalTracker<?> tracker)
Called after everything traversed using the provided analyzer has been transformed.
|
Pattern[] |
getDifferenceCodePatterns() |
default <X extends Element<X>> |
startTraversal(ApiAnalyzer<X> apiAnalyzer,
ArchiveAnalyzer<X> oldArchiveAnalyzer,
ArchiveAnalyzer<X> newArchiveAnalyzer)
Called when Revapi is about to start traversing the elements provided by the given archive analyzers.
|
default Difference |
transform(E oldElement,
E newElement,
Difference difference)
Deprecated.
use
tryTransform(Element, Element, Difference) which offers richer possibilities |
default TransformationResult |
tryTransform(E oldElement,
E newElement,
Difference difference)
Tries to transform the difference into some other one(s) given the old and new elements.
|
close
getExtensionId, getJSONSchema, initialize
Pattern[] getDifferenceCodePatterns()
@Deprecated @Nullable default Difference transform(@Nullable E oldElement, @Nullable E newElement, Difference difference)
tryTransform(Element, Element, Difference)
which offers richer possibilitiesThe code of the supplied difference will match at least one of the regexes returned from the getDifferenceCodePatterns()
method.
oldElement
- the old differing elementnewElement
- the new differing elementdifference
- the difference descriptiondefault TransformationResult tryTransform(@Nullable E oldElement, @Nullable E newElement, Difference difference)
This method is only called on differences matching the getDifferenceCodePatterns()
. The elements are
cast into the required type, but that can result in the class cast exception if the implementation is not careful
enough and wants to react on a difference code that matches elements which are incompatible with the required
type.
Note that this method can be called repeatedly for the same element pair if there are multiple transformations
operating on the two elements. Also note that this method is called only after the traversal tracker has visited
all elements and its DifferenceTransform.TraversalTracker.endTraversal()
has been called.
Only after this method has been called on all element pairs from the traversal,
the endTraversal(TraversalTracker)
is called to potentially clean up the resources before the traversal
with the next api analyzer starts.
oldElement
- the old element, if any, being compared to the new elementnewElement
- the new element, if any, being compared to the old elementdifference
- the difference to transformdefault <X extends Element<X>> Optional<DifferenceTransform.TraversalTracker<X>> startTraversal(ApiAnalyzer<X> apiAnalyzer, ArchiveAnalyzer<X> oldArchiveAnalyzer, ArchiveAnalyzer<X> newArchiveAnalyzer)
This method can invalidate the transform early if it finds out that it cannot possibly work with the api analyzer and the archive analyzers. Simple transforms that only work with generic elements will likely work with any API analyzer, but there may be more specialized transforms that can know upfront whether or not they will be able to work with elements from the supplied analyzers and can opt out straight away reducing the required processing during the API analysis.
apiAnalyzer
- the api analyzer currently analyzing the APIsoldArchiveAnalyzer
- the archive analyzer used for obtaining the element forest of the old APInewArchiveAnalyzer
- the archive analyzer used for obtaining the element forest of the new APIdefault void endTraversal(@Nullable DifferenceTransform.TraversalTracker<?> tracker)
startTraversal(ApiAnalyzer, ArchiveAnalyzer, ArchiveAnalyzer)
again.tracker
- the traversal tracker returned from
startTraversal(ApiAnalyzer, ArchiveAnalyzer, ArchiveAnalyzer)
or null if that method returned an
empty optional.Copyright © 2014-2021 Lukas Krejci. All Rights Reserved.