1<html><head> 2 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 3 <title>第8章 フィルターファイル</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="FindBugs™ マニュアル"><link rel="up" href="index.html" title="FindBugs™ マニュアル"><link rel="prev" href="eclipse.html" title="第7章 FindBugs™ Eclipse プラグインの使用方法"><link rel="next" href="analysisprops.html" title="第9章 分析プロパティー"></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">第8章 フィルターファイル</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="eclipse.html">戻る</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="analysisprops.html">次へ</a></td></tr></table><hr></div><div class="chapter" title="第8章 フィルターファイル"><div class="titlepage"><div><div><h2 class="title"><a name="filter"></a>第8章 フィルターファイル</h2></div></div></div><div class="toc"><p><b>目次</b></p><dl><dt><span class="sect1"><a href="filter.html#d0e1709">1. フィルターファイルの概要</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e1759">2. マッチング条件の種類</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e1958">3. Java 要素名マッチング</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e1982">4. 留意事項</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e2012">5. 例</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e2065">6. 完全な例</a></span></dt></dl></div><p>フィルターファイルを使用することで、特定のクラスやメソッドをバグ報告に含めたりバグ報告から除外したりすることができます。この章では、フィルターファイルの使用方法を説明します。</p><div class="note" title="計画されている機能" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note: 計画されている機能"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[注記]" src="note.png"></td><th align="left">計画されている機能</th></tr><tr><td align="left" valign="top"><p>フィルターは現在、コマンドラインインタフェースでのみサポートされています。最終的には、フィルターのサポートは GUI にも追加される予定です。</p></td></tr></table></div><p> 4</p><div class="sect1" title="1. フィルターファイルの概要"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1709"></a>1. フィルターファイルの概要</h2></div></div></div><p>概念的に言えば、フィルターはバグ検索結果をある基準と照合します。フィルターを定義することで、 特別な取り扱いをするバグ検索結果を選択することができます。例えば、あるバグ検索結果をバグ報告に含めたり、バグ報告から除外したりすることができます。</p><p>フィルターファイルは、 <a class="ulink" href="http://www.w3.org/XML/" target="_top">XML</a> 文書です。最上位要素が　<code class="literal">FindBugsFilter</code> 要素 であり、その子要素として <code class="literal">Match</code> 要素を複数個定義します。それぞれの <code class="literal">Match</code> 要素は、生成されたバグ検索結果に適用される述部にあたります。通常、フィルターはバグ検索結果を除外するために使用します。次に、例を示します:</p><pre class="screen"> 5<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> 6</pre><p>また一方で、的をしぼった報告を得るためにバグ報告結果を選択するためにフィルターを使用することも考えられます :</p><pre class="screen"> 7<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> 8</pre><p> 9</p><p> 10<code class="literal">Match</code> 要素は子要素を持ちます。それらの子要素は論理積で述部になります。つまり、述部が真であるためには、すべての子要素が真である必要があります。</p></div><div class="sect1" title="2. マッチング条件の種類"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1759"></a>2. マッチング条件の種類</h2></div></div></div><div class="variablelist"><dl><dt><span class="term"><code class="literal"><Bug></code></span></dt><dd><p>この要素は、バグパターンを指定して照合します。<code class="literal">pattern</code> 属性には、コンマ区切りでバグパターン類型のリストを指定します。どの警告がどのバグパターン類型にあたるかは、 <span class="command"><strong>-xml</strong></span> オプションをつかって出力されたもの (<code class="literal">BugInstance</code> 要素の <code class="literal">type</code> 属性) を見るか、または、 <a class="ulink" href="/bugDescriptions.html" target="_top">バグ解説ドキュメント</a>を参照してください。</p><p>もっと粒度の粗い照合を行いたいときは、 <code class="literal">code</code> 属性を使用してください。バグ略称のコンマ区切りのリストで指定できます。さらに粒度の粗い照合を行いたいときは、 <code class="literal">category</code> 属性を使用してください。次に示す、バグカテゴリー名のコンマ区切りのリストで指定できます : <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>同じ <code class="literal"><Bug></code> 要素に上記の属性を複数指定した場合は、バグパターン名、バグ略称、バグカテゴリーのいずれか1つでも該当すれば、バグパターンは合致すると判定されます。</p><p>下位互換性を持たせたい場合は、 <code class="literal"><Bug></code> 要素の代わりに <code class="literal"><BugPattern></code> 要素および <code class="literal"><BugCode></code> 要素を使用してください。これらの要素はそれぞれ、 <code class="literal">name</code> 属性で値のリストを指定します。これらの要素は、将来サポートされなくなる可能性があります。</p></dd><dt><span class="term"><code class="literal"><Priority></code></span></dt><dd><p>この要素は、特定の優先度をもつ警告を照合します。<code class="literal">value</code> 属性には、整数値を指定します : 1 は優先度(高)、また、 2 は優先度(中) 、 3 は優先度(低) を示します。</p></dd><dt><span class="term"><code class="literal"><Package></code></span></dt><dd><p>この要素は、 <code class="literal">name</code> 属性で指定した特定のパッケージ内にあるクラスに関連した警告を照合します。入れ子のパッケージは含まれません (Java import 文に従っています) 。しかしながら、正規表現を使うと複数パッケージにマッチさせることは簡単にできます。</p></dd><dt><span class="term"><code class="literal"><Class></code></span></dt><dd><p>この要素は、特定のクラスに関連した警告を照合します。<code class="literal">name</code> 属性を使用して、照合するクラス名をクラス名そのものか、または、正規表現で指定します。</p><p>下位互換性を持たせたい場合は、この要素の代わりに <code class="literal">Match</code> 要素を使用してください。クラス名そのものの指定は <code class="literal">class</code> 属性を、クラス名を正規表現で指定する場合は <code class="literal">classregex</code> 属性をそれぞれ使用してください</p><p>もし <code class="literal">Match</code> 要素に <code class="literal">Class</code> 要素が無かったり、 <code class="literal">class</code> / <code class="literal">classregex</code> 属性が無かったりした場合は、すべてのクラスに適用されます。その場合、想定外に多くのバグ検索結果が一致してしまうことがあり得ます。その場合は、適当なメソッドやフィールドで絞り込んでください。</p></dd><dt><span class="term"><code class="literal"><Method></code></span></dt><dd><p>この要素は、メソッドを指定します。<code class="literal">name</code> 属性を使用して、照合するメソッド名をメソッド名そのものか、または、正規表現で指定します。<code class="literal">params</code> 属性には、コンマ区切りでメソッド引数の型のリストを指定します。<code class="literal">returns</code> 属性にはメソッドの戻り値の型を指定します。<code class="literal">params</code> および <code class="literal">returns</code> においては、クラス名は完全修飾名である必要があります。(例えば、単に "String" ではなく "java.lang.String" としてください。) <code class="literal">params</code> <code class="literal">returns</code> のどちらか一方を指定した場合は、もう一方の属性の指定も必須です。なぜならば、メソッドシグニチャーを構築のために必要だからです。<code class="literal">name</code> 属性、<code class="literal">params</code> 属性 および <code class="literal">returns</code> 属性または 3 つの 属性すべて、のどれかを条件とすることできることを意味しています。このように、名前とシグニチャーに基づく様々な種類の条件を規定できます。</p></dd><dt><span class="term"><code class="literal"><Field></code></span></dt><dd><p>この要素は、フィールドを指定します。<code class="literal">name</code> 属性を使用して、照合するフィールド名をフィールド名そのものか、または、正規表現で指定します。また、フィールドのシグニチャーに照らしたフィルタリングをすることができます。 <code class="literal">type</code> 属性を使用して、フィールドの型を完全修飾名で指定してください。名前とシグニチャーに基づく条件を規定するために、その2つの属性を両方とも指定することができます。</p></dd><dt><span class="term"><code class="literal"><Local></code></span></dt><dd><p>この要素は、ローカル変数を指定します。<code class="literal">name</code> 属性を使用して、照合するローカル変数名をローカル変数名そのものか、または、正規表現で指定します。ローカル変数とは、メソッド内で定義した変数です。</p></dd><dt><span class="term"><code class="literal"><Or></code></span></dt><dd><p>この要素は、論理和として <code class="literal">Match</code> 条項を結合します。すなわち、2つの <code class="literal">Method</code> 要素を <code class="literal">Or</code> 条項に入れることで、どちらか一方のメソッドでマッチさせることができます。</p></dd></dl></div></div><div class="sect1" title="3. Java 要素名マッチング"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1958"></a>3. Java 要素名マッチング</h2></div></div></div><p><code class="literal">Class</code> 、 <code class="literal">Method</code> または <code class="literal">Field</code> の <code class="literal">name</code> 属性が文字 ~ で始まっている場合は、属性値の残りの部分を Java の正規表現として解釈します。そうして、当該 Java 要素の名前に対しての照合が行われます。</p><p>パターンの照合は要素の名前全体に対して行われることに注意してください。そのため、部分一致照合を行いたい場合はパターン文字列の前後に .* を付加して使用する必要があります。</p><p>パターンの構文規則に関しては、 <a class="ulink" href="http://java.sun.com/j2se/1.5.0/ja/docs/ja/api/java/util/regex/Pattern.html" target="_top"><code class="literal">java.util.regex.Pattern</code></a> のドキュメントを参照してください。</p></div><div class="sect1" title="4. 留意事項"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1982"></a>4. 留意事項</h2></div></div></div><p> 11<code class="literal">Match</code> 条項は、バグ検索結果に実際に含まれている情報にのみ一致します。すべてのバグ検索結果はクラスを持っています。したがって、一般的に言って、バグを除外するためにはクラスを用いて行うとうまくいくことが多いです。</p><p>バグ検索結果の中には、2個以上のクラスを保持しているものもあります。例えば、 DE (dropped exception : 例外の無視) バグは、 例外の無視が発生したメソッドを持っているクラスと、 無視された例外の型を表すクラスの両方を含んだ形で報告されます。<code class="literal">Match</code> 条項とは、 <span class="emphasis"><em>1番目</em></span> (主) のクラスのみが照合されます。したがって、例えば、クラス "com.foobar.A" 、 "com.foobar.B" 間での IC (initialization circularity : 初期化時の処理循環) バグ報告を抑止したい場合、以下に示すように 2つの <code class="literal">Match</code> 条項を使用します :</p><pre class="programlisting"> 12 <Match> 13 <Class name="com.foobar.A" /> 14 <Bug code="IC" /> 15 </Match> 16 17 <Match> 18 <Class name="com.foobar.B" /> 19 <Bug code="IC" /> 20 </Match> 21</pre><p>明示的に両方のクラスで照合することによって、循環しているどちらのクラスがバグ検索結果の 1 番目になっているかに関係なく一致させることができます。(もちろんこの方法は、処理循環が "com.foobar.A" 、 "com.foobar.B" に加えて3番目のクラスも含んでいる場合は図らずも失敗してしまう恐れがあります。)</p><p>多くの種類のバグ報告は、自身が出現したメソッドを報告します。それらのバグ検索結果に対しては、 <code class="literal">Method</code> 条項を <code class="literal">Match</code> 要素に加えると期待通りの動作をするでしょう。</p></div><div class="sect1" title="5. 例"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2012"></a>5. 例</h2></div></div></div><p>1. 特定のクラスに対するすべてのバグ報告に一致させます。</p><pre class="programlisting"> 22 23 <Match> 24 <Class name="com.foobar.MyClass" /> 25 </Match> 26 27</pre><p> 28 29</p><p>2. バグ略称を指定して、特定のクラスに対する特定の検査項目に一致させます。</p><pre class="programlisting"> 30 31 <Match> 32 <Class name="com.foobar.MyClass"/ > 33 <Bug code="DE,UrF,SIC" /> 34 </Match> 35 36</pre><p> 37</p><p>3. バグ略称を指定して、すべてのクラスに対する特定の検査項目に一致させます。</p><pre class="programlisting"> 38 39 <Match> 40 <Bug code="DE,UrF,SIC" /> 41 </Match> 42 43</pre><p> 44</p><p>4. バグカテゴリーを指定して、すべてのクラスに対する特定の検査項目に一致させます。</p><pre class="programlisting"> 45 46 <Match> 47 <Bug category="PERFORMANCE" /> 48 </Match> 49 50</pre><p> 51</p><p>5. バグ略称を指定して、特定のクラスの指定されたメソッドに対する特定のバグ種別に一致させます。</p><pre class="programlisting"> 52 53 <Match> 54 <Class name="com.foobar.MyClass" /> 55 <Or> 56 <Method name="frob" params="int,java.lang.String" returns="void" /> 57 <Method name="blat" params="" returns="boolean" /> 58 </Or> 59 <Bug code="DC" /> 60 </Match> 61 62</pre><p> 63</p><p>6. 特定のメソッドに対する特定のバグパターンに一致させます。</p><pre class="programlisting"> 64 65 <!-- open stream に関する誤検出があるメソッド。--> 66 <Match> 67 <Class name="com.foobar.MyClass" /> 68 <Method name="writeDataToFile" /> 69 <Bug pattern="OS_OPEN_STREAM" /> 70 </Match> 71 72</pre><p> 73</p><p>7. 特定のメソッドに対する特定の優先度を付与された特定のバグパターンに一致させます。</p><pre class="programlisting"> 74 75 <!-- dead local store (優先度 (中)) に関する誤検出があるメソッド。--> 76 <Match> 77 <Class name="com.foobar.MyClass" /> 78 <Method name="someMethod" /> 79 <Bug pattern="DLS_DEAD_LOCAL_STORE" /> 80 <Priority value="2" /> 81 </Match> 82 83</pre><p> 84</p><p>8. AspectJ コンパイラーによって引き起こされるマイナーバグに一致させます (AspectJ の開発者でもない限り、それらのバグに関心を持つことはないと考えます)。</p><pre class="programlisting"> 85 86 <Match> 87 <Class name="~.*\$AjcClosure\d+" /> 88 <Bug pattern="DLS_DEAD_LOCAL_STORE" /> 89 <Method name="run" /> 90 </Match> 91 <Match> 92 <Bug pattern="UUF_UNUSED_FIELD" /> 93 <Field name="~ajc\$.*" /> 94 </Match> 95 96</pre><p> 97</p><p>9. 基盤コードの特定の部分に対するバグに一致させます</p><pre class="programlisting"> 98 99 <!-- すべてのパッケージにある Messages クラスに対する unused fields 警告に一致。 --> 100 <Match> 101 <Class name="~.*\.Messages" /> 102 <Bug code="UUF" /> 103 </Match> 104 <!-- すべての internal パッケージ内の mutable statics 警告に一致。 --> 105 <Match> 106 <Package name="~.*\.internal" /> 107 <Bug code="MS" /> 108 </Match> 109 <!-- ui パッケージ階層内の anonymoous inner classes 警告に一致。 --> 110 <Match> 111 <Package name="~com\.foobar\.fooproject\.ui.*" /> 112 <Bug pattern="SIC_INNER_SHOULD_BE_STATIC_ANON" /> 113 </Match> 114 115</pre><p> 116</p><p>10. 特定のシグニチャーを持つフィールドまたはメソッドのバグに一致させます。</p><pre class="programlisting"> 117 118 <!-- すべてのクラスの main(String[]) メソッドに対する System.exit(...) usage 警告に一致。 --> 119 <Match> 120 <Method returns="void" name="main" params="java.lang.String[]" /> 121 <Method pattern="DM_EXIT" /> 122 </Match> 123 <!-- すべてのクラスの com.foobar.DebugInfo 型のフィールドに対する UuF 警告に一致。 --> 124 <Match> 125 <Field type="com.foobar.DebugInfo" /> 126 <Bug code="UuF" /> 127 </Match> 128 129</pre><p> 130 131</p></div><div class="sect1" title="6. 完全な例"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2065"></a>6. 完全な例</h2></div></div></div><pre class="programlisting"> 132 133<FindBugsFilter> 134 <Match> 135 <Class name="com.foobar.ClassNotToBeAnalyzed" /> 136 </Match> 137 138 <Match> 139 <Class name="com.foobar.ClassWithSomeBugsMatched" /> 140 <Bug code="DE,UrF,SIC" /> 141 </Match> 142 143 <!-- XYZ 違反に一致。--> 144 <Match> 145 <Bug code="XYZ" /> 146 </Match> 147 148 <!-- "AnotherClass" の特定のメソッドの doublecheck 違反に一致。--> 149 <Match> 150 <Class name="com.foobar.AnotherClass" /> 151 <Or> 152 <Method name="nonOverloadedMethod" /> 153 <Method name="frob" params="int,java.lang.String" returns="void" /> 154 <Method name="blat" params="" returns="boolean" /> 155 </Or> 156 <Bug code="DC" /> 157 </Match> 158 159 <!-- dead local store (優先度 (中)) に関する誤検出があるメソッド。--> 160 <Match> 161 <Class name="com.foobar.MyClass" /> 162 <Method name="someMethod" /> 163 <Bug pattern="DLS_DEAD_LOCAL_STORE" /> 164 <Priority value="2" /> 165 </Match> 166</FindBugsFilter> 167 168</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">戻る</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="analysisprops.html">次へ</a></td></tr><tr><td width="40%" align="left" valign="top">第7章 <span class="application">FindBugs</span>™ Eclipse プラグインの使用方法 </td><td width="20%" align="center"><a accesskey="h" href="index.html">ホーム</a></td><td width="40%" align="right" valign="top"> 第9章 分析プロパティー</td></tr></table></div></body></html>
