1 <html><head> 2 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 3 <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#d0e1838">1. Introduction to Filter Files</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e1888">2. Types of Match clauses</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e2136">3. Java element name matching</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e2161">4. Caveats</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e2191">5. Examples</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e2249">6. Complete Example</a></span></dt></dl></div><p> 4 Filter files may be used to include or exclude bug reports for particular classes 5 and methods. This chapter explains how to use filter files. 6 7 </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> 8 Filters are currently only supported by the Command Line interface. 9 Eventually, filter support will be added to the GUI. 10 </p></td></tr></table></div><p> 11 </p><div class="sect1" title="1. Introduction to Filter Files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1838"></a>1. Introduction to Filter Files</h2></div></div></div><p> 12 Conceptually, a filter matches bug instances against a set of criteria. 13 By defining a filter, you can select bug instances for special treatment; 14 for example, to exclude or include them in a report. 15 </p><p> 16 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 17 which has some number of <code class="literal">Match</code> elements as children. Each <code class="literal">Match</code> 18 element represents a predicate which is applied to generated bug instances. 19 Usually, a filter will be used to exclude bug instances. For example: 20 21 </p><pre class="screen"> 22 <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> 23 </pre><p> 24 25 However, a filter could also be used to select bug instances to specifically 26 report: 27 28 </p><pre class="screen"> 29 <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> 30 </pre><p> 31 </p><p> 32 <code class="literal">Match</code> elements contain children, which are conjuncts of the predicate. 33 In other words, each of the children must be true for the predicate to be true. 34 </p></div><div class="sect1" title="2. Types of Match clauses"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1888"></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> 35 This element specifies a particular bug pattern or patterns to match. 36 The <code class="literal">pattern</code> attribute is a comma-separated list of 37 bug pattern types. You can find the bug pattern types for particular 38 warnings by looking at the output produced by the <span class="command"><strong>-xml</strong></span> 39 output option (the <code class="literal">type</code> attribute of <code class="literal">BugInstance</code> 40 elements), or from the <a class="ulink" href="../bugDescriptions.html" target="_top">bug 41 descriptions document</a>. 42 </p><p> 43 For more coarse-grained matching, use <code class="literal">code</code> attribute. It takes 44 a comma-separated list of bug abbreviations. For most-coarse grained matching use 45 <code class="literal">category</code> attriute, that takes a comma separated list of bug category names: 46 <code class="literal">CORRECTNESS</code>, <code class="literal">MT_CORRECTNESS</code>, 47 <code class="literal">BAD_PRACTICICE</code>, <code class="literal">PERFORMANCE</code>, <code class="literal">STYLE</code>. 48 </p><p> 49 If more than one of the attributes mentioned above are specified on the same 50 <code class="literal"><Bug></code> element, all bug patterns that match either one of specified 51 pattern names, or abreviations, or categories will be matched. 52 </p><p> 53 As a backwards compatibility measure, <code class="literal"><BugPattern></code> and 54 <code class="literal"><BugCode></code> elements may be used instead of 55 <code class="literal"><Bug></code> element. Each of these uses a 56 <code class="literal">name</code> attribute for specifying accepted values list. Support for these 57 elements may be removed in a future release. 58 </p></dd><dt><span class="term"><code class="literal"><Confidence></code></span></dt><dd><p> 59 This element matches warnings with a particular bug confidence. 60 The <code class="literal">value</code> attribute should be an integer value: 61 1 to match high-confidence warnings, 2 to match normal-confidence warnings, 62 or 3 to match low-confidence warnings. <Confidence> replaced 63 <Priority> in 2.0.0 release. 64 </p></dd><dt><span class="term"><code class="literal"><Priority></code></span></dt><dd><p> 65 Same as <code class="literal"><Confidence></code>, exists for backward compatibility. 66 </p></dd><dt><span class="term"><code class="literal"><Rank></code></span></dt><dd><p> 67 This element matches warnings with a particular bug rank. 68 The <code class="literal">value</code> attribute should be an integer value 69 between 1 and 20, where 1 to 4 are scariest, 5 to 9 scary, 10 to 14 troubling, 70 and 15 to 20 of concern bugs. 71 </p></dd><dt><span class="term"><code class="literal"><Package></code></span></dt><dd><p> 72 This element matches warnings associated with classes within the package specified 73 using <code class="literal">name</code> attribute. Nested packages are not included (along the 74 lines of Java import statement). However matching multiple packages can be achieved 75 easily using regex name match. 76 </p></dd><dt><span class="term"><code class="literal"><Class></code></span></dt><dd><p> 77 This element matches warnings associated with a particular class. The 78 <code class="literal">name</code> attribute is used to specify the exact or regex match pattern 79 for the class name. 80 </p><p> 81 As a backward compatibility measure, instead of element of this type, you can use 82 <code class="literal">class</code> attribute on a <code class="literal">Match</code> element to specify 83 exact an class name or <code class="literal">classregex</code> attribute to specify a regular 84 expression to match the class name against. 85 </p><p> 86 If the <code class="literal">Match</code> element contains neither a <code class="literal">Class</code> element, 87 nor a <code class="literal">class</code> / <code class="literal">classregex</code> attribute, the predicate will apply 88 to all classes. Such predicate is likely to match more bug instances than you want, unless it is 89 refined further down with apropriate method or field predicates. 90 </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 91 the exact or regex match pattern for the method name. 92 The <code class="literal">params</code> attribute is a comma-separated list 93 of the types of the method's parameters. The <code class="literal">returns</code> attribute is 94 the method's return type. In <code class="literal">params</code> and <code class="literal">returns</code>, class names 95 must be fully qualified. (E.g., "java.lang.String" instead of just 96 "String".) If one of the latter attributes is specified the other is required for creating a method signature. 97 Note that you can provide either <code class="literal">name</code> attribute or <code class="literal">params</code> 98 and <code class="literal">returns</code> attributes or all three of them. This way you can provide various kinds of 99 name and signature based matches. 100 </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 101 the exact or regex match pattern for the field name. You can also filter fields according to their signature - 102 use <code class="literal">type</code> attribute to specify fully qualified type of the field. You can specify eiter or both 103 of these attributes in order to perform name / signature based matches. 104 </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 105 the exact or regex match pattern for the local variable name. Local variables are variables defined within a method. 106 </p></dd><dt><span class="term"><code class="literal"><Or></code></span></dt><dd><p> 107 This element combines <code class="literal">Match</code> clauses as disjuncts. I.e., you can put two 108 <code class="literal">Method</code> elements in an <code class="literal">Or</code> clause in order to match either method. 109 </p></dd><dt><span class="term"><code class="literal"><And></code></span></dt><dd><p> 110 This element combines <code class="literal">Match</code> clauses which both must evaluate to true. I.e., you can put 111 <code class="literal">Bug</code> and <code class="literal">Priority</code> elements in an <code class="literal">And</code> clause in order 112 to match specific bugs with given priority only. 113 </p></dd><dt><span class="term"><code class="literal"><Not></code></span></dt><dd><p> 114 This element inverts the included child <code class="literal">Match</code>. I.e., you can put a 115 <code class="literal">Bug</code> element in a <code class="literal">Not</code> clause in order to match any bug 116 excluding the given one. 117 </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="d0e2136"></a>3. Java element name matching</h2></div></div></div><p> 118 If the <code class="literal">name</code> attribute of <code class="literal">Class</code>, <code class="literal">Method</code> or 119 <code class="literal">Field</code> starts with the ~ character the rest of attribute content is interpreted as 120 a Java regular expression that is matched against the names of the Java element in question. 121 </p><p> 122 Note that the pattern is matched against whole element name and therefore .* clauses need to be used 123 at pattern beginning and/or end to perform substring matching. 124 </p><p> 125 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> 126 documentation for pattern syntax. 127 </p></div><div class="sect1" title="4. Caveats"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2161"></a>4. Caveats</h2></div></div></div><p> 128 <code class="literal">Match</code> clauses can only match information that is actually contained in the 129 bug instances. Every bug instance has a class, so in general, excluding 130 bugs by class will work. 131 </p><p> 132 Some bug instances have two (or more) classes. For example, the DE (dropped exception) 133 bugs report both the class containing the method where the dropped exception 134 happens, and the class which represents the type of the dropped exception. 135 Only the <span class="emphasis"><em>first</em></span> (primary) class is matched against <code class="literal">Match</code> clauses. 136 So, for example, if you want to suppress IC (initialization circularity) 137 reports for classes "com.foobar.A" and "com.foobar.B", you would use 138 two <code class="literal">Match</code> clauses: 139 140 </p><pre class="programlisting"> 141 <Match> 142 <Class name="com.foobar.A" /> 143 <Bug code="IC" /> 144 </Match> 145 146 <Match> 147 <Class name="com.foobar.B" /> 148 <Bug code="IC" /> 149 </Match> 150 </pre><p> 151 152 By explicitly matching both classes, you ensure that the IC bug instance will be 153 matched regardless of which class involved in the circularity happens to be 154 listed first in the bug instance. (Of course, this approach might accidentally 155 supress circularities involving "com.foobar.A" or "com.foobar.B" and a third 156 class.) 157 </p><p> 158 Many kinds of bugs report what method they occur in. For those bug instances, 159 you can put <code class="literal">Method</code> clauses in the <code class="literal">Match</code> element and they should work 160 as expected. 161 </p></div><div class="sect1" title="5. Examples"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2191"></a>5. Examples</h2></div></div></div><p> 162 1. Match all bug reports for a class. 163 164 </p><pre class="programlisting"> 165 166 <Match> 167 <Class name="com.foobar.MyClass" /> 168 </Match> 169 170 </pre><p> 171 172 </p><p> 173 2. Match certain tests from a class by specifying their abbreviations. 174 </p><pre class="programlisting"> 175 176 <Match> 177 <Class name="com.foobar.MyClass"/ > 178 <Bug code="DE,UrF,SIC" /> 179 </Match> 180 181 </pre><p> 182 </p><p> 183 3. Match certain tests from all classes by specifying their abbreviations. 184 185 </p><pre class="programlisting"> 186 187 <Match> 188 <Bug code="DE,UrF,SIC" /> 189 </Match> 190 191 </pre><p> 192 </p><p> 193 4. Match certain tests from all classes by specifying their category. 194 195 </p><pre class="programlisting"> 196 197 <Match> 198 <Bug category="PERFORMANCE" /> 199 </Match> 200 201 </pre><p> 202 </p><p> 203 5. Match bug types from specified methods of a class by their abbreviations. 204 205 </p><pre class="programlisting"> 206 207 <Match> 208 <Class name="com.foobar.MyClass" /> 209 <Or> 210 <Method name="frob" params="int,java.lang.String" returns="void" /> 211 <Method name="blat" params="" returns="boolean" /> 212 </Or> 213 <Bug code="DC" /> 214 </Match> 215 216 </pre><p> 217 </p><p> 218 6. Match a particular bug pattern in a particular method. 219 220 </p><pre class="programlisting"> 221 222 <!-- A method with an open stream false positive. --> 223 <Match> 224 <Class name="com.foobar.MyClass" /> 225 <Method name="writeDataToFile" /> 226 <Bug pattern="OS_OPEN_STREAM" /> 227 </Match> 228 229 </pre><p> 230 </p><p> 231 7. Match a particular bug pattern with a given priority in a particular method. 232 233 </p><pre class="programlisting"> 234 235 <!-- A method with a dead local store false positive (medium priority). --> 236 <Match> 237 <Class name="com.foobar.MyClass" /> 238 <Method name="someMethod" /> 239 <Bug pattern="DLS_DEAD_LOCAL_STORE" /> 240 <Priority value="2" /> 241 </Match> 242 243 </pre><p> 244 </p><p> 245 8. Match minor bugs introduced by AspectJ compiler (you are probably not interested in these unless 246 you are an AspectJ developer). 247 248 </p><pre class="programlisting"> 249 250 <Match> 251 <Class name="~.*\$AjcClosure\d+" /> 252 <Bug pattern="DLS_DEAD_LOCAL_STORE" /> 253 <Method name="run" /> 254 </Match> 255 <Match> 256 <Bug pattern="UUF_UNUSED_FIELD" /> 257 <Field name="~ajc\$.*" /> 258 </Match> 259 260 </pre><p> 261 </p><p> 262 9. Match bugs in specific parts of the code base 263 264 </p><pre class="programlisting"> 265 266 <!-- match unused fields warnings in Messages classes in all packages --> 267 <Match> 268 <Class name="~.*\.Messages" /> 269 <Bug code="UUF" /> 270 </Match> 271 <!-- match mutable statics warnings in all internal packages --> 272 <Match> 273 <Package name="~.*\.internal" /> 274 <Bug code="MS" /> 275 </Match> 276 <!-- match anonymoous inner classes warnings in ui package hierarchy --> 277 <Match> 278 <Package name="~com\.foobar\.fooproject\.ui.*" /> 279 <Bug pattern="SIC_INNER_SHOULD_BE_STATIC_ANON" /> 280 </Match> 281 282 </pre><p> 283 </p><p> 284 10. Match bugs on fields or methods with specific signatures 285 </p><pre class="programlisting"> 286 287 <!-- match System.exit(...) usage warnings in void main(String[]) methods in all classes --> 288 <Match> 289 <Method returns="void" name="main" params="java.lang.String[]" /> 290 <Bug pattern="DM_EXIT" /> 291 </Match> 292 <!-- match UuF warnings on fields of type com.foobar.DebugInfo on all classes --> 293 <Match> 294 <Field type="com.foobar.DebugInfo" /> 295 <Bug code="UuF" /> 296 </Match> 297 298 </pre><p> 299 </p><p> 300 11. Match bugs using the Not filter operator 301 </p><pre class="programlisting"> 302 303 <!-- ignore all bugs in test classes, except for those bugs specifically relating to JUnit tests --> 304 <!-- i.e. filter bug if ( classIsJUnitTest && ! bugIsRelatedToJUnit ) --> 305 <Match> 306 <!-- the Match filter is equivalent to a logical 'And' --> 307 308 <Class name="~.*\.*Test" /> 309 <!-- test classes are suffixed by 'Test' --> 310 311 <Not> 312 <Bug code="IJU" /> <!-- 'IJU' is the code for bugs related to JUnit test code --> 313 </Not> 314 </Match> 315 316 </pre><p> 317 </p></div><div class="sect1" title="6. Complete Example"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2249"></a>6. Complete Example</h2></div></div></div><pre class="programlisting"> 318 319 <FindBugsFilter> 320 <Match> 321 <Class name="com.foobar.ClassNotToBeAnalyzed" /> 322 </Match> 323 324 <Match> 325 <Class name="com.foobar.ClassWithSomeBugsMatched" /> 326 <Bug code="DE,UrF,SIC" /> 327 </Match> 328 329 <!-- Match all XYZ violations. --> 330 <Match> 331 <Bug code="XYZ" /> 332 </Match> 333 334 <!-- Match all doublecheck violations in these methods of "AnotherClass". --> 335 <Match> 336 <Class name="com.foobar.AnotherClass" /> 337 <Or> 338 <Method name="nonOverloadedMethod" /> 339 <Method name="frob" params="int,java.lang.String" returns="void" /> 340 <Method name="blat" params="" returns="boolean" /> 341 </Or> 342 <Bug code="DC" /> 343 </Match> 344 345 <!-- A method with a dead local store false positive (medium priority). --> 346 <Match> 347 <Class name="com.foobar.MyClass" /> 348 <Method name="someMethod" /> 349 <Bug pattern="DLS_DEAD_LOCAL_STORE" /> 350 <Priority value="2" /> 351 </Match> 352 353 <!-- All bugs in test classes, except for JUnit-specific bugs --> 354 <Match> 355 <Class name="~.*\.*Test" /> 356 <Not> 357 <Bug code="IJU" /> 358 </Not> 359 </Match> 360 361 </FindBugsFilter> 362 363 </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>
