Package org.revapi

Interface DifferenceTransform<E extends Element<?>>

  • Type Parameters:
    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 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.
    All Superinterfaces:
    AutoCloseable, Configurable
    All Known Implementing Classes:
    BaseDifferenceTransform, SimpleDifferenceTransform
    public interface DifferenceTransform<E extends Element<?>>
extends AutoCloseable, Configurable
    A 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.

    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.

    Since:
    0.1
    Author:
    Lukas Krejci

    • Method Detail

      • getDifferenceCodePatterns

        Pattern[] getDifferenceCodePatterns()
        Returns:
        The list of regexes to match the difference codes this transform can handle.

      • transform

        @Deprecated
@Nullable
default Difference transform​(@Nullable
                             E oldElement,
                             @Nullable
                             E newElement,
                             Difference difference)
        Deprecated.
        use tryTransform(Element, Element, Difference) which offers richer possibilities
        Returns 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 getDifferenceCodePatterns() method.

        Parameters:
        oldElement - the old differing element
        newElement - the new differing element
        difference - the difference description
        Returns:
        the transformed difference or the passed in difference if no transformation necessary or null if the difference should be discarded

      • tryTransform

        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.

        Parameters:
        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
        Returns:
        the transformation result

      • startTraversal

        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.

        Parameters:
        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
        Returns:
        a transform tracker if the transform can work with the provided api analyzer, empty optional otherwise