org.revapi.java.spi

Interface Check

All Superinterfaces:

org.revapi.configuration.Configurable

All Known Implementing Classes:

CheckBase

public interface Check
extends org.revapi.configuration.Configurable

An interface that java API checkers need to implement.

The methods on this interface are called in the following order:

 initialize
 setOldTypeEnvironment
 setNewTypeEnvironment
 (visitClass
     (visitClass ... visitEnd)* //inner classes
     (visitField
         visitAnnotation*
      visitEnd)*
     (visitMethod
         (visitMethodParameter
             visitAnnotation*
          visitEnd)*
         visitAnnotation*
      visitEnd)*
     visitAnnotation*
  visitEnd)*
 

Consider inheriting from the CheckBase instead of directly implementing this interface because it takes care of matching the corresponding visit*() and visitEnd() calls.

Since:

0.1

Author:

Lukas Krejci

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Check.Type

Method Summary

Modifier and Type	Method and Description
EnumSet<Check.Type>	getInterest() Each check typically checks only a single type of java element - a method or an annotation - but may be interested in more.
boolean	isDescendingOnNonExisting() When the analyzer encounters an element that doesn't have a matching counterpart in the other version of the API, by default, the analysis doesn't descend into the children of the existing element.
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<org.revapi.Difference>	visitAnnotation(JavaAnnotationElement oldAnnotation, JavaAnnotationElement newAnnotation) Visiting annotation is slightly different, because it is not followed by the standard visitEnd() call.
void	visitClass(JavaTypeElement oldType, JavaTypeElement newType)
List<org.revapi.Difference>	visitEnd() Each of the other visit* calls is followed by a corresponding call to this method in a stack-like manner.
void	visitField(JavaFieldElement oldField, JavaFieldElement newField)
void	visitMethod(JavaMethodElement oldMethod, JavaMethodElement newMethod)
void	visitMethodParameter(JavaMethodParameterElement oldParameter, JavaMethodParameterElement newParameter)

Methods inherited from interface org.revapi.configuration.Configurable

getExtensionId, getJSONSchema, initialize

Method Detail

isDescendingOnNonExisting

boolean isDescendingOnNonExisting()

When the analyzer encounters an element that doesn't have a matching counterpart in the other version of the API, by default, the analysis doesn't descend into the children of the existing element. I.e. if the new API has an element that didn't exist in the old API, it is usually not necessary to also analyze the children of the element in the new API, because that would usually just add noise to the report. Certain checks though might want to inspect the child elements anyway because they look for qualities that could otherwise be missed.

Returns:

true if this check wants to descend into child elements even for incomplete element pairs

setOldTypeEnvironment

void setOldTypeEnvironment(@Nonnull
                           TypeEnvironment env)

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.

Parameters:

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

setNewTypeEnvironment

void setNewTypeEnvironment(@Nonnull
                           TypeEnvironment env)

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.

Parameters:

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

getInterest

EnumSet<Check.Type> getInterest()

Each check typically checks only a single type of java element - a method or an annotation - but may be interested in more.

This method must be used by the implementations to advertise what type of checks they are interested in. Only the appropriate visit* calls will then be made on the check instances.

Returns:

the set of check types this instance is interested in performing

visitEnd

@Nullable
List<org.revapi.Difference> visitEnd()

Each of the other visit* calls is followed by a corresponding call to this method in a stack-like manner.

I.e. a series of calls might look like this:

 visitClass();
 visitMethod();
 visitEnd();
 visitMethod();
 visitEnd();
 visitEnd(); //"ends" the visitClass()
 

Returns:

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

visitClass

void visitClass(@Nullable
                JavaTypeElement oldType,
                @Nullable
                JavaTypeElement newType)

visitMethod

void visitMethod(@Nullable
                 JavaMethodElement oldMethod,
                 @Nullable
                 JavaMethodElement newMethod)

visitMethodParameter

void visitMethodParameter(@Nullable
                          JavaMethodParameterElement oldParameter,
                          @Nullable
                          JavaMethodParameterElement newParameter)

visitField

void visitField(@Nullable
                JavaFieldElement oldField,
                @Nullable
                JavaFieldElement newField)

visitAnnotation

@Nullable
List<org.revapi.Difference> visitAnnotation(@Nullable
                                                      JavaAnnotationElement oldAnnotation,
                                                      @Nullable
                                                      JavaAnnotationElement newAnnotation)

Visiting annotation is slightly different, because it is not followed by the standard visitEnd() call. Instead, because visiting annotation is always "terminal" in a sense that an annotation doesn't have any child elements, the list of differences is returned straight away.

Parameters:

oldAnnotation - the annotation in the old API

newAnnotation - the annotation in the new API

Returns:

the list of differences between the two annotations