Package org.revapi.base

Class BaseElement<E extends Element<E>>

java.lang.Object

org.revapi.base.BaseElement<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 Summary

Constructors

Modifier	Constructor	Description
protected	BaseElement(API api)
protected	BaseElement(API api, Archive archive)

Method Summary

Modifier and Type	Method	Description
protected E	castThis()	Casts "this" to E.
BaseElement<E>	clone()	Returns a shallow copy of this element.
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()
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).
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)	Similar to search methods but avoids the traversal over the whole forest.
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.
protected Reference<E>	newReference(E target, Reference.Type<E> type)	Creates a new reference instance to be used in the getReferencedElements() or getReferencingElements().
<T extends Element<E>> List<T>	searchChildren(Class<T> resultType, boolean recurse, Filter<? super T> filter)	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.
<T extends Element<E>> void	searchChildren(List<T> results, Class<T> resultType, boolean recurse, Filter<? super T> filter)	Recursively searches the children of this element for elements of given type, potentially applicable to given filter.
protected void	setArchive(Archive archive)
void	setParent(E parent)	Sets the parent element.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.lang.Comparable

compareTo

Methods inherited from interface org.revapi.Element

as, getCumulativeReferencedElements, getCumulativeReferencingElements, stream

Constructor Detail

BaseElement

protected BaseElement(API api)

Parameters:

api - the API the element comes from

BaseElement

protected BaseElement(API api,
                      @Nullable
                      Archive archive)

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

getApi

@Nonnull
public API getApi()

Specified by:

getApi in interface Element<E extends Element<E>>

Returns:

the API version this element comes from

getArchive

@Nullable
public Archive getArchive()

Specified by:

getArchive in interface Element<E extends Element<E>>

Returns:

the archive the element comes from or null if that cannot be determined

setArchive

protected void setArchive(@Nullable
                          Archive archive)

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

getChildren

@Nonnull
public SortedSet<E> getChildren()

Specified by:

getChildren in interface Element<E extends Element<E>>

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