org.revapi.java.spi

Class CheckBase

java.lang.Object

org.revapi.java.spi.CheckBase

All Implemented Interfaces:

Configurable, Check

public abstract class CheckBase
extends Object
implements Check

A basic implementation of the Check interface. This class easies the matching of the visit*() methods and their corresponding visitEnd() by keeping track of the "depth" individual calls (see the recursive nature of the call order).

This class also contains a couple of utility methods for checking the accessibility of elements, etc.

Since:

0.1

Author:

Lukas Krejci

See Also:

pushActive(javax.lang.model.element.Element, javax.lang.model.element.Element, Object...), popIfActive()

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	CheckBase.ActiveElements<T extends Element> Represents the elements that have been pushed onto the active elements stack.

Constructor Summary

Constructors

Constructor and Description
CheckBase()

Method Summary

Methods

Modifier and Type	Method and Description
protected Difference	createDifference(Code code, Object... params)
protected Difference	createDifference(Code code, Object[] params, Object... attachments)
protected List<Difference>	doEnd()
protected List<Difference>	doVisitAnnotation(AnnotationMirror oldAnnotation, AnnotationMirror newAnnotation)
protected void	doVisitClass(TypeElement oldType, TypeElement newType)
protected void	doVisitField(VariableElement oldField, VariableElement newField)
protected void	doVisitMethod(ExecutableElement oldMethod, ExecutableElement newMethod)
protected void	doVisitMethodParameter(VariableElement oldParameter, VariableElement newParameter)
AnalysisContext	getAnalysisContext()
String[]	getConfigurationRootPaths()
Reader	getJSONSchema(String configurationRootPath)
TypeEnvironment	getNewTypeEnvironment()
TypeEnvironment	getOldTypeEnvironment()
void	initialize(AnalysisContext analysisContext)
static boolean	isAccessible(Element e) Returns true if the provided element is public or protected, false otherwise.
static boolean	isAccessibleOrInAPI(Element e, TypeEnvironment env) Certain elements might be forced into the API even if they are not accessible (this is most usually a programming error).
static boolean	isBothAccessible(Element a, Element b) Checks whether both provided elements are public or protected.
static boolean	isBothAccessibleOrInApi(Element a, TypeEnvironment envA, Element b, TypeEnvironment envB) Extension of the isBothAccessibleOrInApi(javax.lang.model.element.Element, TypeEnvironment, javax.lang.model.element.Element, TypeEnvironment) method for 2 elements.
static boolean	isBothPrivate(Element a, Element b) Checks whether both provided elements are (package) private.
static boolean	isMissing(Element e) The element is deemed missing if its type kind (TypeMirror.getKind()) is TypeKind.ERROR.
protected <T extends Element> CheckBase.ActiveElements<T>	popIfActive() Pops the top of the stack of active elements if the current position in the call stack corresponds to the one that pushed the active elements.
protected <T extends Element> void	pushActive(T oldElement, T newElement, Object... context) If called in one of the doVisit*() methods, this method will push the elements along with some contextual data onto an internal stack.
void	setNewTypeEnvironment(TypeEnvironment env) The environment containing the new version of the classes.
void	setOldTypeEnvironment(TypeEnvironment env) The environment containing the old version of the classes.
List<Difference>	visitAnnotation(AnnotationMirror oldAnnotation, AnnotationMirror newAnnotation) Please override the doVisitAnnotation(javax.lang.model.element.AnnotationMirror, javax.lang.model.element.AnnotationMirror) instead.
void	visitClass(TypeElement oldType, TypeElement newType) Please override the doVisitClass(javax.lang.model.element.TypeElement, javax.lang.model.element.TypeElement) instead.
List<Difference>	visitEnd() Please override the doEnd() method instead.
void	visitField(VariableElement oldField, VariableElement newField) Please override the doVisitField(javax.lang.model.element.VariableElement, javax.lang.model.element.VariableElement) instead.
void	visitMethod(ExecutableElement oldMethod, ExecutableElement newMethod) Please override the doVisitMethod(javax.lang.model.element.ExecutableElement, javax.lang.model.element.ExecutableElement) instead.
void	visitMethodParameter(VariableElement oldParameter, VariableElement newParameter)

Methods inherited from class java.lang.Object

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

Constructor Detail

CheckBase

public CheckBase()

Method Detail

isBothPrivate

public static boolean isBothPrivate(@Nullable
                    Element a,
                    @Nullable
                    Element b)

Checks whether both provided elements are (package) private. If one of them is null, the fact cannot be determined and therefore this method would return false.

Parameters:

a - first element

b - second element

Returns:

true if both elements are not null and are private or package private

isBothAccessible

public static boolean isBothAccessible(@Nullable
                       Element a,
                       @Nullable
                       Element b)

Checks whether both provided elements are public or protected. If one at least one of them is null, the method returns false, because the accessibility cannot be truthfully detected in that case.

Parameters:

a - first element

b - second element

Returns:

true if both elements are not null and accessible (i.e. public or protected)

isAccessible

public static boolean isAccessible(@Nonnull
                   Element e)

Returns true if the provided element is public or protected, false otherwise.

isMissing

public static boolean isMissing(@Nonnull
                Element e)

The element is deemed missing if its type kind (TypeMirror.getKind()) is TypeKind.ERROR.

Parameters:

e - the element

Returns:

true if the element is missing, false otherwise

isAccessibleOrInAPI

public static boolean isAccessibleOrInAPI(@Nonnull
                          Element e,
                          @Nonnull
                          TypeEnvironment env)

Certain elements might be forced into the API even if they are not accessible (this is most usually a programming error). This method is an extension of the isAccessible(javax.lang.model.element.Element) and also checks for the explicit presence of the element in the API by using the TypeEnvironment.isExplicitPartOfAPI(javax.lang.model.element.TypeElement) method.

Parameters:

e - the element

env - the type environment from which the element comes from

Returns:

true if the element is accessible or is an explicit part of the API

isBothAccessibleOrInApi

public static boolean isBothAccessibleOrInApi(@Nonnull
                              Element a,
                              @Nonnull
                              TypeEnvironment envA,
                              @Nonnull
                              Element b,
                              @Nonnull
                              TypeEnvironment envB)

Extension of the isBothAccessibleOrInApi(javax.lang.model.element.Element, TypeEnvironment, javax.lang.model.element.Element, TypeEnvironment) method for 2 elements.

Parameters:

a - the first element

envA - the type environment of the first element

b - the second element

envB - the type environment of the second element

Returns:

true if both elements are accessible or an explicit part of their respective APIs.

createDifference

@Nonnull
protected Difference createDifference(@Nonnull
                                  Code code,
                                  Object... params)

createDifference

@Nonnull
protected Difference createDifference(@Nonnull
                                  Code code,
                                  @Nonnull
                                  Object[] params,
                                  Object... attachments)

getOldTypeEnvironment

@Nonnull
public TypeEnvironment getOldTypeEnvironment()

getNewTypeEnvironment

@Nonnull
public TypeEnvironment getNewTypeEnvironment()

getAnalysisContext

@Nonnull
public AnalysisContext getAnalysisContext()

getConfigurationRootPaths

@Nullable
public String[] getConfigurationRootPaths()

Specified by:

getConfigurationRootPaths in interface Configurable

getJSONSchema

@Nullable
public Reader getJSONSchema(@Nonnull
                            String configurationRootPath)

Specified by:

getJSONSchema in interface Configurable

initialize

public void initialize(@Nonnull
              AnalysisContext analysisContext)

Specified by:

initialize in interface Configurable

setOldTypeEnvironment

public void setOldTypeEnvironment(@Nonnull
                         TypeEnvironment env)

Description copied from interface: Check

The environment containing the old version of the classes. This can be used to reason about the classes when doing the checks.

Called once after the check has been instantiated.

Specified by:

setOldTypeEnvironment in interface Check

Parameters:

env - the environment to obtain the helper objects using which one can navigate and examine types

setNewTypeEnvironment

public void setNewTypeEnvironment(@Nonnull
                         TypeEnvironment env)

Description copied from interface: Check

The environment containing the new version of the classes. This can be used to reason about the classes when doing the checks.

Called once after the check has been instantiated.

Specified by:

setNewTypeEnvironment in interface Check

Parameters:

env - the environment to obtain the helper objects using which one can navigate and examine types

visitEnd

@Nullable
public final List<Difference> visitEnd()

Please override the doEnd() method instead.

Specified by:

visitEnd in interface Check

Returns:

the list of found differences between corresponding elements or null if no differences found (null is considered equivalent to returning an empty collection).

See Also:

Check.visitEnd()

doEnd

@Nullable
protected List<Difference> doEnd()

visitClass

public final void visitClass(@Nullable
              TypeElement oldType,
              @Nullable
              TypeElement newType)

Please override the doVisitClass(javax.lang.model.element.TypeElement, javax.lang.model.element.TypeElement) instead.

Specified by:

visitClass in interface Check

See Also:

Check.visitClass(javax.lang.model.element.TypeElement, javax.lang.model.element.TypeElement)

doVisitClass

protected void doVisitClass(@Nullable
                TypeElement oldType,
                @Nullable
                TypeElement newType)

visitMethod

public final void visitMethod(@Nullable
               ExecutableElement oldMethod,
               @Nullable
               ExecutableElement newMethod)

Please override the doVisitMethod(javax.lang.model.element.ExecutableElement, javax.lang.model.element.ExecutableElement) instead.

Specified by:

visitMethod in interface Check

See Also:

Check.visitMethod(javax.lang.model.element.ExecutableElement, javax.lang.model.element.ExecutableElement)

doVisitMethod

protected void doVisitMethod(@Nullable
                 ExecutableElement oldMethod,
                 @Nullable
                 ExecutableElement newMethod)

visitMethodParameter

public final void visitMethodParameter(@Nullable
                        VariableElement oldParameter,
                        @Nullable
                        VariableElement newParameter)

Specified by:

visitMethodParameter in interface Check

doVisitMethodParameter

protected void doVisitMethodParameter(@Nullable
                          VariableElement oldParameter,
                          @Nullable
                          VariableElement newParameter)

visitField

public final void visitField(@Nullable
              VariableElement oldField,
              @Nullable
              VariableElement newField)

Please override the doVisitField(javax.lang.model.element.VariableElement, javax.lang.model.element.VariableElement) instead.

Specified by:

visitField in interface Check

See Also:

Check.visitField(javax.lang.model.element.VariableElement, javax.lang.model.element.VariableElement)

doVisitField

protected void doVisitField(@Nullable
                VariableElement oldField,
                @Nullable
                VariableElement newField)

visitAnnotation

@Nullable
public final List<Difference> visitAnnotation(@Nullable
                                        AnnotationMirror oldAnnotation,
                                        @Nullable
                                        AnnotationMirror newAnnotation)

Please override the doVisitAnnotation(javax.lang.model.element.AnnotationMirror, javax.lang.model.element.AnnotationMirror) instead.

Specified by:

visitAnnotation in interface Check

See Also:

Check.visitAnnotation(javax.lang.model.element.AnnotationMirror, javax.lang.model.element.AnnotationMirror)

doVisitAnnotation

@Nullable
protected List<Difference> doVisitAnnotation(@Nullable
                                          AnnotationMirror oldAnnotation,
                                          @Nullable
                                          AnnotationMirror newAnnotation)

pushActive

protected final <T extends Element> void pushActive(@Nullable
                                  T oldElement,
                                  @Nullable
                                  T newElement,
                                  Object... context)

If called in one of the doVisit*() methods, this method will push the elements along with some contextual data onto an internal stack.

You can then retrieve the contents on the top of the stack in your doEnd() override by calling the popIfActive() method.

Type Parameters:

T - the type of the elements

Parameters:

oldElement - the old API element

newElement - the new API element

context - optional contextual data

popIfActive

@Nullable
protected <T extends Element> CheckBase.ActiveElements<T> popIfActive()

Pops the top of the stack of active elements if the current position in the call stack corresponds to the one that pushed the active elements.

This method does not do any type checks, so take care to retrieve the elements with the same types used to push to them onto the stack.

Type Parameters:

T - the type of the elements

Returns:

the active elements or null if the current call stack did not push any active elements onto the stack