com.puppycrawl.tools.checkstyle.filters

Class SuppressionXpathSingleFilter

java.lang.Object

com.puppycrawl.tools.checkstyle.api.AutomaticBean

com.puppycrawl.tools.checkstyle.filters.SuppressionXpathSingleFilter

All Implemented Interfaces:

Configurable, Contextualizable, TreeWalkerFilter

public class SuppressionXpathSingleFilter
extends AutomaticBean
implements TreeWalkerFilter

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.

SuppressionXpathSingleFilter can suppress Checks that have Treewalker as parent module.

• Property files - Define a Regular Expression matched against the file name associated with an audit event. Type is java.lang.String. Default value is null.
• Property checks - Define a Regular Expression matched against the name of the check associated with an audit event. Type is java.lang.String. Default value is null.
• Property message - Define a Regular Expression matched against the message of the check associated with an audit event. Type is java.lang.String. Default value is null.
• Property id - Define a string matched against the ID of the check associated with an audit event. Type is java.lang.String. Default value is null.
• Property query - Define a string xpath query. Type is java.lang.String. Default value is null.

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

 <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>
 

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="SuppressionXpathSingleFilter">
   <property name="checks" value="MethodName"/>
   <property name="message" value="MyMethod[0-9]"/>
 </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="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/>
 

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="SuppressionXpathSingleFilter>
   <property name="checks" value="PackageName"/>
   <property name="query" query="/PACKAGE_DEF[@text='File']/IDENT"/>
 </module>
 

Code example:

 package File; // OK

 public class FileOne {}
 

To suppress RedundantModifier check for interface definitions:

 <module name="SuppressionXpathSingleFilter">
   <property name="checks" value="RedundantModifier"/>
   <property name="query" value="/INTERFACE_DEF//*"/>
 <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="SuppressionXpathSingleFilter">
   <property name="files" value="FileOne.java"/>
   <property name="checks" value="MyMethod"/>
 </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="SuppressionXpathSingleFilter">
   <property name="checks" value=".*"/>
   <property name="query"
             value="(/CLASS_DEF[@text='FileOne'])|
             (/CLASS_DEF[@text='FileOne']/OBJBLOCK/METHOD_DEF[@text='MyMethod']/IDENT)"/>
 </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="SuppressionXpathSingleFilter">
   <property name="checks" value="MethodName"/>
   <property name="query" value="/CLASS_DEF[@text='FileOne']/OBJBLOCK/
             METHOD_DEF[@text='MyMethod1' or @text='MyMethod2']/IDENT"/>
 </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="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>
 

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="SuppressionXpathSingleFilter">
   <property name="checks" value="LeftCurly"/>
   <property name="query" value="/CLASS_DEF[@text='TestClass']/OBJBLOCK
         /METHOD_DEF[@text='testMethod1']/SLIST*"/>
 </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="SuppressionXpathSingleFilter">
   <property name="checks" value="RequireThis"/>
   <property name="query" value="/CLASS_DEF[@text='InputTest']
         //METHOD_DEF[@text='changeAge']//ASSIGN[@text='age']/IDENT"/>
 </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="SuppressionXpathSingleFilter">
   <property name="checks" value="IllegalThrows"/>
   <property name="query" value="//LITERAL_THROWS/IDENT[
       ..[@text='RuntimeException'] and ./ancestor::METHOD_DEF[@text='throwsMethod']]"/>
 </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="SuppressionXpathSingleFilter">
   <property name="checks" value=".*"/>
   <property name="query" value="//METHOD_DEF[@text='TestMethod1']
         /descendant-or-self::node()"/>
 </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="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>
 

Parent is com.puppycrawl.tools.checkstyle.TreeWalker

Since:

8.18

Nested Class Summary

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

AutomaticBean.OutputStreamOptions

Constructor Summary

Constructors

Constructor and Description
SuppressionXpathSingleFilter()

Method Summary

Modifier and Type	Method and Description
boolean	accept(TreeWalkerAuditEvent treeWalkerAuditEvent) Determines whether or not a filtered TreeWalkerAuditEvent is accepted.
protected void	finishLocalSetup() Provides a hook to finish the part of this component's setup that was not handled by the bean introspection.
void	setChecks(String checks) Setter to define a Regular Expression matched against the name of the check associated with an audit event.
void	setFiles(String files) Setter to define a Regular Expression matched against the file name associated with an audit event.
void	setId(String id) Setter to define a string matched against the ID of the check associated with an audit event.
void	setMessage(String message) Setter to define a Regular Expression matched against the message of the check associated with an audit event.
void	setQuery(String query) Setter to define a string xpath query.

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

Constructor Detail

SuppressionXpathSingleFilter

public SuppressionXpathSingleFilter()

Method Detail

setFiles

public void setFiles(String files)

Setter to define a Regular Expression matched against the file name associated with an audit event.

Parameters:

files - the name of the file

setChecks

public void setChecks(String checks)

Setter to define a Regular Expression matched against the name of the check associated with an audit event.

Parameters:

checks - the name of the check

setMessage

public void setMessage(String message)

Setter to define a Regular Expression matched against the message of the check associated with an audit event.

Parameters:

message - the message of the check

setId

public void setId(String id)

Setter to define a string matched against the ID of the check associated with an audit event.

Parameters:

id - the ID of the check

setQuery

public void setQuery(String query)

Setter to define a string xpath query.

Parameters:

query - the xpath query

finishLocalSetup

protected void finishLocalSetup()

Description copied from class: AutomaticBean

Provides a hook to finish the part of this component's setup that was not handled by the bean introspection.

The default implementation does nothing.

Specified by:

finishLocalSetup in class AutomaticBean

accept

public boolean accept(TreeWalkerAuditEvent treeWalkerAuditEvent)

Description copied from interface: TreeWalkerFilter

Determines whether or not a filtered TreeWalkerAuditEvent is accepted.

Specified by:

accept in interface TreeWalkerFilter

Parameters:

treeWalkerAuditEvent - the TreeWalkerAuditEvent to filter.

Returns:

true if the event is accepted.