Filter files may be used to include or exclude bug reports for particular classes and methods. This chapter explains how to use filter files.
Conceptually, a filter matches bug instances against a set of criteria. By defining a filter, you can select bug instances for special treatment; for example, to exclude or include them in a report.
A filter file is an XML document with a top-level FindBugsFilter
element which has some number of Match elements as children. Each Match element represents a predicate which is applied to generated bug instances. Usually, a filter will be used to exclude bug instances. For example:
$ spotbugs -textui -exclude myExcludeFilter.xml myApp.jar
However, a filter could also be used to select bug instances to specifically report:
$ spotbugs -textui -include myIncludeFilter.xml myApp.jar
Match
elements contain children, which are conjuncts of the predicate. In other words, each of the children must be true
for the predicate to be true
.
This element specifies a particular bug pattern or patterns to match. The
patternattribute is a comma-separated list of bug pattern types. You can find the bug pattern types for particular warnings by looking at the output produced by the **-xml** output option (the type attribute of BugInstance elements), or from the :doc:`bugDescriptions`. For more coarse-grained matching, use
codeattribute. It takes a comma-separated list of bug abbreviations. For most-coarse grained matching use
categoryattriute, that takes a comma separated list of bug category names:
CORRECTNESS,
MT_CORRECTNESS,
BAD_PRACTICICE,
PERFORMANCE,
STYLE. If more than one of the attributes mentioned above are specified on the same <Bug> element, all bug patterns that match either one of specified pattern names, or abreviations, or categories will be matched. As a backwards compatibility measure, <BugPattern> and <BugCode> elements may be used instead of <Bug> element. Each of these uses a name attribute for specifying accepted values list. Support for these elements may be removed in a future release. <Confidence> ^^^^^^^^^^^^ This element matches warnings with a particular bug confidence. The
valueattribute should be an integer value: 1 to match high-confidence warnings, 2 to match normal-confidence warnings, or 3 to match low-confidence warnings.
<Confidence>replaced
<Priority>in 2.0.0 release. <Priority> ^^^^^^^^^^ Same as
<Confidence>, exists for backward compatibility. <Rank> ^^^^^^ This element matches warnings with a particular bug rank. The
valueattribute should be an integer value between 1 and 20, where 1 to 4 are scariest, 5 to 9 scary, 10 to 14 troubling, and 15 to 20 of concern bugs. <Package> ^^^^^^^^^ This element matches warnings associated with classes within the package specified using
nameattribute. Nested packages are not included (along the lines of Java import statement). However matching multiple packages can be achieved easily using regex name match. <Class> ^^^^^^^ This element matches warnings associated with a particular class. The
nameattribute is used to specify the exact or regex match pattern for the class name. The
roleattribute is the class role. As a backward compatibility measure, instead of element of this type, you can use
classattribute on a
Matchelement to specify exact an class name or
classregexattribute to specify a regular expression to match the class name against. If the
Matchelement contains neither a
Classelement, nor a
class/
classregexattribute, the predicate will apply to all classes. Such predicate is likely to match more bug instances than you want, unless it is refined further down with appropriate method or field predicates. <Source> ^^^^^^^^ This element matches warnings associated with a particular source file. The
nameattribute is used to specify the exact or regex match pattern for the source file name. <Method> ^^^^^^^^ This element specifies a method. The
nameattribute is used to specify the exact or regex match pattern for the method name. The
paramsattribute is a comma-separated list of the types of the method's parameters. The
returnsattribute is the method's return type. The
roleattribute is the method role. In
paramsand
returns, class names must be fully qualified. (E.g.,
"java.lang.String"instead of just
"String".) If one of the latter attributes is specified the other is required for creating a method signature. Note that you can provide either
nameattribute or
paramsand
returnsattributes or all three of them. This way you can provide various kinds of name and signature based matches. <Field> ^^^^^^^ This element specifies a field. The
nameattribute is used to specify the exact or regex match pattern for the field name. You can also filter fields according to their signature - use
typeattribute to specify fully qualified type of the field. You can specify either or both of these attributes in order to perform name / signature based matches. The
roleattribute is the field role. <Local> ^^^^^^^ This element specifies a local variable. The
nameattribute is used to specify the exact or regex match pattern for the local variable name. Local variables are variables defined within a method. <Type> ^^^^^^ This element matches warnings associated with a particular type. The
descriptorattribute is used to specify the exact or regex match pattern for type descriptor. If the descriptor starts with the ~ character the rest of attribute content is interpreted as a Java regular expression. The
roleattribute is the class role, and the
typeParametersis the type parameters. Both of
roleand
typeParametersare optional attributes. <Or> ^^^^ This element combines
Matchclauses as disjuncts. I.e., you can put two
Methodelements in an
Orclause in order to match either method. <And> ^^^^^ This element combines
Matchclauses which both must evaluate to
true. I.e., you can put
Bugand
Confidenceelements in an
Andclause in order to match specific bugs with given confidence only. <Not> ^^^^^ This element inverts the included child
Match. I.e., you can put a
Bugelement in a
Notclause in order to match any bug excluding the given one. Java element name matching -------------------------- If the
nameattribute of
Class,
Source,
Methodor
Fieldstarts with the
~character the rest of attribute content is interpreted as a Java regular expression that is matched against the names of the Java element in question. Note that the pattern is matched against whole element name and therefore
.*clauses need to be used at pattern beginning and/or end to perform substring matching. See `java.util.regex.Pattern <https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html>`_ documentation for pattern syntax. Caveats -------
Matchclauses can only match information that is actually contained in the bug instances. Every bug instance has a class, so in general, excluding bugs by class will work. Some bug instances have two (or more) classes. For example, the DE (dropped exception) bugs report both the class containing the method where the dropped exception happens, and the class which represents the type of the dropped exception. Only the *first* (primary) class is matched against
Matchclauses. So, for example, if you want to suppress IC (initialization circularity) reports for classes "com.foobar.A" and "com.foobar.B", you would use two
Match`` clauses:
<Match>
<Class name="com.foobar.A" />
<Bug code="IC" />
</Match>
<Match>
<Class name="com.foobar.B" />
<Bug code="IC" />
</Match>
By explicitly matching both classes, you ensure that the IC bug instance will be matched regardless of which class involved in the circularity happens to be listed first in the bug instance. (Of course, this approach might accidentally supress circularities involving "com.foobar.A" or "com.foobar.B" and a third class.)
Many kinds of bugs report what method they occur in. For those bug instances, you can put Method clauses in the Match element and they should work as expected.
<Match>
<Class name="com.foobar.MyClass" />
</Match>
<Match>
<Class name="com.foobar.MyClass"/ >
<Bug code="DE,UrF,SIC" />
</Match>
<Match>
<Bug code="DE,UrF,SIC" />
</Match>
<Match>
<Bug category="PERFORMANCE" />
</Match>
<Match>
<Class name="com.foobar.MyClass" />
<Or>
<Method name="frob" params="int,java.lang.String" returns="void" />
<Method name="blat" params="" returns="boolean" />
</Or>
<Bug code="DC" />
</Match>
<!-- A method with an open stream false positive. -->
<Match>
<Class name="com.foobar.MyClass" />
<Method name="writeDataToFile" />
<Bug pattern="OS_OPEN_STREAM" />
</Match>
<!-- A method with a dead local store false positive (medium priority). -->
<Match>
<Class name="com.foobar.MyClass" />
<Method name="someMethod" />
<Bug pattern="DLS_DEAD_LOCAL_STORE" />
<Priority value="2" />
</Match>
Match minor bugs introduced by AspectJ compiler (you are probably not interested in these unless you are an AspectJ developer)
<Match>
<Class name="~.*\$AjcClosure\d+" />
<Bug pattern="DLS_DEAD_LOCAL_STORE" />
<Method name="run" />
</Match>
<Match>
<Bug pattern="UUF_UNUSED_FIELD" />
<Field name="~ajc\$.*" />
</Match>
<!-- match unused fields warnings in Messages classes in all packages -->
<Match>
<Class name="~.*\.Messages" />
<Bug code="UUF" />
</Match>
<!-- match mutable statics warnings in all internal packages -->
<Match>
<Package name="~.*\.internal" />
<Bug code="MS" />
</Match>
<!-- match anonymoous inner classes warnings in ui package hierarchy -->
<Match>
<Package name="~com\.foobar\.fooproject\.ui.*" />
<Bug pattern="SIC_INNER_SHOULD_BE_STATIC_ANON" />
</Match>
<!-- match System.exit(...) usage warnings in void main(String[]) methods in all classes -->
<Match>
<Method returns="void" name="main" params="java.lang.String[]" />
<Bug pattern="DM_EXIT" />
</Match>
<!-- match UuF warnings on fields of type com.foobar.DebugInfo on all classes -->
<Match>
<Field type="com.foobar.DebugInfo" />
<Bug code="UuF" />
</Match>
<!-- ignore all bugs in test classes, except for those bugs specifically relating to JUnit tests -->
<!-- i.e. filter bug if ( classIsJUnitTest && ! bugIsRelatedToJUnit ) -->
<Match>
<!-- the Match filter is equivalent to a logical 'And' -->
<Class name="~.*\.*Test" />
<!-- test classes are suffixed by 'Test' -->
<Not>
<Bug code="IJU" /> <!-- 'IJU' is the code for bugs related to JUnit test code -->
</Not>
</Match>
<?xml version="1.0" encoding="UTF-8"?>
<FindBugsFilter>
<Match>
<Source name="~.*\.groovy" />
</Match>
</FindBugsFilter>
<?xml version="1.0" encoding="UTF-8"?>
<FindBugsFilter
xmlns="https://github.com/spotbugs/filter/3.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://github.com/spotbugs/filter/3.0.0 https://raw.githubusercontent.com/spotbugs/spotbugs/3.1.0/spotbugs/etc/findbugsfilter.xsd">
<Match>
<Class name="com.foobar.ClassNotToBeAnalyzed" />
</Match>
<Match>
<Class name="com.foobar.ClassWithSomeBugsMatched" />
<Bug code="DE,UrF,SIC" />
</Match>
<!-- Match all XYZ violations. -->
<Match>
<Bug code="XYZ" />
</Match>
<!-- Match all doublecheck violations in these methods of "AnotherClass". -->
<Match>
<Class name="com.foobar.AnotherClass" />
<Or>
<Method name="nonOverloadedMethod" />
<Method name="frob" params="int,java.lang.String" returns="void" />
<Method name="blat" params="" returns="boolean" />
</Or>
<Bug code="DC" />
</Match>
<!-- A method with a dead local store false positive (medium priority). -->
<Match>
<Class name="com.foobar.MyClass" />
<Method name="someMethod" />
<Bug pattern="DLS_DEAD_LOCAL_STORE" />
<Priority value="2" />
</Match>
<!-- All bugs in test classes, except for JUnit-specific bugs -->
<Match>
<Class name="~.*\.*Test" />
<Not>
<Bug code="IJU" />
</Not>
</Match>
</FindBugsFilter>