Class BaseElement<E extends Element<E>>

  • Type Parameters:
    E - the parent type of all elements in the API
    All Implemented Interfaces:
    Cloneable, Comparable<E>, Element<E>

    public abstract class BaseElement<E extends Element<E>>
    extends Object
    implements Element<E>, Cloneable
    A base class for API elements. It is not mandatory to inherit from this class but it provides a good base implementation for most of the cases.

    The type parameter, <E>, denotes the parent type of all elements produced by a certain ApiAnalyzer. All these types are assumed to be mutually comparable (and therefore implement Comparable<E>).

    • Constructor Detail

      • BaseElement

        protected BaseElement​(API api)
        Parameters:
        api - the API the element comes from
    • Method Detail

      • castThis

        protected E castThis()
        Casts "this" to E. This is unsafe from the language perspective but we suppose E is the base type of all elements of given API analyzer, so this should always be safe.
        Returns:
        this instance as the base element type
      • getFullHumanReadableString

        @Nonnull
        public String getFullHumanReadableString()
        Description copied from interface: Element
        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.
        Specified by:
        getFullHumanReadableString in interface Element<E extends Element<E>>
        Returns:
        human readable representation of the element
      • getParent

        @Nullable
        public E getParent()
        Specified by:
        getParent in interface Element<E extends Element<E>>
        Returns:
        the parent element or null if this is a root element
      • setParent

        public void setParent​(@Nullable
                              E parent)
        Sets the parent element. No other processing is automagically done (i.e. the parent's children set is NOT updated by calling this method).
        Specified by:
        setParent in interface Element<E extends Element<E>>
        Parameters:
        parent - the new parent element
      • getReferencingElements

        public Set<Reference<E>> getReferencingElements()
        Description copied from interface: Element
        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).

        Note that, generally speaking, the references should not be used in TreeFilter implementations because the filters are used during the construction of the ElementForest meaning that the references are not yet finalized at that point in time.

        Specified by:
        getReferencingElements in interface Element<E extends Element<E>>
      • getReferencedElements

        public Set<Reference<E>> getReferencedElements()
        Description copied from interface: Element
        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).

        Note that, generally speaking, the references should not be used in TreeFilter implementations because the filters are used during the construction of the ElementForest meaning that the references are not yet finalized at that point in time.

        Specified by:
        getReferencedElements in interface Element<E extends Element<E>>
      • clone

        public BaseElement<E> clone()
        Returns a shallow copy of this element. In particular, its parent and children will be cleared.
        Overrides:
        clone in class Object
        Returns:
        a copy of this element
      • newChildrenInstance

        protected SortedSet<E> newChildrenInstance()
        Override this method if you need some specialized instance of sorted set or want to do some custom pre-populating or initialization of the children. This default implementation merely returns an empty new TreeSet instance.
        Returns:
        a new sorted set instance to store the children in
      • searchChildren

        public <T extends Element<E>> List<T> searchChildren​(Class<T> resultType,
                                                             boolean recurse,
                                                             @Nullable
                                                             Filter<? super T> filter)
        Description copied from interface: Element
        This method is functionally equivalent to Element.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.
        Specified by:
        searchChildren in interface Element<E extends Element<E>>
        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

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

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

        Specified by:
        searchChildren in interface Element<E extends Element<E>>
        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

        public <T extends Element<E>> Iterator<T> iterateOverChildren​(Class<T> resultType,
                                                                      boolean recurse,
                                                                      @Nullable
                                                                      Filter<? super T> filter)
        Description copied from interface: Element
        Similar to search methods but avoids the traversal over the whole forest. Instead the traversal is incremental and governed by the returned iterator.
        Specified by:
        iterateOverChildren in interface Element<E extends Element<E>>
        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:
        Element.searchChildren(Class, boolean, org.revapi.query.Filter)
      • newReference

        protected Reference<E> newReference​(E target,
                                            Reference.Type<E> type)
        Creates a new reference instance to be used in the getReferencedElements() or getReferencingElements(). This method should be overridden by any subclass that uses a subclass for Reference for referencing the elements.
        Parameters:
        target - the target element
        type - the type of the reference
        Returns:
        a new reference with given type pointing to the target element