manual_ja.xml - Android社区 - https://www.androidos.net.cn/

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://findbugs.googlecode.com/svn/trunk/findbugs/etc/docbook/docbookx.dtd"
[
<!ENTITY FindBugs "<application>FindBugs</application>">
<!ENTITY Ant "<application>Ant</application>">
<!ENTITY Saxon "<application>Saxon</application>">
<!ENTITY FBHome "<replaceable>$FINDBUGS_HOME</replaceable>">
<!ENTITY FBHomeWin "<replaceable>%FINDBUGS_HOME%</replaceable>">
<!ENTITY nbsp " ">
]>
<book lang="ja" id="findbugs-manual">

<bookinfo>
<title>&FindBugs;™ マニュアル</title>

<authorgroup>
  <author>
    <firstname>David</firstname>
    <othername>H.</othername>
    <surname>Hovemeyer</surname>
  </author>
    <author>
        <firstname>William</firstname>
        <othername>W.</othername>
        <surname>Pugh</surname>
    </author>
</authorgroup>

<copyright>
  <year>2003</year>
  <year>2004</year>
  <year>2005</year>
  <year>2006</year>
  <year>2008</year>
  <holder>University of Maryland</holder>
</copyright>

<legalnotice>
<para>このマニュアルは、クリエイティブ・コモンズ表示-非営利-継承に基づく使用許諾がなされています。使用許諾書をご覧になる場合は、 <ulink url="http://creativecommons.org/licenses/by-nc-sa/1.0/deed.ja">http://creativecommons.org/licenses/by-nc-sa/1.0/</ulink> にアクセスするか、クリエイティブ・コモンズ(559 Nathan Abbott Way, Stanford, California 94305, USA)に書簡を送付してください。</para>
<para>名称「FindBugs」および FindBugs のロゴは、メリーランド大学の登録商標です。</para>
</legalnotice>

<pubdate>17:16:15 EST, 22 November, 2013</pubdate>

</bookinfo>

<para>&FindBugs;™ は、Java プログラムの中のバグを見つけるプログラムです。このプログラムは、「バグ パターン」の実例を探します。「バグ パターン」とは、エラーとなる可能性の高いコードの事例です。</para>

<para>この文書は、&FindBugs; バージョン 2.0.3 について説明してます。私たちは、 &FindBugs; に対するフィードバックを心待ちにしています。どうぞ、 <ulink url="http://findbugs.sourceforge.net">&FindBugs; Web ページ</ulink> にアクセスしてください。&FindBugs; についての最新情報、連絡先および &FindBugs; メーリングリストなどのサポート情報を入手することができます。</para>

<sect1>
<title>必要条件</title>
<para>&FindBugs; を使用するには、 <ulink url="http://java.sun.com/j2se">Java 2 Standard Edition</ulink>, バージョン 1.5 以降のバージョンと互換性のあるランタイム環境が必要です。&FindBugs; は、プラットフォーム非依存であり、 GNU/Linux 、 Windows 、 MacOS X プラットフォーム上で動作することが知られています。</para>

<para>&FindBugs; を使用するためには、少なくとも 512 MB のメモリが必要です。巨大なプロジェクトを解析するためには、それより多くのメモリが必要とされることがあります。</para>
</sect1>

</chapter>

<chapter id="installing">
<title>&FindBugs;™ のインストール</title>

<para>この章では、 &FindBugs; のインストール方法を説明します。</para>

<sect1>
<title>配布物の展開</title>

<para>&FindBugs; をインストールする最も簡単な方法は、バイナリ配布物をダウンロードすることです。 バイナリ配布物は、 <ulink url="http://prdownloads.sourceforge.net/findbugs/findbugs-2.0.3.tar.gz?download">gzipped tar 形式</ulink> および <ulink url="http://prdownloads.sourceforge.net/findbugs/findbugs-2.0.3.zip?download">zip 形式</ulink> がそれぞれ入手可能です。バイナリ配布物をダウンロードしてきたら、それを任意のディレクトリーに展開します。</para>

<para>gzipped tar 形式配布物の展開方法例:<screen>
<prompt>$ </prompt><command>gunzip -c findbugs-2.0.3.tar.gz | tar xvf -</command>
</screen>
</para>

<para>zip 形式配布物の展開方法例:<screen>
<prompt>C:\Software></prompt><command>unzip findbugs-2.0.3.zip</command>
</screen>
</para>

<para>バイナリ配布物の展開すると、通常は <filename class="directory">findbugs-2.0.3</filename> ディレクトリーが作成されます。例えば、ディレクトリー <filename class="directory">C:\Software</filename> でバイナリ配布物を展開すると、ディレクトリー <filename class="directory">C:\Software\findbugs-2.0.3</filename> に &FindBugs; は展開されます。このディレクトリーが &FindBugs; のホームディレクトリーになります。このマニュアルでは、このホームディレクトリーを &FBHome; (Windowsでは &FBHomeWin;) を用いて参照します。</para>
</sect1>

</chapter>

<chapter id="building">
<title>&FindBugs;™ のソールからのビルド</title>

<para>この章では、 &FindBugs; をソースコードからビルドする方法を説明します。&FindBugs; を修正することに興味がないのであれば、 <link linkend="running">次の章</link> に進んでください。</para>

<para>ソースから &FindBugs; をコンパイルするためには、以下のものが必要です。<itemizedlist>
  <listitem>
    <para><ulink url="http://prdownloads.sourceforge.net/findbugs/findbugs-2.0.3-source.zip?download">&FindBugs; のソース配布物</ulink>
    </para>
  </listitem>
  <listitem>
    <para>
      <ulink url="http://java.sun.com/j2se/">JDK 1.5.0 ベータ またはそれ以降</ulink>
    </para>
  </listitem>
  <listitem>
    <para>
      <ulink url="http://ant.apache.org/">Apache &Ant;</ulink>, バージョン 1.6.3 またはそれ以降</para>
  </listitem>
</itemizedlist>
</para>

<warning>
    <para>Redhat Linux システムの <filename>/usr/bin/ant</filename> に同梱されている &Ant; のバージョンでは、 &FindBugs; のコンパイルは<emphasis>うまくできません</emphasis>。<ulink url="http://ant.apache.org/">&Ant; web サイト</ulink>からバイナリ配布物をダウンロードしてインストールすることを推奨します。&Ant; を実行する場合は、 環境変数 <replaceable>JAVA_HOME</replaceable> が  JDK 1.5 (またはそれ以降)をインストールしたディレクトリーを指していることを確認してください。</para>
</warning>

<para>体裁の整った &FindBugs; のドキュメントを生成したい場合は、以下のソフトウェアも必要となります:<itemizedlist>
  <listitem>
    <para><ulink url="http://docbook.sourceforge.net/projects/xsl/index.html">DocBook XSL スタイルシート</ulink>。&FindBugs; のマニュアルを HTML に変換するのに必要です。</para>
  </listitem>
  <listitem>
    <para><ulink url="http://saxon.sourceforge.net/">&Saxon; XSLT プロセッサー</ulink>。(同様に、 &FindBugs; のマニュアルを HTML に変換するのに必要です。)</para>
  </listitem>

</itemizedlist>
</para>

</sect1>

<sect1>
<title>ソース配布物の展開</title>
<para>ソース配布物をダウンロードした後に、それを作業用ディレクトリーに展開する必要があります。通常は、次のようなコマンドで展開を行います:<screen>
<prompt>$ </prompt><command>unzip findbugs-2.0.3-source.zip</command>
</screen>

</para>
</sect1>

<sect1>
<title><filename>local.properties</filename> の修正</title>
<para>FindBugs のドキュメントをビルドするためには、 <filename>local.properties</filename> ファイルを修正する必要があります。このファイルは、 &FindBugs; をビルドする際に <ulink url="http://ant.apache.org/">&Ant;</ulink> <filename>build.xml</filename> ファイルが参照します。FindBugs のドキュメントをビルドしない場合は、このファイルは無視してもかまいません。</para>

<para><filename>local.properties</filename> での定義は、 <filename>build.properties</filename> ファイルでの定義に優先します。<filename>build.properties</filename> は次のような内容です:<programlisting>
<![CDATA[
# User Configuration:
# This section must be modified to reflect your system.

local.software.home     =/export/home/daveho/linux

# Set this to the directory containing the DocBook Modular XSL Stylesheets
#  from http://docbook.sourceforge.net/projects/xsl/

xsl.stylesheet.home     =${local.software.home}/docbook/docbook-xsl-1.71.1

# Set this to the directory where Saxon (http://saxon.sourceforge.net/)
# is installed.

saxon.home              =${local.software.home}/java/saxon-6.5.5
]]>
</programlisting>
</para>

<para><varname>xsl.stylesheet.home</varname> プロパティーには、<ulink url="http://docbook.sourceforge.net/projects/xsl/">DocBook Modular XSL スタイルシート</ulink>がインストールしてあるディレクトリーの絶対パスを指定します。&FindBugs; ドキュメントを生成しようと考えている場合にのみ、このプロパティーを指定する必要があります。</para>

<para><varname>saxon.home</varname> プロパティーには、<ulink url="http://saxon.sourceforge.net/">&Saxon; XSLT プロセッサー</ulink>がインストールしてあるディレクトリーの絶対パスを指定します。&FindBugs; ドキュメントを生成しようと考えている場合にのみ、このプロパティーを指定する必要があります。</para>

</sect1>

<para>ソース配布物の展開、 &Ant; のインストール、<filename>build.properties</filename>(<filename>local.properties</filename>) の修正 (これは任意) およびツール (&Saxon; など)の環境構築ができれば、 &FindBugs; をビルドするための準備は完了です。&Ant; の起動する方法は、単にコマンドを実行するだけです。<screen>
<prompt>$ </prompt><command>ant <replaceable>target</replaceable></command>
</screen><replaceable>target</replaceable> には以下のいずれかを指定します: <variablelist> <varlistentry> <term><command>build</command></term>
    <listitem>
       <para>このターゲットは、 &FindBugs; のコードをコンパイルします。これは、デフォルトのターゲットです。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><command>docs</command></term>
    <listitem>
       <para>このターゲットは、ドキュメントの整形を行います(また、副作用としていくつかのソースのコンパイルも行います。)</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><command>runjunit</command></term>
    <listitem>
        <para>このターゲットは、コンパイルを行い &FindBugs; が持っている JUnit テストを実行します。ユニットテストが失敗した場合は、エラーメッセージが表示されます。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><command>bindist</command></term>
    <listitem>
        <para>&FindBugs; のバイナリ配布物を構築します。このターゲットは、 <filename>.zip</filename> および <filename>.tar.gz</filename> のアーカイブをそれぞれ作成します。</para>
    </listitem>
  </varlistentry>
</variablelist>
</para>

<para>&Ant; コマンドの実行後、次のような出力が表示されるはずです。 (この前に &Ant; が実行したタスクに関するメッセージもいくらか出力されます。):<screen>
<computeroutput>
BUILD SUCCESSFUL
Total time: 17 seconds
</computeroutput>
</screen>
</para>

</sect1>

<sect1>
<title>ソースディレクトリーからの &FindBugs;™ の実行</title>
<para><command>build</command> ターゲットの実行が終了すると、バイナリ配布物と同様の状態が作業ディレクトリーに構築されるように &FindBugs; の&Ant; ビルドスクリプトは記述されています。したがって、<xref linkend="running"/> の  &FindBugs; の実行に関する情報はソース配布物の場合にも応用できます。</para>
</sect1>

</chapter>

<chapter id="running">
<title>&FindBugs;™ の実行</title>

<para>&FindBugs; には2つのユーザーインタフェースがあります。すなわち、グラフィカルユーザーインタフェース (GUI) および コマンドラインインタフェースです。この章では、それぞれのインタフェースの実行方法について説明します。</para>

<warning>
        <para>この章は、現在書き直し中です。書き直しはまだ完了していません。</para>
    </warning>

<sect1>
    <title>クイック・スタート</title>
    <para>Windows システムで  &FindBugs; を起動する場合は、 <filename>&FBHomeWin;\lib\findbugs.jar</filename> ファイルをダブルクリックしてください。 &FindBugs; GUI が起動します。</para>

<para>Unix 、 Linux または Mac OS X システムの場合は、<filename>&FBHome;/bin/findbugs</filename> スクリプトを実行するか、以下のコマンドを実行します。<screen>
<command>java -jar &FBHome;/lib/findbugs.jar</command></screen>これで、 &FindBugs; GUI が起動します。</para>

<para>GUI の使用方法については、 <xref linkend="gui"/> を参照してください。</para>
</sect1>

<sect1>

<title>&FindBugs; の起動</title>

<para>このセクションでは、 &FindBugs; の起動方法を説明します。&FindBugs; を起動するには2つの方法があります。すなわち、直接起動する方法、および、ラップしているスクリプトを使用する方法です。</para>

<sect2 id="directInvocation">
        <title>&FindBugs; の直接起動</title>

<para>最初に述べる &FindBugs; の起動方法は、 <filename>&FBHome;/lib/findbugs.jar</filename> を直接実行する方法です。JVM (<command>java</command>) 実行プログラムの <command>-jar</command> コマンドラインスイッチを使用します。(&FindBugs;のバージョンが 1.3.5 より前の場合は、ラップしているスクリプトを使用する必要があります。)</para>

<para>&FindBugs; を直接起動するための、一般的な構文は以下のようになります。<screen>
    <command>java <replaceable>[JVM 引数]</replaceable> -jar &FBHome;/lib/findbugs.jar <replaceable>オプション…</replaceable></command>
</screen>
        </para>

<sect3 id="chooseUI">
            <title> ユーザーインタフェースの選択</title>

<para>1 番目のコマンドラインオプションは、起動する &FindBugs; ユーザーインタフェースを選択するためのものです。指定可能な値は次の通りです:</para>
        <itemizedlist>
            <listitem>
                <para>
                <command>-gui</command>: グラフィカルユーザーインタフェース (GUI) を起動します。</para>
            </listitem>

<listitem>
                <para>
                    <command>-textui</command>: コマンドラインインタフェースを起動します。</para>
            </listitem>

<listitem>
                <para>
                    <command>-version</command>: &FindBugs; のバージョン番号を表示します。</para>
            </listitem>

<listitem>
                <para>
                    <command>-help</command>: &FindBugs; コマンドラインインタフェースのヘルプ情報を表示します。</para>
            </listitem>

<listitem>
                <para>
                    <command>-gui1</command>: 最初に作成された &FindBugs; グラフィカルユーザーインタフェース(すでに廃止されサポートされていない)を起動します。</para>
            </listitem>
        </itemizedlist>

</sect3>

<sect3 id="jvmArgs">
            <title>Java 仮想マシン (JVM) 引数</title>

<para>&FindBugs; を起動する際に有用な Java 仮想マシン 引数をいくつか紹介します。</para>

<variablelist>
                <varlistentry>
                    <term><command>-Xmx<replaceable>NN</replaceable>m</command></term>
                    <listitem>
                        <para>Java ヒープサイズの最大値を <replaceable>NN</replaceable> メガバイトに設定します。&FindBugs; は一般的に大容量のメモリサイズを必要とします。大きなプロジェクトでは、 1500 メガバイトを使用することも珍しくありません。</para>
                    </listitem>
                </varlistentry>

<varlistentry>
                    <term><command>-D<replaceable>name</replaceable>=<replaceable>value</replaceable></command></term>
                    <listitem>
                        <para>Java システムプロパティーを設定します。例えば、引数 <command>-Duser.language=ja</command> を使用すると GUI 文言が日本語で表示されます。</para>
                    </listitem>
                </varlistentry>

</variablelist>
        </sect3>

</sect2>

<sect2 id="wrapperScript">
        <title>ラップしているスクリプトを使用した &FindBugs; の起動</title>

<para>&FindBugs; を起動するもうひとつの方法は、ラップしているスクリプトを使用する方法です。</para>

<para>Unix 系のシステムにおいては、次のようなコマンドでラップしているスクリプトを起動します :<screen>
<prompt>$ </prompt><command>&FBHome;/bin/findbugs <replaceable>オプション…</replaceable></command>
</screen>
</para>

<para>Windows システムにおいては、ラップしているスクリプトを起動するコマンドは次のようになります。<screen>
<prompt>C:\My Directory></prompt><command>&FBHomeWin;\bin\findbugs.bat <replaceable>オプション…</replaceable></command>
</screen>
</para>

<para>Unix 系システム および Windows システムのどちらにおいても、ディレクトリー  <filename><replaceable>$FINDBUGS_HOME</replaceable>/bin</filename> を環境変数 <filename>PATH</filename> に追加するだけで、 <command>findbugs</command> コマンドを使用して FindBugs を起動することができます。</para>

<sect3 id="wrapperOptions">
        <title>ラップしているスクリプトのコマンドラインオプション</title>
        <para>&FindBugs; のラップしているスクリプトは、次のようなコマンドラインオプションをサポートしています。これらのコマンドラインオプションは &FindBugs; プログラム 自体が操作するのでは<emphasis>なく</emphasis>、どちらかといえば、ラップしているスクリプトの方が処理を行います。</para>
    <variablelist>
  <varlistentry>
    <term><command>-jvmArgs <replaceable>引数</replaceable></command></term>
    <listitem>
       <para>JVM に受け渡される引数を指定します。例えば、次のような JVM プロパティが設定できます:<screen>
<prompt>$ </prompt><command>findbugs -textui -jvmArgs "-Duser.language=ja" <replaceable>myApp.jar</replaceable></command>
</screen>
       </para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><command>-javahome <replaceable>ディレクトリー</replaceable></command></term>
    <listitem>
      <para>&FindBugs; の実行に使用する JRE (Java ランタイム環境) がインストールされているディレクトリーを指定します。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><command>-maxHeap <replaceable>サイズ</replaceable></command></term>
    <listitem>
      <para>Java ヒープサイズの最大値をメガバイト単位で指定します。デフォルトは、 256 です。巨大なプログラムやライブラリを分析するには、もっと大きなメモリー容量が必要になる可能性があります。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><command>-debug</command></term>
    <listitem>
      <para>ディテクタ実行およびクラス分析のトレース情報が標準出力に出力されます。分析が予期せず失敗した際の、トラブルシューティングに有用です。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><command>-property</command> <replaceable>name=value</replaceable></term>
    <listitem>
      <para>このオプションを使用してシステムプロパティーを設定することができます。 &FindBugs; はシステムプロパティーを使用して分析特性の設定を行います。<xref linkend="analysisprops"/> を参照してください。このオプションを複数指定して、複数のシステムプロパティを設定することが可能です。注:  Windows の多くのバージョンでは、 <replaceable>name=value</replaceable> 文字列を引用符で囲む必要があります。</para>
    </listitem>
  </varlistentry>

</variablelist>

</sect3>

</sect2>

</sect1>

<sect1 id="commandLineOptions">
<title>コマンドラインオプション</title>

<!--
<para>

There are two ways to invoke &FindBugs;.  The first invokes the the Graphical User Interface (GUI):

<screen>
<prompt>$ </prompt><command>findbugs <replaceable>[standard options]</replaceable> <replaceable>[GUI options]</replaceable></command>
</screen>

The second invokes the Command Line Interface (Text UI):

<screen>
<prompt>$ </prompt><command>findbugs -textui <replaceable>[standard options]</replaceable> <replaceable>[Text UI options]</replaceable></command>
</screen>
</para>
-->

<para>このセクションでは、 &FindBugs; がサポートするコマンドラインオプションについて説明します。ここで示すコマンドラインオプションは、 &FindBugs; 直接起動、または、ラップしているスクリプトによる起動で使用できます。</para>

<sect2>
<title>共通のコマンドラインオプション</title>

<para>ここで示すオプションは、 GUI および コマンドラインインタフェースの両方で使用できます。</para>

<varlistentry>
    <term><command>-effort:min</command></term>
    <listitem>
      <para>このオプションを指定すると、精度を上げるために大量のメモリーを消費する分析が無効になります。&FindBugs; の実行時にメモリー不足になったり、分析を完了するまでに異常に長い時間がかかる場合に試してみてください。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><command>-effort:max</command></term>
    <listitem>
      <para>精度が高く、より多くのバグを検出する分析を有効にします。ただし、多くのメモリー容量を必要とし、また、完了までの時間が多くかかる可能性があります。</para>
    </listitem>
  </varlistentry>

<varlistentry>
  <term><command>-project</command> <replaceable>project</replaceable></term>
  <listitem>
    <para>分析するプロジェクトを指定します。指定するプロジェクトファイルには、 GUI を使って作成したものを使用してください。ファイルの拡張子は、一般的には <filename>.fb</filename> または <filename>.fbp</filename> です。</para>
  </listitem>
  </varlistentry>

<!--
  <varlistentry>
      <term><command></command></term>
      <listitem>
          <para>

</para>
      </listitem>
  </varlistentry>
  -->

</variablelist>

</sect2>

<sect2>
<title>GUI オプション</title>

<para>ここで示すオプションは、グラフィカルユーザーインタフェースでのみ使用できます。<variablelist> <varlistentry> <term><command>-look:</command><replaceable>plastic|gtk|native</replaceable></term>
    <listitem>
       <para>Swing のルック・アンド・フィールを設定します。</para>
    </listitem>
  </varlistentry>

</variablelist>
</para>
</sect2>

<sect2>
<title>テキストユーザーインタフェースオプション</title>

<para>ここで示すオプションは、テキストユーザーインタフェースでのみ使用できます。</para>

<variablelist>
  <varlistentry>
    <term><command>-sortByClass</command></term>
    <listitem>
       <para>報告されるバグ検索結果をクラス名でソートします。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><command>-include</command> <replaceable>filterFile.xml</replaceable></term>
    <listitem>
       <para><replaceable>filterFile.xml</replaceable> で指定したフィルターに一致したバグ検索結果のみ報告されます。<xref linkend="filter"/> を参照してください。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><command>-exclude</command> <replaceable>filterFile.xml</replaceable></term>
    <listitem>
       <para><replaceable>filterFile.xml</replaceable> で指定したフィルターに一致したバグ検索結果は報告されません。<xref linkend="filter"/> を参照してください。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><command>-onlyAnalyze</command> <replaceable>com.foobar.MyClass,com.foobar.mypkg.*</replaceable></term>
    <listitem>
      <para>コンマ区切りで指定したクラスおよびパッケージのみに限定して、バグ検出の分析を行うようにします。フィルターと違って、このオプションを使うと一致しないクラスおよびパッケージに対する分析の実行を回避することができます。大きなプロジェクトにおいて、このオプションを活用すると分析にかかる時間を大きく削減することができる可能性があります。(しかしながら、アプリケーションの全体で実行していないために不正確な結果を出してしまうディテクタがある可能性もあります。) クラスはパッケージも含んだ完全な名前を指定する必要があります。また、パッケージは、 Java の <literal>import</literal> 文でパッケージ下のすべてのクラスをインポートするときと同じ方法で指定します。 (すなわち、パッケージの完全な名前に <literal>.*</literal> を付け加えた形です。)<literal>.*</literal> の代わりに <literal>.-</literal> を指定すると、サブパッケージも含めてすべてが分析されます。</para>
    </listitem>
  </varlistentry>

<varlistentry>
  <term><command>-low</command></term>
  <listitem>
    <para>すべてのバグが報告されます。</para>
  </listitem>
  </varlistentry>

<varlistentry>
  <term><command>-medium</command></term>
  <listitem>
    <para>優先度 (中) および優先度 (高) のバグが報告されます。これは、デフォルトの設定値です。</para>
  </listitem>
  </varlistentry>

<varlistentry>
  <term><command>-high</command></term>
  <listitem>
    <para>優先度 (高) のバグのみが報告されます。</para>
  </listitem>
  </varlistentry>

<varlistentry>
    <term><command>-relaxed</command></term>
    <listitem>
        <para>手抜き報告モードです。このオプションを指定すると、多くのディテクタにおいて 誤検出を回避するためのヒューリスティック機能が抑止されます。</para>
    </listitem>
  </varlistentry>

<varlistentry>
  <term><command>-xml</command></term>
  <listitem>
    <para>バグ報告が XML で作成されます。作成された XML データは 、後で GUI で見ることができます。このオプションは <command>-xml:withMessages</command> と指定することもできます。こうすると 出力 XML には 各バグに関して人間に読むことができるメッセージが含まれるようになります。このオプションで作成された XML ファイルは 報告書に変換するのが簡単です。</para>
  </listitem>
  </varlistentry>

<varlistentry>
  <term><command>-html</command></term>
  <listitem>
    <para>HTML 出力が生成されます。デフォルトでは &FindBugs; は <filename>default.xsl</filename> <ulink url="http://www.w3.org/TR/xslt">XSLT</ulink> スタイルシートを使用して HTML 出力を生成します: このファイルは、 <filename>findbugs.jar</filename> の中、または、 &FindBugs; のソース配布物もしくはバイナリ配布物の中にあります。このオプションには、次のようなバリエーションも存在します。すなわち、 <command>-html:plain.xsl</command> 、 <command>-html:fancy.xsl</command> および <command>-html:fancy-hist.xsl</command> です。<filename>plain.xsl</filename> スタイルシートは Javascript や DOM を利用しません。したがって、古いWeb ブラウザ使用時や印刷時にも比較的うまく表示されるでしょう。<filename>fancy.xsl</filename> スタイルシートは DOM と Javascript を利用してナビゲーションを行います。また、ビジュアル表示に CSS を使用します。<command>fancy-hist.xsl</command> は <command>fancy.xsl</command> スタイルシートを更に進化させたものです。DOM や Javascript をふんだんに駆使して、バグの一覧を動的にフィルタリングします。</para>

<para>ユーザー自身の XSLT スタイルシートを用いて HTML への変換を行いたい場合は、 <command>-html:<replaceable>myStylesheet.xsl</replaceable></command> のように指定してください。ここで、 <replaceable>myStylesheet.xsl</replaceable> はユーザーが使用したいスタイルシートのファイル名です。</para>
  </listitem>
  </varlistentry>

<varlistentry>
  <term><command>-emacs</command></term>
  <listitem>
    <para>バグ報告が Emacs 形式で作成されます。</para>
  </listitem>
  </varlistentry>

<varlistentry>
  <term><command>-xdocs</command></term>
  <listitem>
    <para>バグ報告が xdoc XML 形式で作成されます。Apache Mavenで使用できます。</para>
  </listitem>
  </varlistentry>

<varlistentry>
    <term><command>-output</command> <replaceable>ファイル名</replaceable></term>
    <listitem>
       <para>指定したファイルに出力結果が作成されます。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><command>-outputFile</command> <replaceable>ファイル名</replaceable></term>
    <listitem>
       <para>この引数は、使用すべきではありません。代わりに、 <command>-output</command> を使用してください。</para>
    </listitem>
  </varlistentry>

<varlistentry>
  <term><command>-nested</command><replaceable>[:true|false]</replaceable></term>
  <listitem>
    <para>このオプションは、ファイルやディレクトリーの中で入れ子になった jar および zip ファイルを分析するかどうかを指定します。デフォルトでは、入れ子になった jar および zip ファイルも分析します。入れ子になった jar および zip ファイルの分析するを無効にする場合は、 <command>-nested:false</command> をコマンドライン引数に追加してください。</para>
  </listitem>
  </varlistentry>

<varlistentry>
  <term><command>-auxclasspath</command> <replaceable>クラスパス</replaceable></term>
  <listitem>
    <para>分析時に使用する補助クラスパスを設定します。分析するプログラムで使用するjarファイルやクラスディレクトリーをすべて指定してください。補助クラスパスに指定したクラスは分析の対象にはなりません。</para>
  </listitem>
  </varlistentry>

</variablelist>

</sect2>
</sect1>

</chapter>

<chapter id="gui">
    <title>&FindBugs; GUI の使用方法</title>

<para>この章では、&FindBugs; グラフィカルユーザーインタフェース (GUI) の使用方法を説明します。</para>

<sect1>
<title>プロジェクトの作成</title>
<para><command>findbugs</command>  コマンドで &FindBugs; を起動してから、メニューで <menuchoice><guimenu>File</guimenu><guimenuitem>New Project</guimenuitem></menuchoice> を選択してください。そうすると、次のようなダイアログが表示されます:<mediaobject>
<imageobject>
<imagedata fileref="project-dialog.png"/>
</imageobject>
</mediaobject>
</para>

<para>「Class archives and directories to analyze」テキストフィールドの横にある 「Add」ボタンを押すと、バグを分析する java クラスを含んでいる Java アーカイブファイル (zip, jar, ear, or war file) を選択して指定できます。複数の アーカイブ/ディレクトリーを追加することが可能です。</para>

<para>また、分析を行う Java アーカイブのソースコードを含んだソースディレクトリーを指定することもできます。そうすると、バグの可能性があるソースコードの場所が、&FindBugs; 上でハイライトして表示されます。ソースディレクトリーは、Java パッケージ階層のルートディレクトリーを指定する必要があります。例えば、ユーザのアプリケーションが <varname>org.foobar.myapp</varname> パッケージの中にある場合は、 <filename class="directory">org</filename> ディレクトリーの親ディレクトリーをソースディレクトリーリストに指定する必要があります。</para>

<para>もうひとつ、任意指定の手順があります。それは、補助用の Jar ファイルおよびディレクトリーを 「Auxiliary classpath locations」のエントリーに追加することです。分析するアーカイブ/ディレクトリーにも標準の実行時クラスパスにも含まれていないクラスを、分析するアーカイブ/ディレクトリーが参照している場合は、この項目を設定した方がいいでしょう。クラス階層に関する情報を使用するバグディテクタが、 &FindBugs; にはいくつかあります。したがって、&FindBugs; が分析を行うクラスの完全なクラス階層を参照できれば、より正確な分析結果を取得することができます。</para>

</sect1>

<sect1>
<title>分析の実行</title>
<para>アーカイブ、ディレクトリーおよびソースディレクトリーの指定ができれば、「Finish」ボタンを押して Jar ファイルに含まれるクラスに対する分析を実行します。巨大なプロジェクトを古いコンピュータ上で実行すると、かなりの時間(数十分)がかかることに注意してください。大容量メモリである最近のコンピュータなら、大きなプログラムであっても数分程度で分析できます。</para>
</sect1>

<sect1>
<title>結果の閲覧</title>

<para>分析が完了すると、次のような画面が表示されます :<mediaobject>
  <imageobject>
    <imagedata fileref="example-details.png"/>
  </imageobject>
</mediaobject>
</para>

<para>左上のペインにはバグ階層ツリーが表示されます。これは、分析でみつかったバグの検索結果が階層的に表示されたものです。</para>

<para>上部のペインでバグ検索結果を選択すると、下部の「Details」ペインにバグの詳細説明が表示されます。更に、ソースがみつかれば、右上のソースコードペインにバグの出現箇所に該当するソースコードが表示されます。上図の例で表示されているバグは、ストリームオブジェクトがクローズされていないというものです。ソースコード・ウィンドウにおいて当該ストリームオブジェクトを生成している行がハイライトされています。</para>

<para>バグの検索結果に対してテキストで注釈を入れることができます。階層ツリー図のすぐ下にあるテキストボックスに注釈を入力してください。記録しておきたい情報を何でも自由に入力することができます。バグ結果ファイルの保存および読み込みを行ったときに、注釈も保存されます。</para>

</sect1>

<sect1>
<title>保存と読み込み</title>

<para>メニュー項目から <menuchoice><guimenu>File</guimenu><guimenuitem>Save as...</guimenuitem></menuchoice> を選択すると、ユーザーの作業結果を保存することができます。「Save as...」ダイアログにあるドロップダウン・リストの中から「FindBugs analysis results (.xml)」を選択ことで、ユーザーが指定した jar ファイルリストやバグ検索結果などの作業結果を保存することができます。また、jar ファイルリストのみを保存する選択肢 (「FindBugs project file (.fbp)」) やバグ検索結果のみを保存する選択肢 (「FindBugs analysis file (.fba)」) もあります。保存したファイルは、メニュー項目から <menuchoice><guimenu>File</guimenu><guimenuitem>Open...</guimenuitem></menuchoice> を選択することで、読み込むことができます。</para>

</sect1>

<!--
<sect1 id="textui">
<title>Using the &FindBugs;™ Command Line Interface</title>

<para>
The &FindBugs; Command Line Interface (or Text UI) can be used to
analyze an application for bugs non-interactively.  Each bug instance will be
reported on a single line.  All output is written to the standard output file descriptor.
<xref linkend="filter" /> explains how bug reports may be filtered in order
to get only the output you're interested in.
</para>

<para>
See <xref linkend="commandLineOptions" /> for a description of how to invoke the
Command Line Interface.
</para>
</sect1>
-->

</chapter>

<chapter id="anttask">
<title>&FindBugs;™ &Ant; タスクの使用方法</title>

<para>この章では、 &FindBugs; を <ulink url="http://ant.apache.org/">&Ant;</ulink> のビルドスクリプトに組み入れる方法について説明します。 <ulink url="http://ant.apache.org/">&Ant;</ulink> は、ビルドや配備を行うことができる Java でよく使用されるツールです。&FindBugs; &Ant; タスクを使用すると、 ビルドスクリプトを作成して機械的に &FindBugs; による Java コードの分析を実行することができます。</para>

<para>この &Ant; タスクは、 Mike Fagan 氏の多大な貢献によるものです。</para>

<sect1>
<title>&Ant; タスクのインストール</title>

<para>&Ant; タスクのインストールは、 <filename>&FBHome;/lib/findbugs-ant.jar</filename> を &Ant; インストールディレクトリーの<filename>lib</filename> サブディレクトリーにコピーするだけです。<note>
<para>使用する &Ant; タスクと &FindBugs; 本体は、同梱されていた同じバージョンのものを使用することを強く推奨します。別のバージョンの &FindBugs; に含まれていた &Ant; タスク Jar ファイルでの動作は保証しません。</para>
</note>
</para>

</sect1>

<sect1>
<title>build.xml の書き方</title>

<para>&FindBugs; を <filename>build.xml</filename> (&Ant; ビルドスクリプト) に組み入れるためにはまず、タスク定義を記述する必要があります。タスク定義は次のように記述します。:<screen>
  <taskdef name="findbugs" classname="edu.umd.cs.findbugs.anttask.FindBugsTask"/>
</screen>タスク定義は、 <literal>findbugs</literal> 要素を <filename>build.xml</filename> 上に記述したとき、そのタスクの実行に使用されるクラスを指定します。</para>

<para>タスク定義の記述をすれば、<literal>findbugs</literal> タスクを使ってターゲットを定義できます。次に示すのは、 Apache <ulink url="http://jakarta.apache.org/bcel/">BCEL</ulink> ライブラリーを分析する場合を想定した <filename>build.xml</filename> の記述例です。<screen>
  <property name="findbugs.home" value="/export/home/daveho/work/findbugs" />

<target name="findbugs" depends="jar">
    <findbugs home="${findbugs.home}"
              output="xml"
              outputFile="bcel-fb.xml" >
      <auxClasspath path="${basedir}/lib/Regex.jar" />
      <sourcePath path="${basedir}/src/java" />
      <class location="${basedir}/bin/bcel.jar" />
    </findbugs>
  </target>
</screen><literal>findbugs</literal> 要素には、 <literal>home</literal> 属性が必須です。 &FindBugs; のインストールディレクトリーすなわち &FBHome; の値を設定します。<xref linkend="installing"/> を参照してください。</para>

<para>このターゲットは <filename>bcel.jar</filename> に対して &FindBugs; を実行します。この Jar ファイルは、 BCEL ビルドスクリプトによって作成されるものです。(上記のターゲットが「jar」ターゲットに依存している (depends) と設定することにより、 &FindBugs; が実行される前に当該ライブラリーが完全にコンパイルされていることを保証しています。) &FindBugs; の出力は、 XML 形式で <filename>bcel-fb.xml</filename> ファイルに保存されます。補助 Jar ファイル <filename>Regex.jar</filename> を aux classpath に記述しています。なぜなら、当該 Jar ファイルが BCEL メイン･ライブラリーから参照されるからです。source path を指定することで、保存されるバグデータに BCEL ソースコードへの正確な参照が記述されます。</para>
</sect1>

<sect1>
<title>タスクの実行</title>

<para>コマンドラインから &Ant; を起動する例を次に示します。前述の <literal>findbugs</literal> ターゲットを使用しています。<screen>
  <prompt>[daveho@noir]$</prompt> <command>ant findbugs</command>
  Buildfile: build.xml

init:

compile:

examples:

jar:

findbugs:
   [findbugs] Running FindBugs...
   [findbugs] Bugs were found
   [findbugs] Output saved to bcel-fb.xml

BUILD SUCCESSFUL
  Total time: 35 seconds
</screen>この事例においては、XML ファイルでバグ検索結果を保存しているので、 &FindBugs; GUI を使って結果を参照することができます。 <xref linkend="running"/> を参照してください。</para>

</sect1>

<sect1>
<title>パラメーター</title>

<para>このセクションでは、 &FindBugs; タスクを使用する際に、指定することができるパラメーターについて説明します。<variablelist> <varlistentry> <term><literal>class</literal></term>
    <listitem>
       <para>分析の対象となるクラス群を指定するためのネストされる要素です。<literal>class</literal> 要素には <literal>location</literal> 属性の指定が必須です。分析対象となるアーカイブファイル (jar, zip, 他)、ディレクトリーまたはクラスファイルの名前を記述します。1 つの <literal>findbugs</literal> 要素に対して、複数の <literal>class</literal> 子要素を指定することができます。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><literal>auxClasspath</literal></term>
    <listitem>
       <para>任意指定のネストされる要素です。分析対象のライブラリーまたはアプリケーションによって使用されているが分析の対象にはしたくないクラスを含んでいるクラスパス (Jar ファイルまたはディレクトリー) を指定します。  &Ant; の Java タスクにある <literal>classpath</literal> 要素 と同じ方法で指定することができます。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><literal>sourcePath</literal></term>
    <listitem>
       <para>任意指定のネストされる要素です。分析対象 Java コードのコンパイル時に使用したソースファイルを含んでいるソースディレクトリーへのパスを指定します。ソースパスを指定することにより、生成される XML のバグ出力結果に完全なソース情報をもたせることができ、後になって GUI で参照することができます。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><literal>home</literal></term>
    <listitem>
       <para>必須属性です。&FindBugs; がインストールされているディレクトリー名を設定します。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><literal>quietErrors</literal></term>
    <listitem>
       <para>任意指定のブール値属性です。true を設定すると、深刻な分析エラー発生やクラスがみつからないといった情報が &FindBugs; 出力に記録されません。デフォルトは、 false です。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><literal>reportLevel</literal></term>
    <listitem>
       <para>任意指定の属性です。報告されるバグの優先度のしきい値を指定します。「low」に設定すると、すべてのバグが報告されます。「medium」 (デフォルト) に設定すると、優先度 (中)および優先度 (高)のバグが報告されます。「high」に設定すると、優先度 (高) のバグのみが報告されます。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><literal>output</literal></term>
    <listitem>
       <para>任意指定の属性です。出力形式を指定します。「xml」 (デフォルト) に設定すると、出力は XML 形式になります。「xml:withMessages」 に設定すると、出力は人間が読めるメッセージ が追加された XML 形式になります。(XSL スタイルシートを使ってレポートを作成することを計画している場合はこの形式を使用してください。) 「html」に設定すると、出力は HTML 形式(デフォルトのスタイルシートは default.xsl) になります。 「text」に設定すると、出力は特別なテキスト形式になります。「emacs」に設定すると、出力は <ulink url="http://www.gnu.org/software/emacs/">Emacs</ulink> エラーメッセージ形式になります。「xdocs」に設定すると、出力は Apache Maven で使用できる xdoc XML になります。</para>
    </listitem>
  </varlistentry>
 <varlistentry>
    <term><literal>stylesheet</literal></term>
    <listitem>
       <para>任意指定の属性です。output 属性 に html を指定した場合に、 HTML 出力作成に使用されるスタイルシートを指定します。FindBugs 配布物に含まれているスタイルシートは、 default.xsl、 fancy.xsl 、 fancy-hist.xsl 、 plain.xsl および summary.xsl です。デフォルト値は default.xsl です。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><literal>sort</literal></term>
    <listitem>
       <para>任意指定の属性です。<literal>output</literal> 属性に「text」を指定した場合に、バグの報告をクラス順にソートするかどうかを <literal>sort</literal> 属性で指定します。デフォルトは、 true です。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><literal>outputFile</literal></term>
    <listitem>
       <para>任意指定の属性です。指定した場合、&FindBugs; の出力はその名前のファイルへと保存されます。省略時、出力は &Ant; によって直接表示されます。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><literal>debug</literal></term>
    <listitem>
       <para>任意指定のブール値属性です。true に設定すると、 &FindBugs; は 診断情報を出力します。どのクラスを分析しているか、どのパグパターンディテクタが実行されているか、という情報が表示されます。デフォルトは、 false です。</para>
    </listitem>
  </varlistentry>

<varlistentry>
      <term><literal>effort</literal></term>
      <listitem>
          <para>分析の活動レベルを設定します。<literal>min</literal> 、<literal>default</literal> または <literal>max</literal> のいずれかの値を設定してください。分析レベルの設定に関する詳細情報は、 <xref linkend="commandLineOptions"/> を参照してください。</para>
      </listitem>
  </varlistentry>

<varlistentry>
    <term><literal>conserveSpace</literal></term>
    <listitem>
       <para>effort="min" と同義です。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><literal>workHard</literal></term>
    <listitem>
       <para>effort="max" と同義です。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><literal>visitors</literal></term>
    <listitem>
       <para>任意指定の属性です。どのバグディテクタを実行するかをコンマ区切りのリストで指定します。バグディテクタはパッケージ指定なしのクラス名で指定します。省略時、デフォルトで無効化されているものを除くすべてのディテクタが実行されます。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><literal>omitVisitors</literal></term>
    <listitem>
       <para>任意指定の属性です。<literal>visitors</literal> 属性と似ていますが、こちらは <emphasis>実行されない</emphasis> ディテクタを指定します。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><literal>excludeFilter</literal></term>
    <listitem>
       <para>任意指定の属性です。フィルターファイル名を指定します。報告から除外されるバグを指定します。<xref linkend="filter"/> を参照してください。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><literal>includeFilter</literal></term>
    <listitem>
       <para>任意指定の属性です。フィルターファイル名を指定します。報告されるバグを指定します。<xref linkend="filter"/> を参照してください。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><literal>projectFile</literal></term>
    <listitem>
       <para>任意指定の属性です。プロジェクトファイル名を指定します。プロジェクトファイルは、 &FindBugs; GUI で作成します。分析されるクラス、および、補助クラスパス、ソースディレクトリーが記入されてます。プロジェクトファイルを指定した場合は、 <literal>class</literal> 要素・ <literal>auxClasspath</literal> 属性および <literal>sourcePath</literal> 属性を設定する必要はありません。プロジェクトの作成方法は、 <xref linkend="running"/> を参照してください。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><literal>jvmargs</literal></term>
    <listitem>
       <para>任意指定の属性です。&FindBugs; を実行している Java 仮想マシンに対して受け渡される引数を指定します。巨大なプログラムを分析する場合に、 JVM が使用するメモリ容量を増やす指定をするためにこの引数を利用する必要があるかもしれません。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><literal>systemProperty</literal></term>
    <listitem>
      <para>任意指定のネストされる要素です。指定した場合、Java システムプロパティーを定義します。<literal>name</literal> 属性にはシステムプロパティーの名前を指定します。そして、 <literal>value</literal> 属性にはシステムプロパティの値を指定します。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><literal>timeout</literal></term>
    <listitem>
       <para>任意指定の属性です。&FindBugs; を実行している Java プロセス の実行許容時間をミリ秒単位で指定します。時間を超過するとハングアップしていると判断してプロセスが終了されます。デフォルトは、 600,000 ミリ秒 (10 分) です。巨大なプログラムの場合は、 &FindBugs; が分析を完了するまでに 10 分 以上掛かる可能性があることに注意してください。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><literal>failOnError</literal></term>
    <listitem>
       <para>任意指定のブール値属性です。&FindBugs; の実行中にエラーがあった場合に、ビルドプロセス自体を打ち切って異常終了させるかどうかを指定します。デフォルトは、「false」です。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><literal>errorProperty</literal></term>
    <listitem>
       <para>任意指定の属性です。&FindBugs; の実行中にエラーが発生した場合に、「true」が設定されるプロパティーの名前を指定します。</para>
    </listitem>
  </varlistentry>

<varlistentry>
      <term><literal>warningsProperty</literal></term>
      <listitem>
          <para>任意指定の属性です。&FindBugs; が分析したプログラムにバグ報告が 1 件でもある場合に、「true」が設定されるプロパティーの名前を指定します。</para>
      </listitem>
  </varlistentry>

</variablelist>

</para>

<!--

-->

</sect1>

</chapter>

<chapter id="eclipse">
<title>&FindBugs;™ Eclipse プラグインの使用方法</title>

<para>FindBugs Eclipse プラグインを使用することによって、 &FindBugs; を <ulink url="http://www.eclipse.org/">Eclipse</ulink> IDE で使用することができるようになります。このFindBugs Eclipse プラグインは、 Peter Friese 氏の多大な貢献によるものです。Phil Crosby 氏 と Andrei Loskutov 氏は、プラグインの重要な改良に貢献しました。</para>

<para>&FindBugs; Eclipse Plugin を使用するためには、 Eclipse 3.3 あるいはそれ以降のバージョン、また、 JRE/JDK 1.5 あるいはそれ以降のバージョンが必要です。</para>

</sect1>

<sect1>
<title>インストール</title>

<para>更新サイトが提供されています。更新サイトを利用して、機械的に FindBugs を Eclipse にインストールできます。また自動的に、最新版のアップデートを照会してインストールすることもできます。内容の異なる 3 つの更新サイトが存在します。</para>

<variablelist><title>FindBugs Eclipse 更新サイト一覧</title>
    <varlistentry><term><ulink url="http://findbugs.cs.umd.edu/eclipse/">http://findbugs.cs.umd.edu/eclipse/</ulink></term>

<listitem>
      <para>FindBugs の公式リリース物を提供します。</para>
    </listitem>
    </varlistentry>

<varlistentry><term><ulink url="http://findbugs.cs.umd.edu/eclipse-candidate/">http://findbugs.cs.umd.edu/eclips-candidate/</ulink></term>

<listitem>
        <para>FindBugsの公式リリース物に加えて、公式リリース候補版を提供します。</para>
      </listitem>
    </varlistentry>

<varlistentry><term><ulink url="http://findbugs.cs.umd.edu/eclipse-daily/">http://findbugs.cs.umd.edu/eclipse-daily/</ulink></term>

<listitem>
        <para>FindBugsの日次ビルド物を提供します。コンパイルができること以上のテストは行われていません。</para>
      </listitem>
    </varlistentry>
    </variablelist>

<para>また、次に示すリンクから手動でプラグインをダウンロードすることもできます : <ulink url="http://prdownloads.sourceforge.net/findbugs/edu.umd.cs.findbugs.plugin.eclipse_2.0.3.20131122.zip?download">http://prdownloads.sourceforge.net/findbugs/edu.umd.cs.findbugs.plugin.eclipse_2.0.3.20131122.zip?download</ulink>. 展開して Eclipse の「plugins」サブディレクトリーに入れてください。(そうすると、 <eclipse インストールディレクトリー >/plugins/edu.umd.cs.findbugs.plugin.eclipse_2.0.3.20131122/findbugs.png が &FindBugs; のロゴファイルへのパスになるはずです。)</para>

<para>プラグインの展開ができたら、 Eclipse を起動して <menuchoice> <guimenu>Help</guimenu> <guimenuitem>About Eclipse Platform</guimenuitem> <guimenuitem>Plug-in Details</guimenuitem> </menuchoice> を選択してください。「FindBugs Project」から提供された「FindBugs Plug-in」というプラグインがあることを確認してください。</para>
</sect1>

<sect1>
<title>プラグインの使用方法</title>

<para>実行するには、 Java プロジェクト上で右クリックして「Find Bugs」を選択します。&FindBugs; が実行されて、バグパターンの実例の可能性があると識別されたコード箇所に問題マーカーがつきます。 (ソース画面および Eclipse 問題ビューに表示されます。)</para>

<para>Java プロジェクトのプロパティーダイアログを開いて「Findbugs」プロパティーページを選択することで、 &FindBugs; の動作をカスタマイズすることができます。選択できる項目には次のようなものがあります :</para>

<itemizedlist>
  <listitem>
    <para>「Run FindBugs Automatically」チェックボックスの設定。チェックすると、プロジェクト内の Java クラスが修正されるたびに FindBugs が実行されます。</para>
  </listitem>

<listitem>
    <para>優先度とバグカテゴリーの選択。これらのオプションは、どの警告を表示するかを選択します。例えば、優先度で 「Medium」 を選択すると、優先度 (中) および優先度 (高) の警告のみが表示されます。同様に、「Style」チェックボックスのチェックマークを外すと、Style カテゴリーに属する警告は表示されません。</para>
  </listitem>

<listitem>
    <para>ディテクタの選択。表からプロジェクトで有効にしたいディテクタを選択することができます。</para>
  </listitem>
</itemizedlist>

</sect1>

<sect1>
<title>トラブルシューティング</title>

<para>&FindBugs; Eclipse プラグインは、まだ実験段階です。このセクションでは、プラグインに関する一般的な問題と (判明していれば) それらの問題の解決方法を記述します。</para>

<itemizedlist>
  <listitem>
    <para>&FindBugs; 問題マーカーが (ソース画面および問題ビューに) 表示されない場合は、問題ビューのフィルター設定を変更してください。詳細情報は <ulink url="http://findbugs.sourceforge.net/FAQ.html#q7">http://findbugs.sourceforge.net/FAQ.html#q7</ulink> を参照してください。</para>
  </listitem>

</itemizedlist>

</sect1>

</chapter>

<chapter id="filter">
<title>フィルターファイル</title>

<para>フィルターファイルを使用することで、特定のクラスやメソッドをバグ報告に含めたりバグ報告から除外したりすることができます。この章では、フィルターファイルの使用方法を説明します。<note>
<title>計画されている機能</title>
<para>フィルターは現在、コマンドラインインタフェースでのみサポートされています。最終的には、フィルターのサポートは GUI にも追加される予定です。</para>
</note>
</para>

<sect1>
<title>フィルターファイルの概要</title>

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

<para>フィルターファイルは、 <ulink url="http://www.w3.org/XML/">XML</ulink> 文書です。最上位要素が　<literal>FindBugsFilter</literal> 要素 であり、その子要素として <literal>Match</literal> 要素を複数個定義します。それぞれの <literal>Match</literal> 要素は、生成されたバグ検索結果に適用される述部にあたります。通常、フィルターはバグ検索結果を除外するために使用します。次に、例を示します:<screen>
<prompt>$ </prompt><command>findbugs -textui -exclude <replaceable>myExcludeFilter.xml</replaceable> <replaceable>myApp.jar</replaceable></command>
</screen>また一方で、的をしぼった報告を得るためにバグ報告結果を選択するためにフィルターを使用することも考えられます :<screen>
<prompt>$ </prompt><command>findbugs -textui -include <replaceable>myIncludeFilter.xml</replaceable> <replaceable>myApp.jar</replaceable></command>
</screen>
</para>

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

</sect1>

<sect1>
<title>マッチング条件の種類</title>

<variablelist>
 <varlistentry>
   <term><literal><Bug></literal></term>
   <listitem><para>この要素は、バグパターンを指定して照合します。<literal>pattern</literal> 属性には、コンマ区切りでバグパターン類型のリストを指定します。どの警告がどのバグパターン類型にあたるかは、 <command>-xml</command> オプションをつかって出力されたもの (<literal>BugInstance</literal> 要素の <literal>type</literal> 属性) を見るか、または、 <ulink url="../../bugDescriptions.html">バグ解説ドキュメント</ulink>を参照してください。</para><para>もっと粒度の粗い照合を行いたいときは、 <literal>code</literal> 属性を使用してください。バグ略称のコンマ区切りのリストで指定できます。さらに粒度の粗い照合を行いたいときは、 <literal>category</literal> 属性を使用してください。次に示す、バグカテゴリー名のコンマ区切りのリストで指定できます : <literal>CORRECTNESS</literal>, <literal>MT_CORRECTNESS</literal>, <literal>BAD_PRACTICICE</literal>, <literal>PERFORMANCE</literal>, <literal>STYLE</literal>.</para><para>同じ <literal><Bug></literal> 要素に上記の属性を複数指定した場合は、バグパターン名、バグ略称、バグカテゴリーのいずれか1つでも該当すれば、バグパターンは合致すると判定されます。</para><para>下位互換性を持たせたい場合は、 <literal><Bug></literal> 要素の代わりに <literal><BugPattern></literal> 要素および <literal><BugCode></literal> 要素を使用してください。これらの要素はそれぞれ、 <literal>name</literal> 属性で値のリストを指定します。これらの要素は、将来サポートされなくなる可能性があります。</para></listitem>
 </varlistentry>

<varlistentry>
    <term><literal><Priority></literal></term>
    <listitem>
        <para>この要素は、特定の優先度をもつ警告を照合します。<literal>value</literal> 属性には、整数値を指定します : 1 は優先度(高)、また、 2  は優先度(中) 、 3 は優先度(低) を示します。</para>
    </listitem>
 </varlistentry>

<varlistentry>
   <term><literal><Package></literal></term>
    <listitem>
        <para>この要素は、 <literal>name</literal> 属性で指定した特定のパッケージ内にあるクラスに関連した警告を照合します。入れ子のパッケージは含まれません (Java import 文に従っています) 。しかしながら、正規表現を使うと複数パッケージにマッチさせることは簡単にできます。</para>
    </listitem>
  </varlistentry>

<varlistentry>
   <term><literal><Class></literal></term>
    <listitem>
        <para>この要素は、特定のクラスに関連した警告を照合します。<literal>name</literal> 属性を使用して、照合するクラス名をクラス名そのものか、または、正規表現で指定します。</para>

<para>下位互換性を持たせたい場合は、この要素の代わりに <literal>Match</literal> 要素を使用してください。クラス名そのものの指定は <literal>class</literal> 属性を、クラス名を正規表現で指定する場合は <literal>classregex</literal> 属性をそれぞれ使用してください</para>

<para>もし <literal>Match</literal> 要素に <literal>Class</literal> 要素が無かったり、 <literal>class</literal> / <literal>classregex</literal> 属性が無かったりした場合は、すべてのクラスに適用されます。その場合、想定外に多くのバグ検索結果が一致してしまうことがあり得ます。その場合は、適当なメソッドやフィールドで絞り込んでください。</para>
    </listitem>
 </varlistentry>

<listitem><para>この要素は、メソッドを指定します。<literal>name</literal> 属性を使用して、照合するメソッド名をメソッド名そのものか、または、正規表現で指定します。<literal>params</literal> 属性には、コンマ区切りでメソッド引数の型のリストを指定します。<literal>returns</literal> 属性にはメソッドの戻り値の型を指定します。<literal>params</literal> および <literal>returns</literal> においては、クラス名は完全修飾名である必要があります。(例えば、単に "String" ではなく "java.lang.String" としてください。) <literal>params</literal> <literal>returns</literal> のどちらか一方を指定した場合は、もう一方の属性の指定も必須です。なぜならば、メソッドシグニチャーを構築のために必要だからです。<literal>name</literal> 属性、<literal>params</literal> 属性 および <literal>returns</literal> 属性または 3 つの 属性すべて、のどれかを条件とすることできることを意味しています。このように、名前とシグニチャーに基づく様々な種類の条件を規定できます。</para></listitem>
 </varlistentry>

<listitem><para>この要素は、フィールドを指定します。<literal>name</literal> 属性を使用して、照合するフィールド名をフィールド名そのものか、または、正規表現で指定します。また、フィールドのシグニチャーに照らしたフィルタリングをすることができます。 <literal>type</literal> 属性を使用して、フィールドの型を完全修飾名で指定してください。名前とシグニチャーに基づく条件を規定するために、その2つの属性を両方とも指定することができます。</para></listitem>
 </varlistentry>

<listitem><para>この要素は、ローカル変数を指定します。<literal>name</literal> 属性を使用して、照合するローカル変数名をローカル変数名そのものか、または、正規表現で指定します。ローカル変数とは、メソッド内で定義した変数です。</para></listitem>
 </varlistentry>

<varlistentry>
   <term><literal><Or></literal></term>
    <listitem><para>この要素は、論理和として <literal>Match</literal> 条項を結合します。すなわち、2つの <literal>Method</literal> 要素を <literal>Or</literal> 条項に入れることで、どちらか一方のメソッドでマッチさせることができます。</para></listitem>
 </varlistentry>
</variablelist>

</sect1>

<sect1>
<title>Java 要素名マッチング</title>

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

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

<para>パターンの構文規則に関しては、 <ulink url="http://java.sun.com/j2se/1.5.0/ja/docs/ja/api/java/util/regex/Pattern.html"><literal>java.util.regex.Pattern</literal></ulink> のドキュメントを参照してください。</para>
</sect1>

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

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

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

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

</sect1>

<para>1. 特定のクラスに対するすべてのバグ報告に一致させます。<programlisting>
<![CDATA[
     <Match>
       <Class name="com.foobar.MyClass" />
     </Match>
]]>
</programlisting>

</para>

<para>2. バグ略称を指定して、特定のクラスに対する特定の検査項目に一致させます。<programlisting>
<![CDATA[
     <Match>
       <Class name="com.foobar.MyClass"/ >
       <Bug code="DE,UrF,SIC" />
     </Match>
]]>
</programlisting>
</para>

<para>3. バグ略称を指定して、すべてのクラスに対する特定の検査項目に一致させます。<programlisting>
<![CDATA[
     <Match>
       <Bug code="DE,UrF,SIC" />
     </Match>
]]>
</programlisting>
</para>

<para>4. バグカテゴリーを指定して、すべてのクラスに対する特定の検査項目に一致させます。<programlisting>
<![CDATA[
     <Match>
       <Bug category="PERFORMANCE" />
     </Match>
]]>
</programlisting>
</para>

<para>5. バグ略称を指定して、特定のクラスの指定されたメソッドに対する特定のバグ種別に一致させます。<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. 特定のメソッドに対する特定のバグパターンに一致させます。<programlisting>
<![CDATA[
    
    <Match>
      <Class name="com.foobar.MyClass" />
      <Method name="writeDataToFile" />
      <Bug pattern="OS_OPEN_STREAM" />
    </Match>
]]>
</programlisting>
</para>

<para>7. 特定のメソッドに対する特定の優先度を付与された特定のバグパターンに一致させます。<programlisting>
<![CDATA[
    
    <Match>
      <Class name="com.foobar.MyClass" />
      <Method name="someMethod" />
      <Bug pattern="DLS_DEAD_LOCAL_STORE" />
      <Priority value="2" />
    </Match>
]]>
</programlisting>
</para>

<para>8. AspectJ コンパイラーによって引き起こされるマイナーバグに一致させます (AspectJ の開発者でもない限り、それらのバグに関心を持つことはないと考えます)。<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. 基盤コードの特定の部分に対するバグに一致させます<programlisting>
<![CDATA[
    
    <Match>
      <Class name="~.*\.Messages" />
      <Bug code="UUF" />
    </Match>
    
    <Match>
      <Package name="~.*\.internal" />
      <Bug code="MS" />
    </Match>
    
    <Match>
      <Package name="~com\.foobar\.fooproject\.ui.*" />
      <Bug pattern="SIC_INNER_SHOULD_BE_STATIC_ANON" />
    </Match>
]]>
</programlisting>
</para>

<para>10. 特定のシグニチャーを持つフィールドまたはメソッドのバグに一致させます。<programlisting>
<![CDATA[
    
    <Match>
      <Method returns="void" name="main" params="java.lang.String[]" />
      <Method pattern="DM_EXIT" />
    </Match>
    
    <Match>
      <Field type="com.foobar.DebugInfo" />
      <Bug code="UuF" />
    </Match>
]]>
</programlisting>

</para>

</sect1>

<Match>
       <Bug code="XYZ" />
     </Match>

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

<Match>
       <Class name="com.foobar.MyClass" />
       <Method name="someMethod" />
       <Bug pattern="DLS_DEAD_LOCAL_STORE" />
       <Priority value="2" />
     </Match>
</FindBugsFilter>
]]>
</programlisting>

</sect1>

</chapter>

<chapter id="analysisprops">
<title>分析プロパティー</title>

<para>&FindBugs; は分析する場合にいくつかの観点を持っています。そして、観点をカスタマイズして実行することができます。システムプロパティーを使って、それらのオプションを設定します。この章では、分析オプションの設定方法を説明します。</para>

<para>分析オプションの主な目的は、 2 つあります。1 番目は、 &FindBugs; に対して分析されるアプリケーションのメソッドの意味を伝えることです。そうすることで &FindBugs; がより正確な結果を出すことができ、誤検出を減らすことができます。2 番目に、分析を行うに当たりその精度を設定できるようにすることです。分析の精度を落とすことで、メモリ使用量と分析時間を減らすことができます。ただし、本当のバグを見逃したり、誤検出の数が増えるという代償があります。</para>

<para>コマンドラインオプション <command>-property</command> を使って、分析オプションを設定することができます。次に、例を示します:<screen>
<prompt>$ </prompt><command>findbugs -textui -property "cfg.noprune=true" <replaceable>myApp.jar</replaceable></command>
</screen>
</para>

<para>設定することができる分析オプションの一覧を <xref linkend="analysisproptable"/> に示します。</para>

<table id="analysisproptable">
<title>設定可能な分析プロパティー</title>
<tgroup cols="3" align="left">
  <thead>
    <row>
      <entry>プロパティー名</entry>
      <entry>設定値</entry>
      <entry>目的</entry>
    </row>
  </thead>
  <tbody>

    <row>
      <entry>findbugs.assertionmethods</entry>
      <entry>コンマ区切りの完全修飾メソッド名リスト : 例、 "com.foo.MyClass.checkAssertion"</entry>
      <entry>このプロパティーには、プログラムが正しいことをチェックするために使われるメソッドを指定します。これらのメソッドを指定することで、 チェックメソッドで確認した値に対する null 参照アクセスディテクタの誤検出を回避できます。</entry>
    </row>
    <row>
      <entry>findbugs.de.comment</entry>
      <entry>true または false</entry>
      <entry>true に設定すると、 DroppedException (無視された例外) ディテクタは空の catch ブロック にコメントが無いか探します。そして、コメントがみつかった場合には警告が報告されません。</entry>
    </row>
    <row>
      <entry>findbugs.maskedfields.locals</entry>
      <entry>true または false</entry>
      <entry>true に設定すると、フィールドを隠蔽しているローカル変数に対して優先度(低)の警告が発行されます。デフォルトは、 false です。</entry>
    </row>
    <row>
      <entry>findbugs.nullderef.assumensp</entry>
      <entry>true または false</entry>
      <entry>使用されません。 (意図 : true に設定すると、null 参照アクセスディテクタはメソッドからの戻り値、または、メソッドに受け渡される引数を null であると仮定します。デフォルトは、 false です。このプロパティーを有効にすると、大量の誤検出が生成されるであろうことに注意してください。)</entry>
    </row>
    <row>
      <entry>findbugs.refcomp.reportAll</entry>
      <entry>true または false</entry>
      <entry>true に設定すると、  == および != 演算子を使っている疑わしい参照比較がすべて報告されます。 false に設定すると、同様の警告は 1 メソッドにつき 1 つしか発行されません。デフォルトは、 false です。</entry>
    </row>
    <row>
      <entry>findbugs.sf.comment</entry>
      <entry>true または false</entry>
      <entry>true に設定すると、 SwitchFallthrough ディテクタはソースコードに「fall」または「nobreak」という単語を含んだコメントを記載していない caseラベル に限り警告を報告します。(この機能が正しく動作するためには、正確なソースパスが必要です。) これにより、意図的ではない switch 文の fallthrough を発見し易くなります。</entry>
    </row>

  </tbody>
</tgroup>
</table>

</chapter>

<chapter id="annotations">
<title>アノテーション</title>

<para>&FindBugs; はいくつかのアノテーションをサポートしています。開発者の意図を明確にすることで、 FindBugs はより的確に警告を発行することができます。アノテーションを使用するためには Java 5 が必要であり、 annotations.jar および jsr305.jar ファイルをコンパイル時のクラスパスに含める必要があります。</para>

<variablelist>
  <varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.CheckForNull</command></term>
    <listitem>
<command>[Target]</command> Field, Method, Parameter
    </listitem>
    <listitem>
      <para>アノテーションをつけた要素は、 null である可能性があります。したがって、当該要素を使用する際は null チェックをするべきです。このアノテーションをメソッドに適用すると、メソッドの戻り値に適用されます。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.CheckReturnValue</command></term>
    <listitem>
      <command>[Target]</command> Method, Constructor
    </listitem>
    <listitem>
      <variablelist>
        <varlistentry>
          <term><command>[Parameter]</command></term>
          <listitem>
            <para>
              <command>priority:</command> 警告の優先度を指定します (HIGH, MEDIUM, LOW, IGNORE) 。デフォルト値 :MEDIUM。</para>
          </listitem>
          <listitem>
            <para>
              <command>explanation:</command>戻り値をチェックしなけばならない理由をテキストで説明します。デフォルト値 :""。</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </listitem>
    <listitem>
      <para>このアノテーションを使用して、呼出し後に戻り値をチェックすべきメソッドを表すことができます。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.DefaultAnnotation</command></term>
    <listitem>
      <command>[Target]</command> Type, Package
    </listitem>
    <listitem>
      <variablelist>
        <varlistentry>
          <term><command>[Parameter]</command></term>
          <listitem>
            <para>
              <command>value:</command>アノテーションクラスのclassオブジェクト。複数のクラスを指定することができます。</para>
          </listitem>
          <listitem>
            <para>
              <command>priority:</command>省略時の優先度を指定します (HIGH, MEDIUM, LOW, IGNORE) 。デフォルト値 :MEDIUM。</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </listitem>
    <listitem>
      <para>
Indicates that all members of the class or package should be annotated with the default
value of the supplied annotation classes. This would be used for behavior annotations
such as @NonNull, @CheckForNull, or @CheckReturnValue. In particular, you can use
@DefaultAnnotation(NonNull.class) on a class or package, and then use @Nullable only
on those parameters, methods or fields that you want to allow to be null.
      </para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.DefaultAnnotationForFields</command></term>
    <listitem>
      <command>[Target]</command> Type, Package
    </listitem>
    <listitem>
      <variablelist>
        <varlistentry>
          <term><command>[Parameter]</command></term>
          <listitem>
            <para>
              <command>value:</command>アノテーションクラスのclassオブジェクト。複数のクラスを指定することができます。</para>
          </listitem>
          <listitem>
            <para>
              <command>priority:</command>省略時の優先度を指定します (HIGH, MEDIUM, LOW, IGNORE) 。デフォルト値 :MEDIUM。</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </listitem>
    <listitem>
      <para>
This is same as the DefaultAnnotation except it only applys to fields.
      </para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.DefaultAnnotationForMethods</command></term>
    <listitem>
      <command>[Target]</command> Type, Package
    </listitem>
    <listitem>
      <variablelist>
        <varlistentry>
          <term><command>[Parameter]</command></term>
          <listitem>
            <para>
              <command>value:</command>アノテーションクラスのclassオブジェクト。複数のクラスを指定することができます。</para>
          </listitem>
          <listitem>
            <para>
              <command>priority:</command>省略時の優先度を指定します (HIGH, MEDIUM, LOW, IGNORE) 。デフォルト値 :MEDIUM。</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </listitem>
    <listitem>
      <para>
This is same as the DefaultAnnotation except it only applys to methods.
      </para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.DefaultAnnotationForParameters</command></term>
    <listitem>
      <command>[Target]</command> Type, Package
    </listitem>
    <listitem>
      <variablelist>
        <varlistentry>
          <term><command>[Parameter]</command></term>
          <listitem>
            <para>
              <command>value:</command>アノテーションクラスのclassオブジェクト。複数のクラスを指定することができます。</para>
          </listitem>
          <listitem>
            <para>
              <command>priority:</command>省略時の優先度を指定します (HIGH, MEDIUM, LOW, IGNORE) 。デフォルト値 :MEDIUM。</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </listitem>
    <listitem>
      <para>
This is same as the DefaultAnnotation except it only applys to method parameters.
      </para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.NonNull</command></term>
    <listitem>
      <command>[Target]</command> Field, Method, Parameter
    </listitem>
    <listitem>
      <para>アノテーションをつけた要素は、 null であってはいけません。アノテーションをつけたフィールドは、構築完了後 null であってはいけません。アノテーションをつけたメソッドは、 null ではない値を戻り値としなければなりません。</para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.Nullable</command></term>
    <listitem>
      <command>[Target]</command> Field, Method, Parameter
    </listitem>
    <listitem>
      <para>アノテーションをつけた要素は、 null であってはいけません。In general, this means developers will have to read the documentation to determine when a null value is acceptable and whether it is neccessary to check for a null value. FindBugs will treat the annotated items as though they had no annotation.</para>
      <para>
In pratice this annotation is useful only for overriding an overarching NonNull
annotation.
      </para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.OverrideMustInvoke</command></term>
    <listitem>
      <command>[Target]</command> Method
    </listitem>
    <listitem>
      <variablelist>
        <varlistentry>
          <term><command>[Parameter]</command></term>
          <listitem>
            <para>
              <command>value:</command>Specify when the super invocation should be
              performed (FIRST, ANYTIME, LAST). Default value:ANYTIME.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </listitem>
    <listitem>
      <para>
Used to annotate a method that, if overridden, must (or should) be invoke super
in the overriding method. Examples of such methods include finalize() and clone().
The argument to the method indicates when the super invocation should occur:
at any time, at the beginning of the overriding method, or at the end of the overriding method.
(This anotation is not implmemented in FindBugs as of September 8, 2006).
      </para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.PossiblyNull</command></term>
    <listitem>
      <para>
This annotation is deprecated. Use CheckForNull instead.
      </para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.SuppressWarnings</command></term>
    <listitem>
      <command>[Target]</command> Type, Field, Method, Parameter, Constructor, Package
    </listitem>
    <listitem>
      <variablelist>
        <varlistentry>
          <term><command>[Parameter]</command></term>
          <listitem>
            <para>
              <command>value:</command>The name of the warning. More than one name can be specified.
            </para>
          </listitem>
          <listitem>
            <para>
              <command>justification:</command>Reason why the warning should be ignored. デフォルト値 :""。</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </listitem>
    <listitem>
      <para>
The set of warnings that are to be suppressed by the compiler in the annotated element.
Duplicate names are permitted.  The second and successive occurrences of a name are ignored.
The presence of unrecognized warning names is <emphasis>not</emphasis> an error: Compilers
must ignore any warning names they do not recognize. They are, however, free to emit a
warning if an annotation contains an unrecognized warning name. Compiler vendors should
document the warning names they support in conjunction with this annotation type. They
are encouraged to cooperate to ensure that the same names work across multiple compilers.
      </para>
    </listitem>
  </varlistentry>

<varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.UnknownNullness</command></term>
    <listitem>
      <command>[Target]</command> Field, Method, Parameter
    </listitem>
    <listitem>
      <para>
Used to indicate that the nullness of the target is unknown, or my vary in unknown ways in subclasses.
      </para>
    </listitem>
  </varlistentry>

<para>また、 &FindBugs; 次に示すアノテーションもサポートしています。 :<itemizedlist>
  <listitem>net.jcip.annotations.GuardedBy</listitem>
  <listitem>net.jcip.annotations.Immutable</listitem>
  <listitem>net.jcip.annotations.NotThreadSafe</listitem>
  <listitem>net.jcip.annotations.ThreadSafe</listitem>
</itemizedlist>
</para>
<para><ulink url="http://jcip.net/">Java Concurrency in Practice</ulink> の <ulink url="http://jcip.net/annotations/doc/index.html"> API ドキュメント</ulink> を参照してください。</para>
</chapter>

<chapter id="rejarForAnalysis">
<title>rejarForAnalysis の使用方法</title>

<para>プロジェクトに多くの jar ファイル があったり、 jar ファイルが多くのディレクトリに点在したりする場合は、 <command>rejarForAnalysis </command> スクリプトを使用すると FindBugs の実行が比較的簡単になります。このスクリプトは、数多い jar ファイルを集めて 1 つの大きな jar ファイルに結合します。そうすると、分析時にFindBugs に jar ファイルを設定することが比較的簡単になります。このスクリプトは、 unix システムの 'find' コマンドと組み合わせるととりわけ有用になります ; 次に例を示します。 <command>find . -name '*.jar' | xargs rejarForAnalysis </command>.</para>

<para>また、 <command>rejarForAnalysis</command> スクリプトは巨大なプロジェクトを複数の jar ファイルに分割することに使用できます。プロジェクトのクラスファイルは、複数の jar ファイルに均等に配分されます。これは、プロジェクト全体に対して FindBugs を実行すると時間とメモリ消費が著しい場合に有用です。プロジェクト全体に対して FindBugs を実行する代わりに、 <command> rejarForAnalysis</command> ですべてのクラスを含む大きな jar ファイルを構築します。続いて、 <command>rejarForAnalysis</command> を再び実行して複数の jar ファイルに分割します。そして、各々の jar ファイルに対して順に FindBugs を実行します。その際、 <command>-auxclasspath</command> に最初に 1 つにまとめた jar ファイルを指定してください。</para>

<para><command>rejarForAnalysis</command> スクリプトに指定することができるオプションを以下に示します :</para>

<variablelist>
  <varlistentry>
    <term><command>-maxAge</command> <replaceable>日数</replaceable></term>
    <listitem>
       <para>最後に更新された日からの経過時間を日単位で指定します (指定した日数より古い jar ファイルは無視されます)。</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-inputFileList</command> <replaceable>ファイル名</replaceable></term>
    <listitem>
       <para>jar ファイル名を記載したテキストファイルを指定します。</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-maxClasses</command> <replaceable>クラス数</replaceable></term>
    <listitem>
       <para>analysis*.jar ファイル 1 ファイルに対するクラスの最大数を指定します。</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-prefix</command> <replaceable>プレフィックス</replaceable></term>
    <listitem>
       <para>分析するクラス名のプレフィックスを指定します  (例、 edu.umd.cs.) 。</para>
    </listitem>
  </varlistentry>
</variablelist>
</chapter>

<chapter id="datamining">
    <title>&FindBugs;™ によるデータ・マイニング</title>

<para>バグデータベースへの高機能の問い合わせ機能、および、調査対象のコードの複数のバージョンにわたる警告の追跡記録機能を、 FindBugs は内蔵しています。これらを使って次のようなことができます。すなわち、いつバグが最初持ち込まれたかを捜し出すこと、最終リリース以後持ち込まれた警告の分析を行うこと、または、無限再起ループの数を時間軸でグラフにすることです。</para>

<para>これらの技術は、 FindBugs が警告の保存に使う XML 書式を使用します。これらの XML ファイルは、通常、特定の 1 分析に対する警告が入れられています。しかしそれらには、一連のソフトウェアのビルドやバージョンに対する分析結果を格納することもできます。</para>

<para>すべての FindBugs XML バグデータベースには、バージョン名とタイム・スタンプ が入れられています。FindBugs は分析が行われるファイルの更新時刻からタイム・スタンプを計算します (例えば、タイム・スタンプはクラスファイルの生成時刻になるようになっています。分析が行われた時刻ではありません) 。各々のバグデータベースには、バージョン名も入れられています。バージョン名とタイム・スタンプは、 <command>setBugDatabaseInfo</command> (<xref linkend="setBugDatabaseInfo"/>) コマンドを使用して手動で設定することもできます。</para>

<para>複数バージョンを格納するバグデータベースにおいては、分析されるコードの各バージョンごとにシーケンス番号が割り当てられます。これらのシーケンス番号は単に 0 から始まる連続する整数値です (例えば、 4 つのコードバージョンを格納するバグデータベースには、バージョン 0~3 が入れられます) 。バグデータベースにはまた、各バージョンの名前とタイム・スタンプがそれぞれ記録されます。<command>filterBugs</command> コマンドを使用すると、シーケンス番号、バージョン名またはタイム・スタンプからバージョンを参照することができます。</para>

<para>1 バージョンを格納するバグデータベースの集合から、 1 個の複数バージョンバグデータベースを作成することができます。また、複数バージョンバグデータベースに対して、それ以後に作成された 1 バージョンのバグデータベースを結合することができます。</para>

<para>これらのコマンドのいくつかは、 ant タスクとして実行することができます。コマンドの実行方法および属性・引数の詳細は、以下を参照してください。以下のすべての例においては、 <literal>findbugs.lib</literal> <literal>refid</literal> が正しく設定されていることを前提としています。設定方法の一例を次に示します :</para>

<para>FindBugs データ・マイニング ツールはすべてコマンドラインから実行することができます。また、いくつかのより有用なコマンドは、 ant ビルドファイルから実行することができます。</para>

<para>コマンドラインツールについて簡単に説明します :</para>

<variablelist>
            <varlistentry>
                <term><command><link linkend="unionBugs">unionBugs</link></command></term>
                <listitem>
                    <para>別のクラスに対する別個の分析結果を結合します。</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><command><link linkend="computeBugHistory">computeBugHistory</link></command></term>
                <listitem>
                    <para>複数バージョンから得られた複数のバグ警告を、マージして 1 個の複数バージョンバグデータベースにします。これを使って、既存の複数バージョンバグデータベースに更にバージョンを追加したり、 1 バージョンを格納するバグデータベースの集合から 1 個の複数バージョンバグデータベースを作成したり、できます。</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><command><link linkend="setBugDatabaseInfo">setBugDatabaseInfo</link></command></term>
                <listitem>
                    <para>リビジョン名やタイム・スタンプなどの情報を XML データベースに設定します。</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><command><link linkend="listBugDatabaseInfo">listBugDatabaseInfo</link></command></term>
                <listitem>
                    <para>XML データベースにあるリビジョン名やタイム・スタンプなどの情報を一覧表示します。</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><command><link linkend="filterBugs">filterBugs</link></command></term>
                <listitem>
                    <para>バグデータベースの部分集合を選択します。</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><command><link linkend="mineBugHistory">mineBugHistory</link></command></term>
                <listitem>
                    <para>複数バージョンバグデータベースの各バージョン毎の警告数を一覧にした表を作成します。</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><command><link linkend="defectDensity">defectDensity</link></command></term>
                <listitem>
                    <para>プロジェクト全体およびクラス毎・パッケージ毎の不良密度 (1000 NCSS 毎の警告数) に関する情報を一覧表示します。</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><command><link linkend="convertXmlToText">convertXmlToText</link></command></term>
                <listitem>
                    <para>XML 形式のバグ警告を、 1 行 1 バグのテキスト形式、または、HTML形式に変換します。</para>
                </listitem>
            </varlistentry>
        </variablelist>

<sect2 id="unionBugs">
            <title>unionBugs</title>

<para>分析するのにアプリケーションの jar ファイルを分割している場合、このコマンドを使用することで、別個に生成された XML バグ警告ファイルをすべての警告を含んでいる 1 つの ファイルにすることができます。</para>

<para>同じファイルの異なるバージョンを分析した結果を結合する場合は、このコマンドを<emphasis>使用しないでください</emphasis>。代わりに <command>computeBugHistory</command> を使用してください。</para>

<para>XML ファイルは、コマンドラインで指定してください。結果は、標準出力に送られます。</para>
        </sect2>

<sect2 id="computeBugHistory">
            <title>computeBugHistory</title>

<para>このコマンドを使用することで、分析するソフトウェアの異なるビルドまたはバージョンの情報を含むバグデータベースを生成することができます入力として提供したファイルの 1 番目のファイルから履歴が取得されます。後に続くファイルは 1 バージョンのバグデータベースであるようにしてください (もし、履歴を持っていたとしても無視されます) 。</para>
<para>デフォルトでは、結果は標準出力に送られます。</para>

<para>この機能は、 ant からも使用することができます。まず次に示すように、ビルドファイルに <command>computeBugHistory</command> を taskdef で定義します :</para>

<para>この ant タスクに指定できる属性を、下表に一覧で示します。入力ファイルを指定するには、 <literal><datafile></literal> 要素を入れ子にして入れてください。次に、例を示します:</para>

<table id="computeBugHistoryTable">
            <title>computeBugHistory コマンドのオプション一覧</title>
            <tgroup cols="3" align="left">
                  <thead>
                    <row>
                          <entry>コマンドラインオプション</entry>
                          <entry>Ant 属性</entry>
                          <entry>目的</entry>
                    </row>
                      </thead>
                  <tbody>
<row><entry>-output <file></entry>           <entry>output="<file>"</entry>           <entry>出力結果を保存するファイル名を指定します。 (同時に入力ファイルにもなりえます)</entry></row>
<row><entry>-overrideRevisionNames[:truth]</entry> <entry>overrideRevisionNames="[true|false]"</entry><entry>ファイル名から算出されるそれぞれのバージョン名を指定変更します。</entry></row>
<row><entry>-noPackageMoves[:truth]</entry>        <entry>noPackageMoves="[true|false]"</entry><entry>パッケージを移動したクラスがある場合、当該クラスの警告は別の存在として扱われます。</entry></row>
<row><entry>-preciseMatch[:truth]</entry>          <entry>preciseMatch="[true|false]"</entry><entry>バグパターンが正確に一致することを要求します。</entry></row>
<row><entry>-precisePriorityMatch[:truth]</entry>  <entry>precisePriorityMatch="[true|false]"</entry><entry>優先度が正確に一致した場合のみ警告が同一であると判断されます。</entry></row>
<row><entry>-quiet[:truth]</entry>                 <entry>quiet="[true|false]"</entry><entry>エラーが発生しない限り、標準出力には何も表示されません。</entry></row>
<row><entry>-withMessages[:truth]</entry>          <entry>withMessages="[true|false]"</entry><entry>出力 XML に人間が読むことができるバグメッセージが含まれます。</entry></row>
                </tbody>
            </tgroup>
        </table>

</sect2>
        <sect2 id="filterBugs">
            <title>filterBugs</title>
<para>このコマンドを使用することで、 FindBugs XML 警告ファイルから一部分を選び出して新規 FindBugs 警告ファイルに選択された部分を書き込むことができます。</para>
<para>このコマンドには、オプション群に続いて 0 個から 2 個の findbugs xml バグファイルを指定することができます。</para>
<para>ファイル名をひとつも指定しない場合は、標準入力から読んで標準出力に出力されます。ファイル名を 1 個 指定した場合は、指定したファイルから読んで標準出力に出力されます。ファイル名を 2 個 指定した場合は、 1 番目に指定したファイルから読んで 2 番目に指定したファイルに出力されます。</para>

<para>この機能は、 ant からも使用することができます。まず次に示すように、ビルドファイルに <command>filterBugs</command> を taskdef で定義します :</para>

<para>この ant タスクに指定できる属性を、下表に一覧で示します。入力ファイルを指定するには、 <literal>input</literal>  属性を使用するか、 <literal><datafile></literal> 要素を入れ子にして入れてください。次に、例を示します:</para>

<table id="filterOptionsTable">
            <title>filterBugs コマンドのオプション一覧</title>
            <tgroup cols="3" align="left">
                  <thead>
                    <row>
                          <entry>コマンドラインオプション</entry>
                          <entry>Ant 属性</entry>
                          <entry>目的</entry>
                    </row>
                      </thead>
                  <tbody>
<row><entry/>                            <entry>input="<file>"</entry>             <entry>入力ファイルを指定します。</entry></row>
<row><entry/>                            <entry>output="<file>"</entry>            <entry>出力ファイルを指定します。</entry></row>
<row><entry>-not</entry>                        <entry>not="[true|false]"</entry>               <entry>フィルターのスイッチを反転します。</entry></row>
<row><entry>-withSource[:truth]</entry>         <entry>withSource="[true|false]"</entry>        <entry>ソースが入手可能な警告のみ出力されます。</entry></row>
<row><entry>-exclude <filter file></entry><entry>exclude="<filter file>"</entry>    <entry>フィルターに一致するバグが除外されます。</entry></row>
<row><entry>-include <filter file></entry><entry>include="<filter file>"</entry>    <entry>フィルターに一致するバグのみを含まれます。</entry></row>
<row><entry>-annotation <text></entry>    <entry>annotation="<text>"</entry>        <entry>手で入力した注釈に指定した文言を含む警告のみ出力されます。</entry></row>
<row><entry>-after <when></entry>         <entry>after="<when>"</entry>             <entry>指定したバージョンより後に初めて出現した警告のみ出力されます。</entry></row>
<row><entry>-before <when></entry>        <entry>before="<when>"</entry>            <entry>指定したバージョンより前に初めて出現した警告のみ出力されます。</entry></row>
<row><entry>-first <when></entry>         <entry>first="<when>"</entry>             <entry>指定したバージョンに初めて出現した警告のみ出力されます。</entry></row>
<row><entry>-last <when></entry>          <entry>last="<when>"</entry>              <entry>指定したバージョンが出現した最後である警告のみ出力されます。</entry></row>
<row><entry>-fixed <when></entry>         <entry>fixed="<when>"</entry>             <entry>指定したバージョンの前回のバージョンが出現した最後である警告のみ出力されます。 (<option>-last</option> に優先します)。</entry></row>
<row><entry>-present <when></entry>       <entry>present="<when>"</entry>           <entry>指定したバージョンに存在する警告のみ出力されます。</entry></row>
<row><entry>-absent <when></entry>        <entry>absent="<when>"</entry>            <entry>指定したバージョンに存在しない警告のみ出力されます。</entry></row>
<row><entry>-active[:truth]</entry>             <entry>active="[true|false]"</entry>            <entry>最終通番に存在する警告のみ出力されます。</entry></row>
<row><entry>-introducedByChange[:truth]</entry> <entry>introducedByChange="[true|false]"</entry><entry>存在するクラスの変更によってもたらされた警告のみ出力されます。</entry></row>
<row><entry>-removedByChange[:truth]</entry>    <entry>removedByChange="[true|false]"</entry>   <entry>存在するクラスの変更によって除去された警告のみ出力されます。</entry></row>
<row><entry>-newCode[:truth]</entry>            <entry>newCode="[true|false]"</entry>           <entry>新クラスの追加によってもたらされた警告のみ出力されます。</entry></row>
<row><entry>-removedCode[:truth]</entry>        <entry>removedCode="[true|false]"</entry>       <entry>クラスの削除によって除去された警告のみ出力されます。</entry></row>
<row><entry>-priority <level></entry>     <entry>priority="<level>"</entry>         <entry>指定した優先度以上の優先度をもつ警告のみ出力されます。</entry></row>
<row><entry>-class <pattern></entry>      <entry>class="<class>"</entry>            <entry>指定したパターンに一致する主クラスをもつ警告のみ出力されます。</entry></row>
<row><entry>-bugPattern <pattern></entry> <entry>bugPattern="<pattern>"</entry>     <entry>指定したパターンに一致するバグ種別をもつ警告のみ出力されます。</entry></row>
<row><entry>-category <category></entry>  <entry>category="<category>"</entry>      <entry>指定した文字列で始まるカテゴリーの警告のみ出力されます。</entry></row>
<row><entry>-designation <designation></entry> <entry>designation="<designation>"</entry> <entry>指定したバグ分類指定をもつ警告のみ出力されます。 (例、 -designation SHOULD_FIX)</entry></row>
<row><entry>-withMessages[:truth] </entry>      <entry>withMessages="[true|false]"</entry>      <entry>テキストメッセージを含んだ XML が生成されます。</entry></row>
                </tbody>
            </tgroup>
        </table>

</sect2>

<sect2 id="mineBugHistory">
            <title>mineBugHistory</title>
<para>このコマンドを使用することで、複数バージョンバグデータベースの各バージョン毎の警告数を一覧にした表を作成することができます。</para>

<para>この機能は、 ant からも使用することができます。まず次に示すように、ビルドファイルに <command>mineBugHistory</command> を taskdef で定義します :</para>

<table id="mineBugHistoryOptionsTable">
            <title>mineBugHistory コマンドのオプション一覧</title>
            <tgroup cols="3" align="left">
                  <thead>
                    <row>
                          <entry>コマンドラインオプション</entry>
                          <entry>Ant 属性</entry>
                          <entry>目的</entry>
                    </row>
                  </thead>
                  <tbody>
<row><entry/>               <entry>input="<file>"</entry>             <entry>入力ファイルを指定します。</entry></row>
<row><entry/>               <entry>output="<file>"</entry>            <entry>出力ファイルを指定します。</entry></row>
<row><entry>-formatDates</entry>   <entry>formatDates="[true|false]"</entry>       <entry>データがテキスト形式で描画されます。</entry></row>
<row><entry>-noTabs</entry>        <entry>noTabs="[true|false]"</entry>            <entry>タブの代わりに複数スペースでカラムが区切られます (下記参照)。</entry></row>
<row><entry>-summary</entry>       <entry>summary="[true|false]"</entry>           <entry>最新 10 件の変更の要約が出力されます。</entry></row>
                </tbody>
            </tgroup>
        </table>

<para><option>-noTabs</option> 出力を使うことで、固定幅フォントのシェルで読み易くなります。数値カラムは右寄せされるので、スペースがカラム値の前に挿入されます。また、このオプションを使用した場合、 <option>-formatDates</option> を指定したときに要約の日付を描画するのに空白が埋め込まれなくなります。</para>

<para>出力される表は、 (<option>-noTabs</option> が無ければ) タブ区切りで次に示すカラムから成ります :</para>

<table id="mineBugHistoryColumns">
            <title>mineBugHistory 出力のカラム一覧</title>
            <tgroup cols="2" align="left">
                  <thead>
                    <row>
                          <entry>表題</entry>
                          <entry>目的</entry>
                    </row>
                      </thead>
                  <tbody>
                      <row><entry>seq</entry><entry>シーケンス番号 (0 始まりの連続した整数値)</entry></row>
                      <row><entry>version</entry><entry>バージョン名</entry></row>
                      <row><entry>time</entry><entry>リリースされた日時</entry></row>
                      <row><entry>classes</entry><entry>分析されたクラス数</entry></row>
                      <row><entry>NCSS</entry><entry>コメント文を除いた命令数 (Non Commenting Source Statements)</entry></row>
                      <row><entry>added</entry><entry>前回のバージョンに存在したクラスにおける新規警告数</entry></row>
                      <row><entry>newCode</entry><entry>前回のバージョンに存在しなかったクラスにおける新規警告数</entry></row>
                      <row><entry>fixed</entry><entry>現在のバージョンに存在するクラスにおける除去された警告数</entry></row>
                      <row><entry>removed</entry><entry>現在のバージョンに存在しないクラスの前回のバージョンにおける警告数</entry></row>
                      <row><entry>retained</entry><entry>現在のバージョンと前回のバージョンの両方に存在する警告の数</entry></row>
                      <row><entry>dead</entry><entry>以前のバージョンに存在したが現在のバージョンにも直前のバージョンにも存在しない警告の数</entry></row>
                      <row><entry>active</entry><entry>現在のバージョンに存在する警告総数</entry></row>
                </tbody>
                </tgroup>
        </table>
        </sect2>

<sect2 id="defectDensity">
            <title>defectDensity</title>
<para>このコマンドを使用することで、プロジェクト全体およびクラス毎・パッケージ毎の不良密度 (1000 NCSS 毎の警告数) に関する情報を一覧表示できます。標準入力から読み込む場合はファイル指定なしで、そうでなければ、コマンドラインでファイルを指定して、このコマンドを実行します。</para>
<para>出力される表は、次に示すカラムから成ります。また、プロジェクト全体情報の行、および、4 個以上の警告を含んでいる各パッケージ情報または各クラス情報の行も出力されます。</para>
        <table id="defectDensityColumns">
            <title>defectDensity 出力のカラム一覧</title>
            <tgroup cols="2" align="left">
                  <thead>
                    <row>
                          <entry>表題</entry>
                          <entry>目的</entry>
                    </row>
                      </thead>
                  <tbody>
                      <row><entry>kind</entry><entry>プロジェクト (project)、パッケージ (package) またはクラス (class)</entry></row>
                      <row><entry>name</entry><entry>プロジェクト、パッケージまたはクラスの名前</entry></row>
                      <row><entry>density</entry><entry> 1000 NCSS 毎の警告数</entry></row>
                      <row><entry>bugs</entry><entry>警告数</entry></row>
                      <row><entry>NCSS</entry><entry>コメント文を除いた命令数 (Non Commenting Source Statements) </entry></row>
                </tbody>
                </tgroup>
            </table>
        </sect2>

<sect2 id="convertXmlToText">
            <title>convertXmlToText</title>

<para>このコマンドを使用することで、XML 形式のバグ警告を、 1 行 1 バグのテキスト形式、または、HTML形式に変換することができます。</para>

<para>この機能は、 ant からも使用することができます。まず次に示すように、ビルドファイルに <command>convertXmlToText</command> を taskdef で定義します :</para>

<para>この ant タスクに指定できる属性を、下表に一覧で示します。</para>

<table id="convertXmlToTextTable">
            <title>convertXmlToText コマンドのオプション一覧</title>
            <tgroup cols="3" align="left">
                  <thead>
                    <row>
                          <entry>コマンドラインオプション</entry>
                          <entry>Ant 属性</entry>
                          <entry>目的</entry>
                    </row>
                      </thead>
                  <tbody>
<row><entry/>                   <entry>input="<filename>"</entry>         <entry>入力ファイルを指定します。</entry></row>
<row><entry/>                   <entry>output="<filename>"</entry>        <entry>出力ファイルを指定します。</entry></row>
<row><entry>-longBugCodes</entry>      <entry>longBugCodes="[true|false]"</entry>      <entry>2 文字のバグ略称の代わりに、省略なしのバグパターンコードを使用します。</entry></row>
<row><entry/>                   <entry>format="text"</entry>                    <entry>プレーンテキストの出力が作成されます。1 行につき 1 つのバグが出力されます。コマンドライン時のデフォルトです。</entry></row>
<row><entry>-html[:stylesheet]</entry> <entry>format="html:<stylesheet>"</entry> <entry>指定されたスタイルシートを使用して出力が作成されます (下記参照) 。省略した場合は、 default.xsl が使用されます。</entry></row>
                </tbody>
            </tgroup>
            </table>

<para>-html/format オプションには、plain.xsl 、 default.xsl 、 fancy.xsl 、 fancy-hist.xsl または ユーザ自身が作成した XSL スタイルシートのいずれかを指定することができます。オプション名をよそに、 html 以外の形式を出力するスタイルシートを指定することもできます。FindBugs に含まれているスタイルシート(上述)以外のスタイルシートを使用する場合は、オプション -html/format で当該スタイルシートへのパスまたは URL を指定してください。</para>
        </sect2>

<sect2 id="setBugDatabaseInfo">
            <title>setBugDatabaseInfo</title>

<para>このコマンドを使用することで、指定したバグ警告にメタ情報を設定することができます。このコマンドには次に示すオプションがあります:</para>

<para>この機能は、 ant からも使用することができます。まず次に示すように、ビルドファイルに <command>setBugDatabaseInfo</command> を taskdef で定義します :</para>

<table id="setBugDatabaseInfoOptions">
            <title>setBugDatabaseInfo オプション一覧</title>
            <tgroup cols="3" align="left">
                  <thead>
                    <row>
                          <entry>コマンドラインオプション</entry>
                          <entry>Ant 属性</entry>
                          <entry>目的</entry>
                    </row>
                  </thead>
                  <tbody>
                      <row><entry/>                              <entry>input="<file>"</entry>           <entry>入力ファイルを指定します。</entry></row>
                      <row><entry/>                              <entry>output="<file>"</entry>          <entry>出力ファイルを指定します。</entry></row>
                      <row><entry>-name <name></entry>            <entry>name="<name>"</entry>            <entry>最新リビジョンの名前を設定します。</entry></row>
                      <row><entry>-timestamp <when></entry>       <entry>timestamp="<when>"</entry>       <entry>最新リビジョンのタイム・スタンプを設定します。</entry></row>
                      <row><entry>-source <directory></entry>     <entry>source="<directory>"</entry>     <entry>ソースを検索するディレクトリーを追加指定します。</entry></row>
                      <row><entry>-findSource <directory></entry> <entry>findSource="<directory>"</entry> <entry>指定したディレクトリー内を検索して関連するソースの場所を追加します。</entry></row>
                      <row><entry>-suppress <filter file></entry> <entry>suppress="<filter file>"</entry> <entry>指定したファイルに一致する警告を抑止します (以前に指定した抑止設定は置き換えられます)。</entry></row>
                      <row><entry>-withMessages</entry>                 <entry>withMessages="[true|false]"</entry>    <entry>XMLにテキストメッセージを追加します。</entry></row>
                      <row><entry>-resetSource</entry>                  <entry>resetSource="[true|false]"</entry>     <entry>ソース検索パスをすべて削除します。</entry></row>
                 </tbody>
                </tgroup>
            </table>
        </sect2>

<sect2 id="listBugDatabaseInfo">
            <title>listBugDatabaseInfo</title>

<para>このコマンドの実行においては、コマンドラインで 0 個以上の xml バグデータベースファイル名を指定します。ファイル名を1つも指定しなければ、標準出力から読み込みを行いテーブルのヘッダーは生成されません。</para>

<para>このコマンドには 1 つだけオプションがあります : <option>-formatDates</option> を指定するとテキスト形式でデータが描画されます。</para>

<para>出力される表は、各バグデータベースごとに行を持ち、次に示すカラムから成ります :</para>
        <table id="listBugDatabaseInfoColumns">
            <title>listBugDatabaseInfo カラム一覧</title>
            <tgroup cols="2" align="left">
                  <thead>
                    <row>
                          <entry>カラム</entry>
                          <entry>目的</entry>
                    </row>
                  </thead>
                  <tbody>
                      <row><entry>version</entry><entry>バージョン名</entry></row>
                      <row><entry>time</entry><entry>リリースされた日時</entry></row>
                      <row><entry>classes</entry><entry>分析されたクラス数</entry></row>
                      <row><entry>NCSS</entry><entry>コメント文を除いた命令数 (Non Commenting Source Statements)</entry></row>
                      <row><entry>total</entry><entry>全警告数</entry></row>
                      <row><entry>high</entry><entry>優先度(高)の警告の総数</entry></row>
                      <row><entry>medium</entry><entry>優先度(中)の警告の総数</entry></row>
                      <row><entry>low</entry><entry>優先度(低)の警告の総数</entry></row>
                      <row><entry>filename</entry><entry>データベースのファイル名</entry></row>

                 </tbody>
                </tgroup>
            </table>

</sect2>

</sect1>

<sect1 id="examples">
        <title>例</title>
<sect2 id="unixscriptsexamples">
   <title>提供されたシェル・スクリプトを使用しての履歴マイニング</title>
<para>以下はすべて、 jdk1.6.0-b12, jdk1.6.0-b13, ..., jdk1.6.0-b60 のディレクトリに対してコマンドを実行しています。</para>

<para>以下のコマンドを実行してみます :</para>
<screen>
computeBugHistory jdk1.6.0-b* | filterBugs -bugPattern IL_ | mineBugHistory -formatDates
</screen>
<para>すると、次のような出力が行われます :</para>

<screen>
seq	version	time	classes	NCSS	added	newCode	fixed	removed	retained	dead	active
0	jdk1.6.0-b12	"Thu Nov 11 09:07:20 EST 2004"	13128	811569	0	4	0	0	0	0	4
1	jdk1.6.0-b13	"Thu Nov 18 06:02:06 EST 2004"	13128	811570	0	0	0	0	4	0	4
2	jdk1.6.0-b14	"Thu Dec 02 06:12:26 EST 2004"	13145	811786	0	0	2	0	2	0	2
3	jdk1.6.0-b15	"Thu Dec 09 06:07:04 EST 2004"	13174	811693	0	0	1	0	1	2	1
4	jdk1.6.0-b16	"Thu Dec 16 06:21:28 EST 2004"	13175	811715	0	0	0	0	1	3	1
5	jdk1.6.0-b17	"Thu Dec 23 06:27:22 EST 2004"	13176	811974	0	0	0	0	1	3	1
6	jdk1.6.0-b19	"Thu Jan 13 06:41:16 EST 2005"	13176	812011	0	0	0	0	1	3	1
7	jdk1.6.0-b21	"Thu Jan 27 05:57:52 EST 2005"	13177	812173	0	0	0	0	1	3	1
8	jdk1.6.0-b23	"Thu Feb 10 05:44:36 EST 2005"	13179	812188	0	0	0	0	1	3	1
9	jdk1.6.0-b26	"Thu Mar 03 06:04:02 EST 2005"	13199	811770	0	0	0	0	1	3	1
10	jdk1.6.0-b27	"Thu Mar 10 04:48:38 EST 2005"	13189	812440	0	0	0	0	1	3	1
11	jdk1.6.0-b28	"Thu Mar 17 02:54:22 EST 2005"	13185	812056	0	0	0	0	1	3	1
12	jdk1.6.0-b29	"Thu Mar 24 03:09:20 EST 2005"	13117	809468	0	0	0	0	1	3	1
13	jdk1.6.0-b30	"Thu Mar 31 02:53:32 EST 2005"	13118	809501	0	0	0	0	1	3	1
14	jdk1.6.0-b31	"Thu Apr 07 03:00:14 EDT 2005"	13117	809572	0	0	0	0	1	3	1
15	jdk1.6.0-b32	"Thu Apr 14 02:56:56 EDT 2005"	13169	811096	0	0	0	0	1	3	1
16	jdk1.6.0-b33	"Thu Apr 21 02:46:22 EDT 2005"	13187	811942	0	0	0	0	1	3	1
17	jdk1.6.0-b34	"Thu Apr 28 02:49:00 EDT 2005"	13195	813488	0	1	0	0	1	3	2
18	jdk1.6.0-b35	"Thu May 05 02:49:04 EDT 2005"	13457	829837	0	0	0	0	2	3	2
19	jdk1.6.0-b36	"Thu May 12 02:59:46 EDT 2005"	13462	831278	0	0	0	0	2	3	2
20	jdk1.6.0-b37	"Thu May 19 02:55:08 EDT 2005"	13464	831971	0	0	0	0	2	3	2
21	jdk1.6.0-b38	"Thu May 26 03:08:16 EDT 2005"	13564	836565	0	0	0	0	2	3	2
22	jdk1.6.0-b39	"Fri Jun 03 03:10:48 EDT 2005"	13856	849992	0	1	0	0	2	3	3
23	jdk1.6.0-b40	"Thu Jun 09 03:30:28 EDT 2005"	15972	959619	0	2	0	0	3	3	5
24	jdk1.6.0-b41	"Thu Jun 16 03:19:22 EDT 2005"	15972	959619	0	0	0	0	5	3	5
25	jdk1.6.0-b42	"Fri Jun 24 03:38:54 EDT 2005"	15966	958581	0	0	0	0	5	3	5
26	jdk1.6.0-b43	"Thu Jul 14 03:09:34 EDT 2005"	16041	960544	0	0	0	0	5	3	5
27	jdk1.6.0-b44	"Thu Jul 21 03:05:54 EDT 2005"	16041	960547	0	0	0	0	5	3	5
28	jdk1.6.0-b45	"Thu Jul 28 03:26:10 EDT 2005"	16037	960606	0	0	1	0	4	3	4
29	jdk1.6.0-b46	"Thu Aug 04 03:02:48 EDT 2005"	15936	951355	0	0	0	0	4	4	4
30	jdk1.6.0-b47	"Thu Aug 11 03:18:56 EDT 2005"	15964	952387	0	0	1	0	3	4	3
31	jdk1.6.0-b48	"Thu Aug 18 08:10:40 EDT 2005"	15970	953421	0	0	0	0	3	5	3
32	jdk1.6.0-b49	"Thu Aug 25 03:24:38 EDT 2005"	16048	958940	0	0	0	0	3	5	3
33	jdk1.6.0-b50	"Thu Sep 01 01:52:40 EDT 2005"	16287	974937	1	0	0	0	3	5	4
34	jdk1.6.0-b51	"Thu Sep 08 01:55:36 EDT 2005"	16362	979377	0	0	0	0	4	5	4
35	jdk1.6.0-b52	"Thu Sep 15 02:04:08 EDT 2005"	16477	979399	0	0	0	0	4	5	4
36	jdk1.6.0-b53	"Thu Sep 22 02:00:28 EDT 2005"	16019	957900	0	0	1	0	3	5	3
37	jdk1.6.0-b54	"Thu Sep 29 01:54:34 EDT 2005"	16019	957900	0	0	0	0	3	6	3
38	jdk1.6.0-b55	"Thu Oct 06 01:54:14 EDT 2005"	16051	959014	0	0	0	0	3	6	3
39	jdk1.6.0-b56	"Thu Oct 13 01:54:12 EDT 2005"	16211	970835	0	0	0	0	3	6	3
40	jdk1.6.0-b57	"Thu Oct 20 01:55:26 EDT 2005"	16279	971627	0	0	0	0	3	6	3
41	jdk1.6.0-b58	"Thu Oct 27 01:56:30 EDT 2005"	16283	971945	0	0	0	0	3	6	3
42	jdk1.6.0-b59	"Thu Nov 03 01:56:58 EST 2005"	16232	972193	0	0	0	0	3	6	3
43	jdk1.6.0-b60	"Thu Nov 10 01:54:18 EST 2005"	16235	972346	0	0	0	0	3	6	3
</screen>

<para>次に示すコマンドを実行すると、db.xml 中間ファイルを生成することなく直接同じ情報を作成できます。</para>

<screen>
computeBugHistory  jdk1.6.0-b*/jre/lib/rt.xml | filterBugs -bugPattern IL_ db.xml | mineBugHistory -formatDates
</screen>

<para>この情報を使って、 Sun JDK1.6.0 の各ビルドにおいて FindBugs によって発見された無限再起ループの数を表すグラフを表示します。青色の領域は、当該ビルドにおける無限再起ループの数を表しています。その上に描かれている赤色の領域は、以前のバージョンには存在したが当該バージョンでは除去された無限再起ループの数を表しています。 (したがって、赤色の領域と青色の領域を足し合わせた高さは決して減少しないことが保証されています。そして、新たに無限再起ループのバグが持ち込まれた時点で増加します) 。赤色の領域の高さは、当該バージョンにおいて修正または削除されたバグ数の合計で算出されます。バージョン 13 および 14 において見られる減少は、 FindBugs を使用して見つかった JDK のバグの報告を Sun が受け取ったことによるものです。</para>
<mediaobject>
<imageobject>
<imagedata fileref="infiniteRecursiveLoops.png"/>
</imageobject>
</mediaobject>

<para>db.xml ファイルは、 jdk1.6.0 のすべてのビルドに対する検索結果を保持しています。したがって、次に示すコマンドを実行することで、優先度(高)または優先度(低)の正確性に関する警告の履歴が表示されます :</para>

<screen>
filterBugs -priority M -category C db.xml | mineBugHistory -formatDates
</screen>

<para>作成される表の例 :</para>

<screen>
seq	version	time	classes	NCSS	added	newCode	fixed	removed	retained	dead	active
0	jdk1.6.0-b12	"Thu Nov 11 09:07:20 EST 2004"	13128	811569	0	1075	0	0	0	0	1075
1	jdk1.6.0-b13	"Thu Nov 18 06:02:06 EST 2004"	13128	811570	0	0	0	0	1075	0	1075
2	jdk1.6.0-b14	"Thu Dec 02 06:12:26 EST 2004"	13145	811786	3	0	6	0	1069	0	1072
3	jdk1.6.0-b15	"Thu Dec 09 06:07:04 EST 2004"	13174	811693	2	1	3	0	1069	6	1072
4	jdk1.6.0-b16	"Thu Dec 16 06:21:28 EST 2004"	13175	811715	0	0	1	0	1071	9	1071
5	jdk1.6.0-b17	"Thu Dec 23 06:27:22 EST 2004"	13176	811974	0	0	1	0	1070	10	1070
6	jdk1.6.0-b19	"Thu Jan 13 06:41:16 EST 2005"	13176	812011	0	0	0	0	1070	11	1070
7	jdk1.6.0-b21	"Thu Jan 27 05:57:52 EST 2005"	13177	812173	0	0	1	0	1069	11	1069
8	jdk1.6.0-b23	"Thu Feb 10 05:44:36 EST 2005"	13179	812188	0	0	0	0	1069	12	1069
9	jdk1.6.0-b26	"Thu Mar 03 06:04:02 EST 2005"	13199	811770	0	0	2	1	1066	12	1066
10	jdk1.6.0-b27	"Thu Mar 10 04:48:38 EST 2005"	13189	812440	1	0	1	1	1064	15	1065
11	jdk1.6.0-b28	"Thu Mar 17 02:54:22 EST 2005"	13185	812056	0	0	0	0	1065	17	1065
12	jdk1.6.0-b29	"Thu Mar 24 03:09:20 EST 2005"	13117	809468	3	0	8	26	1031	17	1034
13	jdk1.6.0-b30	"Thu Mar 31 02:53:32 EST 2005"	13118	809501	0	0	0	0	1034	51	1034
14	jdk1.6.0-b31	"Thu Apr 07 03:00:14 EDT 2005"	13117	809572	0	0	0	0	1034	51	1034
15	jdk1.6.0-b32	"Thu Apr 14 02:56:56 EDT 2005"	13169	811096	1	1	0	1	1033	51	1035
16	jdk1.6.0-b33	"Thu Apr 21 02:46:22 EDT 2005"	13187	811942	3	0	2	1	1032	52	1035
17	jdk1.6.0-b34	"Thu Apr 28 02:49:00 EDT 2005"	13195	813488	0	1	0	0	1035	55	1036
18	jdk1.6.0-b35	"Thu May 05 02:49:04 EDT 2005"	13457	829837	0	36	2	0	1034	55	1070
19	jdk1.6.0-b36	"Thu May 12 02:59:46 EDT 2005"	13462	831278	0	0	0	0	1070	57	1070
20	jdk1.6.0-b37	"Thu May 19 02:55:08 EDT 2005"	13464	831971	0	1	1	0	1069	57	1070
21	jdk1.6.0-b38	"Thu May 26 03:08:16 EDT 2005"	13564	836565	1	7	2	6	1062	58	1070
22	jdk1.6.0-b39	"Fri Jun 03 03:10:48 EDT 2005"	13856	849992	6	39	5	0	1065	66	1110
23	jdk1.6.0-b40	"Thu Jun 09 03:30:28 EDT 2005"	15972	959619	7	147	11	0	1099	71	1253
24	jdk1.6.0-b41	"Thu Jun 16 03:19:22 EDT 2005"	15972	959619	0	0	0	0	1253	82	1253
25	jdk1.6.0-b42	"Fri Jun 24 03:38:54 EDT 2005"	15966	958581	3	0	1	2	1250	82	1253
26	jdk1.6.0-b43	"Thu Jul 14 03:09:34 EDT 2005"	16041	960544	5	11	15	8	1230	85	1246
27	jdk1.6.0-b44	"Thu Jul 21 03:05:54 EDT 2005"	16041	960547	0	0	0	0	1246	108	1246
28	jdk1.6.0-b45	"Thu Jul 28 03:26:10 EDT 2005"	16037	960606	19	0	2	0	1244	108	1263
29	jdk1.6.0-b46	"Thu Aug 04 03:02:48 EDT 2005"	15936	951355	13	1	1	32	1230	110	1244
30	jdk1.6.0-b47	"Thu Aug 11 03:18:56 EDT 2005"	15964	952387	163	8	7	20	1217	143	1388
31	jdk1.6.0-b48	"Thu Aug 18 08:10:40 EDT 2005"	15970	953421	0	0	0	0	1388	170	1388
32	jdk1.6.0-b49	"Thu Aug 25 03:24:38 EDT 2005"	16048	958940	1	11	1	0	1387	170	1399
33	jdk1.6.0-b50	"Thu Sep 01 01:52:40 EDT 2005"	16287	974937	19	27	16	7	1376	171	1422
34	jdk1.6.0-b51	"Thu Sep 08 01:55:36 EDT 2005"	16362	979377	1	15	3	0	1419	194	1435
35	jdk1.6.0-b52	"Thu Sep 15 02:04:08 EDT 2005"	16477	979399	0	0	1	1	1433	197	1433
36	jdk1.6.0-b53	"Thu Sep 22 02:00:28 EDT 2005"	16019	957900	13	12	16	20	1397	199	1422
37	jdk1.6.0-b54	"Thu Sep 29 01:54:34 EDT 2005"	16019	957900	0	0	0	0	1422	235	1422
38	jdk1.6.0-b55	"Thu Oct 06 01:54:14 EDT 2005"	16051	959014	1	4	7	0	1415	235	1420
39	jdk1.6.0-b56	"Thu Oct 13 01:54:12 EDT 2005"	16211	970835	6	8	37	0	1383	242	1397
40	jdk1.6.0-b57	"Thu Oct 20 01:55:26 EDT 2005"	16279	971627	0	0	0	0	1397	279	1397
41	jdk1.6.0-b58	"Thu Oct 27 01:56:30 EDT 2005"	16283	971945	0	1	1	0	1396	279	1397
42	jdk1.6.0-b59	"Thu Nov 03 01:56:58 EST 2005"	16232	972193	6	0	5	0	1392	280	1398
43	jdk1.6.0-b60	"Thu Nov 10 01:54:18 EST 2005"	16235	972346	0	0	0	0	1398	285	1398
44	jdk1.6.0-b61	"Thu Nov 17 01:58:42 EST 2005"	16202	971134	2	0	4	0	1394	285	1396
</screen>
</sect2>

<sect2 id="incrementalhistory">
    <title>増分履歴メンテナンス</title>

<para>仮に、 db.xml がビルド b12 - b60 に対する findbugs 実行結果を保持している場合、次に示すコマンドを実行することで、 db.xml に b61 に対する実行結果を追加することができます :</para>
<screen>
computeBugHistory -output db.xml db.xml jdk1.6.0-b61/jre/lib/rt.xml
</screen>
</sect2>

</sect1>

<sect1 id="antexample">
            <title>Ant の例</title>
<para>findbugs の実行とその後のデータ・マイニングツールの活用の両方を実行している ant スクリプトの完全な例を以下に示します :</para>
<screen>
<![CDATA[
<project name="analyze_asm_util" default="findbugs">
   
   <property name="findbugs.home" value="/Users/ben/Documents/workspace/findbugs/findbugs" />
   <property name="jvmargs" value="-server -Xss1m -Xmx800m -Duser.language=en -Duser.region=EN -Dfindbugs.home=${findbugs.home}" />

<target name="findbugs">
      <antcall target="analyze" />
      <antcall target="mine" />
   </target>

<target name="analyze">
      
      <findbugs home="${findbugs.home}"
                output="xml:withMessages"
                timeout="90000000"
                reportLevel="experimental"
                workHard="true"
                effort="max"
                adjustExperimental="true"
                jvmargs="${jvmargs}"
                failOnError="true"
                outputFile="out.xml"
                projectName="Findbugs"
                debug="false">
         <class location="asm-util-3.0.jar" />
      </findbugs>
   </target>

<setBugDatabaseInfo home="${findbugs.home}"
                            withMessages="true"
                            name="asm-util-3.0.jar"
                            input="out.xml"
                            output="out-rel.xml"/>

<condition property="mining.historyfile.available">
         <available file="out-hist.xml"/>
      </condition>
      <condition property="mining.historyfile.notavailable">
         <not>
            <available file="out-hist.xml"/>
         </not>
      </condition>

<antcall target="history-init">
        <param name="data.file" value="out-rel.xml" />
        <param name="hist.file" value="out-hist.xml" />
      </antcall>
      
      <antcall target="history">
        <param name="data.file"         value="out-rel.xml" />
        <param name="hist.file"         value="out-hist.xml" />
        <param name="hist.summary.file" value="out-hist.txt" />
      </antcall>
   </target>

<target name="history-init" if="mining.historyfile.notavailable">
      <copy file="${data.file}" tofile="${hist.file}" />
   </target>

<target name="history" if="mining.historyfile.available">
      
      <computeBugHistory home="${findbugs.home}"
                           withMessages="true"
                           output="${hist.file}">
            <dataFile name="${hist.file}"/>
            <dataFile name="${data.file}"/>
      </computeBugHistory>

<mineBugHistory home="${findbugs.home}"
                        formatDates="true"
                      noTabs="true"
                        input="${hist.file}"
                        output="${hist.summary.file}"/>
   </target>

</project>
]]>
</screen>
         </sect1>
</chapter>

<chapter id="license">
<title>ライセンス</title>

<para>名称「FindBugs」および FindBugs のロゴは、メリーランド大学の登録商標です。FindBugs はフリーソフトウェアであり、 <ulink url="http://www.gnu.org/licenses/lgpl.html">Lesser GNU Public License</ulink> の条件で配布されています。使用承諾書を入手したい場合は、 &FindBugs; 配布物に含まれる <filename>LICENSE.txt</filename> ファイルを参照してください。</para>

<para>最新バージョンの FindBugs および そのソースコードは <ulink url="http://findbugs.sourceforge.net">FindBugs web ページ</ulink> で入手できます。</para>

</chapter>

<chapter id="acknowledgments">
<title>謝辞</title>

<para>&FindBugs; was originally written by Bill Pugh (<email>pugh@cs.umd.edu</email>).
David Hovemeyer (<email>daveho@cs.umd.edu</email>) implemented some of the
detectors, added the Swing GUI, and is a co-maintainer.</para>

<para>Mike Fagan (<email>mfagan@tde.com</email>) contributed the &Ant; build script,
the &Ant; task, and several enhancements and bug fixes to the GUI.</para>

<para>Germano Leichsenring contributed Japanese translations of the bug
summaries.</para>

<para>David Li contributed the Emacs bug report format.</para>

<para>Peter D. Stout contributed recursive detection of Class-Path
attributes in analyzed Jar files, German translations of
text used in the Swing GUI, and other fixes.</para>

<para>Peter Friese wrote the &FindBugs; Eclipse plugin.</para>

<para>Rohan Lloyd contributed several Mac OS X enhancements,
bug detector improvements,
and maintains the Fink package for &FindBugs;.</para>

<para>Hiroshi Okugawa translated the &FindBugs; manual and
more of the bug summaries into Japanese.</para>

<para>Phil Crosby enhanced the Eclipse plugin to add a view
to display the bug details.</para>

<para>Dave Brosius fixed a number of bugs, added user preferences
to the Swing GUI, improved several bug detectors, and
contributed the string concatenation detector.</para>

<para>Thomas Klaeger contributed a number of bug fixes and
bug detector improvements.</para>

<para>Andrei Loskutov made a number of improvements to the
Eclipse plugin.</para>

<para>Brian Goetz contributed a major refactoring of the
visitor classes to improve readability and understandability.</para>

<para> Pete Angstadt fixed several problems in the Swing GUI.</para>

<para>Francis Lalonde provided a task resource file for the
FindBugs Ant task.</para>

<para>Garvin LeClaire contributed support for output in
Xdocs format, for use by Maven.</para>

<para>Holger Stenzhorn contributed improved German translations of items
in the Swing GUI.</para>

<para>Juha Knuutila contributed Finnish translations of items
in the Swing GUI.</para>

<para>Tanel Lebedev contributed Estonian translations of items
in the Swing GUI.</para>

<para>Hanai Shisei (ruimo) contributed full Japanese translations of
bug messages, and text used in the Swing GUI.</para>

<para>David Cotton contributed Fresh translations for bug
messages and for the Swing GUI.</para>

<para>Michael Tamm contributed support for the "errorProperty" attribute
in the Ant task.</para>

<para>Thomas Kuehne improved the German translation of the Swing GUI.</para>

<para>Len Trigg improved source file support for the Emacs output mode.</para>

<para>Greg Bentz provided a fix for the hashcode/equals detector.</para>

<para>K. Hashimoto contributed internationalization fixes and several other
    bug fixes.</para>

<para>
    Glenn Boysko contributed support for ignoring specified local
    variables in the dead local store detector.
</para>

<para>
    Jay Dunning contributed a detector to find equality comparisons
    of floating-point values, and overhauled the analysis summary
    report and its representation in the saved XML format.
</para>

<para>
    Olivier Parent contributed updated French translations for bug descriptions and
    Swing GUI.
</para>

<para>
    Chris Nappin contributed the <filename>plain.xsl</filename>
    stylesheet.
</para>

<para>
    Etienne Giraudy contributed the <filename>fancy.xsl</filename> and  <filename>fancy-hist.xsl</filename>
    stylesheets, and made improvements to the <command>-xml:withMessages</command>
    option.
</para>

<para>
    Takashi Okamoto fixed bugs in the project preferences dialog
    in the Eclipse plugin, and contributed to its internationalization and localization.
</para>

<para>Thomas Einwaller fixed bugs in the project preferences dialog in the Eclipse plugin.</para>

<para>Jeff Knox contributed support for the warningsProperty attribute
in the Ant task.</para>

<para>Peter Hendriks extended the Eclipse plugin preferences,
and fixed a bug related to renaming the Eclipse plugin ID.</para>

<para>Mark McKay contributed an Ant task to launch the findbugs frame.</para>

<para>Dieter von Holten (dvholten) contributed
some German improvements to findbugs_de.properties.</para>

<para>If you have contributed to &FindBugs;, but aren't mentioned above,
please send email to <email>findbugs@cs.umd.edu</email> (and also accept
our humble apologies).</para>

</sect1>

<sect1>
<title>使用しているソフトウェア</title>

<para>&FindBugs; は、いくつかのオープンソースソフトウェアパッケージを使用しています。これらがなければ、 &FindBugs; の開発は、より一層困難なものになったことでしょう。</para>

<sect2>
<title>BCEL</title>
<para>&FindBugs; includes software developed by the Apache Software Foundation
(<ulink url="http://www.apache.org/">http://www.apache.org/</ulink>).
Specifically, it uses the <ulink url="http://jakarta.apache.org/bcel/">Byte Code
Engineering Library</ulink>.</para>
</sect2>

<sect2>
<title>ASM</title>
<para>&FindBugs; uses the <ulink url="http://asm.objectweb.org/">ASM</ulink>
bytecode framework, which is distributed under the following license:</para>

<para>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
</para>

<orderedlist numeration="arabic">
   <listitem><para>
   Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
  </para></listitem>
   <listitem><para>
   Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
  </para></listitem>
   <listitem><para>
   Neither the name of the copyright holders nor the names of its
   contributors may be used to endorse or promote products derived from
   this software without specific prior written permission.
  </para></listitem>
</orderedlist>

<para>
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
THE POSSIBILITY OF SUCH DAMAGE.
</para>
</blockquote>
</sect2>

<sect2>
<title>DOM4J</title>
<para>&FindBugs; uses <ulink url="http://dom4j.org">DOM4J</ulink>, which is
distributed under the following license:</para>

<para>
Redistribution and use of this software and associated documentation
("Software"), with or without modification, are permitted provided that
the following conditions are met:
</para>

<orderedlist numeration="arabic">
   <listitem><para>
   Redistributions of source code must retain copyright statements and
   notices. Redistributions must also contain a copy of this document.
  </para></listitem>
   <listitem><para>
   Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
  </para></listitem>
   <listitem><para>
   The name "DOM4J" must not be used to endorse or promote products
   derived from this Software without prior written permission
   of MetaStuff, Ltd. For written permission, please contact
   <email>dom4j-info@metastuff.com</email>.
  </para></listitem>
   <listitem><para>
   Products derived from this Software may not be called "DOM4J" nor may
   "DOM4J" appear in their names without prior written permission of
   MetaStuff, Ltd. DOM4J is a registered trademark of MetaStuff, Ltd.
  </para></listitem>
   <listitem><para>
   Due credit should be given to the DOM4J Project (<ulink url="http://dom4j.org/">http://dom4j.org/</ulink>).
  </para></listitem>
</orderedlist>

<para>
THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS ``AS IS''
AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL METASTUFF, LTD. OR ITS
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</para>
</blockquote>

</sect2>

</sect1>

</chapter>

</book>

Xml文件 | 2807行 | 158.38 KB

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://findbugs.googlecode.com/svn/trunk/findbugs/etc/docbook/docbookx.dtd"
[
<!ENTITY FindBugs "<application>FindBugs</application>">
<!ENTITY Ant "<application>Ant</application>">
<!ENTITY Saxon "<application>Saxon</application>">
<!ENTITY FBHome "<replaceable>$FINDBUGS_HOME</replaceable>">
<!ENTITY FBHomeWin "<replaceable>&#x25;FINDBUGS_HOME&#x25;</replaceable>">
<!ENTITY nbsp "&#160;">
]>
<book lang="ja" id="findbugs-manual">

<bookinfo>
<title>&FindBugs;&trade; マニュアル</title>

<authorgroup>
  <author>
    <firstname>David</firstname>
    <othername>H.</othername>
    <surname>Hovemeyer</surname>
  </author>
    <author>
        <firstname>William</firstname>
        <othername>W.</othername>
        <surname>Pugh</surname>
    </author>
</authorgroup>

<copyright>
  <year>2003</year>
  <year>2004</year>
  <year>2005</year>
  <year>2006</year>
  <year>2008</year>
  <holder>University of Maryland</holder>
</copyright>

<legalnotice>
<para>このマニュアルは、クリエイティブ・コモンズ表示-非営利-継承に基づく使用許諾がなされています。使用許諾書をご覧になる場合は、 <ulink url="http://creativecommons.org/licenses/by-nc-sa/1.0/deed.ja">http://creativecommons.org/licenses/by-nc-sa/1.0/</ulink> にアクセスするか、クリエイティブ・コモンズ(559 Nathan Abbott Way, Stanford, California 94305, USA)に書簡を送付してください。</para>
<para>名称「FindBugs」および FindBugs のロゴは、メリーランド大学の登録商標です。</para>
</legalnotice>

<edition>2.0.3</edition>

<pubdate>17:16:15 EST, 22 November, 2013</pubdate>

</bookinfo>

<!--
   **************************************************************************
   Introduction
   **************************************************************************
-->

<chapter id="introduction">
<title>はじめに</title>

<para>&FindBugs;&trade; は、Java プログラムの中のバグを見つけるプログラムです。このプログラムは、「バグ パターン」の実例を探します。「バグ パターン」とは、エラーとなる可能性の高いコードの事例です。</para>

<para>この文書は、&FindBugs; バージョン 2.0.3 について説明してます。私たちは、 &FindBugs; に対するフィードバックを心待ちにしています。どうぞ、 <ulink url="http://findbugs.sourceforge.net">&FindBugs; Web ページ</ulink> にアクセスしてください。&FindBugs; についての最新情報、連絡先および &FindBugs; メーリングリストなどのサポート情報を入手することができます。</para>

<sect1>
<title>必要条件</title>
<para>&FindBugs; を使用するには、 <ulink url="http://java.sun.com/j2se">Java 2 Standard Edition</ulink>, バージョン 1.5 以降のバージョンと互換性のあるランタイム環境が必要です。&FindBugs; は、プラットフォーム非依存であり、 GNU/Linux 、 Windows 、 MacOS X プラットフォーム上で動作することが知られています。</para>

<para>&FindBugs; を使用するためには、少なくとも 512 MB のメモリが必要です。巨大なプロジェクトを解析するためには、それより多くのメモリが必要とされることがあります。</para>
</sect1>

</chapter>

<!--
   **************************************************************************
   Installing FindBugs
   **************************************************************************
-->

<chapter id="installing">
<title>&FindBugs;&trade; のインストール</title>

<para>この章では、 &FindBugs; のインストール方法を説明します。</para>

<sect1>
<title>配布物の展開</title>

<para>&FindBugs; をインストールする最も簡単な方法は、バイナリ配布物をダウンロードすることです。 バイナリ配布物は、 <ulink url="http://prdownloads.sourceforge.net/findbugs/findbugs-2.0.3.tar.gz?download">gzipped tar 形式</ulink> および <ulink url="http://prdownloads.sourceforge.net/findbugs/findbugs-2.0.3.zip?download">zip 形式</ulink> がそれぞれ入手可能です。バイナリ配布物をダウンロードしてきたら、それを任意のディレクトリーに展開します。</para>

<para>gzipped tar 形式配布物の展開方法例:<screen>
<prompt>$ </prompt><command>gunzip -c findbugs-2.0.3.tar.gz | tar xvf -</command>
</screen>
</para>

<para>zip 形式配布物の展開方法例:<screen>
<prompt>C:\Software&gt;</prompt><command>unzip findbugs-2.0.3.zip</command>
</screen>
</para>

<para>バイナリ配布物の展開すると、通常は <filename class="directory">findbugs-2.0.3</filename> ディレクトリーが作成されます。例えば、ディレクトリー <filename class="directory">C:\Software</filename> でバイナリ配布物を展開すると、ディレクトリー <filename class="directory">C:\Software\findbugs-2.0.3</filename> に &FindBugs; は展開されます。このディレクトリーが &FindBugs; のホームディレクトリーになります。このマニュアルでは、このホームディレクトリーを &FBHome; (Windowsでは &FBHomeWin;) を用いて参照します。</para>
</sect1>

</chapter>

<!--
   **************************************************************************
   Compiling FindBugs from Source
   **************************************************************************
-->

<chapter id="building">
<title>&FindBugs;&trade; のソールからのビルド</title>

<para>この章では、 &FindBugs; をソースコードからビルドする方法を説明します。&FindBugs; を修正することに興味がないのであれば、 <link linkend="running">次の章</link> に進んでください。</para>

<sect1>
<title>前提条件</title>

<para>ソースから &FindBugs; をコンパイルするためには、以下のものが必要です。<itemizedlist>
  <listitem>
    <para><ulink url="http://prdownloads.sourceforge.net/findbugs/findbugs-2.0.3-source.zip?download">&FindBugs; のソース配布物</ulink>
    </para>
  </listitem>
  <listitem>
    <para>
      <ulink url="http://java.sun.com/j2se/">JDK 1.5.0 ベータ またはそれ以降</ulink>
    </para>
  </listitem>
  <listitem>
    <para>
      <ulink url="http://ant.apache.org/">Apache &Ant;</ulink>, バージョン 1.6.3 またはそれ以降</para>
  </listitem>
</itemizedlist>
</para>

<warning>
    <para>Redhat Linux システムの <filename>/usr/bin/ant</filename> に同梱されている &Ant; のバージョンでは、 &FindBugs; のコンパイルは<emphasis>うまくできません</emphasis>。<ulink url="http://ant.apache.org/">&Ant; web サイト</ulink>からバイナリ配布物をダウンロードしてインストールすることを推奨します。&Ant; を実行する場合は、 環境変数 <replaceable>JAVA_HOME</replaceable> が  JDK 1.5 (またはそれ以降)をインストールしたディレクトリーを指していることを確認してください。</para>
</warning>

<para>体裁の整った &FindBugs; のドキュメントを生成したい場合は、以下のソフトウェアも必要となります:<itemizedlist>
  <listitem>
    <para><ulink url="http://docbook.sourceforge.net/projects/xsl/index.html">DocBook XSL スタイルシート</ulink>。&FindBugs; のマニュアルを HTML に変換するのに必要です。</para>
  </listitem>
  <listitem>
    <para><ulink url="http://saxon.sourceforge.net/">&Saxon; XSLT プロセッサー</ulink>。(同様に、 &FindBugs; のマニュアルを HTML に変換するのに必要です。)</para>
  </listitem>
<!--
  <listitem>
    <para>
    </para>
  </listitem>
-->
</itemizedlist>
</para>

</sect1>

<sect1>
<title>ソース配布物の展開</title>
<para>ソース配布物をダウンロードした後に、それを作業用ディレクトリーに展開する必要があります。通常は、次のようなコマンドで展開を行います:<screen>
<prompt>$ </prompt><command>unzip findbugs-2.0.3-source.zip</command>
</screen>

</para>
</sect1>

<sect1>
<title><filename>local.properties</filename> の修正</title>
<para>FindBugs のドキュメントをビルドするためには、 <filename>local.properties</filename> ファイルを修正する必要があります。このファイルは、 &FindBugs; をビルドする際に <ulink url="http://ant.apache.org/">&Ant;</ulink> <filename>build.xml</filename> ファイルが参照します。FindBugs のドキュメントをビルドしない場合は、このファイルは無視してもかまいません。</para>

<para><filename>local.properties</filename> での定義は、 <filename>build.properties</filename> ファイルでの定義に優先します。<filename>build.properties</filename> は次のような内容です:<programlisting>
<![CDATA[
# User Configuration:
# This section must be modified to reflect your system.

local.software.home     =/export/home/daveho/linux

# Set this to the directory containing the DocBook Modular XSL Stylesheets
#  from http://docbook.sourceforge.net/projects/xsl/

xsl.stylesheet.home     =${local.software.home}/docbook/docbook-xsl-1.71.1

# Set this to the directory where Saxon (http://saxon.sourceforge.net/)
# is installed.

saxon.home              =${local.software.home}/java/saxon-6.5.5
]]>
</programlisting>
</para>

<para><varname>xsl.stylesheet.home</varname> プロパティーには、<ulink url="http://docbook.sourceforge.net/projects/xsl/">DocBook Modular XSL スタイルシート</ulink>がインストールしてあるディレクトリーの絶対パスを指定します。&FindBugs; ドキュメントを生成しようと考えている場合にのみ、このプロパティーを指定する必要があります。</para>

<para><varname>saxon.home</varname> プロパティーには、<ulink url="http://saxon.sourceforge.net/">&Saxon; XSLT プロセッサー</ulink>がインストールしてあるディレクトリーの絶対パスを指定します。&FindBugs; ドキュメントを生成しようと考えている場合にのみ、このプロパティーを指定する必要があります。</para>

</sect1>

<sect1>
<title>&Ant; の実行</title>

<para>ソース配布物の展開、 &Ant; のインストール、<filename>build.properties</filename>(<filename>local.properties</filename>) の修正 (これは任意) およびツール (&Saxon; など)の環境構築ができれば、 &FindBugs; をビルドするための準備は完了です。&Ant; の起動する方法は、単にコマンドを実行するだけです。<screen>
<prompt>$ </prompt><command>ant <replaceable>target</replaceable></command>
</screen><replaceable>target</replaceable> には以下のいずれかを指定します: <variablelist> <varlistentry> <term><command>build</command></term>
    <listitem>
       <para>このターゲットは、 &FindBugs; のコードをコンパイルします。これは、デフォルトのターゲットです。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>docs</command></term>
    <listitem>
       <para>このターゲットは、ドキュメントの整形を行います(また、副作用としていくつかのソースのコンパイルも行います。)</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>runjunit</command></term>
    <listitem>
        <para>このターゲットは、コンパイルを行い &FindBugs; が持っている JUnit テストを実行します。ユニットテストが失敗した場合は、エラーメッセージが表示されます。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>bindist</command></term>
    <listitem>
        <para>&FindBugs; のバイナリ配布物を構築します。このターゲットは、 <filename>.zip</filename> および <filename>.tar.gz</filename> のアーカイブをそれぞれ作成します。</para>
    </listitem>
  </varlistentry>
</variablelist>
</para>

<para>&Ant; コマンドの実行後、次のような出力が表示されるはずです。 (この前に &Ant; が実行したタスクに関するメッセージもいくらか出力されます。):<screen>
<computeroutput>
BUILD SUCCESSFUL
Total time: 17 seconds
</computeroutput>
</screen>
</para>

</sect1>

<sect1>
<title>ソースディレクトリーからの &FindBugs;&trade; の実行</title>
<para><command>build</command> ターゲットの実行が終了すると、バイナリ配布物と同様の状態が作業ディレクトリーに構築されるように &FindBugs; の&Ant; ビルドスクリプトは記述されています。したがって、<xref linkend="running"/> の  &FindBugs; の実行に関する情報はソース配布物の場合にも応用できます。</para>
</sect1>

</chapter>


<!--
   **************************************************************************
   Running FindBugs
   **************************************************************************
-->

<chapter id="running">
<title>&FindBugs;&trade; の実行</title>

<para>&FindBugs; には2つのユーザーインタフェースがあります。すなわち、グラフィカルユーザーインタフェース (GUI) および コマンドラインインタフェースです。この章では、それぞれのインタフェースの実行方法について説明します。</para>

    <warning>
        <para>この章は、現在書き直し中です。書き直しはまだ完了していません。</para>
    </warning>

<!--
<sect1>
<title>Executing the &FindBugs;&trade; GUI</title>
</sect1>
-->

<sect1>
    <title>クイック・スタート</title>
    <para>Windows システムで  &FindBugs; を起動する場合は、 <filename>&FBHomeWin;\lib\findbugs.jar</filename> ファイルをダブルクリックしてください。 &FindBugs; GUI が起動します。</para>

    <para>Unix 、 Linux または Mac OS X システムの場合は、<filename>&FBHome;/bin/findbugs</filename> スクリプトを実行するか、以下のコマンドを実行します。<screen>
<command>java -jar &FBHome;/lib/findbugs.jar</command></screen>これで、 &FindBugs; GUI が起動します。</para>

    <para>GUI の使用方法については、 <xref linkend="gui"/> を参照してください。</para>
</sect1>

<sect1>

    <title>&FindBugs; の起動</title>

    <para>このセクションでは、 &FindBugs; の起動方法を説明します。&FindBugs; を起動するには2つの方法があります。すなわち、直接起動する方法、および、ラップしているスクリプトを使用する方法です。</para>


    <sect2 id="directInvocation">
        <title>&FindBugs; の直接起動</title>

        <para>最初に述べる &FindBugs; の起動方法は、 <filename>&FBHome;/lib/findbugs.jar</filename> を直接実行する方法です。JVM (<command>java</command>) 実行プログラムの <command>-jar</command> コマンドラインスイッチを使用します。(&FindBugs;のバージョンが 1.3.5 より前の場合は、ラップしているスクリプトを使用する必要があります。)</para>

        <para>&FindBugs; を直接起動するための、一般的な構文は以下のようになります。<screen>
    <command>java <replaceable>[JVM 引数]</replaceable> -jar &FBHome;/lib/findbugs.jar <replaceable>オプション…</replaceable></command>
</screen>
        </para>

<!--
        <para>
            By default, executing <filename>findbugs.jar</filename> runs the
            &FindBugs; graphical user interface (GUI).  On windows systems,
            you can double-click on <filename>findbugs.jar</filename> to launch
            the GUI.  From a command line, the command
            <screen>
java -jar <replaceable>&FBHome;</replaceable>/lib/findbugs.jar</screen>
            will launch the GUI.
        </para>
-->

        <sect3 id="chooseUI">
            <title> ユーザーインタフェースの選択</title>

        <para>1 番目のコマンドラインオプションは、起動する &FindBugs; ユーザーインタフェースを選択するためのものです。指定可能な値は次の通りです:</para>
        <itemizedlist>
            <listitem>
                <para>
                <command>-gui</command>: グラフィカルユーザーインタフェース (GUI) を起動します。</para>
            </listitem>

            <listitem>
                <para>
                    <command>-textui</command>: コマンドラインインタフェースを起動します。</para>
            </listitem>

            <listitem>
                <para>
                    <command>-version</command>: &FindBugs; のバージョン番号を表示します。</para>
            </listitem>

            <listitem>
                <para>
                    <command>-help</command>: &FindBugs; コマンドラインインタフェースのヘルプ情報を表示します。</para>
            </listitem>

            <listitem>
                <para>
                    <command>-gui1</command>: 最初に作成された &FindBugs; グラフィカルユーザーインタフェース(すでに廃止されサポートされていない)を起動します。</para>
            </listitem>
        </itemizedlist>

        </sect3>

        <sect3 id="jvmArgs">
            <title>Java 仮想マシン (JVM) 引数</title>

            <para>&FindBugs; を起動する際に有用な Java 仮想マシン 引数をいくつか紹介します。</para>

            <variablelist>
                <varlistentry>
                    <term><command>-Xmx<replaceable>NN</replaceable>m</command></term>
                    <listitem>
                        <para>Java ヒープサイズの最大値を <replaceable>NN</replaceable> メガバイトに設定します。&FindBugs; は一般的に大容量のメモリサイズを必要とします。大きなプロジェクトでは、 1500 メガバイトを使用することも珍しくありません。</para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term><command>-D<replaceable>name</replaceable>=<replaceable>value</replaceable></command></term>
                    <listitem>
                        <para>Java システムプロパティーを設定します。例えば、引数 <command>-Duser.language=ja</command> を使用すると GUI 文言が日本語で表示されます。</para>
                    </listitem>
                </varlistentry>

                <!--
                <varlistentry>
                    <term></term>
                    <listitem>
                        <para>
                        </para>
                    </listitem>
                </varlistentry>
                -->
            </variablelist>
        </sect3>

    </sect2>

    <sect2 id="wrapperScript">
        <title>ラップしているスクリプトを使用した &FindBugs; の起動</title>

        <para>&FindBugs; を起動するもうひとつの方法は、ラップしているスクリプトを使用する方法です。</para>

<para>Unix 系のシステムにおいては、次のようなコマンドでラップしているスクリプトを起動します :<screen>
<prompt>$ </prompt><command>&FBHome;/bin/findbugs <replaceable>オプション…</replaceable></command>
</screen>
</para>

<para>Windows システムにおいては、ラップしているスクリプトを起動するコマンドは次のようになります。<screen>
<prompt>C:\My Directory&gt;</prompt><command>&FBHomeWin;\bin\findbugs.bat <replaceable>オプション…</replaceable></command>
</screen>
</para>

<para>Unix 系システム および Windows システムのどちらにおいても、ディレクトリー  <filename><replaceable>$FINDBUGS_HOME</replaceable>/bin</filename> を環境変数 <filename>PATH</filename> に追加するだけで、 <command>findbugs</command> コマンドを使用して FindBugs を起動することができます。</para>

    <sect3 id="wrapperOptions">
        <title>ラップしているスクリプトのコマンドラインオプション</title>
        <para>&FindBugs; のラップしているスクリプトは、次のようなコマンドラインオプションをサポートしています。これらのコマンドラインオプションは &FindBugs; プログラム 自体が操作するのでは<emphasis>なく</emphasis>、どちらかといえば、ラップしているスクリプトの方が処理を行います。</para>
    <variablelist>
  <varlistentry>
    <term><command>-jvmArgs <replaceable>引数</replaceable></command></term>
    <listitem>
       <para>JVM に受け渡される引数を指定します。例えば、次のような JVM プロパティが設定できます:<screen>
<prompt>$ </prompt><command>findbugs -textui -jvmArgs &quot;-Duser.language=ja&quot; <replaceable>myApp.jar</replaceable></command>
</screen>
       </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>-javahome <replaceable>ディレクトリー</replaceable></command></term>
    <listitem>
      <para>&FindBugs; の実行に使用する JRE (Java ランタイム環境) がインストールされているディレクトリーを指定します。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>-maxHeap <replaceable>サイズ</replaceable></command></term>
    <listitem>
      <para>Java ヒープサイズの最大値をメガバイト単位で指定します。デフォルトは、 256 です。巨大なプログラムやライブラリを分析するには、もっと大きなメモリー容量が必要になる可能性があります。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>-debug</command></term>
    <listitem>
      <para>ディテクタ実行およびクラス分析のトレース情報が標準出力に出力されます。分析が予期せず失敗した際の、トラブルシューティングに有用です。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>-property</command> <replaceable>name=value</replaceable></term>
    <listitem>
      <para>このオプションを使用してシステムプロパティーを設定することができます。 &FindBugs; はシステムプロパティーを使用して分析特性の設定を行います。<xref linkend="analysisprops"/> を参照してください。このオプションを複数指定して、複数のシステムプロパティを設定することが可能です。注:  Windows の多くのバージョンでは、 <replaceable>name=value</replaceable> 文字列を引用符で囲む必要があります。</para>
    </listitem>
  </varlistentry>

    </variablelist>

    </sect3>

</sect2>

</sect1>

<sect1 id="commandLineOptions">
<title>コマンドラインオプション</title>

<!--
<para>

There are two ways to invoke &FindBugs;.  The first invokes the the Graphical User Interface (GUI):

<screen>
<prompt>$ </prompt><command>findbugs <replaceable>[standard options]</replaceable> <replaceable>[GUI options]</replaceable></command>
</screen>

The second invokes the Command Line Interface (Text UI):

<screen>
<prompt>$ </prompt><command>findbugs -textui <replaceable>[standard options]</replaceable> <replaceable>[Text UI options]</replaceable></command>
</screen>
</para>
-->

<para>このセクションでは、 &FindBugs; がサポートするコマンドラインオプションについて説明します。ここで示すコマンドラインオプションは、 &FindBugs; 直接起動、または、ラップしているスクリプトによる起動で使用できます。</para>

<sect2>
<title>共通のコマンドラインオプション</title>

<para>ここで示すオプションは、 GUI および コマンドラインインタフェースの両方で使用できます。</para>

<variablelist>

  <varlistentry>
    <term><command>-effort:min</command></term>
    <listitem>
      <para>このオプションを指定すると、精度を上げるために大量のメモリーを消費する分析が無効になります。&FindBugs; の実行時にメモリー不足になったり、分析を完了するまでに異常に長い時間がかかる場合に試してみてください。</para>
    </listitem>
  </varlistentry>


  <varlistentry>
    <term><command>-effort:max</command></term>
    <listitem>
      <para>精度が高く、より多くのバグを検出する分析を有効にします。ただし、多くのメモリー容量を必要とし、また、完了までの時間が多くかかる可能性があります。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
  <term><command>-project</command> <replaceable>project</replaceable></term>
  <listitem>
    <para>分析するプロジェクトを指定します。指定するプロジェクトファイルには、 GUI を使って作成したものを使用してください。ファイルの拡張子は、一般的には <filename>.fb</filename> または <filename>.fbp</filename> です。</para>
  </listitem>
  </varlistentry>

  <!--
  <varlistentry>
      <term><command></command></term>
      <listitem>
          <para>

          </para>
      </listitem>
  </varlistentry>
  -->

</variablelist>

</sect2>

<sect2>
<title>GUI オプション</title>

<para>ここで示すオプションは、グラフィカルユーザーインタフェースでのみ使用できます。<variablelist> <varlistentry> <term><command>-look:</command><replaceable>plastic|gtk|native</replaceable></term>
    <listitem>
       <para>Swing のルック・アンド・フィールを設定します。</para>
    </listitem>
  </varlistentry>

</variablelist>
</para>
</sect2>

<sect2>
<title>テキストユーザーインタフェースオプション</title>

<para>ここで示すオプションは、テキストユーザーインタフェースでのみ使用できます。</para>

<variablelist>
  <varlistentry>
    <term><command>-sortByClass</command></term>
    <listitem>
       <para>報告されるバグ検索結果をクラス名でソートします。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>-include</command> <replaceable>filterFile.xml</replaceable></term>
    <listitem>
       <para><replaceable>filterFile.xml</replaceable> で指定したフィルターに一致したバグ検索結果のみ報告されます。<xref linkend="filter"/> を参照してください。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>-exclude</command> <replaceable>filterFile.xml</replaceable></term>
    <listitem>
       <para><replaceable>filterFile.xml</replaceable> で指定したフィルターに一致したバグ検索結果は報告されません。<xref linkend="filter"/> を参照してください。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>-onlyAnalyze</command> <replaceable>com.foobar.MyClass,com.foobar.mypkg.*</replaceable></term>
    <listitem>
      <para>コンマ区切りで指定したクラスおよびパッケージのみに限定して、バグ検出の分析を行うようにします。フィルターと違って、このオプションを使うと一致しないクラスおよびパッケージに対する分析の実行を回避することができます。大きなプロジェクトにおいて、このオプションを活用すると分析にかかる時間を大きく削減することができる可能性があります。(しかしながら、アプリケーションの全体で実行していないために不正確な結果を出してしまうディテクタがある可能性もあります。) クラスはパッケージも含んだ完全な名前を指定する必要があります。また、パッケージは、 Java の <literal>import</literal> 文でパッケージ下のすべてのクラスをインポートするときと同じ方法で指定します。 (すなわち、パッケージの完全な名前に <literal>.*</literal> を付け加えた形です。)<literal>.*</literal> の代わりに <literal>.-</literal> を指定すると、サブパッケージも含めてすべてが分析されます。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
  <term><command>-low</command></term>
  <listitem>
    <para>すべてのバグが報告されます。</para>
  </listitem>
  </varlistentry>

  <varlistentry>
  <term><command>-medium</command></term>
  <listitem>
    <para>優先度 (中) および優先度 (高) のバグが報告されます。これは、デフォルトの設定値です。</para>
  </listitem>
  </varlistentry>

  <varlistentry>
  <term><command>-high</command></term>
  <listitem>
    <para>優先度 (高) のバグのみが報告されます。</para>
  </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>-relaxed</command></term>
    <listitem>
        <para>手抜き報告モードです。このオプションを指定すると、多くのディテクタにおいて 誤検出を回避するためのヒューリスティック機能が抑止されます。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
  <term><command>-xml</command></term>
  <listitem>
    <para>バグ報告が XML で作成されます。作成された XML データは 、後で GUI で見ることができます。このオプションは <command>-xml:withMessages</command> と指定することもできます。こうすると 出力 XML には 各バグに関して人間に読むことができるメッセージが含まれるようになります。このオプションで作成された XML ファイルは 報告書に変換するのが簡単です。</para>
  </listitem>
  </varlistentry>

  <varlistentry>
  <term><command>-html</command></term>
  <listitem>
    <para>HTML 出力が生成されます。デフォルトでは &FindBugs; は <filename>default.xsl</filename> <ulink url="http://www.w3.org/TR/xslt">XSLT</ulink> スタイルシートを使用して HTML 出力を生成します: このファイルは、 <filename>findbugs.jar</filename> の中、または、 &FindBugs; のソース配布物もしくはバイナリ配布物の中にあります。このオプションには、次のようなバリエーションも存在します。すなわち、 <command>-html:plain.xsl</command> 、 <command>-html:fancy.xsl</command> および <command>-html:fancy-hist.xsl</command> です。<filename>plain.xsl</filename> スタイルシートは Javascript や DOM を利用しません。したがって、古いWeb ブラウザ使用時や印刷時にも比較的うまく表示されるでしょう。<filename>fancy.xsl</filename> スタイルシートは DOM と Javascript を利用してナビゲーションを行います。また、ビジュアル表示に CSS を使用します。<command>fancy-hist.xsl</command> は <command>fancy.xsl</command> スタイルシートを更に進化させたものです。DOM や Javascript をふんだんに駆使して、バグの一覧を動的にフィルタリングします。</para>

    <para>ユーザー自身の XSLT スタイルシートを用いて HTML への変換を行いたい場合は、 <command>-html:<replaceable>myStylesheet.xsl</replaceable></command> のように指定してください。ここで、 <replaceable>myStylesheet.xsl</replaceable> はユーザーが使用したいスタイルシートのファイル名です。</para>
  </listitem>
  </varlistentry>

  <varlistentry>
  <term><command>-emacs</command></term>
  <listitem>
    <para>バグ報告が Emacs 形式で作成されます。</para>
  </listitem>
  </varlistentry>

  <varlistentry>
  <term><command>-xdocs</command></term>
  <listitem>
    <para>バグ報告が xdoc XML 形式で作成されます。Apache Mavenで使用できます。</para>
  </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>-output</command> <replaceable>ファイル名</replaceable></term>
    <listitem>
       <para>指定したファイルに出力結果が作成されます。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>-outputFile</command> <replaceable>ファイル名</replaceable></term>
    <listitem>
       <para>この引数は、使用すべきではありません。代わりに、 <command>-output</command> を使用してください。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
  <term><command>-nested</command><replaceable>[:true|false]</replaceable></term>
  <listitem>
    <para>このオプションは、ファイルやディレクトリーの中で入れ子になった jar および zip ファイルを分析するかどうかを指定します。デフォルトでは、入れ子になった jar および zip ファイルも分析します。入れ子になった jar および zip ファイルの分析するを無効にする場合は、 <command>-nested:false</command> をコマンドライン引数に追加してください。</para>
  </listitem>
  </varlistentry>

  <varlistentry>
  <term><command>-auxclasspath</command> <replaceable>クラスパス</replaceable></term>
  <listitem>
    <para>分析時に使用する補助クラスパスを設定します。分析するプログラムで使用するjarファイルやクラスディレクトリーをすべて指定してください。補助クラスパスに指定したクラスは分析の対象にはなりません。</para>
  </listitem>
  </varlistentry>

<!--
  <varlistentry>
  <term><command></command> <replaceable></replaceable></term>
  <listitem>
    <para>
    </para>
  </listitem>
  </varlistentry>
-->

</variablelist>

</sect2>
</sect1>


</chapter>

<chapter id="gui">
    <title>&FindBugs; GUI の使用方法</title>

    <para>この章では、&FindBugs; グラフィカルユーザーインタフェース (GUI) の使用方法を説明します。</para>

<sect1>
<title>プロジェクトの作成</title>
<para><command>findbugs</command>  コマンドで &FindBugs; を起動してから、メニューで <menuchoice><guimenu>File</guimenu><guimenuitem>New Project</guimenuitem></menuchoice> を選択してください。そうすると、次のようなダイアログが表示されます:<mediaobject>
<imageobject>
<imagedata fileref="project-dialog.png"/>
</imageobject>
</mediaobject>
</para>

<para>「Class archives and directories to analyze」テキストフィールドの横にある 「Add」ボタンを押すと、バグを分析する java クラスを含んでいる Java アーカイブファイル (zip, jar, ear, or war file) を選択して指定できます。複数の アーカイブ/ディレクトリーを追加することが可能です。</para>

<para>また、分析を行う Java アーカイブのソースコードを含んだソースディレクトリーを指定することもできます。そうすると、バグの可能性があるソースコードの場所が、&FindBugs; 上でハイライトして表示されます。ソースディレクトリーは、Java パッケージ階層のルートディレクトリーを指定する必要があります。例えば、ユーザのアプリケーションが <varname>org.foobar.myapp</varname> パッケージの中にある場合は、 <filename class="directory">org</filename> ディレクトリーの親ディレクトリーをソースディレクトリーリストに指定する必要があります。</para>

<para>もうひとつ、任意指定の手順があります。それは、補助用の Jar ファイルおよびディレクトリーを 「Auxiliary classpath locations」のエントリーに追加することです。分析するアーカイブ/ディレクトリーにも標準の実行時クラスパスにも含まれていないクラスを、分析するアーカイブ/ディレクトリーが参照している場合は、この項目を設定した方がいいでしょう。クラス階層に関する情報を使用するバグディテクタが、 &FindBugs; にはいくつかあります。したがって、&FindBugs; が分析を行うクラスの完全なクラス階層を参照できれば、より正確な分析結果を取得することができます。</para>

</sect1>

<sect1>
<title>分析の実行</title>
<para>アーカイブ、ディレクトリーおよびソースディレクトリーの指定ができれば、「Finish」ボタンを押して Jar ファイルに含まれるクラスに対する分析を実行します。巨大なプロジェクトを古いコンピュータ上で実行すると、かなりの時間(数十分)がかかることに注意してください。大容量メモリである最近のコンピュータなら、大きなプログラムであっても数分程度で分析できます。</para>
</sect1>

<sect1>
<title>結果の閲覧</title>

<para>分析が完了すると、次のような画面が表示されます :<mediaobject>
  <imageobject>
    <imagedata fileref="example-details.png"/>
  </imageobject>
</mediaobject>
</para>

<para>左上のペインにはバグ階層ツリーが表示されます。これは、分析でみつかったバグの検索結果が階層的に表示されたものです。</para>

<para>上部のペインでバグ検索結果を選択すると、下部の「Details」ペインにバグの詳細説明が表示されます。更に、ソースがみつかれば、右上のソースコードペインにバグの出現箇所に該当するソースコードが表示されます。上図の例で表示されているバグは、ストリームオブジェクトがクローズされていないというものです。ソースコード・ウィンドウにおいて当該ストリームオブジェクトを生成している行がハイライトされています。</para>

<para>バグの検索結果に対してテキストで注釈を入れることができます。階層ツリー図のすぐ下にあるテキストボックスに注釈を入力してください。記録しておきたい情報を何でも自由に入力することができます。バグ結果ファイルの保存および読み込みを行ったときに、注釈も保存されます。</para>

</sect1>

<sect1>
<title>保存と読み込み</title>

<para>メニュー項目から <menuchoice><guimenu>File</guimenu><guimenuitem>Save as...</guimenuitem></menuchoice> を選択すると、ユーザーの作業結果を保存することができます。「Save as...」ダイアログにあるドロップダウン・リストの中から「FindBugs analysis results (.xml)」を選択ことで、ユーザーが指定した jar ファイルリストやバグ検索結果などの作業結果を保存することができます。また、jar ファイルリストのみを保存する選択肢 (「FindBugs project file (.fbp)」) やバグ検索結果のみを保存する選択肢 (「FindBugs analysis file (.fba)」) もあります。保存したファイルは、メニュー項目から <menuchoice><guimenu>File</guimenu><guimenuitem>Open...</guimenuitem></menuchoice> を選択することで、読み込むことができます。</para>

</sect1>

<!--
<sect1 id="textui">
<title>Using the &FindBugs;&trade; Command Line Interface</title>

<para>
The &FindBugs; Command Line Interface (or Text UI) can be used to
analyze an application for bugs non-interactively.  Each bug instance will be
reported on a single line.  All output is written to the standard output file descriptor.
<xref linkend="filter" /> explains how bug reports may be filtered in order
to get only the output you're interested in.
</para>

<para>
See <xref linkend="commandLineOptions" /> for a description of how to invoke the
Command Line Interface.
</para>
</sect1>
-->

</chapter>

<!--
   **************************************************************************
   Using the FindBugs Ant task
   **************************************************************************
-->

<chapter id="anttask">
<title>&FindBugs;&trade; &Ant; タスクの使用方法</title>

<para>この章では、 &FindBugs; を <ulink url="http://ant.apache.org/">&Ant;</ulink> のビルドスクリプトに組み入れる方法について説明します。 <ulink url="http://ant.apache.org/">&Ant;</ulink> は、ビルドや配備を行うことができる Java でよく使用されるツールです。&FindBugs; &Ant; タスクを使用すると、 ビルドスクリプトを作成して機械的に &FindBugs; による Java コードの分析を実行することができます。</para>

<para>この &Ant; タスクは、 Mike Fagan 氏の多大な貢献によるものです。</para>

<sect1>
<title>&Ant; タスクのインストール</title>

<para>&Ant; タスクのインストールは、 <filename>&FBHome;/lib/findbugs-ant.jar</filename> を &Ant; インストールディレクトリーの<filename>lib</filename> サブディレクトリーにコピーするだけです。<note>
<para>使用する &Ant; タスクと &FindBugs; 本体は、同梱されていた同じバージョンのものを使用することを強く推奨します。別のバージョンの &FindBugs; に含まれていた &Ant; タスク Jar ファイルでの動作は保証しません。</para>
</note>
</para>

</sect1>

<sect1>
<title>build.xml の書き方</title>

<para>&FindBugs; を <filename>build.xml</filename> (&Ant; ビルドスクリプト) に組み入れるためにはまず、タスク定義を記述する必要があります。タスク定義は次のように記述します。:<screen>
  &lt;taskdef name=&quot;findbugs&quot; classname=&quot;edu.umd.cs.findbugs.anttask.FindBugsTask&quot;/&gt;
</screen>タスク定義は、 <literal>findbugs</literal> 要素を <filename>build.xml</filename> 上に記述したとき、そのタスクの実行に使用されるクラスを指定します。</para>

<para>タスク定義の記述をすれば、<literal>findbugs</literal> タスクを使ってターゲットを定義できます。次に示すのは、 Apache <ulink url="http://jakarta.apache.org/bcel/">BCEL</ulink> ライブラリーを分析する場合を想定した <filename>build.xml</filename> の記述例です。<screen>
  &lt;property name=&quot;findbugs.home&quot; value=&quot;/export/home/daveho/work/findbugs&quot; /&gt;

  &lt;target name=&quot;findbugs&quot; depends=&quot;jar&quot;&gt;
    &lt;findbugs home=&quot;${findbugs.home}&quot;
              output=&quot;xml&quot;
              outputFile=&quot;bcel-fb.xml&quot; &gt;
      &lt;auxClasspath path=&quot;${basedir}/lib/Regex.jar&quot; /&gt;
      &lt;sourcePath path=&quot;${basedir}/src/java&quot; /&gt;
      &lt;class location=&quot;${basedir}/bin/bcel.jar&quot; /&gt;
    &lt;/findbugs&gt;
  &lt;/target&gt;
</screen><literal>findbugs</literal> 要素には、 <literal>home</literal> 属性が必須です。 &FindBugs; のインストールディレクトリーすなわち &FBHome; の値を設定します。<xref linkend="installing"/> を参照してください。</para>

<para>このターゲットは <filename>bcel.jar</filename> に対して &FindBugs; を実行します。この Jar ファイルは、 BCEL ビルドスクリプトによって作成されるものです。(上記のターゲットが「jar」ターゲットに依存している (depends) と設定することにより、 &FindBugs; が実行される前に当該ライブラリーが完全にコンパイルされていることを保証しています。) &FindBugs; の出力は、 XML 形式で <filename>bcel-fb.xml</filename> ファイルに保存されます。補助 Jar ファイル <filename>Regex.jar</filename> を aux classpath に記述しています。なぜなら、当該 Jar ファイルが BCEL メイン･ライブラリーから参照されるからです。source path を指定することで、保存されるバグデータに BCEL ソースコードへの正確な参照が記述されます。</para>
</sect1>

<sect1>
<title>タスクの実行</title>

<para>コマンドラインから &Ant; を起動する例を次に示します。前述の <literal>findbugs</literal> ターゲットを使用しています。<screen>
  <prompt>[daveho@noir]$</prompt> <command>ant findbugs</command>
  Buildfile: build.xml

  init:

  compile:

  examples:

  jar:

  findbugs:
   [findbugs] Running FindBugs...
   [findbugs] Bugs were found
   [findbugs] Output saved to bcel-fb.xml

  BUILD SUCCESSFUL
  Total time: 35 seconds
</screen>この事例においては、XML ファイルでバグ検索結果を保存しているので、 &FindBugs; GUI を使って結果を参照することができます。 <xref linkend="running"/> を参照してください。</para>

</sect1>

<sect1>
<title>パラメーター</title>

<para>このセクションでは、 &FindBugs; タスクを使用する際に、指定することができるパラメーターについて説明します。<variablelist> <varlistentry> <term><literal>class</literal></term>
    <listitem>
       <para>分析の対象となるクラス群を指定するためのネストされる要素です。<literal>class</literal> 要素には <literal>location</literal> 属性の指定が必須です。分析対象となるアーカイブファイル (jar, zip, 他)、ディレクトリーまたはクラスファイルの名前を記述します。1 つの <literal>findbugs</literal> 要素に対して、複数の <literal>class</literal> 子要素を指定することができます。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>auxClasspath</literal></term>
    <listitem>
       <para>任意指定のネストされる要素です。分析対象のライブラリーまたはアプリケーションによって使用されているが分析の対象にはしたくないクラスを含んでいるクラスパス (Jar ファイルまたはディレクトリー) を指定します。  &Ant; の Java タスクにある <literal>classpath</literal> 要素 と同じ方法で指定することができます。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>sourcePath</literal></term>
    <listitem>
       <para>任意指定のネストされる要素です。分析対象 Java コードのコンパイル時に使用したソースファイルを含んでいるソースディレクトリーへのパスを指定します。ソースパスを指定することにより、生成される XML のバグ出力結果に完全なソース情報をもたせることができ、後になって GUI で参照することができます。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>home</literal></term>
    <listitem>
       <para>必須属性です。&FindBugs; がインストールされているディレクトリー名を設定します。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>quietErrors</literal></term>
    <listitem>
       <para>任意指定のブール値属性です。true を設定すると、深刻な分析エラー発生やクラスがみつからないといった情報が &FindBugs; 出力に記録されません。デフォルトは、 false です。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>reportLevel</literal></term>
    <listitem>
       <para>任意指定の属性です。報告されるバグの優先度のしきい値を指定します。「low」に設定すると、すべてのバグが報告されます。「medium」 (デフォルト) に設定すると、優先度 (中)および優先度 (高)のバグが報告されます。「high」に設定すると、優先度 (高) のバグのみが報告されます。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>output</literal></term>
    <listitem>
       <para>任意指定の属性です。出力形式を指定します。「xml」 (デフォルト) に設定すると、出力は XML 形式になります。「xml:withMessages」 に設定すると、出力は人間が読めるメッセージ が追加された XML 形式になります。(XSL スタイルシートを使ってレポートを作成することを計画している場合はこの形式を使用してください。) 「html」に設定すると、出力は HTML 形式(デフォルトのスタイルシートは default.xsl) になります。 「text」に設定すると、出力は特別なテキスト形式になります。「emacs」に設定すると、出力は <ulink url="http://www.gnu.org/software/emacs/">Emacs</ulink> エラーメッセージ形式になります。「xdocs」に設定すると、出力は Apache Maven で使用できる xdoc XML になります。</para>
    </listitem>
  </varlistentry>
 <varlistentry>
    <term><literal>stylesheet</literal></term>
    <listitem>
       <para>任意指定の属性です。output 属性 に html を指定した場合に、 HTML 出力作成に使用されるスタイルシートを指定します。FindBugs 配布物に含まれているスタイルシートは、 default.xsl、 fancy.xsl 、 fancy-hist.xsl 、 plain.xsl および summary.xsl です。デフォルト値は default.xsl です。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>sort</literal></term>
    <listitem>
       <para>任意指定の属性です。<literal>output</literal> 属性に「text」を指定した場合に、バグの報告をクラス順にソートするかどうかを <literal>sort</literal> 属性で指定します。デフォルトは、 true です。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>outputFile</literal></term>
    <listitem>
       <para>任意指定の属性です。指定した場合、&FindBugs; の出力はその名前のファイルへと保存されます。省略時、出力は &Ant; によって直接表示されます。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>debug</literal></term>
    <listitem>
       <para>任意指定のブール値属性です。true に設定すると、 &FindBugs; は 診断情報を出力します。どのクラスを分析しているか、どのパグパターンディテクタが実行されているか、という情報が表示されます。デフォルトは、 false です。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
      <term><literal>effort</literal></term>
      <listitem>
          <para>分析の活動レベルを設定します。<literal>min</literal> 、<literal>default</literal> または <literal>max</literal> のいずれかの値を設定してください。分析レベルの設定に関する詳細情報は、 <xref linkend="commandLineOptions"/> を参照してください。</para>
      </listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>conserveSpace</literal></term>
    <listitem>
       <para>effort=&quot;min&quot; と同義です。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>workHard</literal></term>
    <listitem>
       <para>effort=&quot;max&quot; と同義です。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>visitors</literal></term>
    <listitem>
       <para>任意指定の属性です。どのバグディテクタを実行するかをコンマ区切りのリストで指定します。バグディテクタはパッケージ指定なしのクラス名で指定します。省略時、デフォルトで無効化されているものを除くすべてのディテクタが実行されます。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>omitVisitors</literal></term>
    <listitem>
       <para>任意指定の属性です。<literal>visitors</literal> 属性と似ていますが、こちらは <emphasis>実行されない</emphasis> ディテクタを指定します。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>excludeFilter</literal></term>
    <listitem>
       <para>任意指定の属性です。フィルターファイル名を指定します。報告から除外されるバグを指定します。<xref linkend="filter"/> を参照してください。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>includeFilter</literal></term>
    <listitem>
       <para>任意指定の属性です。フィルターファイル名を指定します。報告されるバグを指定します。<xref linkend="filter"/> を参照してください。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>projectFile</literal></term>
    <listitem>
       <para>任意指定の属性です。プロジェクトファイル名を指定します。プロジェクトファイルは、 &FindBugs; GUI で作成します。分析されるクラス、および、補助クラスパス、ソースディレクトリーが記入されてます。プロジェクトファイルを指定した場合は、 <literal>class</literal> 要素・ <literal>auxClasspath</literal> 属性および <literal>sourcePath</literal> 属性を設定する必要はありません。プロジェクトの作成方法は、 <xref linkend="running"/> を参照してください。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>jvmargs</literal></term>
    <listitem>
       <para>任意指定の属性です。&FindBugs; を実行している Java 仮想マシンに対して受け渡される引数を指定します。巨大なプログラムを分析する場合に、 JVM が使用するメモリ容量を増やす指定をするためにこの引数を利用する必要があるかもしれません。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>systemProperty</literal></term>
    <listitem>
      <para>任意指定のネストされる要素です。指定した場合、Java システムプロパティーを定義します。<literal>name</literal> 属性にはシステムプロパティーの名前を指定します。そして、 <literal>value</literal> 属性にはシステムプロパティの値を指定します。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>timeout</literal></term>
    <listitem>
       <para>任意指定の属性です。&FindBugs; を実行している Java プロセス の実行許容時間をミリ秒単位で指定します。時間を超過するとハングアップしていると判断してプロセスが終了されます。デフォルトは、 600,000 ミリ秒 (10 分) です。巨大なプログラムの場合は、 &FindBugs; が分析を完了するまでに 10 分 以上掛かる可能性があることに注意してください。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>failOnError</literal></term>
    <listitem>
       <para>任意指定のブール値属性です。&FindBugs; の実行中にエラーがあった場合に、ビルドプロセス自体を打ち切って異常終了させるかどうかを指定します。デフォルトは、「false」です。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><literal>errorProperty</literal></term>
    <listitem>
       <para>任意指定の属性です。&FindBugs; の実行中にエラーが発生した場合に、「true」が設定されるプロパティーの名前を指定します。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
      <term><literal>warningsProperty</literal></term>
      <listitem>
          <para>任意指定の属性です。&FindBugs; が分析したプログラムにバグ報告が 1 件でもある場合に、「true」が設定されるプロパティーの名前を指定します。</para>
      </listitem>
  </varlistentry>

</variablelist>


</para>

<!--

-->

</sect1>

</chapter>

<!--
   **************************************************************************
   Using the FindBugs Eclipse plugin
   **************************************************************************
-->

<chapter id="eclipse">
<title>&FindBugs;&trade; Eclipse プラグインの使用方法</title>

<para>FindBugs Eclipse プラグインを使用することによって、 &FindBugs; を <ulink url="http://www.eclipse.org/">Eclipse</ulink> IDE で使用することができるようになります。このFindBugs Eclipse プラグインは、 Peter Friese 氏の多大な貢献によるものです。Phil Crosby 氏 と Andrei Loskutov 氏は、プラグインの重要な改良に貢献しました。</para>

<sect1>
<title>必要条件</title>

<para>&FindBugs; Eclipse Plugin を使用するためには、 Eclipse 3.3 あるいはそれ以降のバージョン、また、 JRE/JDK 1.5 あるいはそれ以降のバージョンが必要です。</para>

</sect1>

<sect1>
<title>インストール</title>

<para>更新サイトが提供されています。更新サイトを利用して、機械的に FindBugs を Eclipse にインストールできます。また自動的に、最新版のアップデートを照会してインストールすることもできます。内容の異なる 3 つの更新サイトが存在します。</para>

  <variablelist><title>FindBugs Eclipse 更新サイト一覧</title>
    <varlistentry><term><ulink url="http://findbugs.cs.umd.edu/eclipse/">http://findbugs.cs.umd.edu/eclipse/</ulink></term>

    <listitem>
      <para>FindBugs の公式リリース物を提供します。</para>
    </listitem>
    </varlistentry>

    <varlistentry><term><ulink url="http://findbugs.cs.umd.edu/eclipse-candidate/">http://findbugs.cs.umd.edu/eclips-candidate/</ulink></term>

      <listitem>
        <para>FindBugsの公式リリース物に加えて、公式リリース候補版を提供します。</para>
      </listitem>
    </varlistentry>

    <varlistentry><term><ulink url="http://findbugs.cs.umd.edu/eclipse-daily/">http://findbugs.cs.umd.edu/eclipse-daily/</ulink></term>

      <listitem>
        <para>FindBugsの日次ビルド物を提供します。コンパイルができること以上のテストは行われていません。</para>
      </listitem>
    </varlistentry>
    </variablelist>

<para>また、次に示すリンクから手動でプラグインをダウンロードすることもできます : <ulink url="http://prdownloads.sourceforge.net/findbugs/edu.umd.cs.findbugs.plugin.eclipse_2.0.3.20131122.zip?download">http://prdownloads.sourceforge.net/findbugs/edu.umd.cs.findbugs.plugin.eclipse_2.0.3.20131122.zip?download</ulink>. 展開して Eclipse の「plugins」サブディレクトリーに入れてください。(そうすると、 &lt;eclipse インストールディレクトリー &gt;/plugins/edu.umd.cs.findbugs.plugin.eclipse_2.0.3.20131122/findbugs.png が &FindBugs; のロゴファイルへのパスになるはずです。)</para>

<para>プラグインの展開ができたら、 Eclipse を起動して <menuchoice> <guimenu>Help</guimenu> <guimenuitem>About Eclipse Platform</guimenuitem> <guimenuitem>Plug-in Details</guimenuitem> </menuchoice> を選択してください。「FindBugs Project」から提供された「FindBugs Plug-in」というプラグインがあることを確認してください。</para>
</sect1>

<sect1>
<title>プラグインの使用方法</title>

<para>実行するには、 Java プロジェクト上で右クリックして「Find Bugs」を選択します。&FindBugs; が実行されて、バグパターンの実例の可能性があると識別されたコード箇所に問題マーカーがつきます。 (ソース画面および Eclipse 問題ビューに表示されます。)</para>

<para>Java プロジェクトのプロパティーダイアログを開いて「Findbugs」プロパティーページを選択することで、 &FindBugs; の動作をカスタマイズすることができます。選択できる項目には次のようなものがあります :</para>

<itemizedlist>
  <listitem>
    <para>「Run FindBugs Automatically」チェックボックスの設定。チェックすると、プロジェクト内の Java クラスが修正されるたびに FindBugs が実行されます。</para>
  </listitem>

  <listitem>
    <para>優先度とバグカテゴリーの選択。これらのオプションは、どの警告を表示するかを選択します。例えば、優先度で 「Medium」 を選択すると、優先度 (中) および優先度 (高) の警告のみが表示されます。同様に、「Style」チェックボックスのチェックマークを外すと、Style カテゴリーに属する警告は表示されません。</para>
  </listitem>

  <listitem>
    <para>ディテクタの選択。表からプロジェクトで有効にしたいディテクタを選択することができます。</para>
  </listitem>
</itemizedlist>

</sect1>

<sect1>
<title>トラブルシューティング</title>

<para>&FindBugs; Eclipse プラグインは、まだ実験段階です。このセクションでは、プラグインに関する一般的な問題と (判明していれば) それらの問題の解決方法を記述します。</para>

<itemizedlist>
  <listitem>
    <para>&FindBugs; 問題マーカーが (ソース画面および問題ビューに) 表示されない場合は、問題ビューのフィルター設定を変更してください。詳細情報は <ulink url="http://findbugs.sourceforge.net/FAQ.html#q7">http://findbugs.sourceforge.net/FAQ.html#q7</ulink> を参照してください。</para>
  </listitem>

</itemizedlist>

</sect1>


</chapter>


<!--
   **************************************************************************
   Filter files
   **************************************************************************
-->

<chapter id="filter">
<title>フィルターファイル</title>

<para>フィルターファイルを使用することで、特定のクラスやメソッドをバグ報告に含めたりバグ報告から除外したりすることができます。この章では、フィルターファイルの使用方法を説明します。<note>
<title>計画されている機能</title>
<para>フィルターは現在、コマンドラインインタフェースでのみサポートされています。最終的には、フィルターのサポートは GUI にも追加される予定です。</para>
</note>
</para>


<sect1>
<title>フィルターファイルの概要</title>

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

<para>フィルターファイルは、 <ulink url="http://www.w3.org/XML/">XML</ulink> 文書です。最上位要素が　<literal>FindBugsFilter</literal> 要素 であり、その子要素として <literal>Match</literal> 要素を複数個定義します。それぞれの <literal>Match</literal> 要素は、生成されたバグ検索結果に適用される述部にあたります。通常、フィルターはバグ検索結果を除外するために使用します。次に、例を示します:<screen>
<prompt>$ </prompt><command>findbugs -textui -exclude <replaceable>myExcludeFilter.xml</replaceable> <replaceable>myApp.jar</replaceable></command>
</screen>また一方で、的をしぼった報告を得るためにバグ報告結果を選択するためにフィルターを使用することも考えられます :<screen>
<prompt>$ </prompt><command>findbugs -textui -include <replaceable>myIncludeFilter.xml</replaceable> <replaceable>myApp.jar</replaceable></command>
</screen>
</para>

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

</sect1>

<sect1>
<title>マッチング条件の種類</title>

<variablelist>
 <varlistentry>
   <term><literal>&lt;Bug&gt;</literal></term>
   <listitem><para>この要素は、バグパターンを指定して照合します。<literal>pattern</literal> 属性には、コンマ区切りでバグパターン類型のリストを指定します。どの警告がどのバグパターン類型にあたるかは、 <command>-xml</command> オプションをつかって出力されたもの (<literal>BugInstance</literal> 要素の <literal>type</literal> 属性) を見るか、または、 <ulink url="../../bugDescriptions.html">バグ解説ドキュメント</ulink>を参照してください。</para><para>もっと粒度の粗い照合を行いたいときは、 <literal>code</literal> 属性を使用してください。バグ略称のコンマ区切りのリストで指定できます。さらに粒度の粗い照合を行いたいときは、 <literal>category</literal> 属性を使用してください。次に示す、バグカテゴリー名のコンマ区切りのリストで指定できます : <literal>CORRECTNESS</literal>, <literal>MT_CORRECTNESS</literal>, <literal>BAD_PRACTICICE</literal>, <literal>PERFORMANCE</literal>, <literal>STYLE</literal>.</para><para>同じ <literal>&lt;Bug&gt;</literal> 要素に上記の属性を複数指定した場合は、バグパターン名、バグ略称、バグカテゴリーのいずれか1つでも該当すれば、バグパターンは合致すると判定されます。</para><para>下位互換性を持たせたい場合は、 <literal>&lt;Bug&gt;</literal> 要素の代わりに <literal>&lt;BugPattern&gt;</literal> 要素および <literal>&lt;BugCode&gt;</literal> 要素を使用してください。これらの要素はそれぞれ、 <literal>name</literal> 属性で値のリストを指定します。これらの要素は、将来サポートされなくなる可能性があります。</para></listitem>
 </varlistentry>

 <varlistentry>
    <term><literal>&lt;Priority&gt;</literal></term>
    <listitem>
        <para>この要素は、特定の優先度をもつ警告を照合します。<literal>value</literal> 属性には、整数値を指定します : 1 は優先度(高)、また、 2  は優先度(中) 、 3 は優先度(低) を示します。</para>
    </listitem>
 </varlistentry>


 <varlistentry>
   <term><literal>&lt;Package&gt;</literal></term>
    <listitem>
        <para>この要素は、 <literal>name</literal> 属性で指定した特定のパッケージ内にあるクラスに関連した警告を照合します。入れ子のパッケージは含まれません (Java import 文に従っています) 。しかしながら、正規表現を使うと複数パッケージにマッチさせることは簡単にできます。</para>
    </listitem>
  </varlistentry>

 <varlistentry>
   <term><literal>&lt;Class&gt;</literal></term>
    <listitem>
        <para>この要素は、特定のクラスに関連した警告を照合します。<literal>name</literal> 属性を使用して、照合するクラス名をクラス名そのものか、または、正規表現で指定します。</para>

        <para>下位互換性を持たせたい場合は、この要素の代わりに <literal>Match</literal> 要素を使用してください。クラス名そのものの指定は <literal>class</literal> 属性を、クラス名を正規表現で指定する場合は <literal>classregex</literal> 属性をそれぞれ使用してください</para>

        <para>もし <literal>Match</literal> 要素に <literal>Class</literal> 要素が無かったり、 <literal>class</literal> / <literal>classregex</literal> 属性が無かったりした場合は、すべてのクラスに適用されます。その場合、想定外に多くのバグ検索結果が一致してしまうことがあり得ます。その場合は、適当なメソッドやフィールドで絞り込んでください。</para>
    </listitem>
 </varlistentry>

 <varlistentry>
   <term><literal>&lt;Method&gt;</literal></term>

   <listitem><para>この要素は、メソッドを指定します。<literal>name</literal> 属性を使用して、照合するメソッド名をメソッド名そのものか、または、正規表現で指定します。<literal>params</literal> 属性には、コンマ区切りでメソッド引数の型のリストを指定します。<literal>returns</literal> 属性にはメソッドの戻り値の型を指定します。<literal>params</literal> および <literal>returns</literal> においては、クラス名は完全修飾名である必要があります。(例えば、単に &quot;String&quot; ではなく &quot;java.lang.String&quot; としてください。) <literal>params</literal> <literal>returns</literal> のどちらか一方を指定した場合は、もう一方の属性の指定も必須です。なぜならば、メソッドシグニチャーを構築のために必要だからです。<literal>name</literal> 属性、<literal>params</literal> 属性 および <literal>returns</literal> 属性または 3 つの 属性すべて、のどれかを条件とすることできることを意味しています。このように、名前とシグニチャーに基づく様々な種類の条件を規定できます。</para></listitem>
 </varlistentry>

 <varlistentry>
   <term><literal>&lt;Field&gt;</literal></term>

   <listitem><para>この要素は、フィールドを指定します。<literal>name</literal> 属性を使用して、照合するフィールド名をフィールド名そのものか、または、正規表現で指定します。また、フィールドのシグニチャーに照らしたフィルタリングをすることができます。 <literal>type</literal> 属性を使用して、フィールドの型を完全修飾名で指定してください。名前とシグニチャーに基づく条件を規定するために、その2つの属性を両方とも指定することができます。</para></listitem>
 </varlistentry>

   <varlistentry>
   <term><literal>&lt;Local&gt;</literal></term>

   <listitem><para>この要素は、ローカル変数を指定します。<literal>name</literal> 属性を使用して、照合するローカル変数名をローカル変数名そのものか、または、正規表現で指定します。ローカル変数とは、メソッド内で定義した変数です。</para></listitem>
 </varlistentry>

 <varlistentry>
   <term><literal>&lt;Or&gt;</literal></term>
    <listitem><para>この要素は、論理和として <literal>Match</literal> 条項を結合します。すなわち、2つの <literal>Method</literal> 要素を <literal>Or</literal> 条項に入れることで、どちらか一方のメソッドでマッチさせることができます。</para></listitem>
 </varlistentry>
</variablelist>

</sect1>

<sect1>
<title>Java 要素名マッチング</title>

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

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

<para>パターンの構文規則に関しては、 <ulink url="http://java.sun.com/j2se/1.5.0/ja/docs/ja/api/java/util/regex/Pattern.html"><literal>java.util.regex.Pattern</literal></ulink> のドキュメントを参照してください。</para>
</sect1>

<sect1>
<title>留意事項</title>

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

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

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

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

</sect1>

<sect1>
<title>例</title>

<para>1. 特定のクラスに対するすべてのバグ報告に一致させます。<programlisting>
<![CDATA[
     <Match>
       <Class name="com.foobar.MyClass" />
     </Match>
]]>
</programlisting>

</para>

<para>2. バグ略称を指定して、特定のクラスに対する特定の検査項目に一致させます。<programlisting>
<![CDATA[
     <Match>
       <Class name="com.foobar.MyClass"/ >
       <Bug code="DE,UrF,SIC" />
     </Match>
]]>
</programlisting>
</para>

<para>3. バグ略称を指定して、すべてのクラスに対する特定の検査項目に一致させます。<programlisting>
<![CDATA[
     <Match>
       <Bug code="DE,UrF,SIC" />
     </Match>
]]>
</programlisting>
</para>

<para>4. バグカテゴリーを指定して、すべてのクラスに対する特定の検査項目に一致させます。<programlisting>
<![CDATA[
     <Match>
       <Bug category="PERFORMANCE" />
     </Match>
]]>
</programlisting>
</para>

<para>5. バグ略称を指定して、特定のクラスの指定されたメソッドに対する特定のバグ種別に一致させます。<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. 特定のメソッドに対する特定のバグパターンに一致させます。<programlisting>
<![CDATA[
    <!-- open stream に関する誤検出があるメソッド。-->
    <Match>
      <Class name="com.foobar.MyClass" />
      <Method name="writeDataToFile" />
      <Bug pattern="OS_OPEN_STREAM" />
    </Match>
]]>
</programlisting>
</para>

<para>7. 特定のメソッドに対する特定の優先度を付与された特定のバグパターンに一致させます。<programlisting>
<![CDATA[
    <!-- dead local store (優先度 (中)) に関する誤検出があるメソッド。-->
    <Match>
      <Class name="com.foobar.MyClass" />
      <Method name="someMethod" />
      <Bug pattern="DLS_DEAD_LOCAL_STORE" />
      <Priority value="2" />
    </Match>
]]>
</programlisting>
</para>

<para>8. AspectJ コンパイラーによって引き起こされるマイナーバグに一致させます (AspectJ の開発者でもない限り、それらのバグに関心を持つことはないと考えます)。<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. 基盤コードの特定の部分に対するバグに一致させます<programlisting>
<![CDATA[
    <!-- すべてのパッケージにある 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>
]]>
</programlisting>
</para>

<para>10. 特定のシグニチャーを持つフィールドまたはメソッドのバグに一致させます。<programlisting>
<![CDATA[
    <!-- すべてのクラスの 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>
]]>
</programlisting>

</para>

</sect1>

<sect1>
<title>完全な例</title>

<programlisting>
<![CDATA[
<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>
</FindBugsFilter>
]]>
</programlisting>

</sect1>


</chapter>


<!--
   **************************************************************************
   Analysis properties
   **************************************************************************
-->

<chapter id="analysisprops">
<title>分析プロパティー</title>

<para>&FindBugs; は分析する場合にいくつかの観点を持っています。そして、観点をカスタマイズして実行することができます。システムプロパティーを使って、それらのオプションを設定します。この章では、分析オプションの設定方法を説明します。</para>

<para>分析オプションの主な目的は、 2 つあります。1 番目は、 &FindBugs; に対して分析されるアプリケーションのメソッドの意味を伝えることです。そうすることで &FindBugs; がより正確な結果を出すことができ、誤検出を減らすことができます。2 番目に、分析を行うに当たりその精度を設定できるようにすることです。分析の精度を落とすことで、メモリ使用量と分析時間を減らすことができます。ただし、本当のバグを見逃したり、誤検出の数が増えるという代償があります。</para>

<para>コマンドラインオプション <command>-property</command> を使って、分析オプションを設定することができます。次に、例を示します:<screen>
<prompt>$ </prompt><command>findbugs -textui -property &quot;cfg.noprune=true&quot; <replaceable>myApp.jar</replaceable></command>
</screen>
</para>

<para>設定することができる分析オプションの一覧を <xref linkend="analysisproptable"/> に示します。</para>

<table id="analysisproptable">
<title>設定可能な分析プロパティー</title>
<tgroup cols="3" align="left">
  <thead>
    <row>
      <entry>プロパティー名</entry>
      <entry>設定値</entry>
      <entry>目的</entry>
    </row>
  </thead>
  <tbody>
<!--
    <row>
      <entry>cfg.noprune</entry>
      <entry>true or false</entry>
      <entry>If true, infeasible exception edges are not pruned from
      the control flow graphs of analyzed methods.  This option
      increases the speed of the analysis (by about 20%-30%),
      but causes some detectors to produce more false warnings.</entry>
    </row>
-->
    <row>
      <entry>findbugs.assertionmethods</entry>
      <entry>コンマ区切りの完全修飾メソッド名リスト : 例、 &quot;com.foo.MyClass.checkAssertion&quot;</entry>
      <entry>このプロパティーには、プログラムが正しいことをチェックするために使われるメソッドを指定します。これらのメソッドを指定することで、 チェックメソッドで確認した値に対する null 参照アクセスディテクタの誤検出を回避できます。</entry>
    </row>
    <row>
      <entry>findbugs.de.comment</entry>
      <entry>true または false</entry>
      <entry>true に設定すると、 DroppedException (無視された例外) ディテクタは空の catch ブロック にコメントが無いか探します。そして、コメントがみつかった場合には警告が報告されません。</entry>
    </row>
    <row>
      <entry>findbugs.maskedfields.locals</entry>
      <entry>true または false</entry>
      <entry>true に設定すると、フィールドを隠蔽しているローカル変数に対して優先度(低)の警告が発行されます。デフォルトは、 false です。</entry>
    </row>
    <row>
      <entry>findbugs.nullderef.assumensp</entry>
      <entry>true または false</entry>
      <entry>使用されません。 (意図 : true に設定すると、null 参照アクセスディテクタはメソッドからの戻り値、または、メソッドに受け渡される引数を null であると仮定します。デフォルトは、 false です。このプロパティーを有効にすると、大量の誤検出が生成されるであろうことに注意してください。)</entry>
    </row>
    <row>
      <entry>findbugs.refcomp.reportAll</entry>
      <entry>true または false</entry>
      <entry>true に設定すると、  == および != 演算子を使っている疑わしい参照比較がすべて報告されます。 false に設定すると、同様の警告は 1 メソッドにつき 1 つしか発行されません。デフォルトは、 false です。</entry>
    </row>
    <row>
      <entry>findbugs.sf.comment</entry>
      <entry>true または false</entry>
      <entry>true に設定すると、 SwitchFallthrough ディテクタはソースコードに「fall」または「nobreak」という単語を含んだコメントを記載していない caseラベル に限り警告を報告します。(この機能が正しく動作するためには、正確なソースパスが必要です。) これにより、意図的ではない switch 文の fallthrough を発見し易くなります。</entry>
    </row>
<!-- see others at src/doc/manual/sysprops.html
    <row>
      <entry></entry>
      <entry></entry>
      <entry></entry>
    </row>
-->
  </tbody>
</tgroup>
</table>

</chapter>

<!--
    **************************************************************************
   Annotations
   ***************************************************************************
-->

<chapter id="annotations">
<title>アノテーション</title>

<para>&FindBugs; はいくつかのアノテーションをサポートしています。開発者の意図を明確にすることで、 FindBugs はより的確に警告を発行することができます。アノテーションを使用するためには Java 5 が必要であり、 annotations.jar および jsr305.jar ファイルをコンパイル時のクラスパスに含める必要があります。</para>

<variablelist>
  <varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.CheckForNull</command></term>
    <listitem>
<command>[Target]</command> Field, Method, Parameter
    </listitem>
    <listitem>
      <para>アノテーションをつけた要素は、 null である可能性があります。したがって、当該要素を使用する際は null チェックをするべきです。このアノテーションをメソッドに適用すると、メソッドの戻り値に適用されます。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.CheckReturnValue</command></term>
    <listitem>
      <command>[Target]</command> Method, Constructor
    </listitem>
    <listitem>
      <variablelist>
        <varlistentry>
          <term><command>[Parameter]</command></term>
          <listitem>
            <para>
              <command>priority:</command> 警告の優先度を指定します (HIGH, MEDIUM, LOW, IGNORE) 。デフォルト値 :MEDIUM。</para>
          </listitem>
          <listitem>
            <para>
              <command>explanation:</command>戻り値をチェックしなけばならない理由をテキストで説明します。デフォルト値 :&quot;&quot;。</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </listitem>
    <listitem>
      <para>このアノテーションを使用して、呼出し後に戻り値をチェックすべきメソッドを表すことができます。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.DefaultAnnotation</command></term>
    <listitem>
      <command>[Target]</command> Type, Package
    </listitem>
    <listitem>
      <variablelist>
        <varlistentry>
          <term><command>[Parameter]</command></term>
          <listitem>
            <para>
              <command>value:</command>アノテーションクラスのclassオブジェクト。複数のクラスを指定することができます。</para>
          </listitem>
          <listitem>
            <para>
              <command>priority:</command>省略時の優先度を指定します (HIGH, MEDIUM, LOW, IGNORE) 。デフォルト値 :MEDIUM。</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </listitem>
    <listitem>
      <para>
Indicates that all members of the class or package should be annotated with the default
value of the supplied annotation classes. This would be used for behavior annotations
such as @NonNull, @CheckForNull, or @CheckReturnValue. In particular, you can use
@DefaultAnnotation(NonNull.class) on a class or package, and then use @Nullable only
on those parameters, methods or fields that you want to allow to be null.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.DefaultAnnotationForFields</command></term>
    <listitem>
      <command>[Target]</command> Type, Package
    </listitem>
    <listitem>
      <variablelist>
        <varlistentry>
          <term><command>[Parameter]</command></term>
          <listitem>
            <para>
              <command>value:</command>アノテーションクラスのclassオブジェクト。複数のクラスを指定することができます。</para>
          </listitem>
          <listitem>
            <para>
              <command>priority:</command>省略時の優先度を指定します (HIGH, MEDIUM, LOW, IGNORE) 。デフォルト値 :MEDIUM。</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </listitem>
    <listitem>
      <para>
This is same as the DefaultAnnotation except it only applys to fields.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.DefaultAnnotationForMethods</command></term>
    <listitem>
      <command>[Target]</command> Type, Package
    </listitem>
    <listitem>
      <variablelist>
        <varlistentry>
          <term><command>[Parameter]</command></term>
          <listitem>
            <para>
              <command>value:</command>アノテーションクラスのclassオブジェクト。複数のクラスを指定することができます。</para>
          </listitem>
          <listitem>
            <para>
              <command>priority:</command>省略時の優先度を指定します (HIGH, MEDIUM, LOW, IGNORE) 。デフォルト値 :MEDIUM。</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </listitem>
    <listitem>
      <para>
This is same as the DefaultAnnotation except it only applys to methods.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.DefaultAnnotationForParameters</command></term>
    <listitem>
      <command>[Target]</command> Type, Package
    </listitem>
    <listitem>
      <variablelist>
        <varlistentry>
          <term><command>[Parameter]</command></term>
          <listitem>
            <para>
              <command>value:</command>アノテーションクラスのclassオブジェクト。複数のクラスを指定することができます。</para>
          </listitem>
          <listitem>
            <para>
              <command>priority:</command>省略時の優先度を指定します (HIGH, MEDIUM, LOW, IGNORE) 。デフォルト値 :MEDIUM。</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </listitem>
    <listitem>
      <para>
This is same as the DefaultAnnotation except it only applys to method parameters.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.NonNull</command></term>
    <listitem>
      <command>[Target]</command> Field, Method, Parameter
    </listitem>
    <listitem>
      <para>アノテーションをつけた要素は、 null であってはいけません。アノテーションをつけたフィールドは、構築完了後 null であってはいけません。アノテーションをつけたメソッドは、 null ではない値を戻り値としなければなりません。</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.Nullable</command></term>
    <listitem>
      <command>[Target]</command> Field, Method, Parameter
    </listitem>
    <listitem>
      <para>アノテーションをつけた要素は、 null であってはいけません。In general, this means developers will have to read the documentation to determine when a null value is acceptable and whether it is neccessary to check for a null value. FindBugs will treat the annotated items as though they had no annotation.</para>
      <para>
In pratice this annotation is useful only for overriding an overarching NonNull
annotation.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.OverrideMustInvoke</command></term>
    <listitem>
      <command>[Target]</command> Method
    </listitem>
    <listitem>
      <variablelist>
        <varlistentry>
          <term><command>[Parameter]</command></term>
          <listitem>
            <para>
              <command>value:</command>Specify when the super invocation should be
              performed (FIRST, ANYTIME, LAST). Default value:ANYTIME.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </listitem>
    <listitem>
      <para>
Used to annotate a method that, if overridden, must (or should) be invoke super
in the overriding method. Examples of such methods include finalize() and clone().
The argument to the method indicates when the super invocation should occur:
at any time, at the beginning of the overriding method, or at the end of the overriding method.
(This anotation is not implmemented in FindBugs as of September 8, 2006).
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.PossiblyNull</command></term>
    <listitem>
      <para>
This annotation is deprecated. Use CheckForNull instead.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.SuppressWarnings</command></term>
    <listitem>
      <command>[Target]</command> Type, Field, Method, Parameter, Constructor, Package
    </listitem>
    <listitem>
      <variablelist>
        <varlistentry>
          <term><command>[Parameter]</command></term>
          <listitem>
            <para>
              <command>value:</command>The name of the warning. More than one name can be specified.
            </para>
          </listitem>
          <listitem>
            <para>
              <command>justification:</command>Reason why the warning should be ignored. デフォルト値 :&quot;&quot;。</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </listitem>
    <listitem>
      <para>
The set of warnings that are to be suppressed by the compiler in the annotated element.
Duplicate names are permitted.  The second and successive occurrences of a name are ignored.
The presence of unrecognized warning names is <emphasis>not</emphasis> an error: Compilers
must ignore any warning names they do not recognize. They are, however, free to emit a
warning if an annotation contains an unrecognized warning name. Compiler vendors should
document the warning names they support in conjunction with this annotation type. They
are encouraged to cooperate to ensure that the same names work across multiple compilers.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.UnknownNullness</command></term>
    <listitem>
      <command>[Target]</command> Field, Method, Parameter
    </listitem>
    <listitem>
      <para>
Used to indicate that the nullness of the target is unknown, or my vary in unknown ways in subclasses.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>edu.umd.cs.findbugs.annotations.UnknownNullness</command></term>
    <listitem>
      <command>[Target]</command> Field, Method, Parameter
    </listitem>
    <listitem>
      <para>
Used to indicate that the nullness of the target is unknown, or my vary in unknown ways in subclasses.
      </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>また、 &FindBugs; 次に示すアノテーションもサポートしています。 :<itemizedlist>
  <listitem>net.jcip.annotations.GuardedBy</listitem>
  <listitem>net.jcip.annotations.Immutable</listitem>
  <listitem>net.jcip.annotations.NotThreadSafe</listitem>
  <listitem>net.jcip.annotations.ThreadSafe</listitem>
</itemizedlist>
</para>
<para><ulink url="http://jcip.net/">Java Concurrency in Practice</ulink> の <ulink url="http://jcip.net/annotations/doc/index.html"> API ドキュメント</ulink> を参照してください。</para>
</chapter>

<!--
   **************************************************************************
   Using rejarForAnalysis
   **************************************************************************
-->

<chapter id="rejarForAnalysis">
<title>rejarForAnalysis の使用方法</title>

<para>プロジェクトに多くの jar ファイル があったり、 jar ファイルが多くのディレクトリに点在したりする場合は、 <command>rejarForAnalysis </command> スクリプトを使用すると FindBugs の実行が比較的簡単になります。このスクリプトは、数多い jar ファイルを集めて 1 つの大きな jar ファイルに結合します。そうすると、分析時にFindBugs に jar ファイルを設定することが比較的簡単になります。このスクリプトは、 unix システムの 'find' コマンドと組み合わせるととりわけ有用になります ; 次に例を示します。 <command>find . -name '*.jar' | xargs rejarForAnalysis </command>.</para>

<para>また、 <command>rejarForAnalysis</command> スクリプトは巨大なプロジェクトを複数の jar ファイルに分割することに使用できます。プロジェクトのクラスファイルは、複数の jar ファイルに均等に配分されます。これは、プロジェクト全体に対して FindBugs を実行すると時間とメモリ消費が著しい場合に有用です。プロジェクト全体に対して FindBugs を実行する代わりに、 <command> rejarForAnalysis</command> ですべてのクラスを含む大きな jar ファイルを構築します。続いて、 <command>rejarForAnalysis</command> を再び実行して複数の jar ファイルに分割します。そして、各々の jar ファイルに対して順に FindBugs を実行します。その際、 <command>-auxclasspath</command> に最初に 1 つにまとめた jar ファイルを指定してください。</para>

<para><command>rejarForAnalysis</command> スクリプトに指定することができるオプションを以下に示します :</para>

<variablelist>
  <varlistentry>
    <term><command>-maxAge</command> <replaceable>日数</replaceable></term>
    <listitem>
       <para>最後に更新された日からの経過時間を日単位で指定します (指定した日数より古い jar ファイルは無視されます)。</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-inputFileList</command> <replaceable>ファイル名</replaceable></term>
    <listitem>
       <para>jar ファイル名を記載したテキストファイルを指定します。</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-maxClasses</command> <replaceable>クラス数</replaceable></term>
    <listitem>
       <para>analysis*.jar ファイル 1 ファイルに対するクラスの最大数を指定します。</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><command>-prefix</command> <replaceable>プレフィックス</replaceable></term>
    <listitem>
       <para>分析するクラス名のプレフィックスを指定します  (例、 edu.umd.cs.) 。</para>
    </listitem>
  </varlistentry>
</variablelist>
</chapter>

<!--
   **************************************************************************
   Data mining
   **************************************************************************
-->

<chapter id="datamining">
    <title>&FindBugs;&trade; によるデータ・マイニング</title>

<para>バグデータベースへの高機能の問い合わせ機能、および、調査対象のコードの複数のバージョンにわたる警告の追跡記録機能を、 FindBugs は内蔵しています。これらを使って次のようなことができます。すなわち、いつバグが最初持ち込まれたかを捜し出すこと、最終リリース以後持ち込まれた警告の分析を行うこと、または、無限再起ループの数を時間軸でグラフにすることです。</para>

<para>これらの技術は、 FindBugs が警告の保存に使う XML 書式を使用します。これらの XML ファイルは、通常、特定の 1 分析に対する警告が入れられています。しかしそれらには、一連のソフトウェアのビルドやバージョンに対する分析結果を格納することもできます。</para>

<para>すべての FindBugs XML バグデータベースには、バージョン名とタイム・スタンプ が入れられています。FindBugs は分析が行われるファイルの更新時刻からタイム・スタンプを計算します (例えば、タイム・スタンプはクラスファイルの生成時刻になるようになっています。分析が行われた時刻ではありません) 。各々のバグデータベースには、バージョン名も入れられています。バージョン名とタイム・スタンプは、 <command>setBugDatabaseInfo</command> (<xref linkend="setBugDatabaseInfo"/>) コマンドを使用して手動で設定することもできます。</para>

<para>複数バージョンを格納するバグデータベースにおいては、分析されるコードの各バージョンごとにシーケンス番号が割り当てられます。これらのシーケンス番号は単に 0 から始まる連続する整数値です (例えば、 4 つのコードバージョンを格納するバグデータベースには、バージョン 0~3 が入れられます) 。バグデータベースにはまた、各バージョンの名前とタイム・スタンプがそれぞれ記録されます。<command>filterBugs</command> コマンドを使用すると、シーケンス番号、バージョン名またはタイム・スタンプからバージョンを参照することができます。</para>

<para>1 バージョンを格納するバグデータベースの集合から、 1 個の複数バージョンバグデータベースを作成することができます。また、複数バージョンバグデータベースに対して、それ以後に作成された 1 バージョンのバグデータベースを結合することができます。</para>

<para>これらのコマンドのいくつかは、 ant タスクとして実行することができます。コマンドの実行方法および属性・引数の詳細は、以下を参照してください。以下のすべての例においては、 <literal>findbugs.lib</literal> <literal>refid</literal> が正しく設定されていることを前提としています。設定方法の一例を次に示します :</para>

<programlisting>
<![CDATA[
   <!-- findbugs タスク定義 -->
   <property name="findbugs.home" value="/your/path/to/findbugs" />
   <path id="findbugs.lib">
      <fileset dir="${findbugs.home}/lib">
         <include name="findbugs-ant.jar"/>
      </fileset>
   </path>
]]>
</programlisting>

    <sect1 id="commands">
        <title>コマンド</title>

        <para>FindBugs データ・マイニング ツールはすべてコマンドラインから実行することができます。また、いくつかのより有用なコマンドは、 ant ビルドファイルから実行することができます。</para>

<para>コマンドラインツールについて簡単に説明します :</para>

        <variablelist>
            <varlistentry>
                <term><command><link linkend="unionBugs">unionBugs</link></command></term>
                <listitem>
                    <para>別のクラスに対する別個の分析結果を結合します。</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><command><link linkend="computeBugHistory">computeBugHistory</link></command></term>
                <listitem>
                    <para>複数バージョンから得られた複数のバグ警告を、マージして 1 個の複数バージョンバグデータベースにします。これを使って、既存の複数バージョンバグデータベースに更にバージョンを追加したり、 1 バージョンを格納するバグデータベースの集合から 1 個の複数バージョンバグデータベースを作成したり、できます。</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><command><link linkend="setBugDatabaseInfo">setBugDatabaseInfo</link></command></term>
                <listitem>
                    <para>リビジョン名やタイム・スタンプなどの情報を XML データベースに設定します。</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><command><link linkend="listBugDatabaseInfo">listBugDatabaseInfo</link></command></term>
                <listitem>
                    <para>XML データベースにあるリビジョン名やタイム・スタンプなどの情報を一覧表示します。</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><command><link linkend="filterBugs">filterBugs</link></command></term>
                <listitem>
                    <para>バグデータベースの部分集合を選択します。</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><command><link linkend="mineBugHistory">mineBugHistory</link></command></term>
                <listitem>
                    <para>複数バージョンバグデータベースの各バージョン毎の警告数を一覧にした表を作成します。</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><command><link linkend="defectDensity">defectDensity</link></command></term>
                <listitem>
                    <para>プロジェクト全体およびクラス毎・パッケージ毎の不良密度 (1000 NCSS 毎の警告数) に関する情報を一覧表示します。</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><command><link linkend="convertXmlToText">convertXmlToText</link></command></term>
                <listitem>
                    <para>XML 形式のバグ警告を、 1 行 1 バグのテキスト形式、または、HTML形式に変換します。</para>
                </listitem>
            </varlistentry>
        </variablelist>


        <sect2 id="unionBugs">
            <title>unionBugs</title>

        <para>分析するのにアプリケーションの jar ファイルを分割している場合、このコマンドを使用することで、別個に生成された XML バグ警告ファイルをすべての警告を含んでいる 1 つの ファイルにすることができます。</para>

            <para>同じファイルの異なるバージョンを分析した結果を結合する場合は、このコマンドを<emphasis>使用しないでください</emphasis>。代わりに <command>computeBugHistory</command> を使用してください。</para>

            <para>XML ファイルは、コマンドラインで指定してください。結果は、標準出力に送られます。</para>
        </sect2>

        <sect2 id="computeBugHistory">
            <title>computeBugHistory</title>

<para>このコマンドを使用することで、分析するソフトウェアの異なるビルドまたはバージョンの情報を含むバグデータベースを生成することができます入力として提供したファイルの 1 番目のファイルから履歴が取得されます。後に続くファイルは 1 バージョンのバグデータベースであるようにしてください (もし、履歴を持っていたとしても無視されます) 。</para>
<para>デフォルトでは、結果は標準出力に送られます。</para>

<para>この機能は、 ant からも使用することができます。まず次に示すように、ビルドファイルに <command>computeBugHistory</command> を taskdef で定義します :</para>

<programlisting>
<![CDATA[
<taskdef name="computeBugHistory" classname="edu.umd.cs.findbugs.anttask.ComputeBugHistoryTask">
    <classpath refid="findbugs.lib" />
</taskdef>
]]>
</programlisting>

<para>この ant タスクに指定できる属性を、下表に一覧で示します。入力ファイルを指定するには、 <literal>&lt;datafile&gt;</literal> 要素を入れ子にして入れてください。次に、例を示します:</para>

<programlisting>
<![CDATA[
<computeBugHistory home="${findbugs.home}" ...>
    <datafile name="analyze1.xml"/>
    <datafile name="analyze2.xml"/>
</computeBugHistory>
]]>
</programlisting>

        <table id="computeBugHistoryTable">
            <title>computeBugHistory コマンドのオプション一覧</title>
            <tgroup cols="3" align="left">
                  <thead>
                    <row>
                          <entry>コマンドラインオプション</entry>
                          <entry>Ant 属性</entry>
                          <entry>目的</entry>
                    </row>
                      </thead>
                  <tbody>
<row><entry>-output &lt;file&gt;</entry>           <entry>output=&quot;&lt;file&gt;&quot;</entry>           <entry>出力結果を保存するファイル名を指定します。 (同時に入力ファイルにもなりえます)</entry></row>
<row><entry>-overrideRevisionNames[:truth]</entry> <entry>overrideRevisionNames=&quot;[true|false]&quot;</entry><entry>ファイル名から算出されるそれぞれのバージョン名を指定変更します。</entry></row>
<row><entry>-noPackageMoves[:truth]</entry>        <entry>noPackageMoves=&quot;[true|false]&quot;</entry><entry>パッケージを移動したクラスがある場合、当該クラスの警告は別の存在として扱われます。</entry></row>
<row><entry>-preciseMatch[:truth]</entry>          <entry>preciseMatch=&quot;[true|false]&quot;</entry><entry>バグパターンが正確に一致することを要求します。</entry></row>
<row><entry>-precisePriorityMatch[:truth]</entry>  <entry>precisePriorityMatch=&quot;[true|false]&quot;</entry><entry>優先度が正確に一致した場合のみ警告が同一であると判断されます。</entry></row>
<row><entry>-quiet[:truth]</entry>                 <entry>quiet=&quot;[true|false]&quot;</entry><entry>エラーが発生しない限り、標準出力には何も表示されません。</entry></row>
<row><entry>-withMessages[:truth]</entry>          <entry>withMessages=&quot;[true|false]&quot;</entry><entry>出力 XML に人間が読むことができるバグメッセージが含まれます。</entry></row>
                </tbody>
            </tgroup>
        </table>

        </sect2>
        <sect2 id="filterBugs">
            <title>filterBugs</title>
<para>このコマンドを使用することで、 FindBugs XML 警告ファイルから一部分を選び出して新規 FindBugs 警告ファイルに選択された部分を書き込むことができます。</para>
<para>このコマンドには、オプション群に続いて 0 個から 2 個の findbugs xml バグファイルを指定することができます。</para>
<para>ファイル名をひとつも指定しない場合は、標準入力から読んで標準出力に出力されます。ファイル名を 1 個 指定した場合は、指定したファイルから読んで標準出力に出力されます。ファイル名を 2 個 指定した場合は、 1 番目に指定したファイルから読んで 2 番目に指定したファイルに出力されます。</para>

<para>この機能は、 ant からも使用することができます。まず次に示すように、ビルドファイルに <command>filterBugs</command> を taskdef で定義します :</para>

<programlisting>
<![CDATA[
<taskdef name="filterBugs" classname="edu.umd.cs.findbugs.anttask.FilterBugsTask">
    <classpath refid="findbugs.lib" />
</taskdef>
]]>
</programlisting>

<para>この ant タスクに指定できる属性を、下表に一覧で示します。入力ファイルを指定するには、 <literal>input</literal>  属性を使用するか、 <literal>&lt;datafile&gt;</literal> 要素を入れ子にして入れてください。次に、例を示します:</para>

<programlisting>
<![CDATA[
<filterBugs home="${findbugs.home}" ...>
    <datafile name="analyze.xml"/>
</filterBugs>
]]>
</programlisting>

        <table id="filterOptionsTable">
            <title>filterBugs コマンドのオプション一覧</title>
            <tgroup cols="3" align="left">
                  <thead>
                    <row>
                          <entry>コマンドラインオプション</entry>
                          <entry>Ant 属性</entry>
                          <entry>目的</entry>
                    </row>
                      </thead>
                  <tbody>
<row><entry/>                            <entry>input=&quot;&lt;file&gt;&quot;</entry>             <entry>入力ファイルを指定します。</entry></row>
<row><entry/>                            <entry>output=&quot;&lt;file&gt;&quot;</entry>            <entry>出力ファイルを指定します。</entry></row>
<row><entry>-not</entry>                        <entry>not=&quot;[true|false]&quot;</entry>               <entry>フィルターのスイッチを反転します。</entry></row>
<row><entry>-withSource[:truth]</entry>         <entry>withSource=&quot;[true|false]&quot;</entry>        <entry>ソースが入手可能な警告のみ出力されます。</entry></row>
<row><entry>-exclude &lt;filter file&gt;</entry><entry>exclude=&quot;&lt;filter file&gt;&quot;</entry>    <entry>フィルターに一致するバグが除外されます。</entry></row>
<row><entry>-include &lt;filter file&gt;</entry><entry>include=&quot;&lt;filter file&gt;&quot;</entry>    <entry>フィルターに一致するバグのみを含まれます。</entry></row>
<row><entry>-annotation &lt;text&gt;</entry>    <entry>annotation=&quot;&lt;text&gt;&quot;</entry>        <entry>手で入力した注釈に指定した文言を含む警告のみ出力されます。</entry></row>
<row><entry>-after &lt;when&gt;</entry>         <entry>after=&quot;&lt;when&gt;&quot;</entry>             <entry>指定したバージョンより後に初めて出現した警告のみ出力されます。</entry></row>
<row><entry>-before &lt;when&gt;</entry>        <entry>before=&quot;&lt;when&gt;&quot;</entry>            <entry>指定したバージョンより前に初めて出現した警告のみ出力されます。</entry></row>
<row><entry>-first &lt;when&gt;</entry>         <entry>first=&quot;&lt;when&gt;&quot;</entry>             <entry>指定したバージョンに初めて出現した警告のみ出力されます。</entry></row>
<row><entry>-last &lt;when&gt;</entry>          <entry>last=&quot;&lt;when&gt;&quot;</entry>              <entry>指定したバージョンが出現した最後である警告のみ出力されます。</entry></row>
<row><entry>-fixed &lt;when&gt;</entry>         <entry>fixed=&quot;&lt;when&gt;&quot;</entry>             <entry>指定したバージョンの前回のバージョンが出現した最後である警告のみ出力されます。 (<option>-last</option> に優先します)。</entry></row>
<row><entry>-present &lt;when&gt;</entry>       <entry>present=&quot;&lt;when&gt;&quot;</entry>           <entry>指定したバージョンに存在する警告のみ出力されます。</entry></row>
<row><entry>-absent &lt;when&gt;</entry>        <entry>absent=&quot;&lt;when&gt;&quot;</entry>            <entry>指定したバージョンに存在しない警告のみ出力されます。</entry></row>
<row><entry>-active[:truth]</entry>             <entry>active=&quot;[true|false]&quot;</entry>            <entry>最終通番に存在する警告のみ出力されます。</entry></row>
<row><entry>-introducedByChange[:truth]</entry> <entry>introducedByChange=&quot;[true|false]&quot;</entry><entry>存在するクラスの変更によってもたらされた警告のみ出力されます。</entry></row>
<row><entry>-removedByChange[:truth]</entry>    <entry>removedByChange=&quot;[true|false]&quot;</entry>   <entry>存在するクラスの変更によって除去された警告のみ出力されます。</entry></row>
<row><entry>-newCode[:truth]</entry>            <entry>newCode=&quot;[true|false]&quot;</entry>           <entry>新クラスの追加によってもたらされた警告のみ出力されます。</entry></row>
<row><entry>-removedCode[:truth]</entry>        <entry>removedCode=&quot;[true|false]&quot;</entry>       <entry>クラスの削除によって除去された警告のみ出力されます。</entry></row>
<row><entry>-priority &lt;level&gt;</entry>     <entry>priority=&quot;&lt;level&gt;&quot;</entry>         <entry>指定した優先度以上の優先度をもつ警告のみ出力されます。</entry></row>
<row><entry>-class &lt;pattern&gt;</entry>      <entry>class=&quot;&lt;class&gt;&quot;</entry>            <entry>指定したパターンに一致する主クラスをもつ警告のみ出力されます。</entry></row>
<row><entry>-bugPattern &lt;pattern&gt;</entry> <entry>bugPattern=&quot;&lt;pattern&gt;&quot;</entry>     <entry>指定したパターンに一致するバグ種別をもつ警告のみ出力されます。</entry></row>
<row><entry>-category &lt;category&gt;</entry>  <entry>category=&quot;&lt;category&gt;&quot;</entry>      <entry>指定した文字列で始まるカテゴリーの警告のみ出力されます。</entry></row>
<row><entry>-designation &lt;designation&gt;</entry> <entry>designation=&quot;&lt;designation&gt;&quot;</entry> <entry>指定したバグ分類指定をもつ警告のみ出力されます。 (例、 -designation SHOULD_FIX)</entry></row>
<row><entry>-withMessages[:truth] </entry>      <entry>withMessages=&quot;[true|false]&quot;</entry>      <entry>テキストメッセージを含んだ XML が生成されます。</entry></row>
                </tbody>
            </tgroup>
        </table>

        </sect2>

        <sect2 id="mineBugHistory">
            <title>mineBugHistory</title>
<para>このコマンドを使用することで、複数バージョンバグデータベースの各バージョン毎の警告数を一覧にした表を作成することができます。</para>


<para>この機能は、 ant からも使用することができます。まず次に示すように、ビルドファイルに <command>mineBugHistory</command> を taskdef で定義します :</para>

<programlisting>
<![CDATA[
<taskdef name="mineBugHistory" classname="edu.umd.cs.findbugs.anttask.MineBugHistoryTask">
    <classpath refid="findbugs.lib" />
</taskdef>
]]>
</programlisting>

<para>この ant タスクに指定できる属性を、下表に一覧で示します。入力ファイルを指定するには、 <literal>input</literal>  属性を使用するか、 <literal>&lt;datafile&gt;</literal> 要素を入れ子にして入れてください。次に、例を示します:</para>

<programlisting>
<![CDATA[
<mineBugHistory home="${findbugs.home}" ...>
    <datafile name="analyze.xml"/>
</mineBugHistory>
]]>
</programlisting>

        <table id="mineBugHistoryOptionsTable">
            <title>mineBugHistory コマンドのオプション一覧</title>
            <tgroup cols="3" align="left">
                  <thead>
                    <row>
                          <entry>コマンドラインオプション</entry>
                          <entry>Ant 属性</entry>
                          <entry>目的</entry>
                    </row>
                  </thead>
                  <tbody>
<row><entry/>               <entry>input=&quot;&lt;file&gt;&quot;</entry>             <entry>入力ファイルを指定します。</entry></row>
<row><entry/>               <entry>output=&quot;&lt;file&gt;&quot;</entry>            <entry>出力ファイルを指定します。</entry></row>
<row><entry>-formatDates</entry>   <entry>formatDates=&quot;[true|false]&quot;</entry>       <entry>データがテキスト形式で描画されます。</entry></row>
<row><entry>-noTabs</entry>        <entry>noTabs=&quot;[true|false]&quot;</entry>            <entry>タブの代わりに複数スペースでカラムが区切られます (下記参照)。</entry></row>
<row><entry>-summary</entry>       <entry>summary=&quot;[true|false]&quot;</entry>           <entry>最新 10 件の変更の要約が出力されます。</entry></row>
                </tbody>
            </tgroup>
        </table>

        <para><option>-noTabs</option> 出力を使うことで、固定幅フォントのシェルで読み易くなります。数値カラムは右寄せされるので、スペースがカラム値の前に挿入されます。また、このオプションを使用した場合、 <option>-formatDates</option> を指定したときに要約の日付を描画するのに空白が埋め込まれなくなります。</para>

        <para>出力される表は、 (<option>-noTabs</option> が無ければ) タブ区切りで次に示すカラムから成ります :</para>

        <table id="mineBugHistoryColumns">
            <title>mineBugHistory 出力のカラム一覧</title>
            <tgroup cols="2" align="left">
                  <thead>
                    <row>
                          <entry>表題</entry>
                          <entry>目的</entry>
                    </row>
                      </thead>
                  <tbody>
                      <row><entry>seq</entry><entry>シーケンス番号 (0 始まりの連続した整数値)</entry></row>
                      <row><entry>version</entry><entry>バージョン名</entry></row>
                      <row><entry>time</entry><entry>リリースされた日時</entry></row>
                      <row><entry>classes</entry><entry>分析されたクラス数</entry></row>
                      <row><entry>NCSS</entry><entry>コメント文を除いた命令数 (Non Commenting Source Statements)</entry></row>
                      <row><entry>added</entry><entry>前回のバージョンに存在したクラスにおける新規警告数</entry></row>
                      <row><entry>newCode</entry><entry>前回のバージョンに存在しなかったクラスにおける新規警告数</entry></row>
                      <row><entry>fixed</entry><entry>現在のバージョンに存在するクラスにおける除去された警告数</entry></row>
                      <row><entry>removed</entry><entry>現在のバージョンに存在しないクラスの前回のバージョンにおける警告数</entry></row>
                      <row><entry>retained</entry><entry>現在のバージョンと前回のバージョンの両方に存在する警告の数</entry></row>
                      <row><entry>dead</entry><entry>以前のバージョンに存在したが現在のバージョンにも直前のバージョンにも存在しない警告の数</entry></row>
                      <row><entry>active</entry><entry>現在のバージョンに存在する警告総数</entry></row>
                </tbody>
                </tgroup>
        </table>
        </sect2>

        <sect2 id="defectDensity">
            <title>defectDensity</title>
<para>このコマンドを使用することで、プロジェクト全体およびクラス毎・パッケージ毎の不良密度 (1000 NCSS 毎の警告数) に関する情報を一覧表示できます。標準入力から読み込む場合はファイル指定なしで、そうでなければ、コマンドラインでファイルを指定して、このコマンドを実行します。</para>
<para>出力される表は、次に示すカラムから成ります。また、プロジェクト全体情報の行、および、4 個以上の警告を含んでいる各パッケージ情報または各クラス情報の行も出力されます。</para>
        <table id="defectDensityColumns">
            <title>defectDensity 出力のカラム一覧</title>
            <tgroup cols="2" align="left">
                  <thead>
                    <row>
                          <entry>表題</entry>
                          <entry>目的</entry>
                    </row>
                      </thead>
                  <tbody>
                      <row><entry>kind</entry><entry>プロジェクト (project)、パッケージ (package) またはクラス (class)</entry></row>
                      <row><entry>name</entry><entry>プロジェクト、パッケージまたはクラスの名前</entry></row>
                      <row><entry>density</entry><entry> 1000 NCSS 毎の警告数</entry></row>
                      <row><entry>bugs</entry><entry>警告数</entry></row>
                      <row><entry>NCSS</entry><entry>コメント文を除いた命令数 (Non Commenting Source Statements) </entry></row>
                </tbody>
                </tgroup>
            </table>
        </sect2>

        <sect2 id="convertXmlToText">
            <title>convertXmlToText</title>

            <para>このコマンドを使用することで、XML 形式のバグ警告を、 1 行 1 バグのテキスト形式、または、HTML形式に変換することができます。</para>

<para>この機能は、 ant からも使用することができます。まず次に示すように、ビルドファイルに <command>convertXmlToText</command> を taskdef で定義します :</para>

<programlisting>
<![CDATA[
<taskdef name="convertXmlToText" classname="edu.umd.cs.findbugs.anttask.ConvertXmlToTextTask">
    <classpath refid="findbugs.lib" />
</taskdef>
]]>
</programlisting>

<para>この ant タスクに指定できる属性を、下表に一覧で示します。</para>

            <table id="convertXmlToTextTable">
            <title>convertXmlToText コマンドのオプション一覧</title>
            <tgroup cols="3" align="left">
                  <thead>
                    <row>
                          <entry>コマンドラインオプション</entry>
                          <entry>Ant 属性</entry>
                          <entry>目的</entry>
                    </row>
                      </thead>
                  <tbody>
<row><entry/>                   <entry>input=&quot;&lt;filename&gt;&quot;</entry>         <entry>入力ファイルを指定します。</entry></row>
<row><entry/>                   <entry>output=&quot;&lt;filename&gt;&quot;</entry>        <entry>出力ファイルを指定します。</entry></row>
<row><entry>-longBugCodes</entry>      <entry>longBugCodes=&quot;[true|false]&quot;</entry>      <entry>2 文字のバグ略称の代わりに、省略なしのバグパターンコードを使用します。</entry></row>
<row><entry/>                   <entry>format=&quot;text&quot;</entry>                    <entry>プレーンテキストの出力が作成されます。1 行につき 1 つのバグが出力されます。コマンドライン時のデフォルトです。</entry></row>
<row><entry>-html[:stylesheet]</entry> <entry>format=&quot;html:&lt;stylesheet&gt;&quot;</entry> <entry>指定されたスタイルシートを使用して出力が作成されます (下記参照) 。省略した場合は、 default.xsl が使用されます。</entry></row>
                </tbody>
            </tgroup>
            </table>

            <para>-html/format オプションには、plain.xsl 、 default.xsl 、 fancy.xsl 、 fancy-hist.xsl または ユーザ自身が作成した XSL スタイルシートのいずれかを指定することができます。オプション名をよそに、 html 以外の形式を出力するスタイルシートを指定することもできます。FindBugs に含まれているスタイルシート(上述)以外のスタイルシートを使用する場合は、オプション -html/format で当該スタイルシートへのパスまたは URL を指定してください。</para>
        </sect2>

        <sect2 id="setBugDatabaseInfo">
            <title>setBugDatabaseInfo</title>

            <para>このコマンドを使用することで、指定したバグ警告にメタ情報を設定することができます。このコマンドには次に示すオプションがあります:</para>

<para>この機能は、 ant からも使用することができます。まず次に示すように、ビルドファイルに <command>setBugDatabaseInfo</command> を taskdef で定義します :</para>

<programlisting>
<![CDATA[
<taskdef name="setBugDatabaseInfo" classname="edu.umd.cs.findbugs.anttask.SetBugDatabaseInfoTask">
    <classpath refid="findbugs.lib" />
</taskdef>
]]>
</programlisting>

<para>この ant タスクに指定できる属性を、下表に一覧で示します。入力ファイルを指定するには、 <literal>input</literal>  属性を使用するか、 <literal>&lt;datafile&gt;</literal> 要素を入れ子にして入れてください。次に、例を示します:</para>

<programlisting>
<![CDATA[
<setBugDatabaseInfo home="${findbugs.home}" ...>
    <datafile name="analyze.xml"/>
</setBugDatabaseInfo>
]]>
</programlisting>

        <table id="setBugDatabaseInfoOptions">
            <title>setBugDatabaseInfo オプション一覧</title>
            <tgroup cols="3" align="left">
                  <thead>
                    <row>
                          <entry>コマンドラインオプション</entry>
                          <entry>Ant 属性</entry>
                          <entry>目的</entry>
                    </row>
                  </thead>
                  <tbody>
                      <row><entry/>                              <entry>input=&quot;&lt;file&gt;&quot;</entry>           <entry>入力ファイルを指定します。</entry></row>
                      <row><entry/>                              <entry>output=&quot;&lt;file&gt;&quot;</entry>          <entry>出力ファイルを指定します。</entry></row>
                      <row><entry>-name &lt;name&gt;</entry>            <entry>name=&quot;&lt;name&gt;&quot;</entry>            <entry>最新リビジョンの名前を設定します。</entry></row>
                      <row><entry>-timestamp &lt;when&gt;</entry>       <entry>timestamp=&quot;&lt;when&gt;&quot;</entry>       <entry>最新リビジョンのタイム・スタンプを設定します。</entry></row>
                      <row><entry>-source &lt;directory&gt;</entry>     <entry>source=&quot;&lt;directory&gt;&quot;</entry>     <entry>ソースを検索するディレクトリーを追加指定します。</entry></row>
                      <row><entry>-findSource &lt;directory&gt;</entry> <entry>findSource=&quot;&lt;directory&gt;&quot;</entry> <entry>指定したディレクトリー内を検索して関連するソースの場所を追加します。</entry></row>
                      <row><entry>-suppress &lt;filter file&gt;</entry> <entry>suppress=&quot;&lt;filter file&gt;&quot;</entry> <entry>指定したファイルに一致する警告を抑止します (以前に指定した抑止設定は置き換えられます)。</entry></row>
                      <row><entry>-withMessages</entry>                 <entry>withMessages=&quot;[true|false]&quot;</entry>    <entry>XMLにテキストメッセージを追加します。</entry></row>
                      <row><entry>-resetSource</entry>                  <entry>resetSource=&quot;[true|false]&quot;</entry>     <entry>ソース検索パスをすべて削除します。</entry></row>
                 </tbody>
                </tgroup>
            </table>
        </sect2>

        <sect2 id="listBugDatabaseInfo">
            <title>listBugDatabaseInfo</title>

            <para>このコマンドの実行においては、コマンドラインで 0 個以上の xml バグデータベースファイル名を指定します。ファイル名を1つも指定しなければ、標準出力から読み込みを行いテーブルのヘッダーは生成されません。</para>

<para>このコマンドには 1 つだけオプションがあります : <option>-formatDates</option> を指定するとテキスト形式でデータが描画されます。</para>

<para>出力される表は、各バグデータベースごとに行を持ち、次に示すカラムから成ります :</para>
        <table id="listBugDatabaseInfoColumns">
            <title>listBugDatabaseInfo カラム一覧</title>
            <tgroup cols="2" align="left">
                  <thead>
                    <row>
                          <entry>カラム</entry>
                          <entry>目的</entry>
                    </row>
                  </thead>
                  <tbody>
                      <row><entry>version</entry><entry>バージョン名</entry></row>
                      <row><entry>time</entry><entry>リリースされた日時</entry></row>
                      <row><entry>classes</entry><entry>分析されたクラス数</entry></row>
                      <row><entry>NCSS</entry><entry>コメント文を除いた命令数 (Non Commenting Source Statements)</entry></row>
                      <row><entry>total</entry><entry>全警告数</entry></row>
                      <row><entry>high</entry><entry>優先度(高)の警告の総数</entry></row>
                      <row><entry>medium</entry><entry>優先度(中)の警告の総数</entry></row>
                      <row><entry>low</entry><entry>優先度(低)の警告の総数</entry></row>
                      <row><entry>filename</entry><entry>データベースのファイル名</entry></row>
<!--
                      <row><entry></entry><entry></entry></row>
                      <row><entry></entry><entry></entry></row>
                      <row><entry></entry><entry></entry></row>
                      <row><entry></entry><entry></entry></row>
                      <row><entry></entry><entry></entry></row>
                      <row><entry></entry><entry></entry></row>
-->
                 </tbody>
                </tgroup>
            </table>

        </sect2>

    </sect1>

    <sect1 id="examples">
        <title>例</title>
<sect2 id="unixscriptsexamples">
   <title>提供されたシェル・スクリプトを使用しての履歴マイニング</title>
<para>以下はすべて、 jdk1.6.0-b12, jdk1.6.0-b13, ..., jdk1.6.0-b60 のディレクトリに対してコマンドを実行しています。</para>

<para>以下のコマンドを実行してみます :</para>
<screen>
computeBugHistory jdk1.6.0-b* | filterBugs -bugPattern IL_ | mineBugHistory -formatDates
</screen>
<para>すると、次のような出力が行われます :</para>

<screen>
seq	version	time	classes	NCSS	added	newCode	fixed	removed	retained	dead	active
0	jdk1.6.0-b12	&quot;Thu Nov 11 09:07:20 EST 2004&quot;	13128	811569	0	4	0	0	0	0	4
1	jdk1.6.0-b13	&quot;Thu Nov 18 06:02:06 EST 2004&quot;	13128	811570	0	0	0	0	4	0	4
2	jdk1.6.0-b14	&quot;Thu Dec 02 06:12:26 EST 2004&quot;	13145	811786	0	0	2	0	2	0	2
3	jdk1.6.0-b15	&quot;Thu Dec 09 06:07:04 EST 2004&quot;	13174	811693	0	0	1	0	1	2	1
4	jdk1.6.0-b16	&quot;Thu Dec 16 06:21:28 EST 2004&quot;	13175	811715	0	0	0	0	1	3	1
5	jdk1.6.0-b17	&quot;Thu Dec 23 06:27:22 EST 2004&quot;	13176	811974	0	0	0	0	1	3	1
6	jdk1.6.0-b19	&quot;Thu Jan 13 06:41:16 EST 2005&quot;	13176	812011	0	0	0	0	1	3	1
7	jdk1.6.0-b21	&quot;Thu Jan 27 05:57:52 EST 2005&quot;	13177	812173	0	0	0	0	1	3	1
8	jdk1.6.0-b23	&quot;Thu Feb 10 05:44:36 EST 2005&quot;	13179	812188	0	0	0	0	1	3	1
9	jdk1.6.0-b26	&quot;Thu Mar 03 06:04:02 EST 2005&quot;	13199	811770	0	0	0	0	1	3	1
10	jdk1.6.0-b27	&quot;Thu Mar 10 04:48:38 EST 2005&quot;	13189	812440	0	0	0	0	1	3	1
11	jdk1.6.0-b28	&quot;Thu Mar 17 02:54:22 EST 2005&quot;	13185	812056	0	0	0	0	1	3	1
12	jdk1.6.0-b29	&quot;Thu Mar 24 03:09:20 EST 2005&quot;	13117	809468	0	0	0	0	1	3	1
13	jdk1.6.0-b30	&quot;Thu Mar 31 02:53:32 EST 2005&quot;	13118	809501	0	0	0	0	1	3	1
14	jdk1.6.0-b31	&quot;Thu Apr 07 03:00:14 EDT 2005&quot;	13117	809572	0	0	0	0	1	3	1
15	jdk1.6.0-b32	&quot;Thu Apr 14 02:56:56 EDT 2005&quot;	13169	811096	0	0	0	0	1	3	1
16	jdk1.6.0-b33	&quot;Thu Apr 21 02:46:22 EDT 2005&quot;	13187	811942	0	0	0	0	1	3	1
17	jdk1.6.0-b34	&quot;Thu Apr 28 02:49:00 EDT 2005&quot;	13195	813488	0	1	0	0	1	3	2
18	jdk1.6.0-b35	&quot;Thu May 05 02:49:04 EDT 2005&quot;	13457	829837	0	0	0	0	2	3	2
19	jdk1.6.0-b36	&quot;Thu May 12 02:59:46 EDT 2005&quot;	13462	831278	0	0	0	0	2	3	2
20	jdk1.6.0-b37	&quot;Thu May 19 02:55:08 EDT 2005&quot;	13464	831971	0	0	0	0	2	3	2
21	jdk1.6.0-b38	&quot;Thu May 26 03:08:16 EDT 2005&quot;	13564	836565	0	0	0	0	2	3	2
22	jdk1.6.0-b39	&quot;Fri Jun 03 03:10:48 EDT 2005&quot;	13856	849992	0	1	0	0	2	3	3
23	jdk1.6.0-b40	&quot;Thu Jun 09 03:30:28 EDT 2005&quot;	15972	959619	0	2	0	0	3	3	5
24	jdk1.6.0-b41	&quot;Thu Jun 16 03:19:22 EDT 2005&quot;	15972	959619	0	0	0	0	5	3	5
25	jdk1.6.0-b42	&quot;Fri Jun 24 03:38:54 EDT 2005&quot;	15966	958581	0	0	0	0	5	3	5
26	jdk1.6.0-b43	&quot;Thu Jul 14 03:09:34 EDT 2005&quot;	16041	960544	0	0	0	0	5	3	5
27	jdk1.6.0-b44	&quot;Thu Jul 21 03:05:54 EDT 2005&quot;	16041	960547	0	0	0	0	5	3	5
28	jdk1.6.0-b45	&quot;Thu Jul 28 03:26:10 EDT 2005&quot;	16037	960606	0	0	1	0	4	3	4
29	jdk1.6.0-b46	&quot;Thu Aug 04 03:02:48 EDT 2005&quot;	15936	951355	0	0	0	0	4	4	4
30	jdk1.6.0-b47	&quot;Thu Aug 11 03:18:56 EDT 2005&quot;	15964	952387	0	0	1	0	3	4	3
31	jdk1.6.0-b48	&quot;Thu Aug 18 08:10:40 EDT 2005&quot;	15970	953421	0	0	0	0	3	5	3
32	jdk1.6.0-b49	&quot;Thu Aug 25 03:24:38 EDT 2005&quot;	16048	958940	0	0	0	0	3	5	3
33	jdk1.6.0-b50	&quot;Thu Sep 01 01:52:40 EDT 2005&quot;	16287	974937	1	0	0	0	3	5	4
34	jdk1.6.0-b51	&quot;Thu Sep 08 01:55:36 EDT 2005&quot;	16362	979377	0	0	0	0	4	5	4
35	jdk1.6.0-b52	&quot;Thu Sep 15 02:04:08 EDT 2005&quot;	16477	979399	0	0	0	0	4	5	4
36	jdk1.6.0-b53	&quot;Thu Sep 22 02:00:28 EDT 2005&quot;	16019	957900	0	0	1	0	3	5	3
37	jdk1.6.0-b54	&quot;Thu Sep 29 01:54:34 EDT 2005&quot;	16019	957900	0	0	0	0	3	6	3
38	jdk1.6.0-b55	&quot;Thu Oct 06 01:54:14 EDT 2005&quot;	16051	959014	0	0	0	0	3	6	3
39	jdk1.6.0-b56	&quot;Thu Oct 13 01:54:12 EDT 2005&quot;	16211	970835	0	0	0	0	3	6	3
40	jdk1.6.0-b57	&quot;Thu Oct 20 01:55:26 EDT 2005&quot;	16279	971627	0	0	0	0	3	6	3
41	jdk1.6.0-b58	&quot;Thu Oct 27 01:56:30 EDT 2005&quot;	16283	971945	0	0	0	0	3	6	3
42	jdk1.6.0-b59	&quot;Thu Nov 03 01:56:58 EST 2005&quot;	16232	972193	0	0	0	0	3	6	3
43	jdk1.6.0-b60	&quot;Thu Nov 10 01:54:18 EST 2005&quot;	16235	972346	0	0	0	0	3	6	3
</screen>

<para>次に示すコマンドを実行すると、db.xml 中間ファイルを生成することなく直接同じ情報を作成できます。</para>

<screen>
computeBugHistory  jdk1.6.0-b*/jre/lib/rt.xml | filterBugs -bugPattern IL_ db.xml | mineBugHistory -formatDates
</screen>

<para>この情報を使って、 Sun JDK1.6.0 の各ビルドにおいて FindBugs によって発見された無限再起ループの数を表すグラフを表示します。青色の領域は、当該ビルドにおける無限再起ループの数を表しています。その上に描かれている赤色の領域は、以前のバージョンには存在したが当該バージョンでは除去された無限再起ループの数を表しています。 (したがって、赤色の領域と青色の領域を足し合わせた高さは決して減少しないことが保証されています。そして、新たに無限再起ループのバグが持ち込まれた時点で増加します) 。赤色の領域の高さは、当該バージョンにおいて修正または削除されたバグ数の合計で算出されます。バージョン 13 および 14 において見られる減少は、 FindBugs を使用して見つかった JDK のバグの報告を Sun が受け取ったことによるものです。</para>
<mediaobject>
<imageobject>
<imagedata fileref="infiniteRecursiveLoops.png"/>
</imageobject>
</mediaobject>

<para>db.xml ファイルは、 jdk1.6.0 のすべてのビルドに対する検索結果を保持しています。したがって、次に示すコマンドを実行することで、優先度(高)または優先度(低)の正確性に関する警告の履歴が表示されます :</para>

<screen>
filterBugs -priority M -category C db.xml | mineBugHistory -formatDates
</screen>

<para>作成される表の例 :</para>

<screen>
seq	version	time	classes	NCSS	added	newCode	fixed	removed	retained	dead	active
0	jdk1.6.0-b12	&quot;Thu Nov 11 09:07:20 EST 2004&quot;	13128	811569	0	1075	0	0	0	0	1075
1	jdk1.6.0-b13	&quot;Thu Nov 18 06:02:06 EST 2004&quot;	13128	811570	0	0	0	0	1075	0	1075
2	jdk1.6.0-b14	&quot;Thu Dec 02 06:12:26 EST 2004&quot;	13145	811786	3	0	6	0	1069	0	1072
3	jdk1.6.0-b15	&quot;Thu Dec 09 06:07:04 EST 2004&quot;	13174	811693	2	1	3	0	1069	6	1072
4	jdk1.6.0-b16	&quot;Thu Dec 16 06:21:28 EST 2004&quot;	13175	811715	0	0	1	0	1071	9	1071
5	jdk1.6.0-b17	&quot;Thu Dec 23 06:27:22 EST 2004&quot;	13176	811974	0	0	1	0	1070	10	1070
6	jdk1.6.0-b19	&quot;Thu Jan 13 06:41:16 EST 2005&quot;	13176	812011	0	0	0	0	1070	11	1070
7	jdk1.6.0-b21	&quot;Thu Jan 27 05:57:52 EST 2005&quot;	13177	812173	0	0	1	0	1069	11	1069
8	jdk1.6.0-b23	&quot;Thu Feb 10 05:44:36 EST 2005&quot;	13179	812188	0	0	0	0	1069	12	1069
9	jdk1.6.0-b26	&quot;Thu Mar 03 06:04:02 EST 2005&quot;	13199	811770	0	0	2	1	1066	12	1066
10	jdk1.6.0-b27	&quot;Thu Mar 10 04:48:38 EST 2005&quot;	13189	812440	1	0	1	1	1064	15	1065
11	jdk1.6.0-b28	&quot;Thu Mar 17 02:54:22 EST 2005&quot;	13185	812056	0	0	0	0	1065	17	1065
12	jdk1.6.0-b29	&quot;Thu Mar 24 03:09:20 EST 2005&quot;	13117	809468	3	0	8	26	1031	17	1034
13	jdk1.6.0-b30	&quot;Thu Mar 31 02:53:32 EST 2005&quot;	13118	809501	0	0	0	0	1034	51	1034
14	jdk1.6.0-b31	&quot;Thu Apr 07 03:00:14 EDT 2005&quot;	13117	809572	0	0	0	0	1034	51	1034
15	jdk1.6.0-b32	&quot;Thu Apr 14 02:56:56 EDT 2005&quot;	13169	811096	1	1	0	1	1033	51	1035
16	jdk1.6.0-b33	&quot;Thu Apr 21 02:46:22 EDT 2005&quot;	13187	811942	3	0	2	1	1032	52	1035
17	jdk1.6.0-b34	&quot;Thu Apr 28 02:49:00 EDT 2005&quot;	13195	813488	0	1	0	0	1035	55	1036
18	jdk1.6.0-b35	&quot;Thu May 05 02:49:04 EDT 2005&quot;	13457	829837	0	36	2	0	1034	55	1070
19	jdk1.6.0-b36	&quot;Thu May 12 02:59:46 EDT 2005&quot;	13462	831278	0	0	0	0	1070	57	1070
20	jdk1.6.0-b37	&quot;Thu May 19 02:55:08 EDT 2005&quot;	13464	831971	0	1	1	0	1069	57	1070
21	jdk1.6.0-b38	&quot;Thu May 26 03:08:16 EDT 2005&quot;	13564	836565	1	7	2	6	1062	58	1070
22	jdk1.6.0-b39	&quot;Fri Jun 03 03:10:48 EDT 2005&quot;	13856	849992	6	39	5	0	1065	66	1110
23	jdk1.6.0-b40	&quot;Thu Jun 09 03:30:28 EDT 2005&quot;	15972	959619	7	147	11	0	1099	71	1253
24	jdk1.6.0-b41	&quot;Thu Jun 16 03:19:22 EDT 2005&quot;	15972	959619	0	0	0	0	1253	82	1253
25	jdk1.6.0-b42	&quot;Fri Jun 24 03:38:54 EDT 2005&quot;	15966	958581	3	0	1	2	1250	82	1253
26	jdk1.6.0-b43	&quot;Thu Jul 14 03:09:34 EDT 2005&quot;	16041	960544	5	11	15	8	1230	85	1246
27	jdk1.6.0-b44	&quot;Thu Jul 21 03:05:54 EDT 2005&quot;	16041	960547	0	0	0	0	1246	108	1246
28	jdk1.6.0-b45	&quot;Thu Jul 28 03:26:10 EDT 2005&quot;	16037	960606	19	0	2	0	1244	108	1263
29	jdk1.6.0-b46	&quot;Thu Aug 04 03:02:48 EDT 2005&quot;	15936	951355	13	1	1	32	1230	110	1244
30	jdk1.6.0-b47	&quot;Thu Aug 11 03:18:56 EDT 2005&quot;	15964	952387	163	8	7	20	1217	143	1388
31	jdk1.6.0-b48	&quot;Thu Aug 18 08:10:40 EDT 2005&quot;	15970	953421	0	0	0	0	1388	170	1388
32	jdk1.6.0-b49	&quot;Thu Aug 25 03:24:38 EDT 2005&quot;	16048	958940	1	11	1	0	1387	170	1399
33	jdk1.6.0-b50	&quot;Thu Sep 01 01:52:40 EDT 2005&quot;	16287	974937	19	27	16	7	1376	171	1422
34	jdk1.6.0-b51	&quot;Thu Sep 08 01:55:36 EDT 2005&quot;	16362	979377	1	15	3	0	1419	194	1435
35	jdk1.6.0-b52	&quot;Thu Sep 15 02:04:08 EDT 2005&quot;	16477	979399	0	0	1	1	1433	197	1433
36	jdk1.6.0-b53	&quot;Thu Sep 22 02:00:28 EDT 2005&quot;	16019	957900	13	12	16	20	1397	199	1422
37	jdk1.6.0-b54	&quot;Thu Sep 29 01:54:34 EDT 2005&quot;	16019	957900	0	0	0	0	1422	235	1422
38	jdk1.6.0-b55	&quot;Thu Oct 06 01:54:14 EDT 2005&quot;	16051	959014	1	4	7	0	1415	235	1420
39	jdk1.6.0-b56	&quot;Thu Oct 13 01:54:12 EDT 2005&quot;	16211	970835	6	8	37	0	1383	242	1397
40	jdk1.6.0-b57	&quot;Thu Oct 20 01:55:26 EDT 2005&quot;	16279	971627	0	0	0	0	1397	279	1397
41	jdk1.6.0-b58	&quot;Thu Oct 27 01:56:30 EDT 2005&quot;	16283	971945	0	1	1	0	1396	279	1397
42	jdk1.6.0-b59	&quot;Thu Nov 03 01:56:58 EST 2005&quot;	16232	972193	6	0	5	0	1392	280	1398
43	jdk1.6.0-b60	&quot;Thu Nov 10 01:54:18 EST 2005&quot;	16235	972346	0	0	0	0	1398	285	1398
44	jdk1.6.0-b61	&quot;Thu Nov 17 01:58:42 EST 2005&quot;	16202	971134	2	0	4	0	1394	285	1396
</screen>
</sect2>

<sect2 id="incrementalhistory">
    <title>増分履歴メンテナンス</title>

<para>仮に、 db.xml がビルド b12 - b60 に対する findbugs 実行結果を保持している場合、次に示すコマンドを実行することで、 db.xml に b61 に対する実行結果を追加することができます :</para>
<screen>
computeBugHistory -output db.xml db.xml jdk1.6.0-b61/jre/lib/rt.xml
</screen>
</sect2>

            </sect1>

         <sect1 id="antexample">
            <title>Ant の例</title>
<para>findbugs の実行とその後のデータ・マイニングツールの活用の両方を実行している ant スクリプトの完全な例を以下に示します :</para>
<screen>
<![CDATA[
<project name="analyze_asm_util" default="findbugs">
   <!-- findbugs タスク定義 -->
   <property name="findbugs.home" value="/Users/ben/Documents/workspace/findbugs/findbugs" />
   <property name="jvmargs" value="-server -Xss1m -Xmx800m -Duser.language=en -Duser.region=EN -Dfindbugs.home=${findbugs.home}" />

    <path id="findbugs.lib">
      <fileset dir="${findbugs.home}/lib">
         <include name="findbugs-ant.jar"/>
      </fileset>
   </path>

   <taskdef name="findbugs" classname="edu.umd.cs.findbugs.anttask.FindBugsTask">
      <classpath refid="findbugs.lib" />
   </taskdef>

   <taskdef name="computeBugHistory" classname="edu.umd.cs.findbugs.anttask.ComputeBugHistoryTask">
      <classpath refid="findbugs.lib" />
   </taskdef>

   <taskdef name="setBugDatabaseInfo" classname="edu.umd.cs.findbugs.anttask.SetBugDatabaseInfoTask">
      <classpath refid="findbugs.lib" />
   </taskdef>

   <taskdef name="mineBugHistory" classname="edu.umd.cs.findbugs.anttask.MineBugHistoryTask">
      <classpath refid="findbugs.lib" />
   </taskdef>

   <!-- findbugs タスク定義 -->
   <target name="findbugs">
      <antcall target="analyze" />
      <antcall target="mine" />
   </target>

   <!-- 分析を行うタスク-->
   <target name="analyze">
      <!-- asm-util に対して findbugs を実行する -->
      <findbugs home="${findbugs.home}"
                output="xml:withMessages"
                timeout="90000000"
                reportLevel="experimental"
                workHard="true"
                effort="max"
                adjustExperimental="true"
                jvmargs="${jvmargs}"
                failOnError="true"
                outputFile="out.xml"
                projectName="Findbugs"
                debug="false">
         <class location="asm-util-3.0.jar" />
      </findbugs>
   </target>

   <target name="mine">

      <!-- 最新の分析結果に情報を設定する -->
      <setBugDatabaseInfo home="${findbugs.home}"
                            withMessages="true"
                            name="asm-util-3.0.jar"
                            input="out.xml"
                            output="out-rel.xml"/>

      <!-- 履歴ファイル (out-hist.xml) が既に存在するかどうかを確認する -->
      <condition property="mining.historyfile.available">
         <available file="out-hist.xml"/>
      </condition>
      <condition property="mining.historyfile.notavailable">
         <not>
            <available file="out-hist.xml"/>
         </not>
      </condition>

      <!-- このターゲットは、履歴ファイルが存在しないとき (初回) だけ実行されます -->
      <antcall target="history-init">
        <param name="data.file" value="out-rel.xml" />
        <param name="hist.file" value="out-hist.xml" />
      </antcall>
      <!-- 上記以外の場合に実行されます -->
      <antcall target="history">
        <param name="data.file"         value="out-rel.xml" />
        <param name="hist.file"         value="out-hist.xml" />
        <param name="hist.summary.file" value="out-hist.txt" />
      </antcall>
   </target>

   <!-- 履歴ファイルを初期化します -->
   <target name="history-init" if="mining.historyfile.notavailable">
      <copy file="${data.file}" tofile="${hist.file}" />
   </target>

   <!-- バグ履歴を算出します -->
   <target name="history" if="mining.historyfile.available">
      <!-- ${data.file} を ${hist.file} にマージします -->
      <computeBugHistory home="${findbugs.home}"
                           withMessages="true"
                           output="${hist.file}">
            <dataFile name="${hist.file}"/>
            <dataFile name="${data.file}"/>
      </computeBugHistory>

      <!-- 履歴を算出して ${hist.summary.file} に出力します -->
      <mineBugHistory home="${findbugs.home}"
                        formatDates="true"
                      noTabs="true"
                        input="${hist.file}"
                        output="${hist.summary.file}"/>
   </target>

</project>
]]>
</screen>
         </sect1>
</chapter>


<!--
   **************************************************************************
   License
   **************************************************************************
-->

<chapter id="license">
<title>ライセンス</title>

<para>名称「FindBugs」および FindBugs のロゴは、メリーランド大学の登録商標です。FindBugs はフリーソフトウェアであり、 <ulink url="http://www.gnu.org/licenses/lgpl.html">Lesser GNU Public License</ulink> の条件で配布されています。使用承諾書を入手したい場合は、 &FindBugs; 配布物に含まれる <filename>LICENSE.txt</filename> ファイルを参照してください。</para>

<para>最新バージョンの FindBugs および そのソースコードは <ulink url="http://findbugs.sourceforge.net">FindBugs web ページ</ulink> で入手できます。</para>

</chapter>


<!--
   **************************************************************************
   Acknowledgments
   **************************************************************************
-->
<chapter id="acknowledgments">
<title>謝辞</title>

<sect1>
<title>貢献者</title>

<para>&FindBugs; was originally written by Bill Pugh (<email>pugh@cs.umd.edu</email>).
David Hovemeyer (<email>daveho@cs.umd.edu</email>) implemented some of the
detectors, added the Swing GUI, and is a co-maintainer.</para>

<para>Mike Fagan (<email>mfagan@tde.com</email>) contributed the &Ant; build script,
the &Ant; task, and several enhancements and bug fixes to the GUI.</para>

<para>Germano Leichsenring contributed Japanese translations of the bug
summaries.</para>

<para>David Li contributed the Emacs bug report format.</para>

<para>Peter D. Stout contributed recursive detection of Class-Path
attributes in analyzed Jar files, German translations of
text used in the Swing GUI, and other fixes.</para>

<para>Peter Friese wrote the &FindBugs; Eclipse plugin.</para>

<para>Rohan Lloyd contributed several Mac OS X enhancements,
bug detector improvements,
and maintains the Fink package for &FindBugs;.</para>

<para>Hiroshi Okugawa translated the &FindBugs; manual and
more of the bug summaries into Japanese.</para>

<para>Phil Crosby enhanced the Eclipse plugin to add a view
to display the bug details.</para>

<para>Dave Brosius fixed a number of bugs, added user preferences
to the Swing GUI, improved several bug detectors, and
contributed the string concatenation detector.</para>

<para>Thomas Klaeger contributed a number of bug fixes and
bug detector improvements.</para>

<para>Andrei Loskutov made a number of improvements to the
Eclipse plugin.</para>

<para>Brian Goetz contributed a major refactoring of the
visitor classes to improve readability and understandability.</para>

<para> Pete Angstadt fixed several problems in the Swing GUI.</para>

<para>Francis Lalonde provided a task resource file for the
FindBugs Ant task.</para>

<para>Garvin LeClaire contributed support for output in
Xdocs format, for use by Maven.</para>

<para>Holger Stenzhorn contributed improved German translations of items
in the Swing GUI.</para>

<para>Juha Knuutila contributed Finnish translations of items
in the Swing GUI.</para>

<para>Tanel Lebedev contributed Estonian translations of items
in the Swing GUI.</para>

<para>Hanai Shisei (ruimo) contributed full Japanese translations of
bug messages, and text used in the Swing GUI.</para>

<para>David Cotton contributed Fresh translations for bug
messages and for the Swing GUI.</para>

<para>Michael Tamm contributed support for the &quot;errorProperty&quot; attribute
in the Ant task.</para>

<para>Thomas Kuehne improved the German translation of the Swing GUI.</para>

<para>Len Trigg improved source file support for the Emacs output mode.</para>

<para>Greg Bentz provided a fix for the hashcode/equals detector.</para>

<para>K. Hashimoto contributed internationalization fixes and several other
    bug fixes.</para>

<para>
    Glenn Boysko contributed support for ignoring specified local
    variables in the dead local store detector.
</para>

<para>
    Jay Dunning contributed a detector to find equality comparisons
    of floating-point values, and overhauled the analysis summary
    report and its representation in the saved XML format.
</para>

<para>
    Olivier Parent contributed updated French translations for bug descriptions and
    Swing GUI.
</para>

<para>
    Chris Nappin contributed the <filename>plain.xsl</filename>
    stylesheet.
</para>

<para>
    Etienne Giraudy contributed the <filename>fancy.xsl</filename> and  <filename>fancy-hist.xsl</filename>
    stylesheets, and made improvements to the <command>-xml:withMessages</command>
    option.
</para>

<para>
    Takashi Okamoto fixed bugs in the project preferences dialog
    in the Eclipse plugin, and contributed to its internationalization and localization.
</para>

<para>Thomas Einwaller fixed bugs in the project preferences dialog in the Eclipse plugin.</para>

<para>Jeff Knox contributed support for the warningsProperty attribute
in the Ant task.</para>

<para>Peter Hendriks extended the Eclipse plugin preferences,
and fixed a bug related to renaming the Eclipse plugin ID.</para>

<para>Mark McKay contributed an Ant task to launch the findbugs frame.</para>

<para>Dieter von Holten (dvholten) contributed
some German improvements to findbugs_de.properties.</para>


<para>If you have contributed to &FindBugs;, but aren't mentioned above,
please send email to <email>findbugs@cs.umd.edu</email> (and also accept
our humble apologies).</para>

</sect1>

<sect1>
<title>使用しているソフトウェア</title>

<para>&FindBugs; は、いくつかのオープンソースソフトウェアパッケージを使用しています。これらがなければ、 &FindBugs; の開発は、より一層困難なものになったことでしょう。</para>

<sect2>
<title>BCEL</title>
<para>&FindBugs; includes software developed by the Apache Software Foundation
(<ulink url="http://www.apache.org/">http://www.apache.org/</ulink>).
Specifically, it uses the <ulink url="http://jakarta.apache.org/bcel/">Byte Code
Engineering Library</ulink>.</para>
</sect2>

<sect2>
<title>ASM</title>
<para>&FindBugs; uses the <ulink url="http://asm.objectweb.org/">ASM</ulink>
bytecode framework, which is distributed under the following license:</para>

<blockquote>
<para>
Copyright (c) 2000-2005 INRIA, France Telecom
All rights reserved.
</para>

<para>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
</para>

<orderedlist numeration="arabic">
   <listitem><para>
   Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
  </para></listitem>
   <listitem><para>
   Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
  </para></listitem>
   <listitem><para>
   Neither the name of the copyright holders nor the names of its
   contributors may be used to endorse or promote products derived from
   this software without specific prior written permission.
  </para></listitem>
</orderedlist>

<para>
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS &quot;AS IS&quot;
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
THE POSSIBILITY OF SUCH DAMAGE.
</para>
</blockquote>
</sect2>

<sect2>
<title>DOM4J</title>
<para>&FindBugs; uses <ulink url="http://dom4j.org">DOM4J</ulink>, which is
distributed under the following license:</para>

<blockquote>
<para>
Copyright 2001 (C) MetaStuff, Ltd. All Rights Reserved.
</para>

<para>
Redistribution and use of this software and associated documentation
(&quot;Software&quot;), with or without modification, are permitted provided that
the following conditions are met:
</para>

<orderedlist numeration="arabic">
   <listitem><para>
   Redistributions of source code must retain copyright statements and
   notices. Redistributions must also contain a copy of this document.
  </para></listitem>
   <listitem><para>
   Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
  </para></listitem>
   <listitem><para>
   The name &quot;DOM4J&quot; must not be used to endorse or promote products
   derived from this Software without prior written permission
   of MetaStuff, Ltd. For written permission, please contact
   <email>dom4j-info@metastuff.com</email>.
  </para></listitem>
   <listitem><para>
   Products derived from this Software may not be called &quot;DOM4J&quot; nor may
   &quot;DOM4J&quot; appear in their names without prior written permission of
   MetaStuff, Ltd. DOM4J is a registered trademark of MetaStuff, Ltd.
  </para></listitem>
   <listitem><para>
   Due credit should be given to the DOM4J Project (<ulink url="http://dom4j.org/">http://dom4j.org/</ulink>).
  </para></listitem>
</orderedlist>

<para>
THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS ``AS IS''
AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL METASTUFF, LTD. OR ITS
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</para>
</blockquote>

</sect2>

</sect1>

</chapter>


</book>

登录后可以享受更多权益