org.revapi.java.spi

Interface Check

All Superinterfaces:

Configurable

All Known Implementing Classes:

CheckBase

public interface Check
extends 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

Method Summary

Modifier and Type	Method and Description
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) Visiting annotation is slightly different, because it is not followed by the standard visitEnd() call.
void	visitClass(TypeElement oldType, TypeElement newType)
List<Difference>	visitEnd() Each of the other visit* calls is followed by a corresponding call to this method in a stack-like manner.
void	visitField(VariableElement oldField, VariableElement newField)
void	visitMethod(ExecutableElement oldMethod, ExecutableElement newMethod)
void	visitMethodParameter(VariableElement oldParameter, VariableElement newParameter)

Methods inherited from interface org.revapi.configuration.Configurable

getConfigurationRootPaths, getJSONSchema, initialize

Method Detail

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

visitEnd

@Nullable
List<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
                TypeElement oldType,
                @Nullable
                TypeElement newType)

visitMethod

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

visitMethodParameter

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

visitField

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

visitAnnotation

@Nullable
List<Difference> visitAnnotation(@Nullable
                                           AnnotationMirror oldAnnotation,
                                           @Nullable
                                           AnnotationMirror 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