Chapter 8. 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:

$ 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 contain children, which are conjuncts of the predicate. In other words, each of the children must be true for the predicate to be true.

If the name attribute of Class, Source, Method or Field starts 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 documentation for pattern syntax.

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 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.

1. Match all bug reports for a class.

     <Match>
       <Class name="com.foobar.MyClass" />
     </Match>

2. Match certain tests from a class by specifying their abbreviations.

     <Match>
       <Class name="com.foobar.MyClass"/ >
       <Bug code="DE,UrF,SIC" />
     </Match>

3. Match certain tests from all classes by specifying their abbreviations.

     <Match>
       <Bug code="DE,UrF,SIC" />
     </Match>

4. Match certain tests from all classes by specifying their category.

     <Match>
       <Bug category="PERFORMANCE" />
     </Match>

5. Match bug types from specified methods of a class by their abbreviations.

     <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>

6. Match a particular bug pattern in a particular method.

    <!-- A method with an open stream false positive. -->
    <Match>
      <Class name="com.foobar.MyClass" />
      <Method name="writeDataToFile" />
      <Bug pattern="OS_OPEN_STREAM" />
    </Match>

7. 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 name="com.foobar.MyClass" />
      <Method name="someMethod" />
      <Bug pattern="DLS_DEAD_LOCAL_STORE" />
      <Priority value="2" />
    </Match>

8. 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>

9. Match bugs in specific parts of the code base

    <!-- 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>

10. Match bugs on fields or methods with specific signatures

    <!-- 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>

11. Match bugs using the Not filter operator

<!-- 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>

12. Full exclusion filter file to match all classes generated from Groovy source files.

<?xml version="1.0" encoding="UTF-8"?>
<FindBugsFilter>
<Match>
    <Source name="~.*\.groovy" />
</Match>
</FindBugsFilter>

<FindBugsFilter>
     <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>