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

  • Method Details

    • 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