| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>Chapter 8. Filter Files</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="FindBugs™ Manual"><link rel="up" href="index.html" title="FindBugs™ Manual"><link rel="prev" href="eclipse.html" title="Chapter 7. Using the FindBugs™ Eclipse plugin"><link rel="next" href="analysisprops.html" title="Chapter 9. Analysis Properties"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 8. Filter Files</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="eclipse.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="analysisprops.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 8. Filter Files"><div class="titlepage"><div><div><h2 class="title"><a name="filter"></a>Chapter 8. Filter Files</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="filter.html#d0e1815">1. Introduction to Filter Files</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e1865">2. Types of Match clauses</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e2113">3. Java element name matching</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e2138">4. Caveats</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e2168">5. Examples</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e2226">6. Complete Example</a></span></dt></dl></div><p> |
| Filter files may be used to include or exclude bug reports for particular classes |
| and methods. This chapter explains how to use filter files. |
| |
| </p><div class="note" title="Planned Features" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note: Planned Features"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="note.png"></td><th align="left">Planned Features</th></tr><tr><td align="left" valign="top"><p> |
| Filters are currently only supported by the Command Line interface. |
| Eventually, filter support will be added to the GUI. |
| </p></td></tr></table></div><p> |
| </p><div class="sect1" title="1. Introduction to Filter Files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1815"></a>1. Introduction to Filter Files</h2></div></div></div><p> |
| 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. |
| </p><p> |
| A filter file is an <a class="ulink" href="http://www.w3.org/XML/" target="_top">XML</a> document with a top-level <code class="literal">FindBugsFilter</code> element |
| which has some number of <code class="literal">Match</code> elements as children. Each <code class="literal">Match</code> |
| element represents a predicate which is applied to generated bug instances. |
| Usually, a filter will be used to exclude bug instances. For example: |
| |
| </p><pre class="screen"> |
| <code class="prompt">$ </code><span class="command"><strong>findbugs -textui -exclude <em class="replaceable"><code>myExcludeFilter.xml</code></em> <em class="replaceable"><code>myApp.jar</code></em></strong></span> |
| </pre><p> |
| |
| However, a filter could also be used to select bug instances to specifically |
| report: |
| |
| </p><pre class="screen"> |
| <code class="prompt">$ </code><span class="command"><strong>findbugs -textui -include <em class="replaceable"><code>myIncludeFilter.xml</code></em> <em class="replaceable"><code>myApp.jar</code></em></strong></span> |
| </pre><p> |
| </p><p> |
| <code class="literal">Match</code> 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. |
| </p></div><div class="sect1" title="2. Types of Match clauses"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1865"></a>2. Types of Match clauses</h2></div></div></div><div class="variablelist"><dl><dt><span class="term"><code class="literal"><Bug></code></span></dt><dd><p> |
| This element specifies a particular bug pattern or patterns to match. |
| The <code class="literal">pattern</code> 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 <span class="command"><strong>-xml</strong></span> |
| output option (the <code class="literal">type</code> attribute of <code class="literal">BugInstance</code> |
| elements), or from the <a class="ulink" href="../bugDescriptions.html" target="_top">bug |
| descriptions document</a>. |
| </p><p> |
| For more coarse-grained matching, use <code class="literal">code</code> attribute. It takes |
| a comma-separated list of bug abbreviations. For most-coarse grained matching use |
| <code class="literal">category</code> attriute, that takes a comma separated list of bug category names: |
| <code class="literal">CORRECTNESS</code>, <code class="literal">MT_CORRECTNESS</code>, |
| <code class="literal">BAD_PRACTICICE</code>, <code class="literal">PERFORMANCE</code>, <code class="literal">STYLE</code>. |
| </p><p> |
| If more than one of the attributes mentioned above are specified on the same |
| <code class="literal"><Bug></code> element, all bug patterns that match either one of specified |
| pattern names, or abreviations, or categories will be matched. |
| </p><p> |
| As a backwards compatibility measure, <code class="literal"><BugPattern></code> and |
| <code class="literal"><BugCode></code> elements may be used instead of |
| <code class="literal"><Bug></code> element. Each of these uses a |
| <code class="literal">name</code> attribute for specifying accepted values list. Support for these |
| elements may be removed in a future release. |
| </p></dd><dt><span class="term"><code class="literal"><Confidence></code></span></dt><dd><p> |
| This element matches warnings with a particular bug confidence. |
| The <code class="literal">value</code> attribute 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. |
| </p></dd><dt><span class="term"><code class="literal"><Priority></code></span></dt><dd><p> |
| Same as <code class="literal"><Confidence></code>, exists for backward compatibility. |
| </p></dd><dt><span class="term"><code class="literal"><Rank></code></span></dt><dd><p> |
| This element matches warnings with a particular bug rank. |
| The <code class="literal">value</code> attribute 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. |
| </p></dd><dt><span class="term"><code class="literal"><Package></code></span></dt><dd><p> |
| This element matches warnings associated with classes within the package specified |
| using <code class="literal">name</code> attribute. Nested packages are not included (along the |
| lines of Java import statement). However matching multiple packages can be achieved |
| easily using regex name match. |
| </p></dd><dt><span class="term"><code class="literal"><Class></code></span></dt><dd><p> |
| This element matches warnings associated with a particular class. The |
| <code class="literal">name</code> attribute is used to specify the exact or regex match pattern |
| for the class name. |
| </p><p> |
| As a backward compatibility measure, instead of element of this type, you can use |
| <code class="literal">class</code> attribute on a <code class="literal">Match</code> element to specify |
| exact an class name or <code class="literal">classregex</code> attribute to specify a regular |
| expression to match the class name against. |
| </p><p> |
| If the <code class="literal">Match</code> element contains neither a <code class="literal">Class</code> element, |
| nor a <code class="literal">class</code> / <code class="literal">classregex</code> attribute, 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 apropriate method or field predicates. |
| </p></dd><dt><span class="term"><code class="literal"><Method></code></span></dt><dd><p>This element specifies a method. The <code class="literal">name</code> is used to specify |
| the exact or regex match pattern for the method name. |
| The <code class="literal">params</code> attribute is a comma-separated list |
| of the types of the method's parameters. The <code class="literal">returns</code> attribute is |
| the method's return type. In <code class="literal">params</code> and <code class="literal">returns</code>, 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 <code class="literal">name</code> attribute or <code class="literal">params</code> |
| and <code class="literal">returns</code> attributes or all three of them. This way you can provide various kinds of |
| name and signature based matches. |
| </p></dd><dt><span class="term"><code class="literal"><Field></code></span></dt><dd><p>This element specifies a field. The <code class="literal">name</code> attribute is is used to specify |
| the exact or regex match pattern for the field name. You can also filter fields according to their signature - |
| use <code class="literal">type</code> attribute to specify fully qualified type of the field. You can specify eiter or both |
| of these attributes in order to perform name / signature based matches. |
| </p></dd><dt><span class="term"><code class="literal"><Local></code></span></dt><dd><p>This element specifies a local variable. The <code class="literal">name</code> attribute is is used to specify |
| the exact or regex match pattern for the local variable name. Local variables are variables defined within a method. |
| </p></dd><dt><span class="term"><code class="literal"><Or></code></span></dt><dd><p> |
| This element combines <code class="literal">Match</code> clauses as disjuncts. I.e., you can put two |
| <code class="literal">Method</code> elements in an <code class="literal">Or</code> clause in order to match either method. |
| </p></dd><dt><span class="term"><code class="literal"><And></code></span></dt><dd><p> |
| This element combines <code class="literal">Match</code> clauses which both must evaluate to true. I.e., you can put |
| <code class="literal">Bug</code> and <code class="literal">Priority</code> elements in an <code class="literal">And</code> clause in order |
| to match specific bugs with given priority only. |
| </p></dd><dt><span class="term"><code class="literal"><Not></code></span></dt><dd><p> |
| This element inverts the included child <code class="literal">Match</code>. I.e., you can put a |
| <code class="literal">Bug</code> element in a <code class="literal">Not</code> clause in order to match any bug |
| excluding the given one. |
| </p></dd></dl></div></div><div class="sect1" title="3. Java element name matching"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2113"></a>3. Java element name matching</h2></div></div></div><p> |
| If the <code class="literal">name</code> attribute of <code class="literal">Class</code>, <code class="literal">Method</code> or |
| <code class="literal">Field</code> 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. |
| </p><p> |
| 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. |
| </p><p> |
| See <a class="ulink" href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html" target="_top"><code class="literal">java.util.regex.Pattern</code></a> |
| documentation for pattern syntax. |
| </p></div><div class="sect1" title="4. Caveats"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2138"></a>4. Caveats</h2></div></div></div><p> |
| <code class="literal">Match</code> 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. |
| </p><p> |
| 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 <span class="emphasis"><em>first</em></span> (primary) class is matched against <code class="literal">Match</code> 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 <code class="literal">Match</code> clauses: |
| |
| </p><pre class="programlisting"> |
| <Match> |
| <Class name="com.foobar.A" /> |
| <Bug code="IC" /> |
| </Match> |
| |
| <Match> |
| <Class name="com.foobar.B" /> |
| <Bug code="IC" /> |
| </Match> |
| </pre><p> |
| |
| 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.) |
| </p><p> |
| Many kinds of bugs report what method they occur in. For those bug instances, |
| you can put <code class="literal">Method</code> clauses in the <code class="literal">Match</code> element and they should work |
| as expected. |
| </p></div><div class="sect1" title="5. Examples"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2168"></a>5. Examples</h2></div></div></div><p> |
| 1. Match all bug reports for a class. |
| |
| </p><pre class="programlisting"> |
| |
| <Match> |
| <Class name="com.foobar.MyClass" /> |
| </Match> |
| |
| </pre><p> |
| |
| </p><p> |
| 2. Match certain tests from a class by specifying their abbreviations. |
| </p><pre class="programlisting"> |
| |
| <Match> |
| <Class name="com.foobar.MyClass"/ > |
| <Bug code="DE,UrF,SIC" /> |
| </Match> |
| |
| </pre><p> |
| </p><p> |
| 3. Match certain tests from all classes by specifying their abbreviations. |
| |
| </p><pre class="programlisting"> |
| |
| <Match> |
| <Bug code="DE,UrF,SIC" /> |
| </Match> |
| |
| </pre><p> |
| </p><p> |
| 4. Match certain tests from all classes by specifying their category. |
| |
| </p><pre class="programlisting"> |
| |
| <Match> |
| <Bug category="PERFORMANCE" /> |
| </Match> |
| |
| </pre><p> |
| </p><p> |
| 5. Match bug types from specified methods of a class by their abbreviations. |
| |
| </p><pre class="programlisting"> |
| |
| <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> |
| |
| </pre><p> |
| </p><p> |
| 6. Match a particular bug pattern in a particular method. |
| |
| </p><pre class="programlisting"> |
| |
| <!-- A method with an open stream false positive. --> |
| <Match> |
| <Class name="com.foobar.MyClass" /> |
| <Method name="writeDataToFile" /> |
| <Bug pattern="OS_OPEN_STREAM" /> |
| </Match> |
| |
| </pre><p> |
| </p><p> |
| 7. Match a particular bug pattern with a given priority in a particular method. |
| |
| </p><pre class="programlisting"> |
| |
| <!-- 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> |
| |
| </pre><p> |
| </p><p> |
| 8. Match minor bugs introduced by AspectJ compiler (you are probably not interested in these unless |
| you are an AspectJ developer). |
| |
| </p><pre class="programlisting"> |
| |
| <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> |
| |
| </pre><p> |
| </p><p> |
| 9. Match bugs in specific parts of the code base |
| |
| </p><pre class="programlisting"> |
| |
| <!-- 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> |
| |
| </pre><p> |
| </p><p> |
| 10. Match bugs on fields or methods with specific signatures |
| </p><pre class="programlisting"> |
| |
| <!-- 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> |
| |
| </pre><p> |
| </p><p> |
| 11. Match bugs using the Not filter operator |
| </p><pre class="programlisting"> |
| |
| <!-- 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> |
| |
| </pre><p> |
| </p></div><div class="sect1" title="6. Complete Example"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2226"></a>6. Complete Example</h2></div></div></div><pre class="programlisting"> |
| |
| <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> |
| |
| </pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eclipse.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="analysisprops.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 7. Using the <span class="application">FindBugs</span>™ Eclipse plugin </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 9. Analysis Properties</td></tr></table></div></body></html> |
