SuppressionXpathSingleFilter

Since Checkstyle 8.18

Description

Filter SuppressionXpathSingleFilter suppresses audit events for Checks violations in the specified file, class, checks, message, module id, and xpath.

Rationale: To allow users use suppressions configured in the same config with other modules. SuppressionFilter and SuppressionXpathFilter are require separate file.

Advice: If checkstyle configuration is used for several projects, single suppressions on common files/folders is better to put in checkstyle configuration as common rule. All suppression that are for specific file names is better to keep in project specific config file.

Attention: This filter only supports single suppression, and will need multiple instances if users wants to suppress multiple violations.

Notes

SuppressionXpathSingleFilter can suppress Checks that have Treewalker as parent module.

Properties

name description type default value since
checks Define a Regular Expression matched against the name of the check associated with an audit event. Pattern null 8.18
files Define a Regular Expression matched against the file name associated with an audit event. Pattern null 8.18
id Define a string matched against the ID of the check associated with an audit event. String null 8.18
message Define a Regular Expression matched against the message of the check associated with an audit event. Pattern null 8.18
query Define a string xpath query. String null 8.18

Examples

To configure to suppress the MethodName check for all methods with name MyMethod inside FileOne and FileTwo files: 

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathSingleFilter">
      <property name="files" value="File(One|Two)\.java"/>
      <property name="checks" value="MethodName"/>
      <property name="query" value="(//CLASS_DEF[@text='FileOne']/OBJBLOCK/
                METHOD_DEF[@text='MyMethod']/IDENT)|
                (//CLASS_DEF[@text='FileTwo']/OBJBLOCK/METHOD_DEF[@text='MyMethod']/IDENT)"/>
    </module>
  </module>
</module>

Code example:

public class FileOne {
  public void MyMethod() {} // OK
}

public class FileTwo {
  public void MyMethod() {} // OK
}

public class FileThree {
  public void MyMethod() {} // violation, name 'MyMethod'
                            // must match pattern '^[a-z](_?[a-zA-Z0-9]+)*$'
}

To suppress MethodName check for method names matched pattern 'MyMethod[0-9]': 

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathSingleFilter">
      <property name="checks" value="MethodName"/>
      <property name="message" value="MyMethod[0-9]"/>
    </module>
  </module>
</module>

Code Example:

public class FileOne {
  public void MyMethod1() {} // OK
  public void MyMethod2() {} // OK
  public void MyMethodA() {} // violation, name 'MyMethodA' must
                             // match pattern '^[a-z](_?[a-zA-Z0-9]+)*$'
}

To suppress checks being specified by id property: 

<module name="Checker">
  <module name="TreeWalker">
    <module name="MethodName">
      <property name="id" value="MethodName1"/>
      <property name="format" value="^[a-z](_?[a-zA-Z0-9]+)*$"/>
    </module>
    <module name="SuppressionXpathSingleFilter">
      <property name="files" value="FileOne.java"/>
      <property name="id" value="MethodName1"/>
    </module>
  </module>
</module>

Code example:

public class FileOne {
  public void MyMethod() {} // OK
}
public class FileTwo {
  public void MyMethod() {} // violation,  name 'MyMethod' must
                            //match pattern '^[a-z](_?[a-zA-Z0-9]+)*$'
}

To suppress checks for all package definitions: 

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathSingleFilter">
      <property name="checks" value="PackageName"/>
      <property name="query" value="/PACKAGE_DEF[@text='File']/IDENT"/>
    </module>
  </module>
</module>

Code example:

package File; // OK

public class FileOne {}

To suppress RedundantModifier check for interface definitions: 

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathSingleFilter">
      <property name="checks" value="RedundantModifier"/>
      <property name="query" value="//INTERFACE_DEF//*"/>
    </module>
  </module>
</module>

Code Example:

public interface TestClass {
  public static final int CONSTANT1 = 1;  // OK
}

To suppress checks in the FileOne file by non-query: 

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathSingleFilter">
      <property name="files" value="FileOne.java"/>
      <property name="checks" value="MyMethod"/>
    </module>
  </module>
</module>

Code example:

public class FileOne {
  public void MyMethod() {} // OK
}

public class FileTwo {
  public void MyMethod() {} // violation, name 'MyMethod'
                            // must match pattern '^[a-z](_?[a-zA-Z0-9]+)*$'
}

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

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathSingleFilter">
      <property name="checks" value=".*"/>
      <property name="query"
                value="(//CLASS_DEF[@text='FileOne'])|
                (//CLASS_DEF[@text='FileOne']/OBJBLOCK/METHOD_DEF[@text='MyMethod']/IDENT)"/>
    </module>
  </module>
</module>

Code example:

abstract class FileOne { // OK
  public void MyMethod() {} // OK
}

abstract class FileTwo { // violation of the AbstractClassName check,
                         // it should match the pattern "^Abstract.+$"
  public void MyMethod() {} // violation, name 'MyMethod'
                            // must match pattern '^[a-z](_?[a-zA-Z0-9]+)*$'
}

Suppress checks for MyMethod1 or MyMethod2 methods: 

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathSingleFilter">
      <property name="checks" value="MethodName"/>
      <property name="query" value="//CLASS_DEF[@text='FileOne']/OBJBLOCK/
                METHOD_DEF[@text='MyMethod1' or @text='MyMethod2']/IDENT"/>
    </module>
  </module>
</module>

Code example:

public class FileOne {
  public void MyMethod1() {} // OK
  public void MyMethod2() {} // OK
  public void MyMethod3() {} // violation, name 'MyMethod3' must
                             // match pattern '^[a-z](_?[a-zA-Z0-9]+)*$'
}

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

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathSingleFilter">
      <property name="checks" value="LocalFinalVariableName"/>
      <property name="query" value="//CLASS_DEF[@text='TestClass']/OBJBLOCK
            /METHOD_DEF[@text='testMethod']/SLIST
            /VARIABLE_DEF[@text='testVariable1']/IDENT"/>
    </module>
  </module>
</module>

Code Example:

public class TestClass {
  public void testMethod() {
    final int testVariable1 = 10; // OK
    final int testVariable2 = 10; // violation of the LocalFinalVariableName check,
                                  // name 'testVariable2' must match pattern '^[A-Z][A-Z0-9]*$'
  }
}

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

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathSingleFilter">
      <property name="checks" value="LeftCurly"/>
      <property name="query" value="//CLASS_DEF[@text='TestClass']/OBJBLOCK
            /METHOD_DEF[@text='testMethod1']/SLIST"/>
    </module>
  </module>
</module>

Code Example:

public class TestClass {
  public void testMethod1()
  { // OK
  }

  public void testMethod2()
  { // violation, '{' should be on the previous line
  }
}

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

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathSingleFilter">
      <property name="checks" value="RequireThis"/>
      <property name="query" value="//CLASS_DEF[@text='InputTest']
            //METHOD_DEF[@text='changeAge']//ASSIGN[@text='age']/IDENT"/>
    </module>
  </module>
</module>

Code Example:

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. 

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathSingleFilter">
      <property name="checks" value="IllegalThrows"/>
      <property name="query" value="//LITERAL_THROWS/IDENT[
          ..[@text='RuntimeException'] and ./ancestor::METHOD_DEF[@text='throwsMethod']]"/>
    </module>
  </module>
</module>

Code Example:

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. 

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathSingleFilter">
      <property name="checks" value=".*"/>
      <property name="query" value="//METHOD_DEF[@text='TestMethod1']
            /descendant-or-self::node()"/>
    </module>
  </module>
</module>

Code Example:

public class TestClass {
  public void TestMethod1() { // OK
    final int num = 10; // OK
  }

  public void TestMethod2() { // violation of the MethodName check,
                              // name 'TestMethod2' must match pattern '^[a-z](_?[a-zA-Z0-9]+)*$'
    final int num = 10; // violation of the LocalFinalVariableName check,
                        // name 'num' must match pattern '^[A-Z][A-Z0-9]*$'
  }
}

The following example is an example of what checks would be suppressed while building Spring projects with checkstyle plugin. Please find more information at: spring-javaformat 

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionXpathSingleFilter">
      <property name="files" value="[\\/]src[\\/]test[\\/]java[\\/]"/>
      <property name="checks" value="Javadoc*"/>
    </module>
    <module name="SuppressionXpathSingleFilter">
      <property name="files" value=".*Tests\.java"/>
      <property name="checks" value="Javadoc*"/>
    </module>
    <module name="SuppressionXpathSingleFilter">
      <property name="files" value="generated-sources"/>
      <property name="checks" value="[a-zA-Z0-9]*"/>
    </module>
  </module>
</module>

Example of Usage

Package

com.puppycrawl.tools.checkstyle.filters

Parent Module

TreeWalker