Class 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.util.regex.Pattern. 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.util.regex.Pattern. 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.util.regex.Pattern. 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" value="/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
    • Field Detail

      • files

        private Pattern files
        Define a Regular Expression matched against the file name associated with an audit event.
      • checks

        private Pattern checks
        Define a Regular Expression matched against the name of the check associated with an audit event.
      • message

        private Pattern message
        Define a Regular Expression matched against the message of the check associated with an audit event.
      • id

        private String id
        Define a string matched against the ID of the check associated with an audit event.
      • query

        private String query
        Define a string xpath query.
    • 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.