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 Summary

Modifier and Type	Method and Description
default <T extends Element<?>> T	as(Class<T> type) Casts this element to the provided type.
API	getApi()
Archive	getArchive()
SortedSet<E>	getChildren()
String	getFullHumanReadableString() Provides the full "path" to the element in the forest in a human readable way.
E	getParent()
<T extends Element<E>> Iterator<T>	iterateOverChildren(Class<T> resultType, boolean recurse, Filter<? super T> filter) Deprecated. use the more standard stream(Class, boolean)
<T extends Element<E>> List<T>	searchChildren(Class<T> resultType, boolean recurse, Filter<? super T> filter) Deprecated. in favor of stream(Class, boolean)
<T extends Element<E>> void	searchChildren(List<T> results, Class<T> resultType, boolean recurse, Filter<? super T> filter) Deprecated. in favor of stream(Class, boolean)
void	setParent(E parent) Sets a new parent.
default <T extends Element<E>> java.util.stream.Stream<T>	stream(Class<T> elementType, boolean recurse) A stream equivalent of iterateOverChildren(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

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

getChildren

SortedSet<E> getChildren()

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

searchChildren

@Deprecated
<T extends Element<E>> List<T> searchChildren(Class<T> resultType,
                                                          boolean recurse,
                                                          @Nullable
                                                          Filter<? super T> filter)

Deprecated. in favor of stream(Class, boolean)

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. in favor of stream(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 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>> java.util.stream.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