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 thecompareTo
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 - Since:
- 0.1
- Author:
- Lukas Krejci
- See Also:
CoIterator
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods Modifier and Type Method Description default <T extends Element<?>>
Tas(Class<T> type)
Casts this element to the provided type.API
getApi()
Archive
getArchive()
SortedSet<E>
getChildren()
default Set<Reference<E>>
getCumulativeReferencedElements()
This returns thereferenced elements
of this element and of all its children, recursively.default Set<Reference<E>>
getCumulativeReferencingElements()
This returns thereferencing elements
of this element and of all its children, recursively.String
getFullHumanReadableString()
Provides the full "path" to the element in the forest in a human readable way.E
getParent()
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).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).<T extends Element<E>>
Iterator<T>iterateOverChildren(Class<T> resultType, boolean recurse, Filter<? super T> filter)
Deprecated.use the more standardstream(Class, boolean)
<T extends Element<E>>
List<T>searchChildren(Class<T> resultType, boolean recurse, Filter<? super T> filter)
Deprecated.in favor ofstream(Class, boolean)
<T extends Element<E>>
voidsearchChildren(List<T> results, Class<T> resultType, boolean recurse, Filter<? super T> filter)
Deprecated.in favor ofstream(Class, boolean)
void
setParent(E parent)
Sets a new parent.default <T extends Element<E>>
Stream<T>stream(Class<T> elementType, boolean recurse)
A stream equivalent ofiterateOverChildren(Class, boolean, Filter)
.-
Methods inherited from interface java.lang.Comparable
compareTo
-
-
-
-
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
-
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 thereferencing 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 thereferenced 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.in favor ofstream(Class, boolean)
This method is functionally equivalent tosearchChildren(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 forrecurse
- false to search only in direct children of the element, true to search recursivelyfilter
- 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.in favor ofstream(Class, boolean)
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 fillresultType
- the type of the elements to look forrecurse
- false to search only in direct children of the element, true to search recursivelyfilter
- 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 standardstream(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 forrecurse
- if true, the iterator traverses the element forest using depth first searchfilter
- 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 ofiterateOverChildren(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 forrecurse
- if true, the iterator traverses the element forest using depth first search- Returns:
- the stream of elements complying to the filter
-
-