Package org.revapi.base

Class BaseArchiveAnalyzer<F extends BaseElementForest<E>,E extends Element<E>>

java.lang.Object

org.revapi.base.BaseArchiveAnalyzer<F,E>

Type Parameters:

E - the parent type of all elements produced by the API analyzer

All Implemented Interfaces:

ArchiveAnalyzer<E>

Direct Known Subclasses:

BaseEagerLoadingArchiveAnalyzer

public abstract class BaseArchiveAnalyzer<F extends BaseElementForest<E>,E extends Element<E>>
extends Object
implements ArchiveAnalyzer<E>

A convenience base class for API analyzers. This class tries to simplify the element filtering performed during the analysis (analyze(TreeFilter)) by requiring the subclasses to implement a more fine-grained "discovery" of elements (preAnalyze(), discoverRoots(Object), discoverElements(Object, Element) and postAnalyze(Object)).

See Also:

BaseEagerLoadingArchiveAnalyzer, ZipArchiveAnalyzer

Constructor Summary

Constructors

Constructor	Description
BaseArchiveAnalyzer(ApiAnalyzer<E> apiAnalyzer, API api)

Method Summary

Modifier and Type	Method	Description
protected void	addTo(Object context, TreeFilter<E> filter, SortedSet<E> siblings, E element)	Adds an element to the set of its potential siblings.
F	analyze(TreeFilter<E> filter)	Analyzes the API archives and filters the forest using the provided filter.
protected abstract Stream<E>	discoverElements(Object context, E parent)	Discovers new elements under the given parent element.
protected abstract Stream<E>	discoverRoots(Object context)	Discovers all the root elements in the relevant archives of the API.
API	getApi()
ApiAnalyzer<E>	getApiAnalyzer()
protected abstract F	newElementForest()	Creates a new empty element forest of given type.
protected void	postAnalyze(Object context)	Called as the last thing in analyze(TreeFilter).
protected Object	preAnalyze()	Called as the first thing in analyze(TreeFilter).
void	prune(ElementForest<E> forest)	Once all the filtering on the element forest is done, the analyzer is allowed one final "pass" through the forest to remove any elements that should not be there any longer.

Methods inherited from class java.lang.Object

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

Constructor Detail

BaseArchiveAnalyzer

public BaseArchiveAnalyzer(ApiAnalyzer<E> apiAnalyzer,
                           API api)

Method Detail

getApiAnalyzer

public ApiAnalyzer<E> getApiAnalyzer()

Specified by:

getApiAnalyzer in interface ArchiveAnalyzer<F extends BaseElementForest<E>>

Returns:

the ApiAnalyzer that created this instance

getApi

public API getApi()

Specified by:

getApi in interface ArchiveAnalyzer<F extends BaseElementForest<E>>

Returns:

the API that this analyzer analyzes

analyze

public F analyze(TreeFilter<E> filter)

Description copied from interface: ArchiveAnalyzer

Analyzes the API archives and filters the forest using the provided filter.

This produces a preliminary forest which can be too "wide" because of Ternary.UNDECIDED elements or non-local relationships between elements. Once this method returns the preliminary forest, the callers should also call the ArchiveAnalyzer.prune(ElementForest) method to obtain a forest that is truly minimal.

Specified by:

analyze in interface ArchiveAnalyzer<F extends BaseElementForest<E>>

Parameters:

filter - the filter to use to filter out unwanted elements from the forest

Returns:

the preliminary element forest that should be pruned before analysis

prune

public void prune(ElementForest<E> forest)

Description copied from interface: ArchiveAnalyzer

Once all the filtering on the element forest is done, the analyzer is allowed one final "pass" through the forest to remove any elements that should not be there any longer.

Specified by:

prune in interface ArchiveAnalyzer<F extends BaseElementForest<E>>

Parameters:

forest - the forest to prune

newElementForest

protected abstract F newElementForest()

Creates a new empty element forest of given type.

preAnalyze

@Nullable
protected Object preAnalyze()

Called as the first thing in analyze(TreeFilter). Can be used by the subclasses to initialize themselves for the analysis.

Returns:

a context object that can be used by the other methods or null if no such thing is needed.

See Also:

postAnalyze(Object)

postAnalyze

protected void postAnalyze(@Nullable
                           Object context)

Called as the last thing in analyze(TreeFilter). Can be used by the subclasses to clean up after the analysis.

Parameters:

context - the context object created in the preAnalyze()

See Also:

preAnalyze()

discoverRoots

protected abstract Stream<E> discoverRoots(@Nullable
                                           Object context)

Discovers all the root elements in the relevant archives of the API. What is a relevant archive is determined by the implementor. This is called after preAnalyze() and before all discoverElements(Object, Element) calls.

Parameters:

context - the optional context obtained from the preAnalyze() method

Returns:

a stream of elements

discoverElements

protected abstract Stream<E> discoverElements(@Nullable
                                              Object context,
                                              E parent)

Discovers new elements under the given parent element.

Parameters:

parent - the parent to discover children of

Returns:

a stream of elements

addTo

protected final void addTo(@Nullable
                           Object context,
                           TreeFilter<E> filter,
                           SortedSet<E> siblings,
                           E element)

Adds an element to the set of its potential siblings. This assumes the siblings are part of a BaseElementForest and therefore automatically update the parent-child relationships.

This method can be used to establish the right hierarchy of elements in the element forest.

Parameters:

filter - the filter that the element needs to match to be added to the siblings

siblings - the set of siblings

element - the element to potentially add to siblings