Filters are currently only supported by the Command Line interface.  Eventually, filter support will be added to the GUI.</para></note></para><sect1><title>Introduction to Filter Files</title><para>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.</para><para>A filter file is an <ulink url="http://www.w3.org/XML/">XML</ulink> document with a top-level <literal>FindBugsFilter</literal> elementwhich has some number of <literal>Match</literal> elements as children.  Each <literal>Match</literal>element represents a predicate which is applied to generated bug instances.Usually, a filter will be used to exclude bug instances.  For example:<screen><prompt>$ </prompt><command>findbugs -textui -exclude <replaceable>myExcludeFilter.xml</replaceable> <replaceable>myApp.jar</replaceable></command></screen>However, a filter could also be used to select bug instances to specificallyreport:<screen><prompt>$ </prompt><command>findbugs -textui -include <replaceable>myIncludeFilter.xml</replaceable> <replaceable>myApp.jar</replaceable></command></screen></para><para><literal>Match</literal> 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.</para></sect1><sect1><title>Types of Match clauses</title><variablelist> <varlistentry>   <term><literal>&lt;Bug&gt;</literal></term>   <listitem><para>			This element specifies a particular bug pattern or patterns to match.			The <literal>pattern</literal> 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 <command>-xml</command>			output option (the <literal>type</literal> attribute of <literal>BugInstance</literal>			elements), or from the <ulink url="../bugDescriptions.html">bug			descriptions document</ulink>.   </para><para>   			For more coarse-grained matching, use <literal>code</literal> attribute. It takes   			a comma-separated list of bug abbreviations. For most-coarse grained matching use    			<literal>category</literal> attriute, that takes a comma separated list of bug category names:    			<literal>CORRECTNESS</literal>, <literal>MT_CORRECTNESS</literal>,    			<literal>BAD_PRACTICICE</literal>, <literal>PERFORMANCE</literal>, <literal>STYLE</literal>.    </para><para>   			   			If more than one of the attributes mentioned above are specified on the same    			<literal>&lt;Bug&gt;</literal> element, all bug patterns that match either one of specified    			pattern names, or abreviations, or categories will be matched.   </para><para>      			As a backwards compatibility measure, <literal>&lt;BugPattern&gt;</literal> and   			<literal>&lt;BugCode&gt;</literal> elements may be used instead of    			<literal>&lt;Bug&gt;</literal> element. Each of these uses a   			<literal>name</literal> attribute for specifying accepted values list. Support for these   			elements may be removed in a future release.   </para></listitem> </varlistentry> <varlistentry>	<term><literal>&lt;Priority&gt;</literal></term>	<listitem>		<para>			This element matches warnings with a particular priority.			The <literal>value</literal> 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.		</para>	</listitem> </varlistentry> <varlistentry>   <term><literal>&lt;Package&gt;</literal></term>	<listitem>		<para> 			This element matches warnings associated with classes within the package specified 			using <literal>name</literal> 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.		</para>	</listitem>  </varlistentry>		 <varlistentry>   <term><literal>&lt;Class&gt;</literal></term>	<listitem>		<para>			This element matches warnings associated with a particular class. The 			<literal>name</literal> attribute is used to specify the exact or regex match pattern 			for the class name.		</para>				<para>			As a backward compatibility measure, instead of element of this type, you can use			 <literal>class</literal> attribute on a <literal>Match</literal> element to specify 			 exact an class name or <literal>classregex</literal> attribute to specify a regular			 expression to match the class name against.		</para>				<para>			If the <literal>Match</literal> element contains neither a <literal>Class</literal> element, 			nor a <literal>class</literal> / <literal>classregex</literal> 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.		</para>	</listitem> </varlistentry> <varlistentry>   <term><literal>&lt;Method&gt;</literal></term>   <listitem><para>This element specifies a method.  The <literal>name</literal> is used to specify   the exact or regex match pattern for the method name.   The <literal>params</literal> attribute is a comma-separated list   of the types of the method's parameters.  The <literal>returns</literal> attribute is   the method's return type.  In <literal>params</literal> and <literal>returns</literal>, 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 <literal>name</literal> attribute or <literal>params</literal>    and <literal>returns</literal> attributes or all three of them. This way you can provide various kinds of   name and signature based matches.   </para></listitem> </varlistentry> <varlistentry>   <term><literal>&lt;Field&gt;</literal></term>   <listitem><para>This element specifies a field. The <literal>name</literal> 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 <literal>type</literal> 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.   </para></listitem> </varlistentry>      <varlistentry>   <term><literal>&lt;Local&gt;</literal></term>   <listitem><para>This element specifies a local variable. The <literal>name</literal> 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.   </para></listitem> </varlistentry>    <varlistentry>   <term><literal>&lt;Or&gt;</literal></term>    <listitem><para>   This element combines <literal>Match</literal> clauses as disjuncts.  I.e., you can put two   <literal>Method</literal> elements in an <literal>Or</literal> clause in order to match either method.   </para></listitem> </varlistentry></variablelist></sect1><sect1><title>Java element name matching</title><para>If the <literal>name</literal> attribute of <literal>Class</literal>, <literal>Method</literal> or<literal>Field</literal> 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. </para><para>Note that the pattern is matched against whole element name and therefore .* clauses need to be usedat pattern beginning and/or end to perform substring matching.</para><para>See <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html"><literal>java.util.regex.Pattern</literal></ulink> documentation for pattern syntax.</para></sect1><sect1><title>Caveats</title><para><literal>Match</literal> clauses can only match information that is actually contained in thebug instances.  Every bug instance has a class, so in general, excludingbugs by class will work.</para><para>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 exceptionhappens, and the class which represents the type of the dropped exception.Only the <emphasis>first</emphasis> (primary) class is matched against <literal>Match</literal> clauses.So, for example, if you want to suppress IC (initialization circularity)reports for classes "com.foobar.A" and "com.foobar.B", you would usetwo <literal>Match</literal> clauses:<programlisting>   &lt;Match&gt;      &lt;Class name="com.foobar.A" /&gt;      &lt;Bug code="IC" /&gt;   &lt;/Match&gt;   &lt;Match&gt;      &lt;Class name="com.foobar.B" /&gt;      &lt;Bug code="IC" /&gt;   &lt;/Match&gt;</programlisting>By explicitly matching both classes, you ensure that the IC bug instance will bematched regardless of which class involved in the circularity happens to belisted first in the bug instance.  (Of course, this approach might accidentallysupress circularities involving "com.foobar.A" or "com.foobar.B" and a thirdclass.)</para><para>Many kinds of bugs report what method they occur in.  For those bug instances,you can put <literal>Method</literal> clauses in the <literal>Match</literal> element and they should workas expected.</para></sect1><sect1><title>Examples</title><para>  1. Match all bug reports for a class.<programlisting><![CDATA[     <Match>       <Class name="com.foobar.MyClass" />     </Match>]]></programlisting></para><para>  2. Match certain tests from a class by specifying their abbreviations.<programlisting><![CDATA[     <Match>       <Class name="com.foobar.MyClass"/ >       <Bug code="DE,UrF,SIC" />     </Match>]]></programlisting></para><para>  3. Match certain tests from all classes by specifying their abbreviations.<programlisting><![CDATA[     <Match>       <Bug code="DE,UrF,SIC" />     </Match>]]></programlisting></para><para>  4. Match certain tests from all classes by specifying their category.<programlisting><![CDATA[     <Match>       <Bug category="PERFORMANCE" />     </Match>]]></programlisting></para><para>  5. Match bug types from specified methods of a class by their abbreviations.<programlisting><![CDATA[     <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>]]></programlisting></para><para>	6. Match a particular bug pattern in a particular method.	<programlisting><![CDATA[    <!-- A method with an open stream false positive. -->    <Match>      <Class name="com.foobar.MyClass" />      <Method name="writeDataToFile" />      <Bug pattern="OS_OPEN_STREAM" />    </Match>]]></programlisting></para><para>	7. Match a particular bug pattern with a given priority in a particular method.	<programlisting><![CDATA[    <!-- 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>]]></programlisting></para><para>	8. Match minor bugs introduced by AspectJ compiler (you are probably not interested in these unless	you are an AspectJ developer).	<programlisting><![CDATA[    <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>]]></programlisting></para><para>	9. Match bugs in specific parts of the code base	<programlisting><![CDATA[    <!-- 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>]]></programlisting></para><para>	10. Match bugs on fieds or methods with specific signatures<programlisting><![CDATA[	<!-- 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>]]></programlisting>	</para>	</sect1><sect1><title>Complete Example</title><programlisting><![CDATA[<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