第8章 フィルターファイル

概念的に言えば、フィルターはバグ検索結果をある基準と照合します。フィルターを定義することで、 特別な取り扱いをするバグ検索結果を選択することができます。例えば、あるバグ検索結果をバグ報告に含めたり、バグ報告から除外したりすることができます。

フィルターファイルは、 XML 文書です。最上位要素が　FindBugsFilter 要素 であり、その子要素として Match 要素を複数個定義します。それぞれの Match 要素は、生成されたバグ検索結果に適用される述部にあたります。通常、フィルターはバグ検索結果を除外するために使用します。次に、例を示します:

$ findbugs -textui -exclude myExcludeFilter.xml myApp.jar

また一方で、的をしぼった報告を得るためにバグ報告結果を選択するためにフィルターを使用することも考えられます :

$ findbugs -textui -include myIncludeFilter.xml myApp.jar

Match 要素は子要素を持ちます。それらの子要素は論理積で述部になります。つまり、述部が真であるためには、すべての子要素が真である必要があります。

Class 、 Source 、 Method または Field の name 属性が文字 ~ で始まっている場合は、 属性値の残りの部分を Java の正規表現として解釈します。 そうして、当該 Java 要素の名前に対しての照合が行われます。

パターンの照合は要素の名前全体に対して行われることに注意してください。そのため、部分一致照合を行いたい場合はパターン文字列の前後に .* を付加して使用する必要があります。

パターンの構文規則に関しては、 java.util.regex.Pattern のドキュメントを参照してください。

Match 条項は、バグ検索結果に実際に含まれている情報にのみ一致します。すべてのバグ検索結果はクラスを持っています。したがって、一般的に言って、バグを除外するためにはクラスを用いて行うとうまくいくことが多いです。

バグ検索結果の中には、2個以上のクラスを保持しているものもあります。例えば、 DE (dropped exception : 例外の無視) バグは、 例外の無視が発生したメソッドを持っているクラスと、 無視された例外の型を表すクラスの両方を含んだ形で報告されます。Match 条項とは、 1番目 (主) のクラスのみが照合されます。したがって、例えば、クラス "com.foobar.A" 、 "com.foobar.B" 間での IC (initialization circularity : 初期化時の処理循環) バグ報告を抑止したい場合、以下に示すように 2つの Match 条項を使用します :

   <Match>
      <Class name="com.foobar.A" />
      <Bug code="IC" />
   </Match>

   <Match>
      <Class name="com.foobar.B" />
      <Bug code="IC" />
   </Match>

明示的に両方のクラスで照合することによって、循環しているどちらのクラスがバグ検索結果の 1 番目になっているかに関係なく一致させることができます。(もちろんこの方法は、処理循環が "com.foobar.A" 、 "com.foobar.B" に加えて3番目のクラスも含んでいる場合は図らずも失敗してしまう恐れがあります。)

多くの種類のバグ報告は、自身が出現したメソッドを報告します。それらのバグ検索結果に対しては、 Method 条項を Match 要素に加えると期待通りの動作をするでしょう。

1. 特定のクラスに対するすべてのバグ報告に一致させます。

     <Match>
       <Class name="com.foobar.MyClass" />
     </Match>

2. バグ略称を指定して、特定のクラスに対する特定の検査項目に一致させます。

     <Match>
       <Class name="com.foobar.MyClass"/ >
       <Bug code="DE,UrF,SIC" />
     </Match>

3. バグ略称を指定して、すべてのクラスに対する特定の検査項目に一致させます。

     <Match>
       <Bug code="DE,UrF,SIC" />
     </Match>

4. バグカテゴリーを指定して、すべてのクラスに対する特定の検査項目に一致させます。

     <Match>
       <Bug category="PERFORMANCE" />
     </Match>

5. バグ略称を指定して、特定のクラスの指定されたメソッドに対する特定のバグ種別に一致させます。

     <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>

6. 特定のメソッドに対する特定のバグパターンに一致させます。

    <!-- open stream に関する誤検出があるメソッド。-->
    <Match>
      <Class name="com.foobar.MyClass" />
      <Method name="writeDataToFile" />
      <Bug pattern="OS_OPEN_STREAM" />
    </Match>

7. 特定のメソッドに対する特定の優先度を付与された特定のバグパターンに一致させます。

    <!-- dead local store (優先度 (中)) に関する誤検出があるメソッド。-->
    <Match>
      <Class name="com.foobar.MyClass" />
      <Method name="someMethod" />
      <Bug pattern="DLS_DEAD_LOCAL_STORE" />
      <Priority value="2" />
    </Match>

8. AspectJ コンパイラーによって引き起こされるマイナーバグに一致させます (AspectJ の開発者でもない限り、それらのバグに関心を持つことはないと考えます)。

    <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>

9. 基盤コードの特定の部分に対するバグに一致させます

    <!-- すべてのパッケージにある Messages クラスに対する unused fields 警告に一致。 -->
    <Match>
      <Class name="~.*\.Messages" />
      <Bug code="UUF" />
    </Match>
    <!-- すべての internal パッケージ内の mutable statics 警告に一致。 -->
    <Match>
      <Package name="~.*\.internal" />
      <Bug code="MS" />
    </Match>
    <!-- ui パッケージ階層内の anonymoous inner classes 警告に一致。 -->
    <Match>
      <Package name="~com\.foobar\.fooproject\.ui.*" />
      <Bug pattern="SIC_INNER_SHOULD_BE_STATIC_ANON" />
    </Match>

10. 特定のシグニチャーを持つフィールドまたはメソッドのバグに一致させます。

    <!-- すべてのクラスの main(String[]) メソッドに対する System.exit(...) usage 警告に一致。 -->
    <Match>
      <Method returns="void" name="main" params="java.lang.String[]" />
      <Method pattern="DM_EXIT" />
    </Match>
    <!-- すべてのクラスの com.foobar.DebugInfo 型のフィールドに対する UuF 警告に一致。 -->
    <Match>
      <Field type="com.foobar.DebugInfo" />
      <Bug code="UuF" />
    </Match>

11. Not フィルター演算子を使用してバグに一致させます。

<!-- テストクラスのバグは無視する。ただし、 JUnit テスト特有のバグは例外とする。 -->
<!-- i.e. filter bug if ( classIsJUnitTest && ! bugIsRelatedToJUnit ) -->
<Match>
  <!-- Match フィルタは論理和と同等 -->

  <Class name="~.*\.*Test" />
  <!-- テストクラスは末尾に「Test」 -->

  <Not>
      <Bug code="IJU" /> <!-- 「IJU」は JUnit テストコード関連のバグコード -->
  </Not>
</Match>

12. 完全な除外フィルター。 Groovy ソースファイルから生成された全クラスを除外します。

<?xml version="1.0" encoding="UTF-8"?>
<FindBugsFilter>
<Match>
    <Source name="~.*\.groovy" />
</Match>
</FindBugsFilter>

<FindBugsFilter>
     <Match>
       <Class name="com.foobar.ClassNotToBeAnalyzed" />
     </Match>

     <Match>
       <Class name="com.foobar.ClassWithSomeBugsMatched" />
       <Bug code="DE,UrF,SIC" />
     </Match>

     <!-- XYZ 違反に一致。-->
     <Match>
       <Bug code="XYZ" />
     </Match>

     <!-- "AnotherClass" の特定のメソッドの doublecheck 違反に一致。-->
     <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>

     <!-- dead local store (優先度 (中)) に関する誤検出があるメソッド。-->
     <Match>
       <Class name="com.foobar.MyClass" />
       <Method name="someMethod" />
       <Bug pattern="DLS_DEAD_LOCAL_STORE" />
       <Priority value="2" />
     </Match>

     <!-- テストクラスのバグすべて。 JUnit 特有のバグは除く。 -->
     <Match>
      <Class name="~.*\.*Test" />
      <Not>
          <Bug code="IJU" />
      </Not>
     </Match>

</FindBugsFilter>