SuppressionFilter

Since Checkstyle 3.2

Description

Filter SuppressionFilter rejects audit events for Check violations according to a suppressions XML document in a file. If there is no configured suppressions file or the optional is set to true and suppressions file was not found the Filter accepts all audit events.

Notes

A suppressions XML document contains a set of suppress elements, where each suppress 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 check id associated with an audit event. Optional as long as checks or message is specified.
lines - a comma-separated list of values, where each value is an int or a range of integers denoted by integer-integer. It is optional.
columns - a comma-separated list of values, where each value is an int or a range of integers denoted by integer-integer. It is optional.

Each audit event is checked against each suppress 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.

You can download template of empty suppression filter here.

Location of the file defined in file property is checked in the 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.

SuppressionFilter can suppress Checks that have Treewalker or Checker as parent module.

Properties

name	description	type	default value	since
file	Specify the location of the suppressions XML document file.	String	`null`	3.2
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 accept all audit events.	boolean	`false`	6.15

Examples

Suppress certain checks by check name, file, and line number:


<module name="Checker">
  <module name="SuppressionFilter">
    <property name="file" value="suppressionexample1.xml"/>
    <property name="optional" value="false"/>
  </module>
  <module name="TreeWalker">
    <module name="JavadocStyle"/>
    <module name="MagicNumber"/>
    <module name="com.puppycrawl.tools.checkstyle.checks.blocks.EmptyBlockCheck"/>
  </module>
</module>

The following suppressions XML document directs a SuppressionFilter to reject JavadocStyleCheck violations for line 4 of file Example1.java, and MagicNumberCheck violations for lines 7 and 11 of file Example1.java, and 'Missing a Javadoc comment' violations for all lines and files:


<?xml version="1.0"?>

<!DOCTYPE suppressions PUBLIC
  "-//Checkstyle//DTD SuppressionFilter Configuration 1.2//EN"
  "https://checkstyle.org/dtds/suppressions_1_2.dtd">

<suppressions>
  <suppress checks="JavadocStyle"
    files="Example1.java"
    lines="20"/>
  <suppress checks="MagicNumber"
    files="Example1.java"
    lines="23,27"/>
  <suppress message="Missing a Javadoc comment"/>
</suppressions>

Example:


public class Example1 {

  // filtered violation below 'First sentence should end with a period.'
  /**
   * This field a is missing period
   */
  int a = 10; // filtered violation ''10' is a magic number.'

  public void exampleMethod() {

    int num = 100; // filtered violation ''100' is a magic number.'

    if (true) {
      // violation above 'Must have at least one statement.'
    }
  }
}

Suppress certain checks by their module id:


<module name="Checker">
  <module name="SuppressionFilter">
    <property name="file" value="suppressionexample2.xml"/>
    <property name="optional" value="false"/>
  </module>
  <module name="TreeWalker">
    <module name="EqualsAvoidNull">
      <property name="id" value="stringEqual"/>
    </module>
    <module name="LineLength">
      <property name="id" value="lineLength"/>
    </module>
  </module>
</module>

The following suppressions XML document directs a SuppressionFilter to reject EqualsAvoidNullCheck by module id stringEqual violations for all lines of file Example2.java:


<?xml version="1.0"?>

<!DOCTYPE suppressions PUBLIC
  "-//Checkstyle//DTD SuppressionFilter Configuration 1.2//EN"
  "https://checkstyle.org/dtds/suppressions_1_2.dtd">

<suppressions>
  <suppress id="stringEqual" files="Example2.java"/>
</suppressions>

Example:


public class Example2 {

  // violation below, 'Line is longer than 80 characters'
  String line = "This line is long and exceeds the default limit of 80 characters.";

  public void foo() {

    String nullString = null;

    // filtered violation below 'expressions should be on the left side'
    nullString.equals("My_Sweet_String");
    "My_Sweet_String".equals(nullString);

    // filtered violation below 'expressions should be on the left side'
    nullString.equalsIgnoreCase("My_Sweet_String");
    "My_Sweet_String".equalsIgnoreCase(nullString);
  }
}

Suppress all checks for hidden files and folders:


<module name="Checker">
  <property name="fileExtensions" value="properties"/>

  <module name="SuppressionFilter">
    <property name="file" value="suppressionexample3.xml"/>
  </module>

  <module name="OrderedProperties"/>
  <module name="UniqueProperties"/>
</module>

The following suppressions XML document directs a SuppressionFilter to reject all checks for hidden files and folders:


<?xml version="1.0"?>

<!DOCTYPE suppressions PUBLIC
  "-//Checkstyle//DTD SuppressionFilter Configuration 1.2//EN"
  "https://checkstyle.org/dtds/suppressions_1_2.dtd">

<suppressions>
  <suppress files="[/\\]\..+" checks=".*"/>
</suppressions>

Below Example is suppressed because hidden.properties file inside the .hidden folder:


keyB=value1 # // filtered violation 'Duplicated property 'keyB' (2 occurrence(s)).'
keyB=value2
# // filtered violation below 'Duplicated property 'keyC' (2 occurrence(s)).'
keyC=value4
keyC=value5

Suppress checks by violation message:


<module name="Checker">
  <module name="SuppressionFilter">
    <property name="file" value="suppressionexample4.xml"/>
    <property name="optional" value="false"/>
  </module>
  <module name="TreeWalker">
    <module name="MemberName">
      <property name="format" value="^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$"/>
    </module>
    <module name="ConstantName"/>
  </module>
</module>

The following suppressions XML document directs a SuppressionFilter to reject violations on variable named 'log' in all files:


<?xml version="1.0"?>

<!DOCTYPE suppressions PUBLIC
  "-//Checkstyle//DTD SuppressionFilter Configuration 1.2//EN"
  "https://checkstyle.org/dtds/suppressions_1_2.dtd">

<suppressions>
  <suppress message="Name 'log' must match pattern"/>
</suppressions>

Example:


public class Example4 {

  public int log;
  // filtered violation above 'Name 'log' must match pattern'

  public int constant;
  // violation above 'Name 'constant' must match pattern'
}

class Inner {

  public static final int log = 10;
  // filtered violation above 'Name 'log' must match pattern'

  public static final String line = "This is a line";
  // violation above 'Name 'line' must match pattern'
}

Suppress all checks for Maven-generated code:


<suppress files="[/\\]target[/\\]" checks=".*"/>

Suppress all checks for archives, classes and other binary files:


<suppress files=".+\.(?:jar|zip|war|class|tar|bin)$" checks=".*"/>

Suppress all checks for image files:


<suppress files=".+\.(?:png|gif|jpg|jpeg)$" checks=".*"/>

Suppress all checks for non-java files:


<suppress files=".+\.(?:txt|xml|csv|sh|thrift|html|sql|eot|ttf|woff|css|png)$"
  checks=".*"/>

Suppress all checks in generated sources:


<suppress checks=".*" files="com[\\/]mycompany[\\/]app[\\/]gen[\\/]"/>

Suppress FileLength check on integration tests in certain folder:


<suppress checks="FileLength"
files="com[\\/]mycompany[\\/]app[\\/].*IT.java"/>

SuppressionFilter

Description

Notes

Properties

Examples

Example of Usage

Package

Parent Module