- Type Parameters:
E- the type of the element expected in the
transformmethod. Note that you need to be careful about this type because the types of the elements passed to
tryTransformdepend on the differences that the transform is interested in. Thus you may end up with
ClassCastExceptions 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, ConfigurableA difference transform may elect to transform certain kinds of differences into other kinds. This comes useful in custom extensions that want to "modify the behavior" of other extensions by consuming and transforming the differences found by the other extensions into something else.
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.
- Lukas Krejci
All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods Modifier and Type Method Description
endTraversal(DifferenceTransform.TraversalTracker<?> tracker)Called after everything traversed using the provided analyzer has been transformed.
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.
transform(E oldElement, E newElement, Difference difference)Deprecated.use
tryTransform(Element, Element, Difference)which offers richer possibilities
tryTransform(E oldElement, E newElement, Difference difference)Tries to transform the difference into some other one(s) given the old and new elements.
- The list of regexes to match the difference codes this transform can handle.
@Deprecated @Nullable default Difference transform(@Nullable E oldElement, @Nullable E newElement, Difference difference)Deprecated.use
tryTransform(Element, Element, Difference)which offers richer possibilitiesReturns a transformed version of the difference. If this method returns null, the difference is discarded and not reported. Therefore, if you don't want to transform a difference, just return it.
The code of the supplied difference will match at least one of the regexes returned from the
oldElement- the old differing element
newElement- the new differing element
difference- the difference description
- the transformed difference or the passed in difference if no transformation necessary or null if the difference should be discarded
default TransformationResult tryTransform(@Nullable E oldElement, @Nullable E newElement, Difference difference)Tries to transform the difference into some other one(s) given the old and new elements.
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 element
newElement- the new element, if any, being compared to the old element
difference- the difference to transform
- the transformation result
default <X extends Element<X>> Optional<DifferenceTransform.TraversalTracker<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.
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 APIs
oldArchiveAnalyzer- the archive analyzer used for obtaining the element forest of the old API
newArchiveAnalyzer- the archive analyzer used for obtaining the element forest of the new API
- a transform tracker if the transform can work with the provided api analyzer, empty optional otherwise
default void endTraversal(@Nullable DifferenceTransform.TraversalTracker<?> tracker)Called after everything traversed using the provided analyzer has been transformed. This can be used to clean up resources used during the analysis using the provided analyzer. After this method was called a new "round" of analysis may start using a different API analyzer. This is advertised to the transforms by calling
startTraversal(ApiAnalyzer, ArchiveAnalyzer, ArchiveAnalyzer)again.
tracker- the traversal tracker returned from
startTraversal(ApiAnalyzer, ArchiveAnalyzer, ArchiveAnalyzer)or null if that method returned an empty optional.