Package org.revapi

Interface Element<E extends Element<E>>

  • Type Parameters:
    E - the common base class of all elements of some api analyzer
    All Superinterfaces:
    Comparable<E>
    All Known Implementing Classes:
    BaseElement, SimpleElement

    public interface Element<E extends Element<E>>
    extends Comparable<E>
    An element in a forest representation of given "language" under API inspection. In case of programming languages this will usually be a (trimmed down) abstract syntax tree, in case of XSD this can be an actual DOM tree.

    An element is comparable with all other element types for given language, giving a total ordering across all and any element types given language defines.

    The Comparable.compareTo(Object) method is used by Revapi to match up the pairs of elements from the old and new API. Revapi sorts the elements from old and new API (using their natural order, i.e. using the compareTo method) and then iterates through both sets at the same time, comparing the elements.

    API traversal outline
    Comparison Meaning Result Iteration Progress
    old < new New is considered removed from the API (old, null) Old moves forward, new stays
    old > new Old is considered removed from the API (null, new) New moves forward, old stays
    old == new New is considered equal to old (old, new) Old moves forward, new moves forward
    The result from the above comparison is handed over to the difference analyzer which is assumed to do a more detailed analysis on the elements and return a (possibly empty) set of differences.
    Since:
    0.1
    Author:
    Lukas Krejci
    See Also:
    CoIterator
    • Method Detail

      • as

        default <T extends Element<?>> T as​(Class<T> type)
        Casts this element to the provided type.
        Parameters:
        type - the type to cast this instance to
        Returns:
        this cast as the provided type
        Throws:
        ClassCastException - if this instance cannot be cast to the provided type
      • getApi

        API getApi()
        Returns:
        the API version this element comes from
      • getArchive

        @Nullable
        Archive getArchive()
        Returns:
        the archive the element comes from or null if that cannot be determined
      • getParent

        @Nullable
        E getParent()
        Returns:
        the parent element or null if this is a root element
      • setParent

        void setParent​(@Nullable
                       E parent)
        Sets a new parent.
        Parameters:
        parent - the new parent of this element
      • getFullHumanReadableString

        String getFullHumanReadableString()
        Provides the full "path" to the element in the forest in a human readable way. This method is meant to be used by the reporters to identify the element in the reports.
        Returns:
        human readable representation of the element
      • getReferencingElements

        default Set<Reference<E>> getReferencingElements()
        If the API analyzer supports the feature, this returns the set of elements that reference this element in some way (typically, those would be the use sites of this element).
      • getCumulativeReferencingElements

        default Set<Reference<E>> getCumulativeReferencingElements()
        This returns the referencing elements of this element and of all its children, recursively.
      • getReferencedElements

        default Set<Reference<E>> getReferencedElements()
        If the API analyzer supports the feature, this returns the set of elements that are referenced by this element in some way (typically, those would be the elements somehow used by this element).
      • getCumulativeReferencedElements

        default Set<Reference<E>> getCumulativeReferencedElements()
        This returns the referenced elements of this element and of all its children, recursively.
      • searchChildren

        @Deprecated
        <T extends Element<E>> List<T> searchChildren​(Class<T> resultType,
                                                      boolean recurse,
                                                      @Nullable
                                                      Filter<? super T> filter)
        Deprecated.
        This method is functionally equivalent to searchChildren(java.util.List, java.lang.Class, boolean, org.revapi.query.Filter) but returns the result in a newly allocated list instance. This is basically a convenience method to enable a more succinct expressions.
        Type Parameters:
        T - the type of the elements to look for
        Parameters:
        resultType - the type of the elements to look for
        recurse - false to search only in direct children of the element, true to search recursively
        filter - optional filter to further trim the number of results @return the list of child elements of given type potentially satisfying given filter
        Returns:
        the list of found elements
      • searchChildren

        @Deprecated
        <T extends Element<E>> void searchChildren​(List<T> results,
                                                   Class<T> resultType,
                                                   boolean recurse,
                                                   @Nullable
                                                   Filter<? super T> filter)
        Deprecated.
        Recursively searches the children of this element for elements of given type, potentially applicable to given filter.

        This is identical to searchChildren(Class, boolean, org.revapi.query.Filter) in behavior but avoids the instantiation of a new list.

        Type Parameters:
        T - the type of the elements to look for
        Parameters:
        results - the list of the results to fill
        resultType - the type of the elements to look for
        recurse - false to search only in direct children of the element, true to search recursively
        filter - optional filter to further trim the number of results
      • iterateOverChildren

        @Deprecated
        <T extends Element<E>> Iterator<T> iterateOverChildren​(Class<T> resultType,
                                                               boolean recurse,
                                                               @Nullable
                                                               Filter<? super T> filter)
        Deprecated.
        use the more standard stream(Class, boolean)
        Similar to search methods but avoids the traversal over the whole forest. Instead the traversal is incremental and governed by the returned iterator.
        Type Parameters:
        T - the type of the elements to look for
        Parameters:
        resultType - the type of elements to look for
        recurse - if true, the iterator traverses the element forest using depth first search
        filter - optional filter to further trim the number of results
        Returns:
        the iterator that will iterate over the results
        See Also:
        searchChildren(Class, boolean, org.revapi.query.Filter)
      • stream

        default <T extends Element<E>> Stream<T> stream​(Class<T> elementType,
                                                        boolean recurse)
        A stream equivalent of iterateOverChildren(Class, boolean, Filter). The resulting stream contains distinct non-null elements.
        Type Parameters:
        T - the type of the elements to look for
        Parameters:
        elementType - the type of elements to look for
        recurse - if true, the iterator traverses the element forest using depth first search
        Returns:
        the stream of elements complying to the filter