Package com.github.sevntu.checkstyle.checks.coding

Class Jsr305AnnotationsCheck

  • All Implemented Interfaces:
    com.puppycrawl.tools.checkstyle.api.Configurable, com.puppycrawl.tools.checkstyle.api.Contextualizable
    public class Jsr305AnnotationsCheck
extends com.puppycrawl.tools.checkstyle.api.AbstractCheck

    The Jsr305 annotations (annotations for software defect detection) contain a subset of "nullness" annotations that can be used to mark parameters as possibly null (@Nullable) or always non-null (@Nonnull), function return values as to be checked for null (@CheckForNull) or always non-null (@Nonnull) including defaults on class level (@ParametersAreNonnullByDefault, @ParametersAreNullableByDefault, @ReturnValuesAreNonnullByDefault).

    Using these annotations a programmer can declare how the code is meant to behave, and static code analysis (like e.g. FindBugs) can be used to verify that this is actually true. Also these annotations help others understanding code more easily, e.g. if confrontend with an annotated interface the necessity for null checks can easily be deducted from the annotations.

    The Jsr305AnnotationsCheck supports enforcing the following code style:

    • Every method declaration, implementation or lambda requires nullness annotations for all parameters and return values except for primitive types (because a void or an int can never be null anyway).
    • The annotation can be made directly or applied through either inheritance from an already annotated class or a annotation for class-wide defaults.
    • Annotations need to make sense. For instance, a class-scope annotation cannot be used for a method, and a method annotation cannot be used for a class.
    • In overridden methods, the following rule applies (regardless of what was annotated in the parent method): For parameter definitions @Nonnull annotation is always illegal because being less "nullable" cannot be assumed for a parameter in an inherited method. Conversely @Nullable is always allowed. For return values it is the other way round: @CheckForNull is always illegal while @Nonnull is always legal.

    The following configuration properties are supported:

    packages = com.github.sevntu.pkg1,com.github.sevntu.pkg2
    Activate this check for a list of parent packages and their children.
    excludePackages = com.github.sevntu.pkg1.sub1,com.github.sevntu.pkg1.sub2
    Set packages excluded from checking. This setting can be useful if under the parent package set with "packages" there are subpackages which should not be checked.
    allowOverridingReturnValue = true
    Annotating return values "@CheckForNull" in overridden methods is flagged as a violation. When setting the this property to true, this will be ignored (useful for upgrading).
    allowOverridingParameters = true
    Annotating parameters "@Nonnull" in overridden methods is flagged as a violation. When setting this property to true, this will be ignored (useful for upgrading).

    Note that by default no files will be checked. To enable this check, you need to set the packages property to one or more parent packages.

    Example code:

    Configure the check so that it scans the packages of the classes we want to run this on: 

     <module name="Jsr305Annotations">
   <property name="packages" value="org,com"/>
   </module>
 
     // Example 1: a class without any class-level annotations
 class Class1 {
     @CheckForNull // Violation: obj2 not annotated!
     String method1(@Nullable Object obj1, Object obj2) {
         return "";
     }

     // Violation: return value not annotated
     String method2() {
         return "";
     }
 }

 // Example 2: a class with class-level annotations for parameters
 @ParametersAreNonnullByDefault
 class Class2 {
     @CheckForNull // Legal
     String method1(Object obj1, Object obj2) {
         return "";
     }

     @Nonnull // Legal
     String method2(Object obj1, @Nullable Object obj2) {
         return "";
     }

     @Nonnull // Violation, redefinition of obj2's nullness
     String method3(Object obj1, @Nonnull Object obj2) {
         return "";
     }

     // Violation: return value not annotated
     String method4() {
         return "";
     }
 }

 // Example 3: a class overriding some methods
 class Class3 implements Interface1 {
     @Override // Legal
     public Object method1(Object obj1, Object obj2) {
         return "";
     }

     @Override
     @Nonnull // Legal, return value becomes less "nullable"
     public Object method2(Object obj1, Object obj2) {
         return "";
     }

     @Override // Violation: Setting a parameter to non-null in an overridden method
     public Object method3(@Nonnull Object obj1, Object obj2) {
         return "";
     }

     @Override // Legal: parameter obj2 becomes more "nullable"
     public Object method4(Object obj1, @Nullable Object obj2) {
         return "";
     }

     @Override
     @CheckForNull // Violation: return value becomes more "nullable"
     public Object method5() {
         return "";
     }
 }

    • Field Detail

      • MSG_ILLEGAL_CLASS_LEVEL_ANNOTATION

        public static final String MSG_ILLEGAL_CLASS_LEVEL_ANNOTATION
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_CONTRADICTING_CLASS_LEVEL_ANNOTATIONS

        public static final String MSG_CONTRADICTING_CLASS_LEVEL_ANNOTATIONS
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_PARAM_DEFINITIONS_WITH_CHECK

        public static final String MSG_PARAM_DEFINITIONS_WITH_CHECK
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_PARAM_DEFINITION_WITH_OVERRIDE

        public static final String MSG_PARAM_DEFINITION_WITH_OVERRIDE
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_PARAM_DEFINITION_WITH_NONNULL_BY_DEFAULT

        public static final String MSG_PARAM_DEFINITION_WITH_NONNULL_BY_DEFAULT
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_PARAM_DEFINITION_WITH_NULLABLE_BY_DEFAULT

        public static final String MSG_PARAM_DEFINITION_WITH_NULLABLE_BY_DEFAULT
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_PARAM_DEFINITION_WITH_RETURN_DEFAULT

        public static final String MSG_PARAM_DEFINITION_WITH_RETURN_DEFAULT
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_PARAM_NONNULL_AND_NULLABLE

        public static final String MSG_PARAM_NONNULL_AND_NULLABLE
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_PRIMITIVES_WITH_NULLNESS_ANNOTATION

        public static final String MSG_PRIMITIVES_WITH_NULLNESS_ANNOTATION
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_OVERRIDDEN_WITH_INCREASED_CONSTRAINT

        public static final String MSG_OVERRIDDEN_WITH_INCREASED_CONSTRAINT
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_REDUNDANT_NONNULL_PARAM_ANNOTATION

        public static final String MSG_REDUNDANT_NONNULL_PARAM_ANNOTATION
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_REDUNDANT_NULLABLE_PARAM_ANNOTATION

        public static final String MSG_REDUNDANT_NULLABLE_PARAM_ANNOTATION
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_PARAMETER_WITHOUT_NULLNESS_ANNOTATION

        public static final String MSG_PARAMETER_WITHOUT_NULLNESS_ANNOTATION
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_RETURN_VALUE_WITH_NONNULL_BY_DEFAULT

        public static final String MSG_RETURN_VALUE_WITH_NONNULL_BY_DEFAULT
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_RETURN_VALUE_WITH_NULLABLE

        public static final String MSG_RETURN_VALUE_WITH_NULLABLE
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_CONTRADICTING_RETURN_VALUE_ANNOTATIONS

        public static final String MSG_CONTRADICTING_RETURN_VALUE_ANNOTATIONS
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_OVERRIDDEN_METHOD_WITH_CHECK_RETURN_VALUE

        public static final String MSG_OVERRIDDEN_METHOD_WITH_CHECK_RETURN_VALUE
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_REDUNDANT_NONNULL_BY_DEFAULT_ANNOTATION

        public static final String MSG_REDUNDANT_NONNULL_BY_DEFAULT_ANNOTATION
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_REDUNDANT_NULLABLE_BY_DEFAULT_ANNOTATION

        public static final String MSG_REDUNDANT_NULLABLE_BY_DEFAULT_ANNOTATION
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_VOID_WITH_CHECK_RETURN_VALUE_ANNOTATION

        public static final String MSG_VOID_WITH_CHECK_RETURN_VALUE_ANNOTATION
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_REDUNDANT_NONNULL_RETURN_ANNOTATION

        public static final String MSG_REDUNDANT_NONNULL_RETURN_ANNOTATION
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_RETURN_WITHOUT_NULLNESS_ANNOTATION

        public static final String MSG_RETURN_WITHOUT_NULLNESS_ANNOTATION
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_OVERRIDDEN_METHODS_ALLOW_ONLY_NONNULL

        public static final String MSG_OVERRIDDEN_METHODS_ALLOW_ONLY_NONNULL
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_NEED_TO_INHERIT_PARAM_ANNOTATIONS

        public static final String MSG_NEED_TO_INHERIT_PARAM_ANNOTATIONS
        Key for violation message.
        See Also:
        Constant Field Values

      • MSG_CONSTRUCTOR_WITH_RETURN_ANNOTATION

        public static final String MSG_CONSTRUCTOR_WITH_RETURN_ANNOTATION
        Key for violation message.
        See Also:
        Constant Field Values

    • Constructor Detail

      • Jsr305AnnotationsCheck

        public Jsr305AnnotationsCheck()

    • Method Detail

      • getDefaultTokens

        public final int[] getDefaultTokens()
        Specified by:
        getDefaultTokens in class com.puppycrawl.tools.checkstyle.api.AbstractCheck

      • getRequiredTokens

        public final int[] getRequiredTokens()
        Specified by:
        getRequiredTokens in class com.puppycrawl.tools.checkstyle.api.AbstractCheck

      • getAcceptableTokens

        public final int[] getAcceptableTokens()
        Specified by:
        getAcceptableTokens in class com.puppycrawl.tools.checkstyle.api.AbstractCheck

      • beginTree

        public void beginTree​(com.puppycrawl.tools.checkstyle.api.DetailAST rootAST)
        Overrides:
        beginTree in class com.puppycrawl.tools.checkstyle.api.AbstractCheck

      • visitToken

        public final void visitToken​(com.puppycrawl.tools.checkstyle.api.DetailAST ast)
        Overrides:
        visitToken in class com.puppycrawl.tools.checkstyle.api.AbstractCheck

      • setPackages

        public void setPackages​(String... packageNames)
        Sets the included packages property.
        Parameters:
        packageNames - the package names, comma separated

      • setExcludePackages

        public void setExcludePackages​(String... packageNames)
        Sets the excluded packages property.
        Parameters:
        packageNames - the package names, comma separated

      • setAllowOverridingReturnValue

        public void setAllowOverridingReturnValue​(boolean newAllowOverridingReturnValue)
        Sets the property for allowing overriding return values.
        Parameters:
        newAllowOverridingReturnValue - true if yes

      • setAllowOverridingParameter

        public void setAllowOverridingParameter​(boolean newAllowOverridingParameter)
        Sets the property for allowing overriding parameters.
        Parameters:
        newAllowOverridingParameter - true if yes

      • isVoid

        protected static boolean isVoid​(com.puppycrawl.tools.checkstyle.api.DetailAST ast)
        Is the current symbol of void type.
        Parameters:
        ast - the ast
        Returns:
        true if yes