Class SuppressionFilter
- All Implemented Interfaces:
Configurable
,Contextualizable
,ExternalResourceHolder
,Filter
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.
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 asid
ormessage
is specified. -
message
- a Pattern matched against the message of the check associated with an audit event. Optional as long aschecks
orid
is specified. -
id
- a String matched against the check id associated with an audit event. Optional as long aschecks
ormessage
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 dependant 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://
orhttps://
, 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.
-
Property
file
- Specify the location of the suppressions XML document file. Type isjava.lang.String
. Default value isnull
. -
Property
optional
- Control what to do when the file is not existing. Ifoptional
is set tofalse
the file must exist, or else it ends with error. On the other hand if optional istrue
and file is not found, the filter accept all audit events. Type isboolean
. Default value isfalse
.
For example, the following configuration fragment directs the Checker to use
a SuppressionFilter
with suppressions file config/suppressions.xml
:
<module name="SuppressionFilter"> <property name="file" value="config/suppressions.xml"/> <property name="optional" value="false"/> </module>
The following suppressions XML document directs a SuppressionFilter
to
reject JavadocStyleCheck
violations for lines 82 and 108 to 122 of file
AbstractComplexityCheck.java
, and MagicNumberCheck
violations for
line 221 of file JavadocStyleCheck.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="JavadocStyleCheck" files="AbstractComplexityCheck.java" lines="82,108-122"/> <suppress checks="MagicNumberCheck" files="JavadocStyleCheck.java" lines="221"/> <suppress message="Missing a Javadoc comment"/> </suppressions>
Suppress check by module id when config have two instances on the same check:
<suppress id="stringEqual" files="SomeTestCode.java"/>
Suppress all checks for hidden files and folders:
<suppress files="[/\\]\..+" checks=".*"/>
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"/>
Suppress naming violations on variable named 'log' in all files:
<suppress message="Name 'log' must match pattern"/>
Parent is com.puppycrawl.tools.checkstyle.Checker
- Since:
- 3.2
-
Nested Class Summary
Nested classes/interfaces inherited from class com.puppycrawl.tools.checkstyle.api.AutomaticBean
AutomaticBean.OutputStreamOptions
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionboolean
accept
(AuditEvent event) Determines whether or not a filtered AuditEvent is accepted.protected void
Provides a hook to finish the part of this component's setup that was not handled by the bean introspection.Returns a set of external configuration resource locations which are used by the module.void
Setter to specify the location of the suppressions XML document file.void
setOptional
(boolean optional) Setter to control what to do when the file is not existing.Methods inherited from class com.puppycrawl.tools.checkstyle.api.AutomaticBean
configure, contextualize, getConfiguration, setupChild
-
Constructor Details
-
SuppressionFilter
public SuppressionFilter()
-
-
Method Details
-
setFile
Setter to specify the location of the suppressions XML document file.- Parameters:
fileName
- name of the suppressions file.
-
setOptional
public void setOptional(boolean optional) Setter to control what to do when the file is not existing. Ifoptional
is set tofalse
the file must exist, or else it ends with error. On the other hand if optional istrue
and file is not found, the filter accept all audit events.- Parameters:
optional
- tells if config file existence is optional.
-
accept
Description copied from interface:Filter
Determines whether or not a filtered AuditEvent is accepted. -
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 classAutomaticBean
- Throws:
CheckstyleException
- if there is a configuration error.
-
getExternalResourceLocations
Description copied from interface:ExternalResourceHolder
Returns a set of external configuration resource locations which are used by the module. ATTENTION! If 'getExternalResourceLocations()' return null, there will beNullPointerException
inChecker
. Such behaviour will signal that your module (check or filter) is designed incorrectly. It make sense to return an empty set from 'getExternalResourceLocations()' only for composite modules likeTreeWalker
.- Specified by:
getExternalResourceLocations
in interfaceExternalResourceHolder
- Returns:
- a set of external configuration resource locations which are used by the module.
-