diff options
Diffstat (limited to 'tools/findbugs/doc/FilterFile.txt')
-rw-r--r-- | tools/findbugs/doc/FilterFile.txt | 125 |
1 files changed, 0 insertions, 125 deletions
diff --git a/tools/findbugs/doc/FilterFile.txt b/tools/findbugs/doc/FilterFile.txt deleted file mode 100644 index 1fed032..0000000 --- a/tools/findbugs/doc/FilterFile.txt +++ /dev/null @@ -1,125 +0,0 @@ -============= -How it works: -============= - -A filter file is an XML file with a top-level "FindBugsFilter" element -which has some number of "Match" elements as children. Each Match -element represents a predicate which is applied to generated bug instances. -Usually, a filter will be used to exclude bug instances. For example: - - findbugs -textui -exclude myExcludeFilter.xml myApp.jar - -However, a filter could also be used to select bug instances to specifically -report: - - findbugs -textui -include myIncludeFilter.xml myApp.jar - -Match has "class" and "classregex" attributes specifying what class or classes -the predicate applies to. - -Match contains children, which are conjuncts of the predicate. -(I.e., each of the children must be true for the predicate to be true.) - -======================= -Types of Match clauses: -======================= - - <BugCode> specifies abbreviations of bugs. - The "name" attribute is a comma-seperated list of abbreviations. - - <Method> specifies a method. The "name" attribute is the name - of the method. The "params" attribute is a comma separated list - of the types of the method's parameters. The "returns" attribute is - the method's return type. In "params" and "returns", class names - must be fully qualified. (E.g., "java.lang.String" instead of just - "String".) Note that "params" and "returns" are optional; you can - just specify "name", and the clause will match all methods with - that name. However, if you specify either "params" or "returns", - you must specify both of them. - - <Or> combines Match clauses as disjuncts. I.e., you can put two - "Method" elements in an Or clause in order match either method. - -======== -Caveats: -======== - -Match 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. - -Some bug instances have two 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 FIRST (primary) class is matched against Match 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 Match clauses: - - <Match class="com.foobar.A"> - <BugCode name="IC" /> - </Match> - - <Match class="com.foobar.B"> - <BugCode name="IC" /> - </Match> - -Many kinds of bugs report what method they occur in. For those bug instances, -you can put Method clauses in the Match element and they should work -as expected. - -========= -Examples: -========= - - 1. Match all bug reports for a class. - - <Match class="com.foobar.MyClass" /> - - 2. Match certain tests from a class. - <Match class="com.foobar.MyClass"> - <BugCode name="DE,UrF,SIC" /> - </Match> - - 3. Match certain tests from all classes. - - <Match classregex=".*" > - <BugCode name="DE,UrF,SIC" /> - </Match> - - 4. Match bug types from specified methods of a class. - - <Match class="com.foobar.MyClass"> - <Or> - <Method name="frob" params="int,java.lang.String" returns="void" /> - <Method name="blat" params="" returns="boolean" /> - </Or> - <BugCode name="DC" /> - </Match> - -================= -Complete Example: -================= - -<FindBugsFilter> - <Match class="com.foobar.ClassNotToBeAnalyzed" /> - - <Match class="com.foobar.ClassWithSomeBugsMatched"> - <BugCode name="DE,UrF,SIC" /> - </Match> - - <!-- Match all XYZ violations. --> - <Match classregex=".*" > - <BugCode name="XYZ" /> - </Match> - - <!-- Match all doublecheck violations in these methods of "AnotherClass". --> - <Match class="com.foobar.AnotherClass"> - <Or> - <Method name="nonOverloadedMethod" /> - <Method name="frob" params="int,java.lang.String" returns="void" /> - <Method name="blat" params="" returns="boolean" /> - </Or> - <BugCode name="DC" /> - </Match> -</FindBugsFilter> |