Description

Filter SuppressionXpathFilter works as SuppressionFilter. Additionally, filter processes suppress-xpath elements, which contains xpath-expressions. Xpath-expressions are queries for suppressed nodes inside the AST tree.

Currently, filter does not support the following checks:

• NoCodeInFile (reason is that AST is not generated for a file not containing code)
• Regexp (reason is at #7759)
• RegexpSinglelineJava (reason is at #7759)

Also, the filter does not support suppressions inside javadoc reported by Javadoc checks:

• AtclauseOrder
• JavadocBlockTagLocation
• JavadocMethod
• JavadocMissingLeadingAsterisk
• JavadocMissingWhitespaceAfterAsterisk
• JavadocParagraph
• JavadocStyle
• JavadocTagContinuationIndentation
• JavadocType
• MissingDeprecated
• NonEmptyAtclauseDescription
• RequireEmptyLineBeforeBlockTagGroup
• SingleLineJavadoc
• SummaryJavadoc
• WriteTag

Note, that support for these Checks will be available after resolving issue #5770.

Currently, filter supports the following xpath axes:

• ancestor
• ancestor-or-self
• attribute
• child
• descendant
• descendant-or-self
• following
• following-sibling
• parent
• preceding
• preceding-sibling
• self

You can use the command line helper tool to generate xpath suppressions based on your configuration file and input files. See here for more details.

Notes

The suppression file location is checked in following order:

1. as a filesystem location
2. if no file found, and the location starts with either http:// or https://, then it is interpreted as a URL
3. if no file found, then passed to the ClassLoader.getResource() method.

SuppressionXpathFilter can suppress Checks that have Treewalker as parent module.

Properties

Examples

For example, the following configuration fragment directs the Checker to use a SuppressionXpathFilter with suppressions file config/suppressions.xml:

<module name="SuppressionXpathFilter">
  <property name="file" value="config/suppressions.xml"/>
  <property name="optional" value="false"/>
</module>
        

A suppressions XML document contains a set of suppress and suppress-xpath elements, where each suppress-xpath element can have the following attributes:

• files - a Pattern matched against the file name associated with an audit event. It is optional.
• checks - a Pattern matched against the name of the check associated with an audit event. Optional as long as id or message is specified.
• message - a Pattern matched against the message of the check associated with an audit event. Optional as long as checks or id is specified.
• id - a String matched against the ID of the check associated with an audit event. Optional as long as checks or message is specified.
• query - a String xpath query. It is optional.

Each audit event is checked against each suppress and suppress-xpath element. It is suppressed if all specified attributes match against the audit event.

ATTENTION: filtering by message is dependent on runtime locale. If project is running in different languages it is better to avoid filtering by message.

The following suppressions XML document directs a SuppressionXpathFilter to reject CyclomaticComplexity violations for all methods with name sayHelloWorld inside FileOne and FileTwo files:

Currently, xpath queries support one type of attribute @text. @text - addresses to the text value of the node. For example: variable name, annotation name, text content, etc. Only the following token types support @text attribute: TokenTypes.IDENT, TokenTypes.STRING_LITERAL, TokenTypes.CHAR_LITERAL, TokenTypes.NUM_LONG, TokenTypes.NUM_INT, TokenTypes.NUM_DOUBLE, TokenTypes.NUM_FLOAT. These token types were selected because only their text values are different in content from token type and represent text value from file and can be used in xpath queries for more accurate results. Other token types always have constant values.

<?xml version="1.0"?>

<!DOCTYPE suppressions PUBLIC
"-//Checkstyle//DTD SuppressionXpathFilter Experimental Configuration 1.2//EN"
"https://checkstyle.org/dtds/suppressions_1_2_xpath_experimental.dtd">

<suppressions>
  <suppress-xpath checks="CyclomaticComplexity"
  files="FileOne.java,FileTwo.java"
  query="//METHOD_DEF[./IDENT[@text='sayHelloWorld']]"/>
</suppressions>
        

Suppress checks for package definitions:

<suppress-xpath checks=".*" query="/PACKAGE_DEF"/>
        

Suppress checks for parent element of the first variable definition:

<suppress-xpath checks=".*" query="(//VARIABLE_DEF)[1]/.."/>
        

Suppress checks for elements which are either class definitions, either method definitions.

<suppress-xpath checks=".*" query="//CLASS_DEF | //METHOD_DEF"/>
        

Suppress checks for certain methods:

<suppress-xpath checks=".*" query="//METHOD_DEF[./IDENT[@text='getSomeVar'
          or @text='setSomeVar']]"/>
        

Suppress checks for variable testVariable inside testMethod method inside TestClass class.

<suppress-xpath checks=".*" query="//CLASS_DEF[@text='TestClass']
          //METHOD_DEF[./IDENT[@text='testMethod']]
          //VARIABLE_DEF[./IDENT[@text='testVariable']]"/>
        

In the following sample, violations for LeftCurly check will be suppressed for classes with name Main or for methods with name calculate.

<suppress-xpath checks="LeftCurly" query="//CLASS_DEF[./IDENT[@text='Main']]//*
          | //METHOD_DEF[./IDENT[@text='calculate']]/*"/>
        

The following example demonstrates how to suppress RequireThis violations for variable age inside changeAge method.

<suppress-xpath checks="RequireThis"
     query="//CLASS_DEF[./IDENT[@text='InputTest']]
          //METHOD_DEF[./IDENT[@text='changeAge']]//ASSIGN/IDENT[@text='age']"/>
        

public class InputTest {
  private int age = 23;

  public void changeAge() {
    age = 24; //violation will be suppressed
  }
}
        

Suppress IllegalThrows violations only for methods with name throwsMethod and only for RuntimeException exceptions. Double colon is used for axis iterations. In the following example ancestor axis is used to iterate all ancestor nodes of the current node with type METHOD_DEF and name throwsMethod. Please read more about xpath axes at W3Schools Xpath Axes.

<suppress-xpath checks="IllegalThrows" query="//LITERAL_THROWS
          /IDENT[@text='RuntimeException' and
          ./ancestor::METHOD_DEF[./IDENT[@text='throwsMethod']]]"/>
        

public class InputTest {
  public void throwsMethod() throws RuntimeException { // violation will be suppressed
  }

  public void sampleMethod() throws RuntimeException { // will throw violation here
  }
}
        

The following sample demonstrates how to suppress all violations for method itself and all descendants. descendant-or-self axis iterates through current node and all children nodes at any level. Keyword node() selects node elements. Please read more about xpath syntax at W3Schools Xpath Syntax.

<suppress-xpath checks=".*" query="//METHOD_DEF[./IDENT[@text='legacyMethod']]
          /descendant-or-self::node()"/>
        

Some elements can be suppressed in different ways. For example, to suppress violation on variable wordCount in following code:

public class InputTest {
    private int wordCount = 11;
}
        

You need to look at AST of such code by our CLI tool:

$ java -jar checkstyle-X.XX-all.jar -t InputTest.java
CLASS_DEF -> CLASS_DEF [1:0]
|--MODIFIERS -> MODIFIERS [1:0]
|   `--LITERAL_PUBLIC -> public [1:0]
|--LITERAL_CLASS -> class [1:7]
|--IDENT -> InputTest [1:13]
`--OBJBLOCK -> OBJBLOCK [1:23]
|--LCURLY -> { [1:23]
|--VARIABLE_DEF -> VARIABLE_DEF [2:4]
|   |--MODIFIERS -> MODIFIERS [2:4]
|   |   `--LITERAL_PRIVATE -> private [2:4]
|   |--TYPE -> TYPE [2:12]
|   |   `--LITERAL_INT -> int [2:12]
|   |--IDENT -> wordCount [2:16]
|   |--ASSIGN -> = [2:26]
|   |   `--EXPR -> EXPR [2:28]
|   |       `--NUM_INT -> 11 [2:28]
|   `--SEMI -> ; [2:30]
`--RCURLY -> } [3:0]
        

The easiest way is to suppress by variable name. As you can see VARIABLE_DEF node refers to variable declaration statement and has child node with token type IDENT which is used for storing class, method, variable names.

The following example demonstrates how variable can be queried by its name:

<suppress-xpath checks="." query="//VARIABLE_DEF[
            ./IDENT[@text='wordCount']]"/>
        

Another way is to suppress by variable value. Again, if you look at the printed AST tree above, you will notice that one of the grandchildren of VARIABLE_DEF node is responsible for storing variable value - NUM_INT with value 11.

The following example demonstrates how variable can be queried by its value, same approach applies to String, char, float, double, int, long data types:

<suppress-xpath checks="." query="//VARIABLE_DEF[.//NUM_INT[@text=11]]"/>
        

Next example is about suppressing method with certain annotation by its name and element value.

public class InputTest {
    @Generated("first") // should not be suppressed
    public void test1() {
    }

    @Generated("second") // should be suppressed
    public void test2() {
    }
}
        

First of all we need to look at AST tree printed by our CLI tool:

$ java -jar checkstyle-X.XX-all.jar -t InputTest.java
CLASS_DEF -> CLASS_DEF [1:0]
|--MODIFIERS -> MODIFIERS [1:0]
|   `--LITERAL_PUBLIC -> public [1:0]
|--LITERAL_CLASS -> class [1:7]
|--IDENT -> InputTest [1:13]
`--OBJBLOCK -> OBJBLOCK [1:23]
|--LCURLY -> { [1:23]
|--METHOD_DEF -> METHOD_DEF [2:4]
|   |--MODIFIERS -> MODIFIERS [2:4]
|   |   |--ANNOTATION -> ANNOTATION [2:4]
|   |   |   |--AT -> @ [2:4]
|   |   |   |--IDENT -> Generated [2:5]
|   |   |   |--LPAREN -> ( [2:14]
|   |   |   |--EXPR -> EXPR [2:15]
|   |   |   |   `--STRING_LITERAL -> "first" [2:15]
|   |   |   `--RPAREN -> ) [2:22]
|   |   `--LITERAL_PUBLIC -> public [3:4]
|   |--TYPE -> TYPE [3:11]
|   |   `--LITERAL_VOID -> void [3:11]
|   |--IDENT -> test1 [3:16]
|   |--LPAREN -> ( [3:21]
|   |--PARAMETERS -> PARAMETERS [3:22]
|   |--RPAREN -> ) [3:22]
|   `--SLIST -> { [3:24]
|       `--RCURLY -> } [4:4]
|--METHOD_DEF -> METHOD_DEF [6:4]
|   |--MODIFIERS -> MODIFIERS [6:4]
|   |   |--ANNOTATION -> ANNOTATION [6:4]
|   |   |   |--AT -> @ [6:4]
|   |   |   |--IDENT -> Generated [6:5]
|   |   |   |--LPAREN -> ( [6:14]
|   |   |   |--EXPR -> EXPR [6:15]
|   |   |   |   `--STRING_LITERAL -> "second" [6:15]
|   |   |   `--RPAREN -> ) [6:23]
|   |   `--LITERAL_PUBLIC -> public [7:4]
|   |--TYPE -> TYPE [7:11]
|   |   `--LITERAL_VOID -> void [7:11]
|   |--IDENT -> test2 [7:16]
|   |--LPAREN -> ( [7:21]
|   |--PARAMETERS -> PARAMETERS [7:22]
|   |--RPAREN -> ) [7:22]
|   `--SLIST -> { [7:24]
|       `--RCURLY -> } [8:4]
`--RCURLY -> } [9:0]
        

AST node ANNOTATION -> ANNOTATION [6:4] has direct child IDENT -> Generated [6:5], therefore can be queried by IDENT value:

<suppress-xpath checks="." query="//METHOD_DEF[
            .//ANNOTATION/IDENT[@text='Generated']]"/>
        

The problem with query above that it will suppress violations for all methods with annotation @Generated. In order to suppress methods with @Generated("second") annotations only, you need to look at AST tree again. Value of the ANNOTATION node is stored inside sub-node with token type STRING_LITERAL. Use the following query to suppress methods with @Generated("second") annotation:

<suppress-xpath checks="." query="//METHOD_DEF[.//ANNOTATION[
            ./IDENT[@text='Generated'] and ./EXPR/STRING_LITERAL[@text='second']]]"/>
        

Example of Usage

• Google Style
• Sun Style
• Checkstyle Style

Package

com.puppycrawl.tools.checkstyle.filters

Parent Module

TreeWalker