<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.71.1"><link rel="start" 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" lang="en"><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#d0e1566">1. Introduction to Filter Files</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e1616">2. Types of Match clauses</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e1809">3. Java element name matching</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e1834">4. Caveats</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e1864">5. Examples</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e1917">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" 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" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1566"></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 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><strong class="command">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><strong class="command">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" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1616"></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><strong class="command">-xml</strong></span>
output option (the <code class="literal">type</code> attribute of <code class="literal">BugInstance</code>
elements), or from the <a 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"><Priority></code></span></dt><dd><p>
This element matches warnings with a particular priority.
The <code class="literal">value</code> attribute should be an integer value:
1 to match high-priority warnings, 2 to match medium-priority warnings,
or 3 to match low-priority warnings.
</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 match either method.
</p></dd></dl></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1809"></a>3. Java element name matching</h2></div></div></div><p>
If the <code class="literal">name</code> attribute or <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 href="http://java.sun.com/j2se/1.4.2/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" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1834"></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" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1864"></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 fieds 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[]" />
<Method 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></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1917"></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 code="DLS_DEAD_LOCAL_STORE" />
<Priority value="2" />
</Match>
</FindBugsFilter&gt;
</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>
distrib
>
Mandriva
>
2008.1
>
x86_64
>
media
>
contrib-release
>
by-pkgid
>
95f5ae0ce06780fd3cab0be9375c9914
>
files
>
47
