Jsr305AnnotationsCheck (sevntu-checks 1.39.0 API)

java.lang.Object
- com.puppycrawl.tools.checkstyle.api.AutomaticBean
- - com.puppycrawl.tools.checkstyle.api.AbstractViolationReporter
  - - com.puppycrawl.tools.checkstyle.api.AbstractCheck
    - - com.github.sevntu.checkstyle.checks.coding.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 "";
     }
 }
 
```

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

class Jsr305AnnotationsCheck.AbstractJsr305Handler
An abstract handler, the base for handling parameters, methods, classes.
- Nested classes/interfaces inherited from class com.puppycrawl.tools.checkstyle.api.AutomaticBean
  com.puppycrawl.tools.checkstyle.api.AutomaticBean.OutputStreamOptions

Nested Classes
Modifier and Type	Class and Description
`class`	`Jsr305AnnotationsCheck.AbstractJsr305Handler` An abstract handler, the base for handling parameters, methods, classes.

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`MSG_CONSTRUCTOR_WITH_RETURN_ANNOTATION` Key for violation message.
`static String`	`MSG_CONTRADICTING_CLASS_LEVEL_ANNOTATIONS` Key for violation message.
`static String`	`MSG_CONTRADICTING_RETURN_VALUE_ANNOTATIONS` Key for violation message.
`static String`	`MSG_ILLEGAL_CLASS_LEVEL_ANNOTATION` Key for violation message.
`static String`	`MSG_NEED_TO_INHERIT_PARAM_ANNOTATIONS` Key for violation message.
`static String`	`MSG_OVERRIDDEN_METHOD_WITH_CHECK_RETURN_VALUE` Key for violation message.
`static String`	`MSG_OVERRIDDEN_METHODS_ALLOW_ONLY_NONNULL` Key for violation message.
`static String`	`MSG_OVERRIDDEN_WITH_INCREASED_CONSTRAINT` Key for violation message.
`static String`	`MSG_PARAM_DEFINITION_WITH_NONNULL_BY_DEFAULT` Key for violation message.
`static String`	`MSG_PARAM_DEFINITION_WITH_NULLABLE_BY_DEFAULT` Key for violation message.
`static String`	`MSG_PARAM_DEFINITION_WITH_OVERRIDE` Key for violation message.
`static String`	`MSG_PARAM_DEFINITION_WITH_RETURN_DEFAULT` Key for violation message.
`static String`	`MSG_PARAM_DEFINITIONS_WITH_CHECK` Key for violation message.
`static String`	`MSG_PARAM_NONNULL_AND_NULLABLE` Key for violation message.
`static String`	`MSG_PARAMETER_WITHOUT_NULLNESS_ANNOTATION` Key for violation message.
`static String`	`MSG_PRIMITIVES_WITH_NULLNESS_ANNOTATION` Key for violation message.
`static String`	`MSG_REDUNDANT_NONNULL_BY_DEFAULT_ANNOTATION` Key for violation message.
`static String`	`MSG_REDUNDANT_NONNULL_PARAM_ANNOTATION` Key for violation message.
`static String`	`MSG_REDUNDANT_NONNULL_RETURN_ANNOTATION` Key for violation message.
`static String`	`MSG_REDUNDANT_NULLABLE_BY_DEFAULT_ANNOTATION` Key for violation message.
`static String`	`MSG_REDUNDANT_NULLABLE_PARAM_ANNOTATION` Key for violation message.
`static String`	`MSG_RETURN_VALUE_WITH_NONNULL_BY_DEFAULT` Key for violation message.
`static String`	`MSG_RETURN_VALUE_WITH_NULLABLE` Key for violation message.
`static String`	`MSG_RETURN_WITHOUT_NULLNESS_ANNOTATION` Key for violation message.
`static String`	`MSG_VOID_WITH_CHECK_RETURN_VALUE_ANNOTATION` Key for violation message.

Constructor Summary

Constructors
Constructor and Description

Jsr305AnnotationsCheck()

Constructors
Constructor and Description
`Jsr305AnnotationsCheck()`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`beginTree(com.puppycrawl.tools.checkstyle.api.DetailAST rootAST)`
`int[]`	`getAcceptableTokens()`
`int[]`	`getDefaultTokens()`
`int[]`	`getRequiredTokens()`
`protected static boolean`	`isVoid(com.puppycrawl.tools.checkstyle.api.DetailAST ast)` Is the current symbol of void type.
`void`	`setAllowOverridingParameter(boolean newAllowOverridingParameter)` Sets the property for allowing overriding parameters.
`void`	`setAllowOverridingReturnValue(boolean newAllowOverridingReturnValue)` Sets the property for allowing overriding return values.
`void`	`setExcludePackages(String... packageNames)` Sets the excluded packages property.
`void`	`setPackages(String... packageNames)` Sets the included packages property.
`void`	`visitToken(com.puppycrawl.tools.checkstyle.api.DetailAST ast)`

Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractCheck
clearMessages, destroy, finishTree, getFileContents, getLine, getLines, getMessages, getTabWidth, getTokenNames, init, isCommentNodesRequired, leaveToken, log, log, log, setFileContents, setTabWidth, setTokens

Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractViolationReporter
finishLocalSetup, getCustomMessages, getId, getMessageBundle, getSeverity, getSeverityLevel, setId, setSeverity

Methods inherited from class com.puppycrawl.tools.checkstyle.api.AutomaticBean
configure, contextualize, getConfiguration, setupChild

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- 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

Class Jsr305AnnotationsCheck

Nested Class Summary

Nested classes/interfaces inherited from class com.puppycrawl.tools.checkstyle.api.AutomaticBean

Field Summary

Constructor Summary

Method Summary

Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractCheck

Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractViolationReporter

Methods inherited from class com.puppycrawl.tools.checkstyle.api.AutomaticBean

Methods inherited from class java.lang.Object

Field Detail

MSG_ILLEGAL_CLASS_LEVEL_ANNOTATION

MSG_CONTRADICTING_CLASS_LEVEL_ANNOTATIONS

MSG_PARAM_DEFINITIONS_WITH_CHECK

MSG_PARAM_DEFINITION_WITH_OVERRIDE

MSG_PARAM_DEFINITION_WITH_NONNULL_BY_DEFAULT

MSG_PARAM_DEFINITION_WITH_NULLABLE_BY_DEFAULT

MSG_PARAM_DEFINITION_WITH_RETURN_DEFAULT

MSG_PARAM_NONNULL_AND_NULLABLE

MSG_PRIMITIVES_WITH_NULLNESS_ANNOTATION

MSG_OVERRIDDEN_WITH_INCREASED_CONSTRAINT

MSG_REDUNDANT_NONNULL_PARAM_ANNOTATION

MSG_REDUNDANT_NULLABLE_PARAM_ANNOTATION

MSG_PARAMETER_WITHOUT_NULLNESS_ANNOTATION

MSG_RETURN_VALUE_WITH_NONNULL_BY_DEFAULT

MSG_RETURN_VALUE_WITH_NULLABLE

MSG_CONTRADICTING_RETURN_VALUE_ANNOTATIONS

MSG_OVERRIDDEN_METHOD_WITH_CHECK_RETURN_VALUE

MSG_REDUNDANT_NONNULL_BY_DEFAULT_ANNOTATION

MSG_REDUNDANT_NULLABLE_BY_DEFAULT_ANNOTATION

MSG_VOID_WITH_CHECK_RETURN_VALUE_ANNOTATION

MSG_REDUNDANT_NONNULL_RETURN_ANNOTATION

MSG_RETURN_WITHOUT_NULLNESS_ANNOTATION

MSG_OVERRIDDEN_METHODS_ALLOW_ONLY_NONNULL

MSG_NEED_TO_INHERIT_PARAM_ANNOTATIONS

MSG_CONSTRUCTOR_WITH_RETURN_ANNOTATION

Constructor Detail

Jsr305AnnotationsCheck

Method Detail

getDefaultTokens

getRequiredTokens

getAcceptableTokens

beginTree

visitToken

setPackages

setExcludePackages

setAllowOverridingReturnValue

setAllowOverridingParameter

isVoid