SuppressionXpathFilter

Since Checkstyle 8.6

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:

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

SuppressionXpathFilter can suppress Checks that have Treewalker as parent 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.

Properties

name	description	type	default value	since
file	Specify the location of the suppressions XML document file.	String	`null`	8.6
optional	Control what to do when the file is not existing. If optional is set to false the file must exist, or else it ends with error. On the other hand if optional is true and file is not found, the filter accepts all audit events.	boolean	`false`	8.6

Examples

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


<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathFilter">
      <property name="file" value="${config.folder}/suppressions1.xml"/>
      <property name="optional" value="false"/>
    </module>
    <module name="CyclomaticComplexity">
      <property name="max" value="3"/>
    </module>
  </module>
</module>

The following suppressions XML document directs a SuppressionXpathFilter to reject CyclomaticComplexity violations for all methods with name sayHelloWorld inside Example1 and Test 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="Example1.java|Test.java"
  query="//METHOD_DEF[./IDENT[@text='sayHelloWorld']]"/>
</suppressions>

Results:


public class Example1 {
  int a, b, c, d, e, n;

  public void sayHelloWorld() { // filtered violation 'Cyclomatic Complexity is 4'
    if (a == b) {
      System.out.println("Hello World");
    }
    else if (a == 0 && b == c) {
      System.out.println("*Silence*");
    }
  }

}

For example #2, To configure the check:


<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathFilter">
      <property name="file" value="${config.folder}/suppressions2.xml"/>
    </module>
    <module name="EmptyLineSeparator"/>
  </module>
</module>

In order to suppress checks for package definitions:


<?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=".*" query="/COMPILATION_UNIT/PACKAGE_DEF"/>
</suppressions>

Results:


// filtered violation below "'package' should be separated from previous line"
package com.puppycrawl.tools.checkstyle.filters.suppressionxpathfilter;
public class Example2 { }
// violation above, "'CLASS_DEF' should be separated from previous line"

For example #3, to configure the check:


<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathFilter">
      <property name="file" value="${config.folder}/suppressions3.xml"/>
    </module>
    <module name="LeftCurly">
      <property name="option" value="nl"/>
    </module>
  </module>
</module>

In order to suppress checks for parent element of the first-ever variable definition:


<?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=".*" query="descendant::VARIABLE_DEF[1]/.."/>
</suppressions>

Results:


public class Example3
{

  // filtered violation below "'{' at column 31 should be on a new line."
  public void testMethodOne() {
    int x = 5;
  }

  // violation below, "'{' at column 31 should be on a new line."
  public void testMethodTwo() {
    int z = 17;
    int y;
  }

}

For example #4, to configure the check:


<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathFilter">
      <property name="file" value="${config.folder}/suppressions4.xml"/>
    </module>
    <module name="EmptyLineSeparator"/>
  </module>
</module>

In order to suppress checks for elements which are either class definitions, or method definitions.


<?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=".*" query="//CLASS_DEF | //METHOD_DEF"/>
</suppressions>

Results:


public class Example4 {
  int y = 3;
  int x = 5; // violation, "'VARIABLE_DEF' should be separated from previous line."
  public void testMethod() {}
  // filtered violation above "'METHOD_DEF' should be separated from previous line."

}

For example #5, to configure the check:


<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathFilter">
      <property name="file" value="${config.folder}/suppressions5.xml"/>
    </module>
    <module name="MethodName"/>
  </module>
</module>

In order to suppress checks for certain methods:


<?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=".*" query="//METHOD_DEF/IDENT[@text='GetSomeVar' or @text='SetSomeVar']"/>
</suppressions>

Results:


public class Example5 {
  // filtered violation below "Name 'SetSomeVar' must match pattern"
  public void SetSomeVar() {}

  public void TestMethod() {} // violation, "Name 'TestMethod' must match pattern"

}

For example #6, to configure the check:


<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathFilter">
      <property name="file" value="${config.folder}/suppressions6.xml"/>
    </module>
    <module name="LocalVariableName"/>
  </module>
</module>

In order to suppress checks for variable TestVariable inside testMethod method inside Example6 class.


<?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=".*" query="//CLASS_DEF[./IDENT[@text='Example6']]
          //METHOD_DEF[./IDENT[@text='testMethod']]
          //VARIABLE_DEF/IDENT[@text='TestVariable']"/>
</suppressions>

Results:


public class Example6 {

  public void testMethod() {

    int TestVariable; // filtered violation 'Name 'TestVariable' must match pattern'

    int WeirdName; // violation, "Name 'WeirdName' must match pattern"
  }

}

For example #7, to configure the check:


<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathFilter">
      <property name="file" value="${config.folder}/suppressions7.xml"/>
    </module>
    <module name="MagicNumber"/>
    <module name="MethodName"/>
  </module>
</module>

In the following sample, violations for MethodName check will be suppressed for classes with name Main or for methods with name DoMATH:


<?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="MethodName" query="//CLASS_DEF[./IDENT[@text='Main']]//*
          | //METHOD_DEF[./IDENT[@text='DoMATH']]/*"/>
</suppressions>

Results:


public class Example7 {
  public void DoMATH() {} // filtered violation "Name 'DoMATH' must match pattern"
  public void DoEng() {} // violation, "Name 'DoEng' must match pattern"
}

class Main {
  int someField = 11; // violation, "'11' is a magic number."
  void FOO() {} // filtered violation "Name 'FOO' must match pattern"
}

For example #8, to configure the check:


<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathFilter">
      <property name="file" value="${config.folder}/suppressions8.xml"/>
    </module>
    <module name="RequireThis">
      <property name="validateOnlyOverlapping" value="false"/>
    </module>
  </module>
</module>

In order to suppress RequireThis violations for variable age inside changeAge method.


<?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="RequireThis"
     query="//CLASS_DEF[./IDENT[@text='Example8']]
          //METHOD_DEF[./IDENT[@text='changeAge']]//ASSIGN/IDENT[@text='age']"/>
</suppressions>

Results:


public class Example8 {

  int age = 23;

  public void changeAge() {
    age = 24; // filtered violation 'Reference to instance variable'
  }

  public int getAge() {
    return age; // violation, 'Reference to instance variable'
  }

}

For example 9, to configure the check:


<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathFilter">
      <property name="file" value="${config.folder}/suppressions9.xml"/>
    </module>
    <module name="IllegalThrows"/>
  </module>
</module>

In order to 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.)


<?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="IllegalThrows" query="//LITERAL_THROWS
          /IDENT[@text='RuntimeException' and
          ./ancestor::METHOD_DEF[./IDENT[@text='throwsMethod']]]"/>
</suppressions>

Results:


public class Example9 {
  // filtered violation below "Throwing 'RuntimeException' is not allowed."
  public void throwsMethod() throws RuntimeException {
  }

  // violation below, "Throwing 'RuntimeException' is not allowed."
  public void sampleMethod() throws RuntimeException {
  }
}

For example #10, to configure the check:


<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathFilter">
      <property name="file" value="${config.folder}/suppressions10.xml"/>
    </module>
    <module name="ModifierOrder"/>
  </module>
</module>

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.


<?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=".*" query="//METHOD_DEF[./IDENT[@text='legacyMethod']]
          /descendant-or-self::node()"/>
</suppressions>

Results:


public class Example10 {

  final public void legacyMethod() { // filtered violation 'modifier out of order'
    strictfp abstract class legacyClass {}
    // filtered violation above 'modifier out of order'
  }

  public void otherMethod() {
    strictfp abstract class strangeClass {} // violation, 'modifier out of order'
  }

}

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]

For example #11, to configure the check:


<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathFilter">
      <property name="file" value="${config.folder}/suppressions11.xml"/>
    </module>
    <module name="MagicNumber"/>
  </module>
</module>

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:


<?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="." query="//VARIABLE_DEF[
            ./IDENT[@text='wordCount']]//*"/>
</suppressions>

Results:


public class Example11 {
  private int wordCount = 11; // filtered violation "'11' is a magic number."
}

Another way is to suppress by variable value.

For example #12, to configure the check:


<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathFilter">
      <property name="file" value="${config.folder}/suppressions12.xml"/>
    </module>
    <module name="MagicNumber"/>
  </module>
</module>

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:


<?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="." query="//VARIABLE_DEF//NUM_INT[@text=11]"/>
</suppressions>

Results:


public class Example12 {
  private int wordCount = 11; // filtered violation "'11' is a magic number."
}

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]

For example #13, to configure the check:


<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathFilter">
      <property name="file" value="${config.folder}/suppressions13.xml"/>
    </module>
    <module name="MethodName"/>
  </module>
</module>

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


<?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="." query="//METHOD_DEF[
            .//ANNOTATION/IDENT[@text='Generated']]//*"/>
</suppressions>

Results:


public class Example13 {
  // filtered violation 2 lines below "Name 'Test1' must match pattern"
  @Generated("first")
  public void Test1() {}

  // filtered violation 2 lines below "Name 'Test2' must match pattern"
  @Generated("second")
  public void Test2() {}
}

The problem with query above that it will suppress violations for all methods with annotation @Generated.

For next example #14, to configure the check:


<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathFilter">
      <property name="file" value="${config.folder}/suppressions14.xml"/>
    </module>
    <module name="MethodName"/>
  </module>
</module>

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:


<?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="." query="//METHOD_DEF[.//ANNOTATION[
            ./IDENT[@text='Generated'] and ./EXPR/STRING_LITERAL[@text='second']]]//*"/>
</suppressions>

Results:


public class Example14 {
  // violation 2 lines below "Name 'Test1' must match pattern"
  @Generated("first")
  public void Test1() {}

  // filtered violation 2 lines below "Name 'Test2' must match pattern"
  @Generated("second")
  public void Test2() {}
}

SuppressionXpathFilter

Description

Notes

Properties

Examples

Example of Usage

Package

Parent Module