summaryrefslogtreecommitdiff
path: root/tools/findbugs/doc/FilterFile.txt
diff options
context:
space:
mode:
Diffstat (limited to 'tools/findbugs/doc/FilterFile.txt')
-rw-r--r--tools/findbugs/doc/FilterFile.txt125
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>