Table of Contents
Filter files may be used to include or exclude bug reports for particular classes and methods. This chapter explains how to use filter files.
![]() | Planned Features |
---|---|
Filters are currently only supported by the Command Line interface. Eventually, filter support will be added to the GUI. |
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:
$ findbugs -textui -exclude myExcludeFilter.xml myApp.jar
However, a filter could also be used to select bug instances to specifically report:
$ findbugs -textui -include myIncludeFilter.xml myApp.jar
Match elements have class and classregex attributes specifying what class or classes the predicate applies to. The class attribute specifies the name of a class. The classregex attribute specifies a regular expression applied to class names of bug instances. The regular expression is used to create a java.util.regex.Pattern object, which does the matching. 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 abbreviations of bugs. The name attribute is a comma-seperated list of abbreviations.
This element specifies a particular bug pattern or bug patterns to match. The name attribute 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 bug descriptions document.
This element matches warnings with a particular priority. The value attribute should be an integer value: 1 to match high-priority warnings, 2 to match medium-priority warnings, or 3 to match low-priority warnings.
This element specifies a method. The name attribute is the name of the method. The params attribute is a comma separated list of the types of the method's parameters. The returns attribute is the method's return type. In params and returns, class names must be fully qualified. (E.g., "java.lang.String" instead of just "String".) Note that params and returns are optional; you can just specify name, and the clause will match all methods with that name. However, if you specify either params or returns, you must specify both of them.
This element combines Match clauses as disjuncts. I.e., you can put two Method elements in an Or clause in order match either method.
Match clauses 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 Match clauses. 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="com.foobar.A"> <BugCode name="IC" /> </Match> <Match class="com.foobar.B"> <BugCode name="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.
1. Match all bug reports for a class.
<Match class="com.foobar.MyClass" />
2. Match certain tests from a class by specifying their abbreviations.
<Match class="com.foobar.MyClass"> <BugCode name="DE,UrF,SIC" /> </Match>
3. Match certain tests from all classes by specifying their abbreviations.
<Match classregex=".*" > <BugCode name="DE,UrF,SIC" /> </Match>
4. Match bug types from specified methods of a class by their abbreviations.
<Match class="com.foobar.MyClass"> <Or> <Method name="frob" params="int,java.lang.String" returns="void" /> <Method name="blat" params="" returns="boolean" /> </Or> <BugCode name="DC" /> </Match>
4. Match a particular bug pattern in a particular method.
<!-- A method with an open stream false positive. --> <Match class="com.foobar.MyClass"> <Method name="writeDataToFile"/> <BugPattern name="OS_OPEN_STREAM"/> </Match>
5. Match a particular bug pattern with a given priority in a particular method.
<!-- A method with a dead local store false positive (medium priority). --> <Match class="com.foobar.MyClass"> <Method name="someMethod"/> <BugPattern name="DLS_DEAD_LOCAL_STORE"/> <Priority value="2"/> </Match>
<FindBugsFilter> <Match class="com.foobar.ClassNotToBeAnalyzed" /> <Match class="com.foobar.ClassWithSomeBugsMatched"> <BugCode name="DE,UrF,SIC" /> </Match> <!-- Match all XYZ violations. --> <Match classregex=".*" > <BugCode name="XYZ" /> </Match> <!-- Match all doublecheck violations in these methods of "AnotherClass". --> <Match class="com.foobar.AnotherClass"> <Or> <Method name="nonOverloadedMethod" /> <Method name="frob" params="int,java.lang.String" returns="void" /> <Method name="blat" params="" returns="boolean" /> </Or> <BugCode name="DC" /> </Match> <!-- A method with a dead local store false positive (medium priority). --> <Match class="com.foobar.MyClass"> <Method name="someMethod"/> <BugPattern name="DLS_DEAD_LOCAL_STORE"/> <Priority value="2"/> </Match> </FindBugsFilter>