OLD | NEW |
1 <html><head> | 1 <html><head> |
2 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | 2 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
3 <title>Chapter 8. Filter Files</title><meta name="generator" conten
t="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="Fi
ndBugs™ Manual"><link rel="up" href="index.html" title="FindBugs™ Ma
nual"><link rel="prev" href="eclipse.html" title="Chapter 7. Using the
FindBugs™ Eclipse plugin"><link rel="next" href="analysisprops.html" titl
e="Chapter 9. Analysis Properties"></head><body bgcolor="white" text="
black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><ta
ble width="100%" summary="Navigation header"><tr><th colspan="3" align="center">
Chapter 8. Filter Files</th></tr><tr><td width="20%" align="left"><a a
ccesskey="p" href="eclipse.html">Prev</a> </td><th width="60%" align="cente
r"> </th><td width="20%" align="right"> <a accesskey="n" href="analysi
sprops.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Cha
pter 8. Filter Files"><div class="titlepage"><div><div><h2 class="titl
e"><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 h
ref="filter.html#d0e1815">1. Introduction to Filter Files</a></span></dt><dt><sp
an class="sect1"><a href="filter.html#d0e1865">2. Types of Match clauses</a></sp
an></dt><dt><span class="sect1"><a href="filter.html#d0e2113">3. Java element na
me 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> | 3 <title>Chapter 8. Filter Files</title><meta name="generator" conten
t="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="Fi
ndBugs™ Manual"><link rel="up" href="index.html" title="FindBugs™ Ma
nual"><link rel="prev" href="eclipse.html" title="Chapter 7. Using the
FindBugs™ Eclipse plugin"><link rel="next" href="analysisprops.html" titl
e="Chapter 9. Analysis Properties"></head><body bgcolor="white" text="
black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><ta
ble width="100%" summary="Navigation header"><tr><th colspan="3" align="center">
Chapter 8. Filter Files</th></tr><tr><td width="20%" align="left"><a a
ccesskey="p" href="eclipse.html">Prev</a> </td><th width="60%" align="cente
r"> </th><td width="20%" align="right"> <a accesskey="n" href="analysi
sprops.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Cha
pter 8. Filter Files"><div class="titlepage"><div><div><h2 class="titl
e"><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 h
ref="filter.html#d0e1838">1. Introduction to Filter Files</a></span></dt><dt><sp
an class="sect1"><a href="filter.html#d0e1888">2. Types of Match clauses</a></sp
an></dt><dt><span class="sect1"><a href="filter.html#d0e2136">3. Java element na
me 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 classe
s | 4 Filter files may be used to include or exclude bug reports for particular classe
s |
5 and methods. This chapter explains how to use filter files. | 5 and methods. This chapter explains how to use filter files. |
6 | 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 rowsp
an="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> | 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 rowsp
an="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. | 8 Filters are currently only supported by the Command Line interface. |
9 Eventually, filter support will be added to the GUI. | 9 Eventually, filter support will be added to the GUI. |
10 </p></td></tr></table></div><p> | 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="d0e1815"></a
>1. Introduction to Filter Files</h2></div></div></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. | 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; | 13 By defining a filter, you can select bug instances for special treatment; |
14 for example, to exclude or include them in a report. | 14 for example, to exclude or include them in a report. |
15 </p><p> | 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> e
lement | 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> e
lement |
17 which has some number of <code class="literal">Match</code> elements as children
. Each <code class="literal">Match</code> | 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. | 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: | 19 Usually, a filter will be used to exclude bug instances. For example: |
20 | 20 |
21 </p><pre class="screen"> | 21 </p><pre class="screen"> |
22 <code class="prompt">$ </code><span class="command"><strong>findbugs -textui -ex
clude <em class="replaceable"><code>myExcludeFilter.xml</code></em> <em class="r
eplaceable"><code>myApp.jar</code></em></strong></span> | 22 <code class="prompt">$ </code><span class="command"><strong>findbugs -textui -ex
clude <em class="replaceable"><code>myExcludeFilter.xml</code></em> <em class="r
eplaceable"><code>myApp.jar</code></em></strong></span> |
23 </pre><p> | 23 </pre><p> |
24 | 24 |
25 However, a filter could also be used to select bug instances to specifically | 25 However, a filter could also be used to select bug instances to specifically |
26 report: | 26 report: |
27 | 27 |
28 </p><pre class="screen"> | 28 </p><pre class="screen"> |
29 <code class="prompt">$ </code><span class="command"><strong>findbugs -textui -in
clude <em class="replaceable"><code>myIncludeFilter.xml</code></em> <em class="r
eplaceable"><code>myApp.jar</code></em></strong></span> | 29 <code class="prompt">$ </code><span class="command"><strong>findbugs -textui -in
clude <em class="replaceable"><code>myIncludeFilter.xml</code></em> <em class="r
eplaceable"><code>myApp.jar</code></em></strong></span> |
30 </pre><p> | 30 </pre><p> |
31 </p><p> | 31 </p><p> |
32 <code class="literal">Match</code> elements contain children, which are conjunct
s of the predicate. | 32 <code class="literal">Match</code> elements contain children, which are conjunct
s of the predicate. |
33 In other words, each of the children must be true for the predicate to be true. | 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="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> | 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
. | 35 This element specifies a particular bug pattern or patterns to match
. |
36 The <code class="literal">pattern</code> attribute is a comma-separa
ted list of | 36 The <code class="literal">pattern</code> attribute is a comma-separa
ted list of |
37 bug pattern types. You can find the bug pattern types for particula
r | 37 bug pattern types. You can find the bug pattern types for particula
r |
38 warnings by looking at the output produced by the <span class="comma
nd"><strong>-xml</strong></span> | 38 warnings by looking at the output produced by the <span class="comma
nd"><strong>-xml</strong></span> |
39 output option (the <code class="literal">type</code> attribute of <c
ode class="literal">BugInstance</code> | 39 output option (the <code class="literal">type</code> attribute of <c
ode class="literal">BugInstance</code> |
40 elements), or from the <a class="ulink" href="../bugDescriptions.htm
l" target="_top">bug | 40 elements), or from the <a class="ulink" href="../bugDescriptions.htm
l" target="_top">bug |
41 descriptions document</a>. | 41 descriptions document</a>. |
42 </p><p> | 42 </p><p> |
43 For more coarse-grained matching, use <code class="literal">code<
/code> attribute. It takes | 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 grai
ned matching use | 44 a comma-separated list of bug abbreviations. For most-coarse grai
ned matching use |
(...skipping 62 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
107 This element combines <code class="literal">Match</code> clauses as disjuncts
. I.e., you can put two | 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. | 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></spa
n></dt><dd><p> | 109 </p></dd><dt><span class="term"><code class="literal"><And></code></spa
n></dt><dd><p> |
110 This element combines <code class="literal">Match</code> clauses which both m
ust evaluate to true. I.e., you can put | 110 This element combines <code class="literal">Match</code> clauses which both m
ust evaluate to true. I.e., you can put |
111 <code class="literal">Bug</code> and <code class="literal">Priority</code> el
ements in an <code class="literal">And</code> clause in order | 111 <code class="literal">Bug</code> and <code class="literal">Priority</code> el
ements in an <code class="literal">And</code> clause in order |
112 to match specific bugs with given priority only. | 112 to match specific bugs with given priority only. |
113 </p></dd><dt><span class="term"><code class="literal"><Not></code></spa
n></dt><dd><p> | 113 </p></dd><dt><span class="term"><code class="literal"><Not></code></spa
n></dt><dd><p> |
114 This element inverts the included child <code class="literal">Match</code>. I
.e., you can put a | 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 | 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. | 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="d0e2113"></a>3. Java element name matching</h2></div></div></div
><p> | 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">Clas
s</code>, <code class="literal">Method</code> or | 118 If the <code class="literal">name</code> attribute of <code class="literal">Clas
s</code>, <code class="literal">Method</code> or |
119 <code class="literal">Field</code> starts with the ~ character the rest of attri
bute content is interpreted as | 119 <code class="literal">Field</code> starts with the ~ character the rest of attri
bute content is interpreted as |
120 a Java regular expression that is matched against the names of the Java element
in question. | 120 a Java regular expression that is matched against the names of the Java element
in question. |
121 </p><p> | 121 </p><p> |
122 Note that the pattern is matched against whole element name and therefore .* cla
uses need to be used | 122 Note that the pattern is matched against whole element name and therefore .* cla
uses need to be used |
123 at pattern beginning and/or end to perform substring matching. | 123 at pattern beginning and/or end to perform substring matching. |
124 </p><p> | 124 </p><p> |
125 See <a class="ulink" href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/reg
ex/Pattern.html" target="_top"><code class="literal">java.util.regex.Pattern</co
de></a> | 125 See <a class="ulink" href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/reg
ex/Pattern.html" target="_top"><code class="literal">java.util.regex.Pattern</co
de></a> |
126 documentation for pattern syntax. | 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="d0e2138"></a>4. Caveat
s</h2></div></div></div><p> | 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. Caveat
s</h2></div></div></div><p> |
128 <code class="literal">Match</code> clauses can only match information that is ac
tually contained in the | 128 <code class="literal">Match</code> clauses can only match information that is ac
tually contained in the |
129 bug instances. Every bug instance has a class, so in general, excluding | 129 bug instances. Every bug instance has a class, so in general, excluding |
130 bugs by class will work. | 130 bugs by class will work. |
131 </p><p> | 131 </p><p> |
132 Some bug instances have two (or more) classes. For example, the DE (dropped exc
eption) | 132 Some bug instances have two (or more) classes. For example, the DE (dropped exc
eption) |
133 bugs report both the class containing the method where the 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. | 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. | 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) | 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 | 137 reports for classes "com.foobar.A" and "com.foobar.B", you would use |
(...skipping 13 matching lines...) Expand all Loading... |
151 | 151 |
152 By explicitly matching both classes, you ensure that the IC bug instance will be | 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 | 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 | 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 | 155 supress circularities involving "com.foobar.A" or "com.foobar.B" and a third |
156 class.) | 156 class.) |
157 </p><p> | 157 </p><p> |
158 Many kinds of bugs report what method they occur in. For those bug instances, | 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="lite
ral">Match</code> element and they should work | 159 you can put <code class="literal">Method</code> clauses in the <code class="lite
ral">Match</code> element and they should work |
160 as expected. | 160 as expected. |
161 </p></div><div class="sect1" title="5. Examples"><div class="titlepage"><di
v><div><h2 class="title" style="clear: both"><a name="d0e2168"></a>5. Examp
les</h2></div></div></div><p> | 161 </p></div><div class="sect1" title="5. Examples"><div class="titlepage"><di
v><div><h2 class="title" style="clear: both"><a name="d0e2191"></a>5. Examp
les</h2></div></div></div><p> |
162 1. Match all bug reports for a class. | 162 1. Match all bug reports for a class. |
163 | 163 |
164 </p><pre class="programlisting"> | 164 </p><pre class="programlisting"> |
165 | 165 |
166 <Match> | 166 <Match> |
167 <Class name="com.foobar.MyClass" /> | 167 <Class name="com.foobar.MyClass" /> |
168 </Match> | 168 </Match> |
169 | 169 |
170 </pre><p> | 170 </pre><p> |
171 | 171 |
(...skipping 135 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
307 | 307 |
308 <Class name="~.*\.*Test" /> | 308 <Class name="~.*\.*Test" /> |
309 <!-- test classes are suffixed by 'Test' --> | 309 <!-- test classes are suffixed by 'Test' --> |
310 | 310 |
311 <Not> | 311 <Not> |
312 <Bug code="IJU" /> <!-- 'IJU' is the code for bugs related to JUn
it test code --> | 312 <Bug code="IJU" /> <!-- 'IJU' is the code for bugs related to JUn
it test code --> |
313 </Not> | 313 </Not> |
314 </Match> | 314 </Match> |
315 | 315 |
316 </pre><p> | 316 </pre><p> |
317 </p></div><div class="sect1" title="6. Complete Example"><div class="titlep
age"><div><div><h2 class="title" style="clear: both"><a name="d0e2226"></a>6.&nb
sp;Complete Example</h2></div></div></div><pre class="programlisting"> | 317 </p></div><div class="sect1" title="6. Complete Example"><div class="titlep
age"><div><div><h2 class="title" style="clear: both"><a name="d0e2249"></a>6.&nb
sp;Complete Example</h2></div></div></div><pre class="programlisting"> |
318 | 318 |
319 <FindBugsFilter> | 319 <FindBugsFilter> |
320 <Match> | 320 <Match> |
321 <Class name="com.foobar.ClassNotToBeAnalyzed" /> | 321 <Class name="com.foobar.ClassNotToBeAnalyzed" /> |
322 </Match> | 322 </Match> |
323 | 323 |
324 <Match> | 324 <Match> |
325 <Class name="com.foobar.ClassWithSomeBugsMatched" /> | 325 <Class name="com.foobar.ClassWithSomeBugsMatched" /> |
326 <Bug code="DE,UrF,SIC" /> | 326 <Bug code="DE,UrF,SIC" /> |
327 </Match> | 327 </Match> |
(...skipping 26 matching lines...) Expand all Loading... |
354 <Match> | 354 <Match> |
355 <Class name="~.*\.*Test" /> | 355 <Class name="~.*\.*Test" /> |
356 <Not> | 356 <Not> |
357 <Bug code="IJU" /> | 357 <Bug code="IJU" /> |
358 </Not> | 358 </Not> |
359 </Match> | 359 </Match> |
360 | 360 |
361 </FindBugsFilter> | 361 </FindBugsFilter> |
362 | 362 |
363 </pre></div></div><div class="navfooter"><hr><table width="100%" summary="Naviga
tion footer"><tr><td width="40%" align="left"><a accesskey="p" href="eclipse.htm
l">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 <s
pan class="application">FindBugs</span>™ Eclipse plugin </td><td widt
h="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> | 363 </pre></div></div><div class="navfooter"><hr><table width="100%" summary="Naviga
tion footer"><tr><td width="40%" align="left"><a accesskey="p" href="eclipse.htm
l">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 <s
pan class="application">FindBugs</span>™ Eclipse plugin </td><td widt
h="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> |
OLD | NEW |