Package 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

    • 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).

      • 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