GitHub Twitter Stackoverflow GoogleGroups JProfiler

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 to use suppressions configured in the same config as other modules. SuppressionFilter and SuppressionXpathFilter require a 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 Example1 and Example3 files: 


<module name="Checker">
  <module name="TreeWalker">
    <module name="MethodName"/>
    <module name="SuppressionXpathSingleFilter">
      <property name="files" value="Example(1|3)\.java"/>
      <property name="checks" value="MethodName"/>
      <property name="query" value="(//CLASS_DEF[./IDENT[@text='Example1']]
                /OBJBLOCK/METHOD_DEF/IDENT[@text='MyMethod'])|
                (//CLASS_DEF[./IDENT[@text='Example3']]/OBJBLOCK
                /METHOD_DEF/IDENT[@text='MyMethod'])"/>
    </module>
  </module>
</module>

Code example:


public class Example1 {
  public void MyMethod() {}
  // filtered violation above 'Name 'MyMethod' must match pattern'
}

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


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

Code Example:


public class Example2 {
  // filtered violation below 'Name 'MyMethod1' must match pattern'
  public void MyMethod1() {}
  // filtered violation below 'Name 'MyMethod2' must match pattern'
  public void MyMethod2() {}
  // violation below 'Name 'MyMethodA' must match pattern'
  public void MyMethodA() {}
}

To suppress checks being specified by id property: 


<module name="Checker">
  <module name="TreeWalker">
    <module name="MethodName">
      <property name="id" value="MethodName1"/>
    </module>
    <module name="SuppressionXpathSingleFilter">
      <property name="files" value="Example3\.java"/>
      <property name="id" value="MethodName1"/>
    </module>
  </module>
</module>

Code example:


public class Example3 {
  // filtered violation below 'Name 'MyMethod' must match pattern'
  public void MyMethod() {}
}

To suppress checks for all package definitions: 


<module name="Checker">
  <module name="TreeWalker">
    <module name="PackageName">
      <property name="format"
        value="^[A-Z]+(\.[A-Z]*)*$"/>
    </module>
    <module name="SuppressionXpathSingleFilter">
      <property name="checks" value="PackageName"/>
      <property name="query" value="(//PACKAGE_DEF[.//IDENT
                [@text='suppressionxpathsinglefilter']])
                //IDENT[not(preceding::IDENT)]"/>
    </module>
  </module>
</module>

Code example:


package com.puppycrawl.tools.checkstyle.filters.suppressionxpathsinglefilter;
// filtered violation above 'must match pattern'

public class Example4 {}

To suppress RedundantModifier check for interface definitions: 


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

Code Example:


public interface Example5 {
  public int CONSTANT1 = 1; // filtered violation 'Redundant 'public' modifier.'
}

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


<module name="Checker">
  <module name="TreeWalker">
    <module name="MagicNumber"/>
    <module name="SuppressionXpathSingleFilter">
      <property name="files" value="Example6"/>
      <property name="checks" value="MagicNumber"/>
    </module>
  </module>
</module>

Code example:


public class Example6 {
  private int field = 177; // filtered violation ''177' is a magic number.'
}

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


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

Code example:


// filtered violation below 'Name 'Example7' must match pattern'
abstract class Example7 {
  public void MyMethod() {}
  // filtered violation above 'Name 'MyMethod' must match pattern'
}

// violation below, 'Name 'AnotherClass' must match pattern'
abstract class AnotherClass {
  public void MyMethod() {}
  // violation above, 'Name 'MyMethod' must match pattern'
}

Suppress checks for MyMethod1 or MyMethod2 methods: 


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

Code example:


class Example8 {
  // filtered violation below 'Name 'MyMethod1' must match pattern'
  public void MyMethod1() {}
  // filtered violation below 'Name 'MyMethod2' must match pattern'
  public void MyMethod2() {}
  // violation below, 'Name 'MyMethod3' must match pattern'
  public void MyMethod3() {}
}

Suppress checks for variable testVariable1 inside testMethod method inside Example9 class: 


<module name="Checker">
  <module name="TreeWalker">
    <module name="LocalFinalVariableName">
      <property name="format" value="^[A-Z][A-Z0-9]*$"/>
    </module>
    <module name="SuppressionXpathSingleFilter">
      <property name="checks" value="LocalFinalVariableName"/>
      <property name="query" value="//CLASS_DEF[./IDENT[@text='Example9']]/OBJBLOCK
            /METHOD_DEF[./IDENT[@text='testMethod']]/SLIST
            /VARIABLE_DEF/IDENT[@text='testVariable1']"/>
    </module>
  </module>
</module>

Code Example:


public class Example9 {
  public void testMethod() {
    // filtered violation below 'Name 'testVariable1' must match pattern'
    final int testVariable1 = 10;
    // violation below, 'Name 'testVariable2' must match pattern'
    final int testVariable2 = 10;
  }
}

In the following sample, violations for LeftCurly check will be suppressed for methods with name testMethod1 inside Example10 file. 


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

Code Example:


public class Example10 {
  public void testMethod1()
  { // filtered violation ''{' at column 3 should be on the previous line.'
  }

  public void testMethod2()
  { // violation, ''{' at column 3 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="RequireThis">
      <property name="validateOnlyOverlapping" value="false"/>
    </module>
    <module name="SuppressionXpathSingleFilter">
      <property name="checks" value="RequireThis"/>
      <property name="query" value="//CLASS_DEF[./IDENT[@text='Example11']]
            //METHOD_DEF[./IDENT[@text='changeAge']]//ASSIGN/IDENT[@text='age']"/>
    </module>
  </module>
</module>

Code Example:


public class Example11 {
  private int age = 23;
  private int number = 100;

  public void changeAge() {
    // filtered violation below 'Reference to instance variable 'age' needs "this.".'
    age = 24;
  }
  public void changeNumber(int number) {
    // violation below, 'Reference to instance variable 'number' needs "this.".'
    number = number;
  }
}

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="IllegalThrows"/>
    <module name="SuppressionXpathSingleFilter">
      <property name="checks" value="IllegalThrows"/>
      <property name="query" value="//LITERAL_THROWS/IDENT[@text='RuntimeException'
                    and ./ancestor::METHOD_DEF[./IDENT[@text='throwsMethod']]]"/>
    </module>
  </module>
</module>

Code Example:


public class Example12 {
  // 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 {
  }
}

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="LocalFinalVariableName">
      <property name="format" value="^[A-Z][A-Z0-9]*$"/>
    </module>
    <module name="MethodName">
      <property name="format" value="^[a-z](_?[a-zA-Z0-9]+)*$"/>
    </module>
    <module name="SuppressionXpathSingleFilter">
      <property name="checks" value=".*"/>
      <property name="query" value="//METHOD_DEF[./IDENT[@text='TestMethod1']]
            /descendant-or-self::node()"/>
    </module>
  </module>
</module>

Code Example:


public class Example13 {
  // filtered violation below 'Name 'TestMethod1' must match pattern'
  public void TestMethod1() {
    // filtered violation below 'Name 'num' must match pattern'
    final int num = 10;
  }

  // violation below, 'Name 'TestMethod2' must match pattern'
  public void TestMethod2() {
    // violation below, 'Name 'num' must match pattern'
    final int num = 10;
  }
}

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="IllegalIdentifierName">
      <property name="format" value="^[A-Z][a-zA-Z0-9]*$"/>
      <property name="tokens" value="CLASS_DEF"/>
    </module>
    <module name="SuppressionXpathSingleFilter">
      <property name="files" value="[\\/]src[\\/]test[\\/]java[\\/]"/>
      <property name="checks" value="IllegalIdentifierName"/>
    </module>
    <module name="SuppressionXpathSingleFilter">
      <property name="files" value=".*Tests\.java"/>
      <property name="checks" value="IllegalIdentifierName"/>
    </module>
    <module name="SuppressionXpathSingleFilter">
      <property name="files" value="generated-sources"/>
      <property name="checks" value="[a-zA-Z0-9]*"/>
    </module>
  </module>
</module>

Code Example:


.../src/myApplication.java // violation, Name 'myApplication' must match pattern.
.../src/myApplicationTests.java // filtered violation 'must match pattern'
.../src/test/java/insidePackage.java // filtered violation 'must match pattern'

Example of Usage

Package

com.puppycrawl.tools.checkstyle.filters

Parent Module

TreeWalker