Home | History | Annotate | Download | only in doc 
      1 =============
      2 How it works:
      3 =============
      4 
      5 A filter file is an XML file with a top-level "FindBugsFilter" element
      6 which has some number of "Match" elements as children.  Each Match
      7 element represents a predicate which is applied to generated bug instances.
      8 Usually, a filter will be used to exclude bug instances.  For example:
      9 
     10   findbugs -textui -exclude myExcludeFilter.xml myApp.jar
     11 
     12 However, a filter could also be used to select bug instances to specifically
     13 report:
     14 
     15   findbugs -textui -include myIncludeFilter.xml myApp.jar
     16 
     17 Match has "class" and "classregex" attributes specifying what class or classes
     18 the predicate applies to.
     19 
     20 Match contains children, which are conjuncts of the predicate.
     21 (I.e., each of the children must be true for the predicate to be true.)
     22 
     23 =======================
     24 Types of Match clauses:
     25 =======================
     26 
     27    <BugCode> specifies abbreviations of bugs.
     28    The "name" attribute is a comma-seperated list of abbreviations.
     29 
     30    <Method> specifies a method.  The "name" attribute is the name
     31    of the method.  The "params" attribute is a comma separated list
     32    of the types of the method's parameters.  The "returns" attribute is
     33    the method's return type.  In "params" and "returns", class names
     34    must be fully qualified.  (E.g., "java.lang.String" instead of just
     35    "String".)  Note that "params" and "returns" are optional; you can
     36    just specify "name", and the clause will match all methods with
     37    that name.  However, if you specify either "params" or "returns",
     38    you must specify both of them.
     39 
     40    <Or> combines Match clauses as disjuncts.  I.e., you can put two
     41    "Method" elements in an Or clause in order match either method.
     42 
     43 ========
     44 Caveats:
     45 ========
     46 
     47 Match clauses can only match information that is actually contained in the
     48 bug instances.  Every bug instance has a class, so in general, excluding
     49 bugs by class will work.
     50 
     51 Some bug instances have two classes.  For example, the DE (dropped exception)
     52 bugs report both the class containing the method where the dropped exception
     53 happens, and the class which represents the type of the dropped exception.
     54 Only the FIRST (primary) class is matched against Match clauses.
     55 So, for example, if you want to suppress IC (initialization circularity)
     56 reports for classes "com.foobar.A" and "com.foobar.B", you would use
     57 two Match clauses:
     58 
     59    <Match class="com.foobar.A">
     60       <BugCode name="IC" />
     61    </Match>
     62 
     63    <Match class="com.foobar.B">
     64       <BugCode name="IC" />
     65    </Match>
     66 
     67 Many kinds of bugs report what method they occur in.  For those bug instances,
     68 you can put Method clauses in the Match element and they should work
     69 as expected.
     70 
     71 =========
     72 Examples:
     73 =========
     74 
     75   1. Match all bug reports for a class.
     76 
     77      <Match class="com.foobar.MyClass" />
     78 
     79   2. Match certain tests from a class.
     80      <Match class="com.foobar.MyClass">
     81        <BugCode name="DE,UrF,SIC" />
     82      </Match>
     83 
     84   3. Match certain tests from all classes.
     85 
     86      <Match classregex=".*" >
     87        <BugCode name="DE,UrF,SIC" />
     88      </Match>
     89 
     90   4. Match bug types from specified methods of a class.
     91 
     92      <Match class="com.foobar.MyClass">
     93        <Or>
     94          <Method name="frob" params="int,java.lang.String" returns="void" />
     95          <Method name="blat" params="" returns="boolean" />
     96        </Or>
     97        <BugCode name="DC" />
     98      </Match>
     99 
    100 =================
    101 Complete Example:
    102 =================
    103 
    104 <FindBugsFilter>
    105      <Match class="com.foobar.ClassNotToBeAnalyzed" />
    106 
    107      <Match class="com.foobar.ClassWithSomeBugsMatched">
    108        <BugCode name="DE,UrF,SIC" />
    109      </Match>
    110 
    111      <!-- Match all XYZ violations. -->
    112      <Match classregex=".*" >
    113        <BugCode name="XYZ" />
    114      </Match>
    115 
    116      <!-- Match all doublecheck violations in these methods of "AnotherClass". -->
    117      <Match class="com.foobar.AnotherClass">
    118        <Or>
    119          <Method name="nonOverloadedMethod" />
    120          <Method name="frob" params="int,java.lang.String" returns="void" />
    121          <Method name="blat" params="" returns="boolean" />
    122        </Or>
    123        <BugCode name="DC" />
    124      </Match>
    125 </FindBugsFilter>
    126