| <?xml version="1.0" encoding="UTF-8"?> |
| |
| <document xmlns="http://maven.apache.org/XDOC/2.0" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd"> |
| |
| <head> |
| <title>Filters</title> |
| <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"/> |
| <script type="text/javascript" src="js/anchors.js"/> |
| <script type="text/javascript" src="js/google-analytics.js"/> |
| <link rel="icon" href="images/favicon.png" type="image/x-icon" /> |
| <link rel="shortcut icon" href="images/favicon.ico" type="image/ico" /> |
| </head> |
| |
| <body> |
| <section name="Content"> |
| <macro name="toc"> |
| <param name="fromDepth" value="1"/> |
| <param name="toDepth" value="1"/> |
| </macro> |
| </section> |
| |
| <section name="SeverityMatchFilter"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 3.2</p> |
| <p> |
| Filter <code>SeverityMatchFilter</code> decides |
| audit events according to the <a href="config.html#Severity">severity |
| level</a> of the event. |
| </p> |
| </subsection> |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>severity</td> |
| <td>the severity level of this filter</td> |
| <td><a href="property_types.html#severity">Severity</a></td> |
| <td><code>error</code></td> |
| <td>3.2</td> |
| </tr> |
| <tr> |
| <td>acceptOnMatch</td> |
| <td> |
| If acceptOnMatch is <code>true</code>, then |
| the filter accepts an audit event if and only if there is |
| a match between the event's severity level and property |
| severity. If acceptOnMatch |
| is <code>false</code>, then the filter |
| accepts an audit event if and only if there is not a match |
| between the event's severity level and property severity. |
| </td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td><code>true</code></td> |
| <td>3.2</td> |
| </tr> |
| </table> |
| </subsection> |
| <subsection name="Examples"> |
| <p> |
| For example, the following configuration fragment directs the |
| Checker to not report audit events with severity |
| level <code>info</code>: |
| </p> |
| <source> |
| <module name="SeverityMatchFilter"> |
| <property name="severity" value="info"/> |
| <property name="acceptOnMatch" value="false"/> |
| </module> |
| </source> |
| </subsection> |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SeverityMatchFilter"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| <subsection name="Package"> |
| <p> com.puppycrawl.tools.checkstyle.filters </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> <a href="config.html#Checker">Checker</a> </p> |
| </subsection> |
| </section> |
| |
| <section name="SuppressionCommentFilter"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 3.5</p> |
| <p> |
| Filter <code>SuppressionCommentFilter</code> uses |
| pairs of comments to suppress audit events. |
| </p> |
| <p> |
| Rationale: Sometimes there are legitimate reasons for violating |
| a check. When this is a matter of the code in question and not |
| personal preference, the best place to override the policy is in |
| the code itself. Semi-structured comments can be associated |
| with the check. This is sometimes superior to a separate |
| suppressions file, which must be kept up-to-date as the source |
| file is edited. |
| </p> |
| <p> |
| Note that the suppression comment should be put before the violation. You can use more |
| than one suppression comment each on separate line. |
| </p> |
| </subsection> |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>offCommentFormat</td> |
| <td>comment pattern to trigger filter to begin suppression</td> |
| <td><a href="property_types.html#regexp">Regular Expression</a></td> |
| <td><code>"CHECKSTYLE:OFF"</code></td> |
| <td>3.5</td> |
| </tr> |
| <tr> |
| <td>onCommentFormat</td> |
| <td>comment pattern to trigger filter to end suppression</td> |
| <td><a href="property_types.html#regexp">Regular Expression</a></td> |
| <td><code>"CHECKSTYLE:ON"</code></td> |
| <td>3.5</td> |
| </tr> |
| <tr> |
| <td>checkFormat</td> |
| <td>check pattern to suppress</td> |
| <td><a href="property_types.html#regexp">Regular Expression</a></td> |
| <td><code>".*"</code></td> |
| <td>3.5</td> |
| </tr> |
| <tr> |
| <td>messageFormat</td> |
| <td>message pattern to suppress</td> |
| <td><a href="property_types.html#regexp">Regular Expression</a></td> |
| <td><code>null</code></td> |
| <td>3.5</td> |
| </tr> |
| <tr> |
| <td>checkCPP</td> |
| <td>whether to check C++ style comments (<code>//</code>)</td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td><code>true</code></td> |
| <td>3.5</td> |
| </tr> |
| <tr> |
| <td>checkC</td> |
| <td>whether to check C style comments (<code>/* ... */</code>)</td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td><code>true</code></td> |
| <td>3.5</td> |
| </tr> |
| </table> |
| <p> |
| offCommentFormat and onCommentFormat must have equal <a |
| href="https://docs.oracle.com/javase/7/docs/api/java/util/regex/Matcher.html#groupCount()">paren counts</a>. |
| </p> |
| </subsection> |
| <subsection name="Examples"> |
| <p> |
| To configure a filter to suppress audit events between a comment |
| containing <code>CHECKSTYLE:OFF</code> and a comment containing |
| <code>CHECKSTYLE:ON</code>: |
| </p> |
| <source> |
| <module name="TreeWalker"> |
| ... |
| <module name="SuppressionCommentFilter"/> |
| ... |
| </module> |
| </source> |
| <p> |
| To configure a filter to suppress audit events between a comment |
| containing line <code>BEGIN GENERATED CODE</code> and a comment |
| containing line <code>END GENERATED CODE</code>: |
| </p> |
| <source> |
| <module name="SuppressionCommentFilter"> |
| <property name="offCommentFormat" value="BEGIN GENERATED CODE"/> |
| <property name="onCommentFormat" value="END GENERATED CODE"/> |
| </module> |
| </source> |
| <source> |
| //BEGIN GENERATED CODE |
| @Override |
| public boolean equals(Object obj) { ... } // No violation events will be reported |
| |
| @Override |
| public int hashCode() { ... } // No violation events will be reported |
| //END GENERATED CODE |
| . . . |
| </source> |
| <p> |
| To configure a filter so that <code>// stop constant |
| check</code> and <code>// resume constant check</code> marks |
| legitimate constant names: |
| </p> |
| <source> |
| <module name="SuppressionCommentFilter"> |
| <property name="offCommentFormat" value="stop constant check"/> |
| <property name="onCommentFormat" value="resume constant check"/> |
| <property name="checkFormat" value="ConstantNameCheck"/> |
| </module> |
| </source> |
| <source> |
| //stop constant check |
| public static final int someConstant; // won't warn here |
| //resume constant check |
| public static final int someConstant; // will warn here as constant's name doesn't match the |
| // pattern "^[A-Z][A-Z0-9]*$" |
| </source> |
| <p> |
| To configure a filter so that <code>UNUSED OFF: |
| <i>var</i></code> and <code>UNUSED ON: <i>var</i></code> marks a |
| variable or parameter known not to be used by the code by |
| matching the variable name in the message: |
| </p> |
| <source> |
| <module name="SuppressionCommentFilter"> |
| <property name="offCommentFormat" value="UNUSED OFF\: (\w+)"/> |
| <property name="onCommentFormat" value="UNUSED ON\: (\w+)"/> |
| <property name="checkFormat" value="Unused"/> |
| <property name="messageFormat" value="^Unused \w+ '$1'.$"/> |
| </module> |
| </source> |
| <source> |
| private static void foo(int a, int b) // UNUSED OFF: b |
| { |
| System.out.println(a); |
| } |
| |
| private static void foo1(int a, int b) // UNUSED ON: b |
| { |
| System.out.println(a); |
| } |
| </source> |
| <p> |
| To configure a filter so that name of suppressed check mentioned |
| in comment <code>CSOFF: <i>regexp</i></code> |
| and <code>CSON: <i>regexp</i></code> mark a matching check: |
| </p> |
| <source> |
| <module name="SuppressionCommentFilter"> |
| <property name="offCommentFormat" value="CSOFF\: ([\w\|]+)"/> |
| <property name="onCommentFormat" value="CSON\: ([\w\|]+)"/> |
| <property name="checkFormat" value="$1"/> |
| </module> |
| </source> |
| <source> |
| public static final int lowerCaseConstant; // CSOFF: ConstantNameCheck |
| public static final int lowerCaseConstant1; // CSON: ConstantNameCheck |
| </source> |
| <p> |
| To configure a filter to suppress all audit events between a comment |
| containing <code>CHECKSTYLE_OFF: ALMOST_ALL</code> and a comment containing |
| <code>CHECKSTYLE_OFF: ALMOST_ALL</code> except for the <em>EqualsHashCode</em> check: |
| </p> |
| <source> |
| <module name="SuppressionCommentFilter"> |
| <property name="offCommentFormat" value="CHECKSTYLE_OFF: ALMOST_ALL"/> |
| <property name="onCommentFormat" value="CHECKSTYLE_ON: ALMOST_ALL"/> |
| <property name="checkFormat" value="^((?!(EqualsHashCode)).)*$"/> |
| </module> |
| </source> |
| <source> |
| public static final int array []; // CHECKSTYLE_OFF: ALMOST_ALL |
| private String [] strArray; |
| private int array1 []; // CHECKSTYLE_ON: ALMOST_ALL |
| </source> |
| <p> |
| To configure a filter to suppress Check's violation message <b>which matches |
| specified message in messageFormat</b> (so suppression will be not only by |
| Check's name, but by message text additionally, as the same Check could report |
| different by message format violations) between a comment |
| containing <code>stop</code> and comment containing <code>resume</code>: |
| </p> |
| <source> |
| <module name="SuppressionCommentFilter"> |
| <property name="offCommentFormat" value="stop"/> |
| <property name="onCommentFormat" value="resume"/> |
| <property name="checkFormat" value="IllegalTypeCheck"/> |
| <property name="messageFormat" value="^Declaring variables, return values or parameters of type 'GregorianCalendar' is not allowed.$"/> |
| </module> |
| </source> |
| <p> |
| Code before filter above is applied with Check's audit events: |
| </p> |
| <source> |
| ... |
| GregorianCalendar calendar; // Warning here: Declaring variables, return values or parameters of type 'GregorianCalendar' is not allowed. |
| HashSet hashSet; // Warning here: Declaring variables, return values or parameters of type 'HashSet' is not allowed. |
| ... |
| </source> |
| <p> |
| Code after filter is applied: |
| </p> |
| <source> |
| ... |
| //stop |
| GregorianCalendar calendar; // No warning here as it is suppressed by filter. |
| HashSet hashSet; // Warning here: Declaring variables, return values or parameters of type 'HashSet' is not allowed. |
| //resume |
| ... |
| </source> |
| <p> |
| It is possible to specify an ID of checks, so that it can be leveraged by the |
| SuppressionCommentFilter to skip validations. The following examples show how to skip |
| validations near code that is surrounded with <code>// CSOFF <ID> (reason)</code> |
| and <code>// CSON <ID></code>, where ID is the ID of checks you want to suppress. |
| </p> |
| <p> |
| Examples of Checkstyle checks configuration: |
| </p> |
| <source> |
| <module name="RegexpSinglelineJava"> |
| <property name="id" value="ignore"/> |
| <property name="format" value="^.*@Ignore\s*$"/> |
| <property name="message" value="@Ignore should have a reason."/> |
| </module> |
| |
| <module name="RegexpSinglelineJava"> |
| <property name="id" value="systemout"/> |
| <property name="format" value="^.*System\.(out|err).*$"/> |
| <property name="message" value="Don't use System.out/err, use SLF4J instead."/> |
| </module> |
| </source> |
| <p> |
| Example of SuppressionCommentFilter configuration (checkFormat which is set to '$1' |
| points that ID of the checks is in the first group of offCommentFormat and |
| onCommentFormat regular expressions): |
| </p> |
| <source> |
| <module name="SuppressionCommentFilter"> |
| <property name="offCommentFormat" value="CSOFF (\w+) \(\w+\)"/> |
| <property name="onCommentFormat" value="CSON (\w+)"/> |
| <property name="checkFormat" value="$1"/> |
| </module> |
| </source> |
| <source> |
| // CSOFF ignore (test has not been implemented yet) |
| @Ignore // should NOT fail RegexpSinglelineJava |
| @Test |
| public void testMethod() { } |
| // CSON ignore |
| |
| // CSOFF systemout (debug) |
| public static void foo() { |
| System.out.println("Debug info."); // should NOT fail RegexpSinglelineJava |
| } |
| // CSON systemout |
| </source> |
| <p> |
| Example of how to configure the check to suppress more than one checks. |
| </p> |
| <source> |
| <module name="SuppressionCommentFilter"> |
| <property name="offCommentFormat" value="@cs-\: ([\w\|]+)"/> |
| <property name="checkFormat" value="$1"/> |
| </module> |
| </source> |
| <source> |
| // @cs-: ClassDataAbstractionCoupling |
| // @cs-: MagicNumber |
| @Service // no violations from ClassDataAbstractionCoupling here |
| @Transactional |
| public class UserService { |
| private int value = 10022; // no violations from MagicNumber here |
| } |
| </source> |
| </subsection> |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SuppressionCommentFilter"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| <subsection name="Package"> |
| <p> com.puppycrawl.tools.checkstyle.filters </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> <a href="config.html#TreeWalker">TreeWalker</a> </p> |
| </subsection> |
| </section> |
| |
| <section name="SuppressionFilter"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 3.2</p> |
| <p> |
| Filter <code>SuppressionFilter</code> rejects |
| audit events for Check errors according to |
| a <a href="config.html#XML_Structure"><em>suppressions XML |
| document</em></a> 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. |
| </p> |
| </subsection> |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>file</td> |
| <td> |
| the location of the <em>suppressions XML document</em> file. |
| The order the location is checked is: |
| <ol> |
| <li>as a filesystem location</li> |
| <li> |
| if no file found, and the location starts with either |
| <code>http://</code> or <code>https://</code>, then it |
| is interpreted as a URL |
| </li> |
| <li> |
| if no file found, then passed to the |
| <code>ClassLoader.getResource()</code> method. |
| </li> |
| </ol> |
| </td> |
| <td><a href="property_types.html#string">string</a></td> |
| <td><code>none</code></td> |
| <td>3.2</td> |
| </tr> |
| <tr> |
| <td>optional</td> |
| <td> |
| Tells 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. |
| </td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td><code>false</code></td> |
| <td>6.15</td> |
| </tr> |
| </table> |
| </subsection> |
| <subsection name="Examples"> |
| <p> |
| For example, the following configuration fragment directs the |
| Checker to use a <code>SuppressionFilter</code> |
| with suppressions |
| file <code>config/suppressions.xml</code>: |
| </p> |
| <source> |
| <module name="SuppressionFilter"> |
| <property name="file" value="config/suppressions.xml"/> |
| <property name="optional" value="false"/> |
| </module> |
| </source> |
| <p> |
| A <a href="config.html#XML_Structure"><em>suppressions XML |
| document</em></a> contains a set |
| of <code>suppress</code> elements, where |
| each <code>suppress</code> element can have the |
| following attributes: |
| </p> |
| <ul> |
| <li> |
| <code>files</code> - |
| a <a href="property_types.html#regexp">Regular Expression</a> |
| matched against the file name associated with an audit |
| event. It is optional. |
| </li> |
| <li> |
| <code>checks</code> - |
| a <a href="property_types.html#regexp">Regular Expression</a> |
| matched against the name of the check associated with an audit |
| event. Optional as long as <code>id</code> or <code>message</code> is specified. |
| </li> |
| <li> |
| <code>message</code> - |
| a <a href="property_types.html#regexp">Regular Expression</a> |
| matched against the message of the check associated with an audit |
| event. Optional as long as <code>checks</code> or <code>id</code> is specified. |
| </li> |
| <li> |
| <code>id</code> - |
| a <a href="property_types.html#string">string</a> |
| matched against the ID of the check associated with an audit |
| event. Optional as long as <code>checks</code> or <code>message</code> is specified. |
| </li> |
| <li> |
| <code>lines</code> - a comma-separated list of |
| values, where each value is |
| an <a href="property_types.html#integer">integer</a> or a |
| range of integers denoted by integer-integer. It is optional. |
| </li> |
| <li> |
| <code>columns</code> - a comma-separated list of |
| values, where each value is |
| an <a href="property_types.html#integer">integer</a> or a |
| range of integers denoted by integer-integer. It is optional. |
| </li> |
| </ul> |
| <p> |
| Each audit event is checked against |
| each <code>suppress</code> element. It is |
| suppressed if all specified attributes match against the audit |
| event. |
| </p> |
| <p> |
| You can download template of empty suppression filter |
| <a href="files/suppressions_none.xml">here</a>. |
| </p> |
| <p> |
| The following suppressions XML document directs |
| a <code>SuppressionFilter</code> to |
| reject <code>JavadocStyleCheck</code> errors for |
| lines 82 and 108 to 122 of |
| file <code>AbstractComplexityCheck.java</code>, |
| and <code>MagicNumberCheck</code> errors for line |
| 221 of file <code>JavadocStyleCheck.java</code>, |
| and '<code>Missing a Javadoc comment</code>' errors |
| for all lines and files: |
| </p> |
| <source> |
| <?xml version="1.0"?> |
| |
| <!DOCTYPE suppressions PUBLIC |
| "-//Puppy Crawl//DTD Suppressions 1.1//EN" |
| "http://checkstyle.sourceforge.net/dtds/suppressions_1_1.dtd"> |
| |
| <suppressions> |
| <suppress checks="JavadocStyleCheck" |
| files="AbstractComplexityCheck.java" |
| lines="82,108-122"/> |
| <suppress checks="MagicNumberCheck" |
| files="JavadocStyleCheck.java" |
| lines="221"/> |
| </suppressions> |
| <suppress message="Missing a Javadoc comment"/></suppressions> |
| </source> |
| <p> |
| As another example to suppress Check by module id: |
| </p> |
| <source> |
| <module name="DescendantToken"> |
| <property name="id" value="stringEqual"/> |
| <property name="tokens" value="EQUAL,NOT_EQUAL"/> |
| <property name="limitedTokens" value="STRING_LITERAL"/> |
| <property name="maximumNumber" value="0"/> |
| <property name="maximumDepth" value="1"/> |
| </module> |
| |
| <module name="DescendantToken"> |
| <property name="id" value="switchNoDefault"/> |
| <property name="tokens" value="LITERAL_SWITCH"/> |
| <property name="maximumDepth" value="2"/> |
| <property name="limitedTokens" value="LITERAL_DEFAULT"/> |
| <property name="minimumNumber" value="1"/> |
| </module> |
| </source> |
| <p> |
| Then the following can be used to suppress only the first |
| check and not the second by using |
| the <code>id</code> attribute: |
| </p> |
| <source> |
| <suppress id="stringEqual" files="SomeTestCode.java"/> |
| </source> |
| <p> |
| Suppress checks for hidden files and folders: |
| </p> |
| <source> |
| <suppress files="[/\\]\..+" checks=".*"/> |
| </source> |
| <p> |
| Suppress checks for Maven-generated code: |
| </p> |
| <source> |
| <suppress files="[/\\]target[/\\]" checks=".*"/> |
| </source> |
| <p> |
| Suppress checks for archives, classes and other binary files: |
| </p> |
| <source> |
| <suppress files=".+\.(?:jar|zip|war|class|tar|bin)$" checks=".*"/> |
| </source> |
| <p> |
| Suppress checks for image files: |
| </p> |
| <source> |
| <suppress files=".+\.(?:png|gif|jpg|jpeg)$" checks=".*"/> |
| </source> |
| <p> |
| Suppress checks for non-java files: |
| </p> |
| <source> |
| <suppress files=".+\.(?:txt|xml|csv|sh|thrift|html|sql|eot|ttf|woff|css|png)$" checks=".*"/> |
| </source> |
| <p> |
| Suppress all checks in generated sources: |
| </p> |
| <source> |
| <suppress checks=".*" files="com[\\/]mycompany[\\/]app[\\/]gen[\\/]"/> |
| </source> |
| <p> |
| Suppress FileLength check on integration tests in certain folder: |
| </p> |
| <source> |
| <suppress checks="FileLength" files="com[\\/]mycompany[\\/]app[\\/].*IT.java"/> |
| </source> |
| <p> |
| Suppress naming errors on variable named 'log' in all files: |
| </p> |
| <source> |
| <suppress message="Name 'log' must match pattern"/> |
| </source> |
| </subsection> |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SuppressionFilter"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| <subsection name="Package"> |
| <p> com.puppycrawl.tools.checkstyle.filters </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> <a href="config.html#Checker">Checker</a> </p> |
| </subsection> |
| </section> |
| |
| <section name="SuppressionXpathFilter"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 8.6</p> |
| <p> |
| Filter <code>SuppressionXpathFilter</code> works as |
| <a href="config_filters.html#SuppressionFilter">SuppressionFilter</a>. |
| Additionally, filter processes <code>suppress-xpath</code> elements, |
| which contains xpath-expressions. Xpath-expressions |
| are queries for suppressed nodes inside the AST tree. |
| </p> |
| <p> |
| Note, after resolving |
| <a href="https://github.com/checkstyle/checkstyle/issues/4530">issue 4530</a> |
| CLI will have option to generate the basic suppression xpath to elements. |
| </p> |
| <p> |
| Currently, filter supports the following |
| checks: |
| </p> |
| <ul> |
| <li>CyclomaticComplexityCheck</li> |
| <li>DeclarationOrderCheck</li> |
| <li>DefaultComesLastCheck</li> |
| <li>ExplicitInitializationCheck</li> |
| <li>FallThroughCheck</li> |
| <li>HiddenFieldCheck</li> |
| <li>IllegalCatchCheck</li> |
| <li>IllegalThrowsCheck</li> |
| <li>JavadocMethodCheck</li> |
| <li>JavadocVariableCheck</li> |
| <li>ImportControlCheck</li> |
| <li>LeftCurlyCheck</li> |
| <li>MethodParamPadCheck</li> |
| <li>MultipleVariableDeclarationCheck</li> |
| <li>NestedForDepthCheck</li> |
| <li>NestedIfDepthCheck</li> |
| <li>NestedTryDepthCheck</li> |
| <li>NPathComplexityCheck</li> |
| <li>OneStatementPerLineCheck</li> |
| <li>OuterTypeNumberCheck</li> |
| <li>RequireThisCheck</li> |
| <li>RightCurlyCheck</li> |
| </ul> |
| <p> |
| Note, that support for other Checks will be available after resolving |
| <a href="https://github.com/checkstyle/checkstyle/issues/4830">issue 4830</a>. |
| </p> |
| </subsection> |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>file</td> |
| <td> |
| the location of the <em>suppressions XML document</em> file. |
| The order the location is checked is: |
| <ol> |
| <li>as a filesystem location</li> |
| <li> |
| if no file found, and the location starts with either |
| <code>http://</code> or <code>https://</code>, then it |
| is interpreted as a URL |
| </li> |
| <li> |
| if no file found, then passed to the |
| <code>ClassLoader.getResource()</code> method. |
| </li> |
| </ol> |
| </td> |
| <td><a href="property_types.html#string">string</a></td> |
| <td><code>none</code></td> |
| <td>8.6</td> |
| </tr> |
| <tr> |
| <td>optional</td> |
| <td> |
| Tells 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. |
| </td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td><code>false</code></td> |
| <td>8.6</td> |
| </tr> |
| </table> |
| </subsection> |
| <subsection name="Examples"> |
| <p> |
| For example, the following configuration fragment directs the |
| Checker to use a <code>SuppressionXpathFilter</code> |
| with suppressions |
| file <code>config/suppressions.xml</code>: |
| </p> |
| <source> |
| <module name="SuppressionXpathFilter"> |
| <property name="file" value="config/suppressions.xml"/> |
| <property name="optional" value="false"/> |
| </module> |
| </source> |
| <p> |
| A <a href="config.html#XML_Structure"><em>suppressions XML |
| document</em></a> contains a set |
| of <code>suppress</code> and <code>suppress-xpath</code> elements, where |
| each <code>suppress-xpath</code> element can have the |
| following attributes: |
| </p> |
| <ul> |
| <li> |
| <code>files</code> - |
| a <a href="property_types.html#regexp">Regular Expression</a> |
| matched against the file name associated with an audit |
| event. It is optional. |
| </li> |
| <li> |
| <code>checks</code> - |
| a <a href="property_types.html#regexp">Regular Expression</a> |
| matched against the name of the check associated with an audit |
| event. Optional as long as <code>id</code> or <code>message</code> is specified. |
| </li> |
| <li> |
| <code>message</code> - |
| a <a href="property_types.html#regexp">Regular Expression</a> |
| matched against the message of the check associated with an audit |
| event. Optional as long as <code>checks</code> or <code>id</code> is specified. |
| </li> |
| <li> |
| <code>id</code> - |
| a <a href="property_types.html#string">string</a> |
| matched against the ID of the check associated with an audit |
| event. Optional as long as <code>checks</code> or <code>message</code> is specified. |
| </li> |
| <li> |
| <code>query</code> - |
| a <a href="property_types.html#string">string</a> |
| xpath query. It is optional. |
| </li> |
| </ul> |
| <p> |
| Each audit event is checked against |
| each <code>suppress</code> and <code>suppress-xpath</code> element. It is |
| suppressed if all specified attributes match against the audit |
| event. |
| </p> |
| <p> |
| The following suppressions XML document directs |
| a <code>SuppressionXpathFilter</code> to |
| reject <code>CyclomaticComplexity</code> errors for |
| all methods with name <i>sayHelloWorld</i> inside <i>FileOne</i> |
| and <i>FileTwo</i> classes: |
| </p> |
| <source> |
| <?xml version="1.0"?> |
| |
| <!DOCTYPE suppressions PUBLIC |
| "-//Puppy Crawl//DTD Suppressions Xpath Experimental 1.2//EN" |
| "http://checkstyle.sourceforge.net/dtds/suppressions_1_2_xpath_experimental.dtd"> |
| |
| <suppressions> |
| <suppress-xpath checks="CyclomaticComplexity" |
| files="FileOne.java,FileTwo.java" |
| query="//METHOD_DEF[@text='sayHelloWorld']"/> |
| </suppressions> |
| </source> |
| <p> |
| Suppress checks for package definitions: |
| </p> |
| <source> |
| <suppress-xpath checks=".*" query="/PACKAGE_DEF"/> |
| </source> |
| <p> |
| Suppress checks for parent element of the first variable definition: |
| </p> |
| <source> |
| <suppress-xpath checks=".*" query="(//VARIABLE_DEF)[1]/.."/> |
| </source> |
| <p> |
| Suppress checks for elements which are either class definitions, |
| either method definitions. |
| </p> |
| <source> |
| <suppress-xpath checks=".*" query="//CLASS_DEF | //METHOD_DEF"/> |
| </source> |
| <p> |
| Suppress checks for certain methods: |
| </p> |
| <source> |
| <suppress-xpath checks=".*" query="//METHOD_DEF[@text='getSomeVar' |
| or @text='setSomeVar']"/> |
| </source> |
| <p> |
| Suppress checks for variable <i>testVariable</i> inside <i>testMethod</i> method |
| inside <i>TestClass</i> class. |
| </p> |
| <source> |
| <suppress-xpath checks=".*" query="/CLASS_DEF[@text='TestClass'] |
| //METHOD_DEF[@text='testMethod']//VARIABLE_DEF[@text='testVariable']"/> |
| </source> |
| </subsection> |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SuppressionXpathFilter"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| <subsection name="Package"> |
| <p> com.puppycrawl.tools.checkstyle.filters </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> <a href="config.html#TreeWalker">TreeWalker</a> </p> |
| </subsection> |
| </section> |
| |
| <section name="SuppressWarningsFilter"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 5.7</p> |
| <p> |
| Filter <code>SuppressWarningsFilter</code> uses annotations to |
| suppress audit events. |
| </p> |
| <p> |
| Rationale: Same as for |
| <code>SuppressionCommentFilter</code>. In the contrary to it |
| here, comments are not used comments but the builtin syntax of |
| <code>@SuppressWarnings</code>. This can be perceived as a |
| more elegant solution than using comments. Also this approach |
| maybe supported by various IDE. |
| </p> |
| <p> |
| Usage: This filter only works in conjunction with a |
| <a href="config_annotation.html#SuppressWarningsHolder">SuppressWarningsHolder</a>, since that check finds |
| the annotations in the Java files and makes them available for |
| the filter. Because of that, a configuration that includes |
| this filter must also include |
| <code>SuppressWarningsHolder</code> as a child module of the |
| <code>TreeWalker</code>. Name of check in annotation is case-insensitive |
| and should be written with any dotted prefix or "Check" suffix removed. |
| </p> |
| </subsection> |
| <subsection name="Examples"> |
| <p> |
| To configure the check that makes tha annotations available to |
| the filter. |
| </p> |
| <source> |
| <module name="TreeWalker"> |
| ... |
| <module name="SuppressWarningsHolder" /> |
| ... |
| </module> |
| </source> |
| <p>To configure filter to suppress audit events for annotations add:</p> |
| <source> |
| <module name="SuppressWarningsFilter" /> |
| </source> |
| <source> |
| @SuppressWarnings({"memberName"}) |
| private int J; // should NOT fail MemberNameCheck |
| |
| @SuppressWarnings({"MemberName"}) |
| @SuppressWarnings({"NoWhitespaceAfter"}) |
| private int [] ARRAY; // should NOT fail MemberNameCheck and NoWhitespaceAfterCheck |
| </source> |
| <p> |
| It is possible to specify an ID of checks, so that it can be leveraged by the |
| SuppressWarningsFilter to skip validations. The following examples show how to skip |
| validations near code that has <code>@SuppressWarnings("checkstyle:<ID>")</code> or |
| just <code>@SuppressWarnings("<ID>")</code> annotation, where ID is the ID of checks |
| you want to suppress. |
| </p> |
| <p> |
| Example of Checkstyle check configuration: |
| </p> |
| <source> |
| <module name="RegexpSinglelineJava"> |
| <property name="id" value="systemout"/> |
| <property name="format" value="^.*System\.(out|err).*$"/> |
| <property name="message" value="Don't use System.out/err, use SLF4J instead."/> |
| </module> |
| </source> |
| <p> |
| To make the annotations available to the filter. |
| </p> |
| <source> |
| <module name="TreeWalker"> |
| ... |
| <module name="SuppressWarningsHolder" /> |
| ... |
| </module> |
| </source> |
| <p> |
| To configure filter to suppress audit events for annotations add: |
| </p> |
| <source> |
| <module name="SuppressWarningsFilter" /> |
| </source> |
| <source> |
| @SuppressWarnings("checkstyle:systemout") |
| public static void foo() { |
| System.out.println("Debug info."); // should NOT fail RegexpSinglelineJava |
| } |
| </source> |
| </subsection> |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SuppressWarningsFilter"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| <subsection name="Package"> |
| <p> com.puppycrawl.tools.checkstyle.filters </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> <a href="config.html#Checker">Checker</a> </p> |
| </subsection> |
| </section> |
| |
| <section name="SuppressWithNearbyCommentFilter"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 5.0</p> |
| <p> |
| Filter <code>SuppressWithNearbyCommentFilter</code> uses |
| individual comments to suppress audit events. |
| </p> |
| <p> |
| Rationale: Same as <code>SuppressionCommentFilter</code>. |
| Whereas the SuppressionCommentFilter uses matched pairs of |
| filters to turn on/off comment matching, |
| <code>SuppressWithNearbyCommentFilter</code> uses |
| single comments. This requires fewer lines to mark a region, and |
| may be aesthetically preferable in some contexts. |
| </p> |
| </subsection> |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>commentFormat</td> |
| <td>comment pattern to trigger filter to begin suppression</td> |
| <td><a href="property_types.html#regexp">Regular Expression</a></td> |
| <td><code>"SUPPRESS CHECKSTYLE (\w+)"</code></td> |
| <td>5.0</td> |
| </tr> |
| <tr> |
| <td>checkFormat</td> |
| <td>check pattern to suppress</td> |
| <td><a href="property_types.html#regexp">Regular Expression</a></td> |
| <td><code>".*"</code></td> |
| <td>5.0</td> |
| </tr> |
| <tr> |
| <td>messageFormat</td> |
| <td>message pattern to suppress</td> |
| <td><a href="property_types.html#regexp">Regular Expression</a></td> |
| <td><code>null</code></td> |
| <td>5.0</td> |
| </tr> |
| <tr> |
| <td>influenceFormat</td> |
| <td>a negative/zero/positive value that defines the number of |
| lines preceding/at/following the suppression comment</td> |
| <td><a href="property_types.html#regexp">Regular Expression</a></td> |
| <td><code>"0"</code></td> |
| <td>5.0</td> |
| </tr> |
| <tr> |
| <td>checkCPP</td> |
| <td>whether to check C++ style comments (<code>//</code>)</td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td><code>true</code></td> |
| <td>5.0</td> |
| </tr> |
| <tr> |
| <td>checkC</td> |
| <td>whether to check C style comments (<code>/* ... */</code>)</td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td><code>true</code></td> |
| <td>5.0</td> |
| </tr> |
| </table> |
| </subsection> |
| <subsection name="Examples"> |
| <p> |
| To configure a filter to suppress audit events for <i>check</i> |
| on any line with a comment <code>SUPPRESS CHECKSTYLE <i>check</i></code>: |
| </p> |
| <source> |
| <module name="SuppressWithNearbyCommentFilter"/> |
| </source> |
| <source> |
| private int [] array; // SUPPRESS CHECKSTYLE |
| </source> |
| <p> |
| To configure a filter to suppress all audit events on any line |
| containing the comment <code>CHECKSTYLE IGNORE THIS LINE</code>: |
| </p> |
| <source> |
| <module name="SuppressWithNearbyCommentFilter"> |
| <property name="commentFormat" value="CHECKSTYLE IGNORE THIS LINE"/> |
| <property name="checkFormat" value=".*"/> |
| <property name="influenceFormat" value="0"/> |
| </module> |
| </source> |
| <source> |
| public static final int lowerCaseConstant; // CHECKSTYLE IGNORE THIS LINE |
| </source> |
| <p> |
| To configure a filter so that |
| <code>// OK to catch (Throwable|Exception|RuntimeException) here</code> |
| permits the current and previous line to avoid generating an IllegalCatch |
| audit event: |
| </p> |
| <source> |
| <module name="SuppressWithNearbyCommentFilter"> |
| <property name="commentFormat" value="OK to catch (\w+) here"/> |
| <property name="checkFormat" value="IllegalCatchCheck"/> |
| <property name="messageFormat" value="$1"/> |
| <property name="influenceFormat" value="-1"/> |
| </module> |
| </source> |
| <source> |
| . . . |
| catch (RuntimeException re) { |
| // OK to catch RuntimeException here |
| } |
| catch (Throwable th) { ... } |
| . . . |
| </source> |
| <p> |
| To configure a filter so that <code>CHECKSTYLE IGNORE <i>check</i> FOR NEXT <i>var</i> LINES</code> |
| avoids triggering any audits for the given check for the current line and the next <i>var</i> lines |
| (for a total of <i>var</i>+1 lines): |
| </p> |
| <source> |
| <module name="SuppressWithNearbyCommentFilter"> |
| <property name="commentFormat" value="CHECKSTYLE IGNORE (\w+) FOR NEXT (\d+) LINES"/> |
| <property name="checkFormat" value="$1"/> |
| <property name="influenceFormat" value="$2"/> |
| </module> |
| </source> |
| <source> |
| public static final int lowerCaseConstant; // CHECKSTYLE IGNORE ConstantNameCheck FOR NEXT 3 LINES |
| public static final int lowerCaseConstant1; |
| public static final int lowerCaseConstant2; |
| public static final int lowerCaseConstant3; |
| public static final int lowerCaseConstant4; // will warn here |
| </source> |
| <p> |
| To configure a filter to avoid any audits on code like: |
| </p> |
| <source> |
| <module name="SuppressWithNearbyCommentFilter"> |
| <property name="commentFormat" value="ALLOW (\\w+) ON PREVIOUS LINE"/> |
| <property name="checkFormat" value="$1"/> |
| <property name="influenceFormat" value="-1"/> |
| </module> |
| </source> |
| <source> |
| private int D2; |
| // ALLOW MemberName ON PREVIOUS LINE |
| . . . |
| </source> |
| <p> |
| To configure a filter to allow suppress one or more Checks(separated by "|") |
| and demand comment no less than 14 symbols: |
| </p> |
| <source> |
| <module name="SuppressWithNearbyCommentFilter"> |
| <property name="commentFormat" value="@cs\.suppress \[(\w+(\|\w+)*)\] \w[-\.'`,:;\w ]{14,}"/> |
| <property name="checkFormat" value="$1"/> |
| <property name="influenceFormat" value="1"/> |
| </module> |
| </source> |
| <source> |
| public static final int [] array; // @cs.suppress [ConstantName|NoWhitespaceAfter] A comment here |
| </source> |
| <p> |
| It is possible to specify an ID of checks, so that it can be leveraged by the |
| SuppressWithNearbyCommentFilter to skip validations. The following examples |
| show how to skip validations near code that has comment like |
| <code>// @cs-: <ID/> (reason)</code>, where ID is the ID of checks you want to |
| suppress. |
| </p> |
| <p> |
| Examples of Checkstyle checks configuration: |
| </p> |
| <source> |
| <module name="RegexpSinglelineJava"> |
| <property name="id" value="ignore"/> |
| <property name="format" value="^.*@Ignore\s*$"/> |
| <property name="message" value="@Ignore should have a reason."/> |
| </module> |
| |
| <module name="RegexpSinglelineJava"> |
| <property name="id" value="systemout"/> |
| <property name="format" value="^.*System\.(out|err).*$"/> |
| <property name="message" value="Don't use System.out/err, use SLF4J instead."/> |
| </module> |
| </source> |
| <p> |
| Example of SuppressWithNearbyCommentFilter configuration (checkFormat which |
| is set to '$1' points that ID of the checks is in the first group of |
| commentFormat regular expressions): |
| </p> |
| <source> |
| <module name="SuppressWithNearbyCommentFilter"> |
| <property name="commentFormat" value="@cs-: (\w+) \(\w+\)"/> |
| <property name="checkFormat" value="$1"/> |
| <property name="influenceFormat" value="0"/> |
| </module> |
| </source> |
| <source> |
| @Ignore // @cs-: ignore (test has not been implemented yet) |
| @Test |
| public void testMethod() { } |
| |
| public static void foo() { |
| System.out.println("Debug info."); // @cs-: systemout (should not fail RegexpSinglelineJava) |
| } |
| </source> |
| <p> |
| Example of how to configure the check to suppress more than one checks. |
| The influence format format is specified in the second regexp group. |
| </p> |
| <source> |
| <module name="SuppressWithNearbyCommentFilter"> |
| <property name="commentFormat" value="@cs-\: ([\w\|]+) influence (\d+)"/> |
| <property name="checkFormat" value="$1"/> |
| <property name="influenceFormat" value="$2"/> |
| </module> |
| </source> |
| <source> |
| // @cs-: ClassDataAbstractionCoupling influence 2 |
| // @cs-: MagicNumber influence 4 |
| @Service // no violations from ClassDataAbstractionCoupling here |
| @Transactional |
| public class UserService { |
| private int value = 10022; // no violations from MagicNumber here |
| } |
| </source> |
| </subsection> |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SuppressWithNearbyCommentFilter"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| <subsection name="Package"> |
| <p> com.puppycrawl.tools.checkstyle.filters </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> <a href="config.html#TreeWalker">TreeWalker</a> </p> |
| </subsection> |
| </section> |
| </body> |
| </document> |
