diff options
Diffstat (limited to 'tools/findbugs/doc/manual/filter.html')
| -rw-r--r-- | tools/findbugs/doc/manual/filter.html | 363 |
1 files changed, 0 insertions, 363 deletions
diff --git a/tools/findbugs/doc/manual/filter.html b/tools/findbugs/doc/manual/filter.html deleted file mode 100644 index 98b264f..0000000 --- a/tools/findbugs/doc/manual/filter.html +++ /dev/null @@ -1,363 +0,0 @@ -<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#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> -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="d0e1838"></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="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> - 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="d0e2136"></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="d0e2161"></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="d0e2191"></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="d0e2249"></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>
\ No newline at end of file |