filelock/src/build/lib/findbugs/doc/manual.xml

   1 <?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3                     "file:../etc/docbook/docbookx.dtd" [
   4 <!ENTITY FindBugs "<application>FindBugs</application>">
   5 <!ENTITY Ant "<application>Ant</application>">
   6 <!ENTITY Saxon "<application>Saxon</application>">
   7 <!ENTITY FBHome "<replaceable>$FINDBUGS_HOME</replaceable>">
   8 <!ENTITY nbsp "&#160;">
   9 ]>
  10
  11 <book lang="en" id="findbugs-manual">
  12
  13 <bookinfo>
  14 <title>&FindBugs;&trade; Manual</title>
  15
  16 <authorgroup>
  17   <author>
  18     <firstname>David</firstname>
  19     <othername>H.</othername>
  20     <surname>Hovemeyer</surname>
  21   </author>
  22         <author>
  23                 <firstname>William</firstname>
  24                 <othername>W.</othername>
  25                 <surname>Pugh</surname>
  26         </author>
  27 </authorgroup>
  28
  29 <copyright>
  30   <year>2003</year>
  31   <year>2004</year>
  32   <year>2005</year>
  33   <year>2006</year>
  34   <holder>University of Maryland</holder>
  35 </copyright>
  36
  37 <legalnotice>
  38 <para>
  39 This manual is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike License.
  40 To view a copy of this license, visit
  41 <ulink url="http://creativecommons.org/licenses/by-nc-sa/1.0/">http://creativecommons.org/licenses/by-nc-sa/1.0/</ulink>
  42 or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.
  43 </para>
  44 <para>
  45 The name FindBugs and the FindBugs logo is trademarked by the University of Maryland.
  46 </para>
  47 </legalnotice>
  48
  49 <edition>1.3.0</edition>
  50
  51 <pubdate>09:39:09 EST, 08 November, 2007</pubdate>
  52
  53 </bookinfo>
  54
  55 <!--
  56    **************************************************************************
  57    Introduction
  58    **************************************************************************
  59 -->
  60
  61 <chapter id="introduction">
  62 <title>Introduction</title>
  63
  64 <para> &FindBugs;&trade; is a program to find bugs in Java programs.  It looks for instances
  65 of "bug patterns" --- code instances that are likely to be errors.</para>
  66
  67 <para> This document describes version 1.3.0 of &FindBugs;. This is an
  68 early release of the tool, so you may find problems with it. We
  69 are very interested in getting your feedback on &FindBugs;. Please visit
  70 the <ulink url="http://findbugs.sourceforge.net">&FindBugs; web page</ulink> for
  71 the latest information on &FindBugs;, contact information, and support resources such
  72 as information about the &FindBugs; mailing lists.</para>
  73
  74 <sect1>
  75 <title>Requirements</title>
  76 <para> To use &FindBugs;, you need a runtime environment compatible with
  77 <ulink url="http://java.sun.com/j2se">Java 2 Standard Edition</ulink>, version 1.4.0 or later.
  78 &FindBugs; is platform independent, and is known to run on GNU/Linux, Windows, and
  79 MacOS X platforms.</para>
  80
  81 <para>You should have at least 512 MB of memory to use &FindBugs;.
  82 To analyze very large projects, more memory may be needed.</para>
  83 </sect1>
  84
  85 </chapter>
  86
  87 <!--
  88    **************************************************************************
  89    Installing FindBugs
  90    **************************************************************************
  91 -->
  92
  93 <chapter id="installing">
  94 <title>Installing and Running &FindBugs;&trade;</title>
  95
  96 <para>
  97 This chapter explains how to install and run &FindBugs;.
  98 </para>
  99
 100 <sect1>
 101 <title>Extracting the Distribution</title>
 102
 103 <para>
 104 The easiest way to install &FindBugs; is to download a binary distribution.
 105 Binary distributions are available in
 106 <ulink url="http://prdownloads.sourceforge.net/findbugs/findbugs-1.3.0.tar.gz?download">gzipped tar format</ulink> and
 107 <ulink url="http://prdownloads.sourceforge.net/findbugs/findbugs-1.3.0.zip?download">zip format</ulink>.
 108 Once you have downloaded a binary distribution, extract it into a directory of your choice.
 109 </para>
 110
 111 <para>
 112 Extracting a gzipped tar format distribution:
 113 <screen>
 114 <prompt>$ </prompt><command>gunzip -c findbugs-1.3.0.tar.gz | tar xvf -</command>
 115 </screen>
 116 </para>
 117
 118 <para>
 119 Extracting a zip format distribution:
 120 <screen>
 121 <prompt>C:\Software></prompt><command>unzip findbugs-1.3.0.zip</command>
 122 </screen>
 123 </para>
 124
 125 <para>
 126 Usually, extracting a binary distribution will create a directory ending in
 127 <filename class="directory">findbugs-1.3.0</filename>. For example, if you extracted
 128 the binary distribution from the <filename class="directory">C:\Software</filename>
 129 directory, then the &FindBugs; software will be extracted into the directory
 130 <filename class="directory">C:\Software\findbugs-1.3.0</filename>.
 131 This directory is the &FindBugs; home directory.  We'll refer to it as
 132 &FBHome; throughout this manual.
 133 </para>
 134 </sect1>
 135
 136 <sect1>
 137 <title>Configuration</title>
 138
 139 <para>
 140 Once you have extracted the binary distribution, all you need to do in order
 141 to run &FindBugs; is to invoke the wrapper script.
 142 </para>
 143
 144 <para>
 145 On Unix-like systems, use the following command to invoke the wrapper script:
 146 <screen>
 147 <prompt>$ </prompt><command>&FBHome;/bin/findbugs <replaceable>options...</replaceable></command>
 148 </screen>
 149 </para>
 150
 151 <para>
 152 On Windows systems, the command to invoke the wrapper script is
 153 <screen>
 154 <prompt>C:\My Directory></prompt><command>&FBHome;\bin\findbugs.bat <replaceable>options...</replaceable></command>
 155 </screen>
 156 </para>
 157
 158 <para>
 159 On both Unix-like and Windows systems, you can simply add the <filename><replaceable>$FINDBUGS_HOME</replaceable>/bin</filename>
 160 directory to your <filename>PATH</filename> environment variable and then invoke
 161 FindBugs using the <command>findbugs</command> command.
 162 </para>
 163
 164 </sect1>
 165
 166 <sect1 id="commandLineOptions">
 167 <title>Command Line Options</title>
 168
 169 <para>
 170
 171 There are two ways to invoke &FindBugs;.  The first invokes the the Graphical User Interface (GUI):
 172
 173 <screen>
 174 <prompt>$ </prompt><command>findbugs <replaceable>[standard options]</replaceable> <replaceable>[GUI options]</replaceable></command>
 175 </screen>
 176
 177 The second invokes the Command Line Interface (Text UI):
 178
 179 <screen>
 180 <prompt>$ </prompt><command>findbugs -textui <replaceable>[standard options]</replaceable> <replaceable>[Text UI options]</replaceable></command>
 181 </screen>
 182 </para>
 183
 184 <sect2>
 185 <title>Standard options</title>
 186
 187 <para>
 188 These options may be used with both the GUI and Text UI.
 189
 190 <variablelist>
 191   <varlistentry>
 192     <term><command>-jvmArgs <replaceable>args</replaceable></command></term>
 193     <listitem>
 194        <para>
 195          Specifies arguments to pass to the JVM.  For example, you might want
 196          to set a JVM property:
 197 <screen>
 198 <prompt>$ </prompt><command>findbugs -textui -jvmArgs "-Duser.language=ja" <replaceable>myApp.jar</replaceable></command>
 199 </screen>
 200        </para>
 201     </listitem>
 202   </varlistentry>
 203
 204   <varlistentry>
 205     <term><command>-javahome <replaceable>directory</replaceable></command></term>
 206     <listitem>
 207       <para>
 208         Specifies the directory containing the JRE (Java Runtime Environment) to
 209         use to execute &FindBugs;.
 210       </para>
 211     </listitem>
 212   </varlistentry>
 213
 214   <varlistentry>
 215     <term><command>-maxHeap <replaceable>size</replaceable></command></term>
 216     <listitem>
 217       <para>
 218       Specifies the maximum Java heap size in megabytes. The default is 256.
 219       More memory may be required to analyze very large programs or libraries.
 220       </para>
 221     </listitem>
 222   </varlistentry>
 223
 224   <varlistentry>
 225     <term><command>-debug</command></term>
 226     <listitem>
 227       <para>
 228       Prints a trace of detectors run and classes analyzed to standard output.
 229       Useful for troubleshooting unexpected analysis failures.
 230       </para>
 231     </listitem>
 232   </varlistentry>
 233 <!--
 234   <varlistentry>
 235     <term><command>-conserveSpace</command></term>
 236     <listitem>
 237       <para>
 238       This option disables analyses that increase precision but also
 239       increase memory consumption.  You may want to try this option if
 240       you find that &FindBugs; runs out of memory, or takes an unusually
 241       long time to complete its analysis.
 242       </para>
 243     </listitem>
 244   </varlistentry>
 245 -->
 246   <varlistentry>
 247     <term><command>-effort:min</command></term>
 248     <listitem>
 249       <para>
 250       This option disables analyses that increase precision but also
 251       increase memory consumption.  You may want to try this option if
 252       you find that &FindBugs; runs out of memory, or takes an unusually
 253       long time to complete its analysis.
 254       </para>
 255     </listitem>
 256   </varlistentry>
 257
 258   <varlistentry>
 259     <term><command>-effort:max</command></term>
 260     <listitem>
 261       <para>
 262                 Enable analyses which increase precision and find more bugs, but which
 263                 may require more memory and take more time to complete.
 264       </para>
 265     </listitem>
 266   </varlistentry>
 267
 268   <varlistentry>
 269     <term><command>-property</command> <replaceable>name=value</replaceable></term>
 270     <listitem>
 271       <para>
 272       This option sets a system property.&nbsp; &FindBugs; uses system properties
 273       to configure analysis options.  See <xref linkend="analysisprops"/>.
 274       You can use this option multiple times in order to set multiple properties.
 275       Note: In most versions of Windows, the <replaceable>name=value</replaceable>
 276       string must be in quotes.
 277       </para>
 278     </listitem>
 279   </varlistentry>
 280
 281   <varlistentry>
 282   <term><command>-project</command> <replaceable>project</replaceable></term>
 283   <listitem>
 284     <para>
 285     Specify a project to be analyzed.  The project file you specify should
 286     be one that was created using the GUI interface.  It will typically end
 287     in the extension <filename>.fb</filename>.
 288     </para>
 289   </listitem>
 290   </varlistentry>
 291
 292 </variablelist>
 293 </para>
 294
 295 </sect2>
 296
 297 <sect2>
 298 <title>GUI Options</title>
 299
 300 <para>
 301 These options are only accepted by the Graphical User Interface.
 302
 303 <variablelist>
 304   <varlistentry>
 305     <term><command>-look:</command><replaceable>plastic|gtk|native</replaceable></term>
 306     <listitem>
 307        <para>
 308                 Set Swing look and feel.
 309        </para>
 310     </listitem>
 311   </varlistentry>
 312
 313 </variablelist>
 314 </para>
 315 </sect2>
 316
 317 <sect2>
 318 <title>Text UI Options</title>
 319
 320 <para>
 321 These options are only accepted by the Text User Interface.
 322 </para>
 323
 324 <variablelist>
 325   <varlistentry>
 326     <term><command>-sortByClass</command></term>
 327     <listitem>
 328        <para>
 329        Sort reported bug instances by class name.
 330        </para>
 331     </listitem>
 332   </varlistentry>
 333
 334   <varlistentry>
 335     <term><command >-include</command> <replaceable>filterFile.xml</replaceable></term>
 336     <listitem>
 337        <para>
 338        Only report bug instances that match the filter specified by <replaceable>filterFile.xml</replaceable>.
 339        See <xref linkend="filter" />.
 340        </para>
 341     </listitem>
 342   </varlistentry>
 343
 344   <varlistentry>
 345     <term><command >-exclude</command> <replaceable>filterFile.xml</replaceable></term>
 346     <listitem>
 347        <para>
 348        Report all bug instances except those matching the filter specified by <replaceable>filterFile.xml</replaceable>.
 349        See <xref linkend="filter" />.
 350        </para>
 351     </listitem>
 352   </varlistentry>
 353
 354   <varlistentry>
 355     <term><command>-onlyAnalyze</command> <replaceable>com.foobar.MyClass,com.foobar.mypkg.*</replaceable></term>
 356     <listitem>
 357       <para>
 358       Restrict analysis to find bugs to given comma-separated list of
 359       classes and packages.
 360       Unlike filtering, this option avoids running analysis on
 361       classes and packages that are not explicitly matched:
 362       for large projects, this may greatly reduce the amount of time
 363       needed to run the analysis.  (However, some detectors may produce
 364       inaccurate results if they aren't run on the entire application.)
 365       Classes should be specified using their full classnames (including
 366       package), and packages should be specified in the same way
 367       they would in a Java <literal>import</literal> statement to
 368       import all classes in the package (i.e., add <literal>.*</literal>
 369       to the full name of the package).
 370       Replace <literal>.*</literal> with <literal>.-</literal> to also
 371       analyze all subpackages.
 372       </para>
 373     </listitem>
 374   </varlistentry>
 375
 376   <varlistentry>
 377   <term><command>-low</command></term>
 378   <listitem>
 379     <para>
 380     Report all bugs.
 381     </para>
 382   </listitem>
 383   </varlistentry>
 384
 385   <varlistentry>
 386   <term><command>-medium</command></term>
 387   <listitem>
 388     <para>
 389     Report medium and high priority bugs.  This is the default setting.
 390     </para>
 391   </listitem>
 392   </varlistentry>
 393
 394   <varlistentry>
 395   <term><command>-high</command></term>
 396   <listitem>
 397     <para>
 398     Report only high priority bugs.
 399     </para>
 400   </listitem>
 401   </varlistentry>
 402
 403   <varlistentry>
 404         <term><command>-relaxed</command></term>
 405         <listitem>
 406                 <para>
 407                         Relaxed reporting mode.  For many detectors, this option
 408                         suppresses the heuristics used to avoid reporting false positives.
 409                 </para>
 410         </listitem>
 411   </varlistentry>
 412
 413   <varlistentry>
 414   <term><command>-xml</command></term>
 415   <listitem>
 416     <para>
 417     Produce the bug reports as XML.  The XML data produced may be
 418     viewed in the GUI at a later time.  You may also specify this
 419     option as <command>-xml:withMessages</command>; when this variant
 420     of the option is used, the XML output will contain human-readable
 421     messages describing the warnings contained in the file.
 422     XML files generated this way are easy to transform into reports.
 423     </para>
 424   </listitem>
 425   </varlistentry>
 426
 427   <varlistentry>
 428   <term><command>-html</command></term>
 429   <listitem>
 430     <para>
 431     Generate HTML output.  By default, &FindBugs; will use the <filename>default.xsl</filename>
 432     <ulink url="http://www.w3.org/TR/xslt">XSLT</ulink>
 433     stylesheet to generate the HTML: you can find this file in <filename>findbugs.jar</filename>,
 434     or in the &FindBugs; source or binary distributions.  Variants of this option include
 435         <command>-html:plain.xsl</command>, <command>-html:fancy.xsl</command> and <command>-html:fancy-hist.xsl</command>.
 436         The <filename>plain.xsl</filename> stylesheet does not use Javascript or DOM,
 437         and may work better with older web browsers, or for printing.  The <filename>fancy.xsl</filename>
 438         stylesheet uses DOM and Javascript for navigation and CSS for
 439         visual presentation. The <command>fancy-hist.xsl</command> an evolution of <command>fancy.xsl</command> stylesheet.
 440         It makes an extensive use of DOM and Javascript for dynamically filtering the lists of bugs.
 441         </para>
 442
 443         <para>
 444         If you want to specify your own
 445     XSLT stylesheet to perform the transformation to HTML, specify the option as
 446     <command>-html:<replaceable>myStylesheet.xsl</replaceable></command>,
 447     where <replaceable>myStylesheet.xsl</replaceable> is the filename of the
 448     stylesheet you want to use.
 449     </para>
 450   </listitem>
 451   </varlistentry>
 452
 453   <varlistentry>
 454   <term><command>-emacs</command></term>
 455   <listitem>
 456     <para>
 457     Produce the bug reports in Emacs format.
 458     </para>
 459   </listitem>
 460   </varlistentry>
 461
 462   <varlistentry>
 463   <term><command>-xdocs</command></term>
 464   <listitem>
 465     <para>
 466     Produce the bug reports in xdoc XML format for use with Apache Maven.
 467     </para>
 468   </listitem>
 469   </varlistentry>
 470
 471   <varlistentry>
 472     <term><command>-output</command> <replaceable>filename</replaceable></term>
 473     <listitem>
 474        <para>
 475        Produce the output in the specified file.
 476        </para>
 477     </listitem>
 478   </varlistentry>
 479
 480   <varlistentry>
 481     <term><command>-outputFile</command> <replaceable>filename</replaceable></term>
 482     <listitem>
 483        <para>
 484        This argument is deprecated.  Use <command>-output</command> instead.
 485        </para>
 486     </listitem>
 487   </varlistentry>
 488
 489   <varlistentry>
 490   <term><command>-nested</command><replaceable>[:true|false]</replaceable></term>
 491   <listitem>
 492     <para>
 493     This option enables or disables scanning of nested jar and zip files found in
 494     the list of files and directories to be analyzed.
 495     By default, scanning of nested jar/zip files is enabled.
 496     To disable it, add <command>-nested:false</command> to the command line
 497     arguments.
 498     </para>
 499   </listitem>
 500   </varlistentry>
 501
 502   <varlistentry>
 503   <term><command>-auxclasspath</command> <replaceable>classpath</replaceable></term>
 504   <listitem>
 505     <para>
 506     Set the auxiliary classpath for analysis.  This classpath should include all
 507     jar files and directories containing classes that are part of the program
 508     being analyzed but you do not want to have analyzed for bugs.
 509     </para>
 510   </listitem>
 511   </varlistentry>
 512
 513 <!--
 514   <varlistentry>
 515   <term><command></command> <replaceable></replaceable></term>
 516   <listitem>
 517     <para>
 518     </para>
 519   </listitem>
 520   </varlistentry>
 521 -->
 522
 523 </variablelist>
 524
 525 </sect2>
 526 </sect1>
 527
 528 </chapter>
 529
 530 <!--
 531    **************************************************************************
 532    Compiling FindBugs from Source
 533    **************************************************************************
 534 -->
 535
 536 <chapter id="building">
 537 <title>Building &FindBugs;&trade; from Source</title>
 538
 539 <para>
 540 This chapter describes how to build &FindBugs; from source code.  Unless you are
 541 interesting in modifying &FindBugs;, you will probably want to skip to the
 542 <link linkend="gui">next chapter</link>.
 543 </para>
 544
 545 <sect1>
 546 <title>Prerequisites</title>
 547
 548 <para>
 549 To compile &FindBugs; from source, you will need the following:
 550 <itemizedlist>
 551   <listitem>
 552     <para>
 553       The <ulink url="http://prdownloads.sourceforge.net/findbugs/findbugs-1.3.0-source.zip?download"
 554       >&FindBugs; source distribution</ulink>
 555     </para>
 556   </listitem>
 557   <listitem>
 558     <para>
 559       <ulink url="http://java.sun.com/j2se/">JDK 1.5.0 beta or later</ulink>
 560     </para>
 561   </listitem>
 562   <listitem>
 563     <para>
 564       <ulink url="http://ant.apache.org/">Apache &Ant;</ulink>, version 1.6.3 or later
 565     </para>
 566   </listitem>
 567 </itemizedlist>
 568 </para>
 569
 570 <warning>
 571         <para>
 572                 The version of &Ant; included as <filename>/usr/bin/ant</filename> on
 573                 Redhat Linux systems will <emphasis>not</emphasis> work for compiling
 574                 &FindBugs;.  We recommend you install a binary distribution of &Ant;
 575                 downloaded from the <ulink url="http://ant.apache.org/">&Ant; website</ulink>.
 576                 Make sure that when you run &Ant; your <replaceable>JAVA_HOME</replaceable>
 577                 environment variable points to the directory in which you installed
 578                 JDK 1.5 (or later).
 579         </para>
 580 </warning>
 581
 582 <para>
 583 If you want to be able to generate formatted versions of the &FindBugs; documentation,
 584 you will also need the following software:
 585 <itemizedlist>
 586   <listitem>
 587     <para>
 588     The <ulink url="http://docbook.sourceforge.net/projects/xsl/index.html">DocBook XSL Stylesheets</ulink>.
 589     These are required to convert the &FindBugs; manual into HTML and PDF formats.
 590     </para>
 591   </listitem>
 592   <listitem>
 593     <para>
 594       The <ulink url="http://saxon.sourceforge.net/">&Saxon; XSLT Processor</ulink>.
 595       The file <filename>saxon.jar</filename> should be in your <envar>CLASSPATH</envar>.
 596     </para>
 597   </listitem>
 598 <!--
 599   <listitem>
 600     <para>
 601     </para>
 602   </listitem>
 603 -->
 604 </itemizedlist>
 605 </para>
 606
 607 </sect1>
 608
 609 <sect1>
 610 <title>Extracting the Source Distribution</title>
 611 <para>
 612 After you download the source distribution, you'll need to extract it into
 613 a working directory.  A typical command to do this is:
 614
 615 <screen>
 616 <prompt>$ </prompt><command>unzip findbugs-1.3.0-source.zip</command>
 617 </screen>
 618
 619 </para>
 620 </sect1>
 621
 622 <sect1>
 623 <title>Modifying <filename>build.properties</filename></title>
 624 <para>
 625 If you intend to build the FindBugs documentation,
 626 you will need to modify the <filename>build.properties</filename> file
 627 used by the <ulink url="http://ant.apache.org/">&Ant;</ulink>
 628 <filename>build.xml</filename> file to build &FindBugs;.
 629 If you do not want to build the FindBugs documentation, then you
 630 can ignore this file.
 631 </para>
 632
 633 <para>
 634 The <filename>build.properties</filename> looks like this:
 635 <programlisting>
 636 <![CDATA[
 637 # User Configuration:
 638 # This section must be modified to reflect your system.
 639
 640 local.software.home     =/export/home/daveho/linux
 641
 642 # Set this to the directory containing the DocBook Modular XSL Stylesheets
 643 #  from http://docbook.sourceforge.net/projects/xsl/
 644
 645 xsl.stylesheet.home     =${local.software.home}/docbook/docbook-xsl-1.71.1
 646
 647 # Set this to the directory where Saxon (http://saxon.sourceforge.net/)
 648 # is installed.
 649
 650 saxon.home              =${local.software.home}/java/saxon-6.5.5
 651 ]]>
 652 </programlisting>
 653 </para>
 654
 655 <para>
 656 The <varname>xsl.stylesheet.home</varname> property specifies the full
 657 path to the directory where you have installed the
 658 <ulink url="http://docbook.sourceforge.net/projects/xsl/">DocBook Modular XSL
 659 Stylesheets</ulink>.  You only need to specify this property if you will be
 660 generating the &FindBugs; documentation.
 661 </para>
 662
 663 <para>
 664 The <varname>saxon.home</varname> property is the full path to the
 665 directory where you installed the <ulink url="http://saxon.sourceforge.net/">&Saxon; XSLT Processor</ulink>.
 666 You only need to specify this property if you will be
 667 generating the &FindBugs; documentation.
 668 </para>
 669
 670 </sect1>
 671
 672 <sect1>
 673 <title>Running &Ant;</title>
 674
 675 <para>
 676 Once you have extracted the source distribution,
 677 made sure that &Ant; is installed,
 678 modified <filename>build.properties</filename> (optional),
 679 and configured the tools (such as &Saxon;),
 680 you are ready to build &FindBugs;.  Invoking &Ant; is a simple matter
 681 of running the command
 682 <screen>
 683 <prompt>$ </prompt><command>ant <replaceable>target</replaceable></command>
 684 </screen>
 685 where <replaceable>target</replaceable> is one of the following:
 686 <variablelist>
 687   <varlistentry>
 688     <term><command>build</command></term>
 689     <listitem>
 690        <para>
 691          This target compiles the code for &FindBugs;. It is the default target.
 692        </para>
 693     </listitem>
 694   </varlistentry>
 695
 696   <varlistentry>
 697     <term><command>docs</command></term>
 698     <listitem>
 699        <para>
 700        This target formats the documentation.  (It also compiles some of
 701        the source code as a side-effect.)
 702        </para>
 703     </listitem>
 704   </varlistentry>
 705
 706   <varlistentry>
 707         <term><command>runjunit</command></term>
 708         <listitem>
 709                 <para>
 710                         This target compiles and runs the internal JUnit tests included
 711                         in &FindBugs;.  It will print an error message if any unit
 712                         tests fail.
 713                 </para>
 714         </listitem>
 715   </varlistentry>
 716
 717   <varlistentry>
 718         <term><command>bindist</command></term>
 719         <listitem>
 720                 <para>
 721                         Builds a binary distribution of &FindBugs;.
 722                         The target creates both <filename>.zip</filename> and
 723                         <filename>.tar.gz</filename> archives.
 724                 </para>
 725         </listitem>
 726   </varlistentry>
 727 </variablelist>
 728 </para>
 729
 730 <para>
 731 After running an &Ant; command, you should see output similar to
 732 the following (after some other messages regarding the tasks that
 733 &Ant; is running):
 734 <screen>
 735 <computeroutput>
 736 BUILD SUCCESSFUL
 737 Total time: 17 seconds
 738 </computeroutput>
 739 </screen>
 740 </para>
 741
 742 </sect1>
 743
 744 <sect1>
 745 <title>Running &FindBugs;&trade;</title>
 746 <para>
 747 The &Ant; build script for &FindBugs; is set up such that after
 748 building the <command>build</command> target, the working directory
 749 is set up just like a binary distribution.  So, the information about
 750 installing a binary distribution of &FindBugs; in <xref linkend="installing" />
 751 applies to source distributions, too.
 752 </para>
 753 </sect1>
 754
 755 </chapter>
 756
 757
 758 <!--
 759    **************************************************************************
 760    Using the FindBugs Graphical Interface
 761    **************************************************************************
 762 -->
 763
 764 <chapter id="gui">
 765 <title>Using the &FindBugs;&trade; Graphical User Interface</title>
 766
 767 <para>
 768 &FindBugs; has two user interfaces: a graphical user interface (GUI) and a
 769 command line user interface.  This chapter describes the graphical user interface.
 770 </para>
 771
 772 <!--
 773 <sect1>
 774 <title>Executing the &FindBugs;&trade; GUI</title>
 775 </sect1>
 776 -->
 777
 778 <sect1>
 779 <title>Creating a Project</title>
 780 <para>
 781 After you have started &FindBugs; using the <command>findbugs</command> command,
 782 choose the <menuchoice><guimenu>File</guimenu><guimenuitem>New Project</guimenuitem></menuchoice>
 783 menu item.  You will see a dialog which looks like this:
 784 <mediaobject>
 785 <imageobject>
 786 <imagedata fileref="project-dialog.png" />
 787 </imageobject>
 788 </mediaobject>
 789 </para>
 790
 791 <para>
 792 Use the "Add" button next to the "Class archives and directories to analyze" text field to select a Java archive
 793 file (zip, jar, ear, or war file) or directory containing java classes to analyze for bugs.  You may add multiple
 794 archives/directories.
 795 </para>
 796
 797 <para>
 798 You can also add the source directories which contain
 799 the source code for the Java archives you are analyzing.  This will enable
 800 &FindBugs; to highlight the source code which contains a possible error.
 801 The source directories you add should be the roots of the Java
 802 package hierarchy.  For example, if your application is contained in the
 803 <varname>org.foobar.myapp</varname> package, you should add the
 804 parent directory of the <filename class="directory">org</filename> directory
 805 to the source directory list for the project.
 806 </para>
 807
 808 <para>
 809 Another optional step is to add additional Jar files or directories as
 810 "Auxiliary classpath locations" entries.  You should do this if the archives and directories you are analyzing
 811 have references to other classes which are not included in the analyzed
 812 archives/directories and are not in the standard runtime classpath.  Some of the bug
 813 pattern detectors in &FindBugs; make use of class hierarchy information,
 814 so you will get more accurate results if the entire class hierarchy is
 815 available which &FindBugs; performs its analysis.
 816 </para>
 817
 818 </sect1>
 819
 820 <sect1>
 821 <title>Running the Analysis</title>
 822 <para>
 823 Once you have added all of the archives, directories, and source directories,
 824 click the "Finish" button to analyze the classes contained in the
 825 Jar files.  Note that for a very large program on an older computer,
 826 this may take quite a while (tens of minutes).  A recent computer with
 827 ample memory will typically be able to analyze a large program in only a
 828 few minutes.
 829 </para>
 830 </sect1>
 831
 832 <sect1>
 833 <title>Browsing Results</title>
 834
 835 <para>
 836 When the analysis completes, you will see a screen like the following:
 837 <mediaobject>
 838   <imageobject>
 839     <imagedata fileref="example-details.png" />
 840   </imageobject>
 841 </mediaobject>
 842 </para>
 843
 844 <para>
 845 The upper left-hand pane of the window shows the bug tree; this is a hierarchical
 846 representation of all of the potential bugs detected in the analyzed
 847 Jar files.
 848 </para>
 849
 850 <para>
 851 When you select a particular bug instance in the top pane, you will
 852 see a description of the bug in the "Details" tab of the bottom pane.
 853 In addition, the source code pane on the upper-right will show the
 854 program source code where the potential bug occurs, if source is available.
 855 In the above example, the bug is a stream object that is not closed.  The
 856 source code window highlights the line where the stream object is created.
 857 </para>
 858
 859 <para>
 860 You may add a textual annotations to bug instances.  To do so, type them
 861 into the text box just below the hierarchical view.  You can type any
 862 information which you would like to record.  When you load and save bug
 863 results files, the annotations are preserved.
 864 </para>
 865
 866 </sect1>
 867
 868 <sect1>
 869 <title>Saving and Opening</title>
 870
 871 <para>
 872 You may use the <menuchoice><guimenu>File</guimenu><guimenuitem>Save as...</guimenuitem></menuchoice>
 873 menu option to save your work.  To save your work, including the jar
 874 file lists you specified and all bug results, choose
 875 "FindBugs analysis results (.xml)" from the drop-down list in the
 876 "Save as..." dialog.  There are also options for saving just the jar
 877 file lists ("FindBugs project file (.fbp)") or just the results
 878 ("FindBugs analysis file (.fba)"), but these are rarely needed.  A
 879 saved file may be loaded with the
 880 <menuchoice><guimenu>File</guimenu><guimenuitem>Open...</guimenuitem></menuchoice>
 881 menu option.
 882 </para>
 883
 884 </sect1>
 885
 886 </chapter>
 887
 888
 889
 890 <!--
 891    **************************************************************************
 892    Using the FindBugs Command Line Interface
 893    **************************************************************************
 894 -->
 895
 896 <chapter id="textui">
 897 <title>Using the &FindBugs;&trade; Command Line Interface</title>
 898
 899 <para>
 900 The &FindBugs; Command Line Interface (or Text UI) can be used to
 901 analyze an application for bugs non-interactively.  Each bug instance will be
 902 reported on a single line.  All output is written to the standard output file descriptor.
 903 <xref linkend="filter" /> explains how bug reports may be filtered in order
 904 to get only the output you're interested in.
 905 </para>
 906
 907 <para>
 908 See <xref linkend="commandLineOptions" /> in <xref linkend="installing" /> for a description of how to invoke the
 909 Command Line Interface.
 910 </para>
 911
 912
 913 </chapter>
 914
 915
 916 <!--
 917    **************************************************************************
 918    Using the FindBugs Ant task
 919    **************************************************************************
 920 -->
 921
 922 <chapter id="anttask">
 923 <title>Using the &FindBugs;&trade; &Ant; task</title>
 924
 925 <para>
 926 This chapter describes how to integrate &FindBugs; into a build script
 927 for <ulink url="http://ant.apache.org/">&Ant;</ulink>, which is a popular Java build
 928 and deployment tool.  Using the &FindBugs; &Ant; task, your build script can
 929 automatically run &FindBugs; on your Java code.
 930 </para>
 931
 932 <para>
 933 The &Ant; task was generously contributed by Mike Fagan.
 934 </para>
 935
 936 <sect1>
 937 <title>Installing the &Ant; task</title>
 938
 939 <para>
 940 To install the &Ant; task, simply copy <filename>&FBHome;/lib/findbugs-ant.jar</filename>
 941 into the <filename>lib</filename> subdirectory of your &Ant; installation.
 942
 943 <note>
 944 <para>It is strongly recommended that you use the &Ant; task with the version
 945 of &FindBugs; it was included with.  We do not guarantee that the &Ant; task Jar file
 946 will work with any version of &FindBugs; other than the one it was included with.</para>
 947 </note>
 948 </para>
 949
 950 </sect1>
 951
 952 <sect1>
 953 <title>Modifying build.xml</title>
 954
 955 <para>
 956 To incorporate &FindBugs; into <filename>build.xml</filename> (the build script
 957 for &Ant;), you first need to add a task definition.  This should appear as follows:
 958
 959 <screen>
 960   &lt;taskdef name="findbugs" classname="edu.umd.cs.findbugs.anttask.FindBugsTask"/&gt;
 961 </screen>
 962
 963 The task definition specifies that when a <literal>findbugs</literal> element is
 964 seen in <filename>build.xml</filename>, it should use the indicated class to execute the task.
 965 </para>
 966
 967 <para>
 968 After you have added the task definition, you can define a target
 969 which uses the <literal>findbugs</literal> task.  Here is an example
 970 which could be added to the <filename>build.xml</filename> for the
 971 Apache <ulink url="http://jakarta.apache.org/bcel/">BCEL</ulink> library.
 972
 973 <screen>
 974   &lt;property name="findbugs.home" value="/export/home/daveho/work/findbugs" /&gt;
 975
 976   &lt;target name="findbugs" depends="jar"&gt;
 977     &lt;findbugs home="${findbugs.home}"
 978               output="xml"
 979               outputFile="bcel-fb.xml" &gt;
 980       &lt;auxClasspath path="${basedir}/lib/Regex.jar" /&gt;
 981       &lt;sourcePath path="${basedir}/src/java" /&gt;
 982       &lt;class location="${basedir}/bin/bcel.jar" /&gt;
 983     &lt;/findbugs&gt;
 984   &lt;/target&gt;
 985 </screen>
 986
 987 The <literal>findbugs</literal> element must have the <literal>home</literal>
 988 attribute set to the directory in which &FindBugs; is installed; in other words,
 989 &FBHome;.  See <xref linkend="installing" />.
 990 </para>
 991
 992 <para>
 993 This target will execute &FindBugs; on <filename>bcel.jar</filename>, which is the
 994 Jar file produced by BCEL's build script.  (By making it depend on the "jar"
 995 target, we ensure that the library is fully compiled before running &FindBugs; on it.)
 996 The output of &FindBugs; will be saved in XML format to a file called
 997 <filename>bcel-fb.xml</filename>.
 998 An auxiliary Jar file, <filename>Regex.jar</filename>, is added to the aux classpath,
 999 because it is referenced by the main BCEL library.  A source path is specified
1000 so that the saved bug data will have accurate references to the BCEL source code.
1001 </para>
1002 </sect1>
1003
1004 <sect1>
1005 <title>Executing the task</title>
1006
1007 <para>
1008 Here is an example of invoking &Ant; from the command line, using the <literal>findbugs</literal>
1009 target defined above.
1010
1011 <screen>
1012   <prompt>[daveho@noir]$</prompt> <command>ant findbugs</command>
1013   Buildfile: build.xml
1014
1015   init:
1016
1017   compile:
1018
1019   examples:
1020
1021   jar:
1022
1023   findbugs:
1024    [findbugs] Running FindBugs...
1025    [findbugs] Bugs were found
1026    [findbugs] Output saved to bcel-fb.xml
1027
1028   BUILD SUCCESSFUL
1029   Total time: 35 seconds
1030 </screen>
1031
1032 In this case, because we saved the bug results in an XML file, we can
1033 use the &FindBugs; GUI to view the results; see <xref linkend="gui"/>.
1034 </para>
1035
1036 </sect1>
1037
1038 <sect1>
1039 <title>Parameters</title>
1040
1041 <para>This section describes the parameters that may be specified when
1042 using the &FindBugs; task.
1043
1044 <variablelist>
1045
1046   <varlistentry>
1047     <term><literal>class</literal></term>
1048     <listitem>
1049        <para>
1050        A nested element specifying which classes to analyze.  The <literal>class</literal>
1051        element must specify a <literal>location</literal> attribute which names the
1052        archive file (jar, zip, etc.), directory, or class file to be analyzed.  Multiple <literal>class</literal>
1053        elements may be specified as children of a single <literal>findbugs</literal> element.
1054        </para>
1055     </listitem>
1056   </varlistentry>
1057
1058   <varlistentry>
1059     <term><literal>auxClasspath</literal></term>
1060     <listitem>
1061        <para>
1062        An optional nested element which specifies a classpath (Jar files or directories)
1063        containing classes used by the analyzed library or application, but which
1064        you don't want to analyze.  It is specified the same way as
1065        &Ant;'s <literal>classpath</literal> element for the Java task.
1066        </para>
1067     </listitem>
1068   </varlistentry>
1069
1070   <varlistentry>
1071     <term><literal>sourcePath</literal></term>
1072     <listitem>
1073        <para>
1074        An optional nested element which specifies a source directory path
1075        containing source files used to compile the Java code being analyzed.
1076        By specifying a source path, any generated XML bug output will have
1077        complete source information, which allows later viewing in the
1078        GUI.
1079        </para>
1080     </listitem>
1081   </varlistentry>
1082
1083   <varlistentry>
1084     <term><literal>home</literal></term>
1085     <listitem>
1086        <para>
1087        A required attribute.
1088        It must be set to the name of the directory where &FindBugs; is installed.
1089        </para>
1090     </listitem>
1091   </varlistentry>
1092
1093   <varlistentry>
1094     <term><literal>quietErrors</literal></term>
1095     <listitem>
1096        <para>
1097        An optional boolean attribute.
1098        If true, reports of serious analysis errors and missing classes will
1099        be suppressed in the &FindBugs; output.  Default is false.
1100        </para>
1101     </listitem>
1102   </varlistentry>
1103
1104   <varlistentry>
1105     <term><literal>reportLevel</literal></term>
1106     <listitem>
1107        <para>
1108        An optional attribute.  It specifies
1109        the priority threshold for reporting bugs.  If set to "low", all bugs are reported.
1110        If set to "medium" (the default), medium and high priority bugs are reported.
1111        If set to "high", only high priority bugs are reported.
1112        </para>
1113     </listitem>
1114   </varlistentry>
1115
1116   <varlistentry>
1117     <term><literal>output</literal></term>
1118     <listitem>
1119        <para>
1120        Optional attribute.
1121        It specifies the output format.  If set to "xml" (the default), output
1122        is in XML format.
1123            If set to "xml:withMessages", output is in XML format augmented with
1124            human-readable messages.  (You should use this format if you plan
1125                 to generate a report using an XSL stylesheet.)
1126            If set to "html", output is in HTML formatted (default stylesheet is default.xsl).
1127                 If set to "text", output is in ad-hoc text format.
1128        If set to "emacs", output is in <ulink url="http://www.gnu.org/software/emacs/">Emacs</ulink> error message format.
1129            If set to "xdocs", output is xdoc XML for use with Apache Maven.
1130        </para>
1131     </listitem>
1132   </varlistentry>
1133  <varlistentry>
1134     <term><literal>stylesheet</literal></term>
1135     <listitem>
1136        <para>
1137        Optional attribute.
1138       It specifies the stylesheet to use to generate html output when the output is set to html.
1139       Stylesheets included in the FindBugs distribution include default.xsl, fancy.xsl, fancy-hist.xsl, plain.xsl, and summary.xsl.
1140        The default value, if no stylesheet attribute is provided, is default.xsl.
1141
1142        </para>
1143     </listitem>
1144   </varlistentry>
1145
1146   <varlistentry>
1147     <term><literal>sort</literal></term>
1148     <listitem>
1149        <para>
1150        Optional attribute.  If the <literal>output</literal> attribute
1151        is set to "text", then the <literal>sort</literal> attribute specifies
1152        whether or not reported bugs are sorted by class.  Default is true.
1153        </para>
1154     </listitem>
1155   </varlistentry>
1156
1157   <varlistentry>
1158     <term><literal>outputFile</literal></term>
1159     <listitem>
1160        <para>
1161        Optional attribute.  If specified, names the output file in which the
1162        &FindBugs; output will be saved.  By default, the output is displayed
1163        directly by &Ant;.
1164        </para>
1165     </listitem>
1166   </varlistentry>
1167
1168   <varlistentry>
1169     <term><literal>debug</literal></term>
1170     <listitem>
1171        <para>
1172       Optional boolean attribute.  If set to true, &FindBugs; prints diagnostic
1173       information about which classes are being analyzed, and which bug pattern
1174       detectors are being run.  Default is false.
1175        </para>
1176     </listitem>
1177   </varlistentry>
1178
1179   <varlistentry>
1180           <term><literal>effort</literal></term>
1181           <listitem>
1182                   <para>
1183                           Set the analysis effort level.  The value specified should be
1184                           one of <literal>min</literal>, <literal>default</literal>,
1185                           or <literal>max</literal>.  See <xref linkend="commandLineOptions"/>
1186                           for more information about setting the analysis level.
1187                   </para>
1188           </listitem>
1189   </varlistentry>
1190
1191   <varlistentry>
1192     <term><literal>conserveSpace</literal></term>
1193     <listitem>
1194        <para>Synonym for effort="min".</para>
1195     </listitem>
1196   </varlistentry>
1197
1198   <varlistentry>
1199     <term><literal>workHard</literal></term>
1200     <listitem>
1201        <para>Synonym for effort="max".</para>
1202     </listitem>
1203   </varlistentry>
1204
1205   <varlistentry>
1206     <term><literal>visitors</literal></term>
1207     <listitem>
1208        <para>
1209        Optional attribute.  It specifies a comma-separated list of bug detectors
1210        which should be run.  The bug detectors are specified by their class names,
1211        without any package qualification.  By default, all detectors which are
1212        not disabled by default are run.
1213        </para>
1214     </listitem>
1215   </varlistentry>
1216
1217   <varlistentry>
1218     <term><literal>omitVisitors</literal></term>
1219     <listitem>
1220        <para>
1221        Optional attribute.  It is like the <literal>visitors</literal> attribute,
1222        except it specifies detectors which will <emphasis>not</emphasis> be run.
1223        </para>
1224     </listitem>
1225   </varlistentry>
1226
1227   <varlistentry>
1228     <term><literal>excludeFilter</literal></term>
1229     <listitem>
1230        <para>
1231        Optional attribute.  It specifies the filename of a filter specifying bugs
1232        to exclude from being reported.  See <xref linkend="filter" />.
1233        </para>
1234     </listitem>
1235   </varlistentry>
1236
1237   <varlistentry>
1238     <term><literal>includeFilter</literal></term>
1239     <listitem>
1240        <para>
1241        Optional attribute.  It specifies the filename of a filter specifying
1242        which bugs are reported.  See <xref linkend="filter" />.
1243        </para>
1244     </listitem>
1245   </varlistentry>
1246
1247   <varlistentry>
1248     <term><literal>projectFile</literal></term>
1249     <listitem>
1250        <para>
1251        Optional attribute.  It specifies the name of a project file.
1252        Project files are created by the &FindBugs; GUI, and specify classes,
1253        aux classpath entries, and source directories.  By naming a project,
1254        you don't need to specify any <literal>class</literal> elements,
1255        nor do you need to specify <literal>auxClasspath</literal> or
1256        <literal>sourcePath</literal> attributes.
1257        See <xref linkend="gui"/> for how to create a project.
1258        </para>
1259     </listitem>
1260   </varlistentry>
1261
1262   <varlistentry>
1263     <term><literal>jvmargs</literal></term>
1264     <listitem>
1265        <para>
1266        Optional attribute.  It specifies any arguments that should be passed
1267        to the Java virtual machine used to run &FindBugs;.  You may need to
1268        use this attribute to specify flags to increase the amount of memory
1269        the JVM may use if you are analyzing a very large program.
1270        </para>
1271     </listitem>
1272   </varlistentry>
1273
1274   <varlistentry>
1275     <term><literal>systemProperty</literal></term>
1276     <listitem>
1277       <para>
1278       Optional nested element.  If specified, defines a system property.
1279       The <literal>name</literal> attribute specifies the name of the
1280       system property, and the <literal>value</literal> attribute specifies
1281       the value of the system property.
1282       </para>
1283     </listitem>
1284   </varlistentry>
1285
1286   <varlistentry>
1287     <term><literal>timeout</literal></term>
1288     <listitem>
1289        <para>
1290        Optional attribute.  It specifies the amount of time, in milliseconds,
1291        that the Java process executing &FindBugs; may run before it is
1292        assumed to be hung and is terminated.  The default is 600,000
1293        milliseconds, which is ten minutes.  Note that for very large
1294        programs, &FindBugs; may require more than ten minutes to complete its
1295        analysis.
1296        </para>
1297     </listitem>
1298   </varlistentry>
1299
1300   <varlistentry>
1301     <term><literal>failOnError</literal></term>
1302     <listitem>
1303        <para>
1304        Optional boolean attribute.  Whether to abort the build process if there is an
1305        error running &FindBugs;. Defaults to "false"
1306        </para>
1307     </listitem>
1308   </varlistentry>
1309
1310   <varlistentry>
1311     <term><literal>errorProperty</literal></term>
1312     <listitem>
1313        <para>
1314        Optional attribute which specifies the name of a property that
1315        will be set to "true" if an error occurs while running &FindBugs;.
1316        </para>
1317     </listitem>
1318   </varlistentry>
1319
1320   <varlistentry>
1321           <term><literal>warningsProperty</literal></term>
1322           <listitem>
1323                   <para>
1324                           Optional attribute which specifies the name of a property
1325                           that will be set to "true" if any warnings are reported by
1326                           &FindBugs; on the analyzed program.
1327                   </para>
1328           </listitem>
1329   </varlistentry>
1330
1331 </variablelist>
1332
1333
1334 </para>
1335
1336 <!--
1337
1338 -->
1339
1340 </sect1>
1341
1342 </chapter>
1343
1344 <!--
1345    **************************************************************************
1346    Using the FindBugs Eclipse plugin
1347    **************************************************************************
1348 -->
1349
1350 <chapter id="eclipse">
1351 <title>Using the &FindBugs;&trade; Eclipse plugin</title>
1352
1353 <para>
1354 The FindBugs Eclipse plugin allows &FindBugs; to be used within
1355 the <ulink url="http://www.eclipse.org/">Eclipse</ulink> IDE.
1356 The FindBugs Eclipse plugin was generously contributed by Peter Friese.
1357 Phil Crosby and Andrei Loskutov contributed major improvements
1358 to the plugin.
1359 </para>
1360
1361 <sect1>
1362 <title>Requirements</title>
1363
1364 <para>
1365 To use the &FindBugs; Plugin for Eclipse, you need Eclipse 3.0.1 or later,
1366 and JRE/JDK 1.4.0 or later.
1367 </para>
1368
1369 </sect1>
1370
1371 <sect1>
1372 <title>Installation</title>
1373
1374 <para>
1375   We provide update sites that allow you to automatically install FindBugs into Eclipse and also query and install updates.
1376   There are three different update sites</para>
1377
1378   <variablelist><title>FindBugs Eclipse update sites</title>
1379     <varlistentry><term><ulink url="http://findbugs.cs.umd.edu/eclipse/">http://findbugs.cs.umd.edu/eclipse/</ulink></term>
1380
1381     <listitem>
1382       <para>
1383        Only provides official releases of FindBugs.
1384       </para>
1385     </listitem>
1386     </varlistentry>
1387
1388     <varlistentry><term><ulink url="http://findbugs.cs.umd.edu/eclipse-candidate/">http://findbugs.cs.umd.edu/eclips-candidate/</ulink></term>
1389
1390       <listitem>
1391         <para>
1392           Provides official releases and release candidates of FindBugs.
1393         </para>
1394       </listitem>
1395     </varlistentry>
1396
1397     <varlistentry><term><ulink url="http://findbugs.cs.umd.edu/eclipse-daily/">http://findbugs.cs.umd.edu/eclipse-daily/</ulink></term>
1398
1399       <listitem>
1400         <para>
1401          Provides the daily build of FindBugs. No testing other than that it compiles.
1402         </para>
1403       </listitem>
1404     </varlistentry>
1405     </variablelist>
1406
1407 <para>You can also manually
1408 download the plugin from the following link:
1409 <ulink url="http://prdownloads.sourceforge.net/findbugs/edu.umd.cs.findbugs.plugin.eclipse_1.3.0.20071108.zip?download"
1410 >http://prdownloads.sourceforge.net/findbugs/edu.umd.cs.findbugs.plugin.eclipse_1.3.0.20071108.zip?download</ulink>.
1411 Extract it in Eclipse's "plugins" subdirectory.
1412 (So &lt;eclipse_install_dir&gt;/plugins/edu.umd.cs.findbugs.plugin.eclipse_1.3.0.20071108/findbugs.png
1413 should be the path to the &FindBugs; logo.)
1414
1415 </para>
1416
1417 <para>
1418 Once the plugin is extracted, start Eclipse and choose
1419 <menuchoice>
1420   <guimenu>Help</guimenu>
1421   <guimenuitem>About Eclipse Platform</guimenuitem>
1422   <guimenuitem>Plug-in Details</guimenuitem>
1423 </menuchoice>.
1424 You should find a plugin called "FindBugs Plug-in" provided by "FindBugs Project".
1425 </para>
1426 </sect1>
1427
1428 <sect1>
1429 <title>Using the Plugin</title>
1430
1431 <para>
1432 To get started, right click on a Java project,
1433 and select the option labeled "Find Bugs".
1434 &FindBugs; will run, and problem markers (displayed in source
1435 windows, and also in the Eclipse Problems view) will point to
1436 locations in your code which have been identified as potential instances
1437 of bug patterns.
1438 </para>
1439
1440 <para>
1441 You may customize how &FindBugs; runs by opening the Properties
1442 dialog for a Java project, and choosing the "Findbugs" property page.
1443 Options you may choose include:
1444 </para>
1445
1446 <itemizedlist>
1447   <listitem>
1448     <para>
1449     Enable or disable the "Run FindBugs Automatically" checkbox.
1450     When enabled, FindBugs will run every time you modify a Java class
1451     within the project.
1452     </para>
1453   </listitem>
1454
1455   <listitem>
1456     <para>
1457     Choose minimum warning priority and enabled bug categories.
1458     These options will choose which warnings are shown.
1459     For example, if you select the "Medium" warning priority,
1460     only Medium and High priority warnings will be shown.
1461     Similarly, if you uncheck the "Style" checkbox, no warnings
1462     in the Style category will be displayed.
1463     </para>
1464   </listitem>
1465
1466   <listitem>
1467     <para>
1468     Select detectors.  The table allows you to select which detectors
1469     you want to enable for your project.
1470     </para>
1471   </listitem>
1472 </itemizedlist>
1473
1474 </sect1>
1475
1476 <sect1>
1477 <title>Troubleshooting</title>
1478
1479 <para>
1480 The &FindBugs; Eclipse plugin is still experimental.&nbsp; This section
1481 lists common problems with the plugin and (if known) how to resolve them.
1482 </para>
1483
1484 <itemizedlist>
1485   <listitem>
1486     <para>
1487     If you do not see any &FindBugs; problem markers (in your source
1488     windows or in the Problems View), you may need to change your
1489     Problems View filter settings.  See
1490     <ulink url="http://findbugs.sourceforge.net/FAQ.html#q7">http://findbugs.sourceforge.net/FAQ.html#q7</ulink> for more information.
1491     </para>
1492   </listitem>
1493
1494 </itemizedlist>
1495
1496 </sect1>
1497
1498
1499 </chapter>
1500
1501
1502 <!--
1503    **************************************************************************
1504    Filter files
1505    **************************************************************************
1506 -->
1507
1508 <chapter id="filter">
1509 <title>Filter Files</title>
1510
1511 <para>
1512 Filter files may be used to include or exclude bug reports for particular classes
1513 and methods.  This chapter explains how to use filter files.
1514
1515 <note>
1516 <title>Planned Features</title>
1517 <para>
1518   Filters are currently only supported by the Command Line interface.
1519   Eventually, filter support will be added to the GUI.
1520 </para>
1521 </note>
1522 </para>
1523
1524
1525 <sect1>
1526 <title>Introduction to Filter Files</title>
1527
1528 <para>
1529 Conceptually, a filter matches bug instances against a set of criteria.
1530 By defining a filter, you can select bug instances for special treatment;
1531 for example, to exclude or include them in a report.
1532 </para>
1533
1534 <para>
1535 A filter file is an <ulink url="http://www.w3.org/XML/">XML</ulink> document with a top-level <literal>FindBugsFilter</literal> element
1536 which has some number of <literal>Match</literal> elements as children.  Each <literal>Match</literal>
1537 element represents a predicate which is applied to generated bug instances.
1538 Usually, a filter will be used to exclude bug instances.  For example:
1539
1540 <screen>
1541 <prompt>$ </prompt><command>findbugs -textui -exclude <replaceable>myExcludeFilter.xml</replaceable> <replaceable>myApp.jar</replaceable></command>
1542 </screen>
1543
1544 However, a filter could also be used to select bug instances to specifically
1545 report:
1546
1547 <screen>
1548 <prompt>$ </prompt><command>findbugs -textui -include <replaceable>myIncludeFilter.xml</replaceable> <replaceable>myApp.jar</replaceable></command>
1549 </screen>
1550 </para>
1551
1552 <para>
1553 <literal>Match</literal> elements contain children, which are conjuncts of the predicate.
1554 In other words, each of the children must be true for the predicate to be true.
1555 </para>
1556
1557 </sect1>
1558
1559 <sect1>
1560 <title>Types of Match clauses</title>
1561
1562 <variablelist>
1563  <varlistentry>
1564    <term><literal>&lt;Bug&gt;</literal></term>
1565    <listitem><para>
1566                         This element specifies a particular bug pattern or patterns to match.
1567                         The <literal>pattern</literal> attribute is a comma-separated list of
1568                         bug pattern types.  You can find the bug pattern types for particular
1569                         warnings by looking at the output produced by the <command>-xml</command>
1570                         output option (the <literal>type</literal> attribute of <literal>BugInstance</literal>
1571                         elements), or from the <ulink url="../bugDescriptions.html">bug
1572                         descriptions document</ulink>.
1573    </para><para>
1574                         For more coarse-grained matching, use <literal>code</literal> attribute. It takes
1575                         a comma-separated list of bug abbreviations. For most-coarse grained matching use
1576                         <literal>category</literal> attriute, that takes a comma separated list of bug category names:
1577                         <literal>CORRECTNESS</literal>, <literal>MT_CORRECTNESS</literal>,
1578                         <literal>BAD_PRACTICICE</literal>, <literal>PERFORMANCE</literal>, <literal>STYLE</literal>.
1579    </para><para>
1580                         If more than one of the attributes mentioned above are specified on the same
1581                         <literal>&lt;Bug&gt;</literal> element, all bug patterns that match either one of specified
1582                         pattern names, or abreviations, or categories will be matched.
1583    </para><para>
1584                         As a backwards compatibility measure, <literal>&lt;BugPattern&gt;</literal> and
1585                         <literal>&lt;BugCode&gt;</literal> elements may be used instead of
1586                         <literal>&lt;Bug&gt;</literal> element. Each of these uses a
1587                         <literal>name</literal> attribute for specifying accepted values list. Support for these
1588                         elements may be removed in a future release.
1589    </para></listitem>
1590  </varlistentry>
1591
1592  <varlistentry>
1593         <term><literal>&lt;Priority&gt;</literal></term>
1594         <listitem>
1595                 <para>
1596                         This element matches warnings with a particular priority.
1597                         The <literal>value</literal> attribute should be an integer value:
1598                         1 to match high-priority warnings, 2 to match medium-priority warnings,
1599                         or 3 to match low-priority warnings.
1600                 </para>
1601         </listitem>
1602  </varlistentry>
1603
1604
1605  <varlistentry>
1606    <term><literal>&lt;Package&gt;</literal></term>
1607         <listitem>
1608                 <para>
1609                         This element matches warnings associated with classes within the package specified
1610                         using <literal>name</literal> attribute. Nested packages are not included (along the
1611                         lines of Java import statement). However matching multiple packages can be achieved
1612                         easily using regex name match.
1613                 </para>
1614         </listitem>
1615   </varlistentry>
1616
1617  <varlistentry>
1618    <term><literal>&lt;Class&gt;</literal></term>
1619         <listitem>
1620                 <para>
1621                         This element matches warnings associated with a particular class. The
1622                         <literal>name</literal> attribute is used to specify the exact or regex match pattern
1623                         for the class name.
1624                 </para>
1625
1626                 <para>
1627                         As a backward compatibility measure, instead of element of this type, you can use
1628                          <literal>class</literal> attribute on a <literal>Match</literal> element to specify
1629                          exact an class name or <literal>classregex</literal> attribute to specify a regular
1630                          expression to match the class name against.
1631                 </para>
1632
1633                 <para>
1634                         If the <literal>Match</literal> element contains neither a <literal>Class</literal> element,
1635                         nor a <literal>class</literal> / <literal>classregex</literal> attribute, the predicate will apply
1636                         to all classes. Such predicate is likely to match more bug instances than you want, unless it is
1637                         refined further down with apropriate method or field predicates.
1638                 </para>
1639         </listitem>
1640  </varlistentry>
1641
1642  <varlistentry>
1643    <term><literal>&lt;Method&gt;</literal></term>
1644
1645    <listitem><para>This element specifies a method.  The <literal>name</literal> is used to specify
1646    the exact or regex match pattern for the method name.
1647    The <literal>params</literal> attribute is a comma-separated list
1648    of the types of the method's parameters.  The <literal>returns</literal> attribute is
1649    the method's return type.  In <literal>params</literal> and <literal>returns</literal>, class names
1650    must be fully qualified. (E.g., "java.lang.String" instead of just
1651    "String".) If one of the latter attributes is specified the other is required for creating a method signature.
1652    Note that you can provide either <literal>name</literal> attribute or <literal>params</literal>
1653    and <literal>returns</literal> attributes or all three of them. This way you can provide various kinds of
1654    name and signature based matches.
1655    </para></listitem>
1656  </varlistentry>
1657
1658  <varlistentry>
1659    <term><literal>&lt;Field&gt;</literal></term>
1660
1661    <listitem><para>This element specifies a field. The <literal>name</literal> attribute is is used to specify
1662    the exact or regex match pattern for the field name. You can also filter fields according to their signature -
1663    use <literal>type</literal> attribute to specify fully qualified type of the field. You can specify eiter or both
1664    of these attributes in order to perform name / signature based matches.
1665    </para></listitem>
1666  </varlistentry>
1667
1668    <varlistentry>
1669    <term><literal>&lt;Local&gt;</literal></term>
1670
1671    <listitem><para>This element specifies a local variable. The <literal>name</literal> attribute is is used to specify
1672    the exact or regex match pattern for the local variable name. Local variables are variables defined within a method.
1673    </para></listitem>
1674  </varlistentry>
1675
1676  <varlistentry>
1677    <term><literal>&lt;Or&gt;</literal></term>
1678     <listitem><para>
1679    This element combines <literal>Match</literal> clauses as disjuncts.  I.e., you can put two
1680    <literal>Method</literal> elements in an <literal>Or</literal> clause in order match either method.
1681    </para></listitem>
1682  </varlistentry>
1683 </variablelist>
1684
1685 </sect1>
1686
1687 <sect1>
1688 <title>Java element name matching</title>
1689
1690 <para>
1691 If the <literal>name</literal> attribute or <literal>Class</literal>, <literal>Method</literal> or
1692 <literal>Field</literal> starts with the ~ character the rest of attribute content is interpreted as
1693 a Java regular expression that is matched against the names of the Java element in question.
1694 </para>
1695
1696 <para>
1697 Note that the pattern is matched against whole element name and therefore .* clauses need to be used
1698 at pattern beginning and/or end to perform substring matching.
1699 </para>
1700
1701 <para>
1702 See <ulink url="http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html"><literal>java.util.regex.Pattern</literal></ulink>
1703 documentation for pattern syntax.
1704 </para>
1705 </sect1>
1706
1707 <sect1>
1708 <title>Caveats</title>
1709
1710 <para>
1711 <literal>Match</literal> clauses can only match information that is actually contained in the
1712 bug instances.  Every bug instance has a class, so in general, excluding
1713 bugs by class will work.
1714 </para>
1715
1716 <para>
1717 Some bug instances have two (or more) classes.  For example, the DE (dropped exception)
1718 bugs report both the class containing the method where the dropped exception
1719 happens, and the class which represents the type of the dropped exception.
1720 Only the <emphasis>first</emphasis> (primary) class is matched against <literal>Match</literal> clauses.
1721 So, for example, if you want to suppress IC (initialization circularity)
1722 reports for classes "com.foobar.A" and "com.foobar.B", you would use
1723 two <literal>Match</literal> clauses:
1724
1725 <programlisting>
1726    &lt;Match&gt;
1727       &lt;Class name="com.foobar.A" /&gt;
1728       &lt;Bug code="IC" /&gt;
1729    &lt;/Match&gt;
1730
1731    &lt;Match&gt;
1732       &lt;Class name="com.foobar.B" /&gt;
1733       &lt;Bug code="IC" /&gt;
1734    &lt;/Match&gt;
1735 </programlisting>
1736
1737 By explicitly matching both classes, you ensure that the IC bug instance will be
1738 matched regardless of which class involved in the circularity happens to be
1739 listed first in the bug instance.  (Of course, this approach might accidentally
1740 supress circularities involving "com.foobar.A" or "com.foobar.B" and a third
1741 class.)
1742 </para>
1743
1744 <para>
1745 Many kinds of bugs report what method they occur in.  For those bug instances,
1746 you can put <literal>Method</literal> clauses in the <literal>Match</literal> element and they should work
1747 as expected.
1748 </para>
1749
1750 </sect1>
1751
1752 <sect1>
1753 <title>Examples</title>
1754
1755 <para>
1756   1. Match all bug reports for a class.
1757
1758 <programlisting>
1759 <![CDATA[
1760      <Match>
1761        <Class name="com.foobar.MyClass" />
1762      </Match>
1763 ]]>
1764 </programlisting>
1765
1766 </para>
1767
1768 <para>
1769   2. Match certain tests from a class by specifying their abbreviations.
1770 <programlisting>
1771 <![CDATA[
1772      <Match>
1773        <Class name="com.foobar.MyClass"/ >
1774        <Bug code="DE,UrF,SIC" />
1775      </Match>
1776 ]]>
1777 </programlisting>
1778 </para>
1779
1780 <para>
1781   3. Match certain tests from all classes by specifying their abbreviations.
1782
1783 <programlisting>
1784 <![CDATA[
1785      <Match>
1786        <Bug code="DE,UrF,SIC" />
1787      </Match>
1788 ]]>
1789 </programlisting>
1790 </para>
1791
1792 <para>
1793   4. Match certain tests from all classes by specifying their category.
1794
1795 <programlisting>
1796 <![CDATA[
1797      <Match>
1798        <Bug category="PERFORMANCE" />
1799      </Match>
1800 ]]>
1801 </programlisting>
1802 </para>
1803
1804 <para>
1805   5. Match bug types from specified methods of a class by their abbreviations.
1806
1807 <programlisting>
1808 <![CDATA[
1809      <Match>
1810        <Class name="com.foobar.MyClass" />
1811        <Or>
1812          <Method name="frob" params="int,java.lang.String" returns="void" />
1813          <Method name="blat" params="" returns="boolean" />
1814        </Or>
1815        <Bug code="DC" />
1816      </Match>
1817 ]]>
1818 </programlisting>
1819 </para>
1820
1821 <para>
1822         6. Match a particular bug pattern in a particular method.
1823
1824 <programlisting>
1825 <![CDATA[
1826     <!-- A method with an open stream false positive. -->
1827     <Match>
1828       <Class name="com.foobar.MyClass" />
1829       <Method name="writeDataToFile" />
1830       <Bug pattern="OS_OPEN_STREAM" />
1831     </Match>
1832 ]]>
1833 </programlisting>
1834 </para>
1835
1836 <para>
1837         7. Match a particular bug pattern with a given priority in a particular method.
1838
1839 <programlisting>
1840 <![CDATA[
1841     <!-- A method with a dead local store false positive (medium priority). -->
1842     <Match>
1843       <Class name="com.foobar.MyClass" />
1844       <Method name="someMethod" />
1845       <Bug pattern="DLS_DEAD_LOCAL_STORE" />
1846       <Priority value="2" />
1847     </Match>
1848 ]]>
1849 </programlisting>
1850 </para>
1851
1852 <para>
1853         8. Match minor bugs introduced by AspectJ compiler (you are probably not interested in these unless
1854         you are an AspectJ developer).
1855
1856 <programlisting>
1857 <![CDATA[
1858     <Match>
1859       <Class name="~.*\$AjcClosure\d+" />
1860       <Bug pattern="DLS_DEAD_LOCAL_STORE" />
1861       <Method name="run" />
1862     </Match>
1863     <Match>
1864       <Bug pattern="UUF_UNUSED_FIELD" />
1865       <Field name="~ajc\$.*" />
1866     </Match>
1867 ]]>
1868 </programlisting>
1869 </para>
1870
1871 <para>
1872         9. Match bugs in specific parts of the code base
1873
1874 <programlisting>
1875 <![CDATA[
1876     <!-- match unused fields warnings in Messages classes in all packages -->
1877     <Match>
1878       <Class name="~.*\.Messages" />
1879       <Bug code="UUF" />
1880     </Match>
1881     <!-- match mutable statics warnings in all internal packages -->
1882     <Match>
1883       <Package name="~.*\.internal" />
1884       <Bug code="MS" />
1885     </Match>
1886     <!-- match anonymoous inner classes warnings in ui package hierarchy -->
1887     <Match>
1888       <Package name="~com\.foobar\.fooproject\.ui.*" />
1889       <Bug pattern="SIC_INNER_SHOULD_BE_STATIC_ANON" />
1890     </Match>
1891 ]]>
1892 </programlisting>
1893 </para>
1894
1895 <para>
1896         10. Match bugs on fieds or methods with specific signatures
1897 <programlisting>
1898 <![CDATA[
1899         <!-- match System.exit(...) usage warnings in void main(String[]) methods in all classes -->
1900         <Match>
1901           <Method returns="void" name="main" params="java.lang.String[]" />
1902           <Method pattern="DM_EXIT" />
1903         </Match>
1904         <!-- match UuF warnings on fields of type com.foobar.DebugInfo on all classes -->
1905         <Match>
1906           <Field type="com.foobar.DebugInfo" />
1907           <Bug code="UuF" />
1908         </Match>
1909 ]]>
1910 </programlisting>
1911
1912 </para>
1913
1914 </sect1>
1915
1916 <sect1>
1917 <title>Complete Example</title>
1918
1919 <programlisting>
1920 <![CDATA[
1921 <FindBugsFilter>
1922      <Match>
1923        <Class name="com.foobar.ClassNotToBeAnalyzed" />
1924      </Match>
1925
1926      <Match>
1927        <Class name="com.foobar.ClassWithSomeBugsMatched" />
1928        <Bug code="DE,UrF,SIC" />
1929      </Match>
1930
1931      <!-- Match all XYZ violations. -->
1932      <Match>
1933        <Bug code="XYZ" />
1934      </Match>
1935
1936      <!-- Match all doublecheck violations in these methods of "AnotherClass". -->
1937      <Match>
1938        <Class name="com.foobar.AnotherClass" />
1939        <Or>
1940          <Method name="nonOverloadedMethod" />
1941          <Method name="frob" params="int,java.lang.String" returns="void" />
1942          <Method name="blat" params="" returns="boolean" />
1943        </Or>
1944        <Bug code="DC" />
1945      </Match>
1946
1947      <!-- A method with a dead local store false positive (medium priority). -->
1948      <Match>
1949        <Class name="com.foobar.MyClass" />
1950        <Method name="someMethod" />
1951        <Bug code="DLS_DEAD_LOCAL_STORE" />
1952        <Priority value="2" />
1953      </Match>
1954 </FindBugsFilter&gt;
1955 ]]>
1956 </programlisting>
1957
1958 </sect1>
1959
1960
1961 </chapter>
1962
1963
1964 <!--
1965    **************************************************************************
1966    Analysis properties
1967    **************************************************************************
1968 -->
1969
1970 <chapter id="analysisprops">
1971 <title>Analysis Properties</title>
1972
1973 <para>
1974 &FindBugs; allows several aspects of the analyses it performs to be
1975 customized.  System properties are used to configure these options.
1976 This chapter describes the configurable analysis options.
1977 </para>
1978
1979 <para>
1980 The analysis options have two main purposes.  First, they allow you
1981 to inform &FindBugs; about the meaning of methods in your application,
1982 so that it can produce more accurate results, or produce fewer
1983 false warnings.  Second, they allow you to configure the precision
1984 of the analysis performed.  Reducing analysis precision can save
1985 memory and analysis time, at the expense of missing some real bugs,
1986 or producing more false warnings.
1987 </para>
1988
1989 <para>
1990 The analysis options are set using the <command>-property</command>
1991 command line option.  For example:
1992 <screen>
1993 <prompt>$ </prompt><command>findbugs -textui -property "cfg.noprune=true" <replaceable>myApp.jar</replaceable></command>
1994 </screen>
1995 </para>
1996
1997 <para>
1998 The list of configurable analysis properties is shown in
1999 <xref linkend="analysisproptable"/>.
2000 </para>
2001
2002 <table id="analysisproptable">
2003 <title>Configurable Analysis Properties</title>
2004 <tgroup cols="3" align="left">
2005   <thead>
2006     <row>
2007       <entry>Property Name</entry>
2008       <entry>Value</entry>
2009       <entry>Meaning</entry>
2010     </row>
2011   </thead>
2012   <tbody>
2013 <!--
2014     <row>
2015       <entry>cfg.noprune</entry>
2016       <entry>true or false</entry>
2017       <entry>If true, infeasible exception edges are not pruned from
2018       the control flow graphs of analyzed methods.  This option
2019       increases the speed of the analysis (by about 20%-30%),
2020       but causes some detectors to produce more false warnings.</entry>
2021     </row>
2022 -->
2023     <row>
2024       <entry>findbugs.assertionmethods</entry>
2025       <entry>Comma-separated list of fully qualified method names:
2026       e.g., "com.foo.MyClass.checkAssertion"</entry>
2027       <entry>This property specifies the names of methods that are used
2028       to check program assertions.  Specifying these methods allows
2029       the null pointer dereference bug detector to avoid reporting
2030       false warnings for values which are checked by assertion
2031       methods.</entry>
2032     </row>
2033     <row>
2034       <entry>findbugs.de.comment</entry>
2035       <entry>true or false</entry>
2036       <entry>If true, the DroppedException detector scans source code
2037         for empty catch blocks for a comment, and if one is found, does
2038         not report a warning.</entry>
2039     </row>
2040     <row>
2041       <entry>findbugs.maskedfields.locals</entry>
2042       <entry>true or false</entry>
2043       <entry>If true, emit low priority warnings for local variables
2044       which obscure fields.  Default is false.</entry>
2045     </row>
2046     <row>
2047       <entry>findbugs.nullderef.assumensp</entry>
2048       <entry>true or false</entry>
2049       <entry>not used
2050       (intention: If true, the null dereference detector assumes that any
2051       reference value returned from a method or passed to a method
2052       in a parameter might be null.  Default is false.  Note that
2053       enabling this property will very likely cause a large number
2054       of false warnings to be produced.)</entry>
2055     </row>
2056     <row>
2057       <entry>findbugs.refcomp.reportAll</entry>
2058       <entry>true or false</entry>
2059       <entry>If true, all suspicious reference comparisons
2060         using the == and != operators are reported.&nbsp; If false,
2061         only one such warning is issued per method.&nbsp; Default
2062         is false.</entry>
2063     </row>
2064     <row>
2065       <entry>findbugs.sf.comment</entry>
2066       <entry>true or false</entry>
2067       <entry>If true, the SwitchFallthrough detector will only report
2068       warnings for cases where the source code does not have a comment
2069       containing the words "fall" or "nobreak".  (An accurate source
2070       path must be used for this feature to work correctly.)
2071       This helps find cases where the switch fallthrough is likely
2072       to be unintentional.</entry>
2073     </row>
2074 <!-- see others at src/doc/manual/sysprops.html
2075     <row>
2076       <entry></entry>
2077       <entry></entry>
2078       <entry></entry>
2079     </row>
2080 -->
2081   </tbody>
2082 </tgroup>
2083 </table>
2084
2085 </chapter>
2086
2087 <!--
2088     **************************************************************************
2089    Annotations
2090    ***************************************************************************
2091 -->
2092
2093 <chapter id="annotations">
2094 <title>Annotations</title>
2095
2096 <para>
2097 &FindBugs; supports several annotations to express the developer's intent
2098 so that FindBugs can issue warnings more appropriately. You need to use
2099 Java 5 to use annotations, and must place the annotations.jar on the
2100 classpath while compiling your program.
2101 </para>
2102
2103 <variablelist>
2104   <varlistentry>
2105     <term><command>edu.umd.cs.findbugs.annotations.CheckForNull</command></term>
2106     <listitem>
2107 <command>[Target]</command> Field, Method, Parameter, Local variable
2108     </listitem>
2109     <listitem>
2110       <para>
2111 The annotated element might be null, and uses of the element should check for null.
2112 When this annotation is applied to a method it applies to the method return value.
2113       </para>
2114     </listitem>
2115   </varlistentry>
2116
2117   <varlistentry>
2118     <term><command>edu.umd.cs.findbugs.annotations.CheckReturnValue</command></term>
2119     <listitem>
2120       <command>[Target]</command> Method, Constructor
2121     </listitem>
2122     <listitem>
2123       <variablelist>
2124         <varlistentry>
2125           <term><command>[Parameter]</command></term>
2126           <listitem>
2127             <para>
2128               <command>priority:</command>The priority of the warning (HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM.
2129             </para>
2130           </listitem>
2131           <listitem>
2132             <para>
2133               <command>explanation:</command>A textual explaination of why the return value should be checked. Default value:"".
2134             </para>
2135           </listitem>
2136         </varlistentry>
2137       </variablelist>
2138     </listitem>
2139     <listitem>
2140       <para>
2141 This annotation is used to denote a method whose return value should always be checked after invoking the method.
2142       </para>
2143     </listitem>
2144   </varlistentry>
2145
2146   <varlistentry>
2147     <term><command>edu.umd.cs.findbugs.annotations.DefaultAnnotation</command></term>
2148     <listitem>
2149       <command>[Target]</command> Type, Package
2150     </listitem>
2151     <listitem>
2152       <variablelist>
2153         <varlistentry>
2154           <term><command>[Parameter]</command></term>
2155           <listitem>
2156             <para>
2157               <command>value:</command>Annotation class objects. More than one class can be specified.
2158             </para>
2159           </listitem>
2160           <listitem>
2161             <para>
2162               <command>priority:</command>Default priority(HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM.
2163             </para>
2164           </listitem>
2165         </varlistentry>
2166       </variablelist>
2167     </listitem>
2168     <listitem>
2169       <para>
2170 Indicates that all members of the class or package should be annotated with the default
2171 value of the supplied annotation classes. This would be used for behavior annotations
2172 such as @NonNull, @CheckForNull, or @CheckReturnValue. In particular, you can use
2173 @DefaultAnnotation(NonNull.class) on a class or package, and then use @Nullable only
2174 on those parameters, methods or fields that you want to allow to be null.
2175       </para>
2176     </listitem>
2177   </varlistentry>
2178
2179   <varlistentry>
2180     <term><command>edu.umd.cs.findbugs.annotations.DefaultAnnotationForFields</command></term>
2181     <listitem>
2182       <command>[Target]</command> Type, Package
2183     </listitem>
2184     <listitem>
2185       <variablelist>
2186         <varlistentry>
2187           <term><command>[Parameter]</command></term>
2188           <listitem>
2189             <para>
2190               <command>value:</command>Annotation class objects. More than one class can be specified.
2191             </para>
2192           </listitem>
2193           <listitem>
2194             <para>
2195               <command>priority:</command>Default priority(HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM.
2196             </para>
2197           </listitem>
2198         </varlistentry>
2199       </variablelist>
2200     </listitem>
2201     <listitem>
2202       <para>
2203 This is same as the DefaultAnnotation except it only applys to fields.
2204       </para>
2205     </listitem>
2206   </varlistentry>
2207
2208   <varlistentry>
2209     <term><command>edu.umd.cs.findbugs.annotations.DefaultAnnotationForMethods</command></term>
2210     <listitem>
2211       <command>[Target]</command> Type, Package
2212     </listitem>
2213     <listitem>
2214       <variablelist>
2215         <varlistentry>
2216           <term><command>[Parameter]</command></term>
2217           <listitem>
2218             <para>
2219               <command>value:</command>Annotation class objects. More than one class can be specified.
2220             </para>
2221           </listitem>
2222           <listitem>
2223             <para>
2224               <command>priority:</command>Default priority(HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM.
2225             </para>
2226           </listitem>
2227         </varlistentry>
2228       </variablelist>
2229     </listitem>
2230     <listitem>
2231       <para>
2232 This is same as the DefaultAnnotation except it only applys to methods.
2233       </para>
2234     </listitem>
2235   </varlistentry>
2236
2237   <varlistentry>
2238     <term><command>edu.umd.cs.findbugs.annotations.DefaultAnnotationForParameters</command></term>
2239     <listitem>
2240       <command>[Target]</command> Type, Package
2241     </listitem>
2242     <listitem>
2243       <variablelist>
2244         <varlistentry>
2245           <term><command>[Parameter]</command></term>
2246           <listitem>
2247             <para>
2248               <command>value:</command>Annotation class objects. More than one class can be specified.
2249             </para>
2250           </listitem>
2251           <listitem>
2252             <para>
2253               <command>priority:</command>Default priority(HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM.
2254             </para>
2255           </listitem>
2256         </varlistentry>
2257       </variablelist>
2258     </listitem>
2259     <listitem>
2260       <para>
2261 This is same as the DefaultAnnotation except it only applys to method parameters.
2262       </para>
2263     </listitem>
2264   </varlistentry>
2265
2266   <varlistentry>
2267     <term><command>edu.umd.cs.findbugs.annotations.NonNull</command></term>
2268     <listitem>
2269       <command>[Target]</command> Field, Method, Parameter, Local variable
2270     </listitem>
2271     <listitem>
2272       <para>
2273 The annotated element must not be null.
2274 Annotated fields must not be null after construction has completed. Annotated methods must have non-null return values.
2275       </para>
2276     </listitem>
2277   </varlistentry>
2278
2279   <varlistentry>
2280     <term><command>edu.umd.cs.findbugs.annotations.Nullable</command></term>
2281     <listitem>
2282       <command>[Target]</command> Field, Method, Parameter, Local variable
2283     </listitem>
2284     <listitem>
2285       <para>
2286 The annotated element could be null under some circumstances. In general, this means
2287 developers will have to read the documentation to determine when a null value is
2288 acceptable and whether it is neccessary to check for a null value.
2289       </para>
2290     </listitem>
2291   </varlistentry>
2292
2293   <varlistentry>
2294     <term><command>edu.umd.cs.findbugs.annotations.OverrideMustInvoke</command></term>
2295     <listitem>
2296       <command>[Target]</command> Method
2297     </listitem>
2298     <listitem>
2299       <variablelist>
2300         <varlistentry>
2301           <term><command>[Parameter]</command></term>
2302           <listitem>
2303             <para>
2304               <command>value:</command>Specify when the super invocation should be
2305               performed (FIRST, ANYTIME, LAST). Default value:ANYTIME.
2306             </para>
2307           </listitem>
2308         </varlistentry>
2309       </variablelist>
2310     </listitem>
2311     <listitem>
2312       <para>
2313 Used to annotate a method that, if overridden, must (or should) be invoke super
2314 in the overriding method. Examples of such methods include finalize() and clone().
2315 The argument to the method indicates when the super invocation should occur:
2316 at any time, at the beginning of the overriding method, or at the end of the overriding method.
2317 (This anotation is not implmemented in FindBugs as of September 8, 2006).
2318       </para>
2319     </listitem>
2320   </varlistentry>
2321
2322   <varlistentry>
2323     <term><command>edu.umd.cs.findbugs.annotations.PossiblyNull</command></term>
2324     <listitem>
2325       <para>
2326 This annotation is deprecated. Use CheckForNull instead.
2327       </para>
2328     </listitem>
2329   </varlistentry>
2330
2331   <varlistentry>
2332     <term><command>edu.umd.cs.findbugs.annotations.SuppressWarnings</command></term>
2333     <listitem>
2334       <command>[Target]</command> Type, Field, Method, Parameter, Constructor, Local variable, Package
2335     </listitem>
2336     <listitem>
2337       <variablelist>
2338         <varlistentry>
2339           <term><command>[Parameter]</command></term>
2340           <listitem>
2341             <para>
2342               <command>value:</command>The name of the warning. More than one name can be specified.
2343             </para>
2344           </listitem>
2345           <listitem>
2346             <para>
2347               <command>justification:</command>Reason why the warning should be ignored. Default value:"".
2348             </para>
2349           </listitem>
2350         </varlistentry>
2351       </variablelist>
2352     </listitem>
2353     <listitem>
2354       <para>
2355 The set of warnings that are to be suppressed by the compiler in the annotated element.
2356 Duplicate names are permitted.  The second and successive occurrences of a name are ignored.
2357 The presence of unrecognized warning names is <emphasis>not</emphasis> an error: Compilers
2358 must ignore any warning names they do not recognize. They are, however, free to emit a
2359 warning if an annotation contains an unrecognized warning name. Compiler vendors should
2360 document the warning names they support in conjunction with this annotation type. They
2361 are encouraged to cooperate to ensure that the same names work across multiple compilers.
2362       </para>
2363     </listitem>
2364   </varlistentry>
2365
2366   <varlistentry>
2367     <term><command>edu.umd.cs.findbugs.annotations.UnknownNullness</command></term>
2368     <listitem>
2369       <command>[Target]</command> Field, Method, Parameter, Local variable
2370     </listitem>
2371     <listitem>
2372       <para>
2373 Used to indicate that the nullness of the target is unknown, or my vary in unknown ways in subclasses.
2374       </para>
2375     </listitem>
2376   </varlistentry>
2377
2378   <varlistentry>
2379     <term><command>edu.umd.cs.findbugs.annotations.UnknownNullness</command></term>
2380     <listitem>
2381       <command>[Target]</command> Field, Method, Parameter, Local variable
2382     </listitem>
2383     <listitem>
2384       <para>
2385 Used to indicate that the nullness of the target is unknown, or my vary in unknown ways in subclasses.
2386       </para>
2387     </listitem>
2388   </varlistentry>
2389 </variablelist>
2390
2391 <para>
2392  &FindBugs; also supports the following annotations:
2393 <itemizedlist>
2394   <listitem>net.jcip.annotations.GuardedBy</listitem>
2395   <listitem>net.jcip.annotations.Immutable</listitem>
2396   <listitem>net.jcip.annotations.NotThreadSafe</listitem>
2397   <listitem>net.jcip.annotations.ThreadSafe</listitem>
2398 </itemizedlist>
2399 </para>
2400 <para>
2401 You can refer the JCIP annotation <ulink url="http://jcip.net/annotations/doc/index.html">
2402 API documentation</ulink> at <ulink url="http://jcip.net/">Java Concurrency in Practice</ulink>.
2403 </para>
2404 </chapter>
2405
2406 <!--
2407    **************************************************************************
2408    Using rejarForAnalysis
2409    **************************************************************************
2410 -->
2411
2412 <chapter>
2413 <title>Using rejarForAnalysis</title>
2414
2415 <para>
2416 If your project consists of many jarfiles or the jarfiles are scattered
2417 over many directories, you may wish to use the <command>rejarForAnalysis
2418 </command> script to make
2419 FindBugs invocation easier.  The script collects many jarfiles and combines them
2420 into a single, large jarfile that can then be easily passed to FindBugs for
2421 analysis.  This can be particularly useful in combination with the 'find' command
2422 on unix systems; e.g. <command>find . -name '*.jar' | xargs rejarForAnalysis
2423 </command>.
2424 </para>
2425
2426 <para>
2427 The <command>rejarForAnalysis</command> script
2428 can also be used to split a very large project up into a set of jarfiles with
2429 the project classfiles evenly divided between them.  This is useful when running
2430 FindBugs on the entire project is not practical due to time or memory consumption.
2431 Instead of running FindBugs on the entire project, you may use <command>
2432 rejarForAnalysis</command> build one large, all-inclusive jarfile
2433 containing all classes, invoke <command>rejarForAnalysis</command>
2434 again to split the project into multiple jarfiles, then run FindBugs
2435 on each divided jarfiles in turn, specifying the the all-inclusive jarfile in
2436 the <command>-auxclasspath</command>.
2437 </para>
2438
2439 <para>
2440 These are the options accepted by the <command>rejarForAnalysis</command> script:
2441 </para>
2442
2443 <variablelist>
2444   <varlistentry>
2445     <term><command>-maxAge</command> <replaceable>days</replaceable></term>
2446     <listitem>
2447        <para>
2448        Maximum age in days (ignore jar files older than this).
2449        </para>
2450     </listitem>
2451   </varlistentry>
2452   <varlistentry>
2453     <term><command>-inputFileList</command> <replaceable>filename</replaceable></term>
2454     <listitem>
2455        <para>
2456        Text file containing names of jar files.
2457        </para>
2458     </listitem>
2459   </varlistentry>
2460   <varlistentry>
2461     <term><command>-maxClasses</command> <replaceable>num</replaceable></term>
2462     <listitem>
2463        <para>
2464        Maximum number of classes per analysis*.jar file.
2465        </para>
2466     </listitem>
2467   </varlistentry>
2468   <varlistentry>
2469     <term><command>-prefix</command> <replaceable>class name prefix</replaceable></term>
2470     <listitem>
2471        <para>
2472        Prefix of class names that should be analyzed (e.g., edu.umd.cs.).
2473        </para>
2474     </listitem>
2475   </varlistentry>
2476 </variablelist>
2477 </chapter>
2478
2479 <!--
2480    **************************************************************************
2481    Data mining
2482    **************************************************************************
2483 -->
2484
2485 <chapter id="datamining">
2486         <title>Data mining of bugs with &FindBugs;&trade;</title>
2487
2488 <para>
2489 FindBugs incorporates an ability to perform sophisticated queries on bug
2490 databases and track warnings across multiple versions of code being
2491 studied, allowing you to do things such as seeing when a bug was first introduced, examining
2492 just the warnings that have been introduced since the last release, or graphing the number
2493 of infinite recursive loops in your code over time.</para>
2494
2495 <para>
2496 These techniques all depend upon the XML format used by FindBugs for storing warnings.
2497 These XML files usually contain just the warnings from one particular analysis run, but
2498 they can also store the results from analyzing a sequence of software builds or versions.
2499         </para>
2500
2501 <para>
2502 Any FindBugs XML bug database contains a version name and timestamp.
2503 FindBugs tries to compute a timestamp from the timestamps of the files that
2504 are analyzed (e.g., the timestamp is intended to be the time the class files
2505 were generated, not analyzed). Each bug database also contains a version name.
2506 Both the version name and timestamp can be set manually using the
2507 <command>setBugDatabaseInfo</command> (<xref linkend="setBugDatabaseInfo" />) command.
2508         </para>
2509
2510 <para>A multiversion bug database assigns a sequence number to each version of
2511 the analyzed code. These sequence numbers are simply successive integers,
2512 starting at 0 (e.g., a bug database for 4 versions of the code will contain
2513 versions 0..3). The bug database will also record the name and timestamp for
2514 each version. The <command>filterBugs</command> command allows you to refer
2515 to a version by sequence number, name or timestamp.</para>
2516
2517 <para>
2518 You can take a sequence (or pair) of single version bug databases and create
2519 from them a multiversion bug database, or combine a multiversion bug database
2520 with a sequence of later single-version bug databases.</para>
2521
2522 <para>
2523 Some of these commands can be invoked as ant tasks.  See below for specifics
2524 on how to invoke them and what attributes and arguments they take.  All of
2525 the examples assume that the <literal>findbugs.lib</literal>
2526 <literal>refid</literal> is set correctly.  Here is one way to set it:
2527 </para>
2528
2529 <programlisting>
2530 <![CDATA[
2531    <!-- findbugs task definition -->
2532    <property name="findbugs.home" value="/your/path/to/findbugs" />
2533    <path id="findbugs.lib">
2534       <fileset dir="${findbugs.home}/lib">
2535          <include name="findbugs-ant.jar"/>
2536       </fileset>
2537    </path>
2538 ]]>
2539 </programlisting>
2540
2541         <sect1 id="commands">
2542                 <title>Commands</title>
2543
2544                 <para>
2545 All tools for FindBugs data mining are can be invoked from the command line,
2546 and some of the more useful tools can also be invoked from an
2547 ant build file.</para>
2548
2549 <para>
2550 Briefly, the command-line tools are:</para>
2551
2552                 <variablelist>
2553                         <varlistentry>
2554                                 <term><command><link linkend="unionBugs">unionBugs</link></command></term>
2555                                 <listitem>
2556                                         <para>
2557                                                  combine the results from separate analysis of disjoint
2558                 classes
2559                                         </para>
2560                                 </listitem>
2561                         </varlistentry>
2562                         <varlistentry>
2563                                 <term><command><link linkend="computeBugHistory">computeBugHistory</link></command></term>
2564                                 <listitem>
2565                                         <para>Merge bug warnings from multiple versions of
2566                         analyzed code into
2567                         a single multiversion bug database. This can either be used
2568                         to add more versions to an existing multiversion database,
2569                         or to create a multiversion database from a sequence of single version
2570                         bug warning databases.</para>
2571                                 </listitem>
2572                         </varlistentry>
2573                         <varlistentry>
2574                                 <term><command><link linkend="setBugDatabaseInfo">setBugDatabaseInfo</link></command></term>
2575                                 <listitem>
2576                                         <para>Set information such as the revision name or
2577 timestamp in an XML bug database</para>
2578                                 </listitem>
2579                         </varlistentry>
2580                         <varlistentry>
2581                                 <term><command><link linkend="listBugDatabaseInfo">listBugDatabaseInfo</link></command></term>
2582                                 <listitem>
2583                                         <para>List information such as the revision name and
2584 timestamp for a list of XML bug databases</para>
2585                                 </listitem>
2586                         </varlistentry>
2587                         <varlistentry>
2588                                 <term><command><link linkend="filterBugs">filterBugs</link></command></term>
2589                                 <listitem>
2590                                         <para>Select a subset of a bug database</para>
2591                                 </listitem>
2592                         </varlistentry>
2593                         <varlistentry>
2594                                 <term><command><link linkend="mineBugHistory">mineBugHistory</link></command></term>
2595                                 <listitem>
2596                                         <para>Generate a tabular listing of the number of warnings in each
2597                 version of a multiversion bug database</para>
2598                                 </listitem>
2599                         </varlistentry>
2600                         <varlistentry>
2601                                 <term><command><link linkend="defectDensity">defectDensity</link></command></term>
2602                                 <listitem>
2603                                         <para>List information about defect density
2604                                                  (warnings per 1000 NCSS)
2605                                                  for the entire project and each class and package</para>
2606                                 </listitem>
2607                         </varlistentry>
2608                         <varlistentry>
2609                                 <term><command><link linkend="convertXmlToText">convertXmlToText</link></command></term>
2610                                 <listitem>
2611                                         <para>Convert bug warnings in XML format to
2612                                         a textual one-line-per-bug format, or to HTML</para>
2613                                 </listitem>
2614                         </varlistentry>
2615                 </variablelist>
2616
2617
2618                 <sect2 id="unionBugs">
2619                         <title>unionBugs</title>
2620
2621                 <para>
2622                 If you have, for example, separately analyzing each jar file used in an application,
2623                 you can use this command to combine the separately generated xml bug warning files into
2624                 a single file containing all of the warnings.</para>
2625
2626                         <para>Do <emphasis>not</emphasis> use this command to combine results from analyzing different versions of the same
2627                         file; use <command>computeBugHistory</command> instead.</para>
2628
2629                         <para>Specify the xml files on the command line. The result is sent to standard output.</para>
2630                 </sect2>
2631
2632                 <sect2 id="computeBugHistory">
2633                         <title>computeBugHistory</title>
2634
2635 <para>Use this command to generate a bug database containing information from different builds or versions
2636 of software you are analyzing.
2637 History is taken from the first file provided as input; any following
2638 files should be single version bug databases (if they contain history, the history in those
2639 files will be ignored).</para>
2640 <para>By default, output is written to the standard output.
2641 </para>
2642
2643 <para>This functionality may also can be accessed from ant.
2644 First create a taskdef for <command>computeBugHistory</command> in your
2645 build file:
2646 </para>
2647
2648 <programlisting>
2649 <![CDATA[
2650 <taskdef name="computeBugHistory" classname="edu.umd.cs.findbugs.anttask.ComputeBugHistoryTask">
2651     <classpath refid="findbugs.lib" />
2652 </taskdef>
2653 ]]>
2654 </programlisting>
2655
2656 <para>Attributes for this ant task are listed in the following table.
2657 To specify input files, nest them inside with a
2658 <literal>&lt;datafile&gt;</literal> element.  For example:
2659 </para>
2660
2661 <programlisting>
2662 <![CDATA[
2663 <computeBugHistory home="${findbugs.home}" ...>
2664     <datafile name="analyze1.xml"/>
2665     <datafile name="analyze2.xml"/>
2666 </computeBugHistory>
2667 ]]>
2668 </programlisting>
2669
2670                 <table id="computeBugHistoryTable">
2671                         <title>Options for computeBugHistory command</title>
2672                         <tgroup cols="3" align="left">
2673                                 <thead>
2674                                 <row>
2675                                         <entry>Command-line option</entry>
2676                                         <entry>Ant attribute</entry>
2677                                         <entry>Meaning</entry>
2678                                 </row>
2679                                         </thead>
2680                                 <tbody>
2681 <row><entry>-output &lt;file&gt;</entry>           <entry>output="&lt;file&gt;"</entry>           <entry>save output in the named file (may also be an input file)</entry></row>
2682 <row><entry>-overrideRevisionNames[:truth]</entry> <entry>overrideRevisionNames="[true|false]"</entry><entry>override revision names for each version with names computed from the filenames</entry></row>
2683 <row><entry>-noPackageMoves[:truth]</entry>        <entry>noPackageMoves="[true|false]"</entry><entry>if a class has moved to another package, treat warnings in that class as seperate</entry></row>
2684 <row><entry>-preciseMatch[:truth]</entry>          <entry>preciseMatch="[true|false]"</entry><entry>require bug patterns to match precisely</entry></row>
2685 <row><entry>-precisePriorityMatch[:truth]</entry>  <entry>precisePriorityMatch="[true|false]"</entry><entry>consider two warnings as the same only if priorities match exactly</entry></row>
2686 <row><entry>-quiet[:truth]</entry>                 <entry>quiet="[true|false]"</entry><entry>don't generate any output to standard out unless there is an error</entry></row>
2687 <row><entry>-withMessages[:truth]</entry>          <entry>withMessages="[true|false]"</entry><entry>include human-readable messages describing the warnings in XML output</entry></row>
2688                                 </tbody>
2689                         </tgroup>
2690                 </table>
2691
2692                 </sect2>
2693                 <sect2 id="filterBugs">
2694                         <title>filterBugs</title>
2695 <para>This command is used to select a subset of warnings from a FindBugs XML warning file
2696 and write the selected subset to a new FindBugs warning file.</para>
2697 <para>
2698 This command takes a sequence of options, and either zero, one or two
2699 filenames of findbugs xml bug files on the command line.</para>
2700 <para>If no file names are provided, the command reads from standard input
2701 and writes to standard output. If one file name is provided,
2702 it reads from the file and writes to standard output.
2703 If two file names are provided, it reads from the first and writes the output
2704 to the second file name.</para>
2705
2706 <para>This functionality may also can be accessed from ant.
2707 First create a taskdef for <command>filterBugs</command> in your
2708 build file:
2709 </para>
2710
2711 <programlisting>
2712 <![CDATA[
2713 <taskdef name="filterBugs" classname="edu.umd.cs.findbugs.anttask.FilterBugsTask">
2714     <classpath refid="findbugs.lib" />
2715 </taskdef>
2716 ]]>
2717 </programlisting>
2718
2719 <para>Attributes for this ant task are listed in the following table.
2720 To specify an input file either use the input attribute or nest it inside
2721 the ant call with a <literal>&lt;datafile&gt;</literal> element.  For example:
2722 </para>
2723
2724 <programlisting>
2725 <![CDATA[
2726 <filterBugs home="${findbugs.home}" ...>
2727     <datafile name="analyze.xml"/>
2728 </filterBugs>
2729 ]]>
2730 </programlisting>
2731
2732                 <table id="filterOptionsTable">
2733                         <title>Options for filterBugs command</title>
2734                         <tgroup cols="3" align="left">
2735                                 <thead>
2736                                 <row>
2737                                         <entry>Command-line option</entry>
2738                                         <entry>Ant attribute</entry>
2739                                         <entry>Meaning</entry>
2740                                 </row>
2741                                         </thead>
2742                                 <tbody>
2743 <row><entry></entry>                            <entry>input="&lt;file&gt;"</entry>             <entry>use file as input</entry></row>
2744 <row><entry></entry>                            <entry>output="&lt;file&gt;"</entry>            <entry>output results to file</entry></row>
2745 <row><entry>-not</entry>                        <entry>not="[true|false]"</entry>               <entry>reverse (all) switches for the filter</entry></row>
2746 <row><entry>-withSource[:truth]</entry>         <entry>withSource="[true|false]"</entry>        <entry>only warnings for switch source is available</entry></row>
2747 <row><entry>-exclude &lt;filter file&gt;</entry><entry>exclude="&lt;filter file&gt;"</entry>    <entry>exclude bugs matching given filter</entry></row>
2748 <row><entry>-include &lt;filter file&gt;</entry><entry>include="&lt;filter file&gt;"</entry>    <entry>include only bugs matching given filter</entry></row>
2749 <row><entry>-annotation &lt;text&gt;</entry>    <entry>annotation="&lt;text&gt;"</entry>        <entry>allow only warnings containing this text in a manual annotation</entry></row>
2750 <row><entry>-after &lt;when&gt;</entry>         <entry>after="&lt;when&gt;"</entry>             <entry>allow only warnings that first occurred after this version</entry></row>
2751 <row><entry>-before &lt;when&gt;</entry>        <entry>before="&lt;when&gt;"</entry>            <entry>allow only warnings that first occurred before this version</entry></row>
2752 <row><entry>-first &lt;when&gt;</entry>         <entry>first="&lt;when&gt;"</entry>             <entry>allow only warnings that first occurred in this version</entry></row>
2753 <row><entry>-last &lt;when&gt;</entry>          <entry>last="&lt;when&gt;"</entry>              <entry>allow only warnings that last occurred in this version</entry></row>
2754 <row><entry>-fixed &lt;when&gt;</entry>         <entry>fixed="&lt;when&gt;"</entry>             <entry>allow only warnings that last occurred in the previous version (clobbers <option>-last</option>)</entry></row>
2755 <row><entry>-present &lt;when&gt;</entry>       <entry>present="&lt;when&gt;"</entry>           <entry>allow only warnings present in this version</entry></row>
2756 <row><entry>-absent &lt;when&gt;</entry>        <entry>absent="&lt;when&gt;"</entry>            <entry>allow only warnings absent in this version</entry></row>
2757 <row><entry>-active[:truth]</entry>             <entry>active="[true|false]"</entry>            <entry>allow only warnings alive in the last sequence number</entry></row>
2758 <row><entry>-introducedByChange[:truth]</entry> <entry>introducedByChange="[true|false]"</entry><entry>allow only warnings introduced by a change of an existing class</entry></row>
2759 <row><entry>-removedByChange[:truth]</entry>    <entry>removedByChange="[true|false]"</entry>   <entry>allow only warnings removed by a change of a persisting class</entry></row>
2760 <row><entry>-newCode[:truth]</entry>            <entry>newCode="[true|false]"</entry>           <entry>allow only warnings introduced by the addition of a new class</entry></row>
2761 <row><entry>-removedCode[:truth]</entry>        <entry>removedCode="[true|false]"</entry>       <entry>allow only warnings removed by removal of a class</entry></row>
2762 <row><entry>-priority &lt;level&gt;</entry>     <entry>priority="&lt;level&gt;"</entry>         <entry>allow only warnings with this priority or higher</entry></row>
2763 <row><entry>-class &lt;pattern&gt;</entry>      <entry>class="&lt;class&gt;"</entry>            <entry>allow only bugs whose primary class name matches this pattern</entry></row>
2764 <row><entry>-bugPattern &lt;pattern&gt;</entry> <entry>bugPattern="&lt;pattern&gt;"</entry>     <entry>allow only bugs whose type matches this pattern</entry></row>
2765 <row><entry>-category &lt;category&gt;</entry>  <entry>category="&lt;category&gt;"</entry>      <entry>allow only warnings with a category that starts with this string</entry></row>
2766 <row><entry>-designation &lt;designation&gt;</entry> <entry>designation="&lt;designation&gt;"</entry> <entry>allow only warnings with this designation (e.g., -designation SHOULD_FIX)</entry></row>
2767 <row><entry>-withMessages[:truth] </entry>      <entry>withMessages="[true|false]"</entry>      <entry>the generated XML should contain textual messages</entry></row>
2768                                 </tbody>
2769                         </tgroup>
2770                 </table>
2771
2772                 </sect2>
2773
2774                 <sect2 id="mineBugHistory">
2775                         <title>mineBugHistory</title>
2776 <para>This command generates a table containing counts of the numbers of warnings
2777 in each version of a multiversion bug database.</para>
2778
2779
2780 <para>This functionality may also can be accessed from ant.
2781 First create a taskdef for <command>mineBugHistory</command> in your
2782 build file:
2783 </para>
2784
2785 <programlisting>
2786 <![CDATA[
2787 <taskdef name="mineBugHistory" classname="edu.umd.cs.findbugs.anttask.MineBugHistoryTask">
2788     <classpath refid="findbugs.lib" />
2789 </taskdef>
2790 ]]>
2791 </programlisting>
2792
2793 <para>Attributes for this ant task are listed in the following table.
2794 To specify an input file either use the <literal>input</literal>
2795 attribute or nest it inside the ant call with a
2796 <literal>&lt;datafile&gt;</literal> element.  For example:
2797 </para>
2798
2799 <programlisting>
2800 <![CDATA[
2801 <mineBugHistory home="${findbugs.home}" ...>
2802     <datafile name="analyze.xml"/>
2803 </mineBugHistory>
2804 ]]>
2805 </programlisting>
2806
2807                 <table id="mineBugHistoryOptionsTable">
2808                         <title>Options for mineBugHistory command</title>
2809                         <tgroup cols="3" align="left">
2810                                 <thead>
2811                                 <row>
2812                                         <entry>Command-line option</entry>
2813                                         <entry>Ant attribute</entry>
2814                                         <entry>Meaning</entry>
2815                                 </row>
2816                                 </thead>
2817                                 <tbody>
2818 <row><entry></entry>               <entry>input="&lt;file&gt;"</entry>             <entry>use file as input</entry></row>
2819 <row><entry></entry>               <entry>output="&lt;file&gt;"</entry>            <entry>write output to file</entry></row>
2820 <row><entry>-formatDates</entry>   <entry>formatDates="[true|false]"</entry>       <entry>render dates in textual form</entry></row>
2821 <row><entry>-noTabs</entry>        <entry>noTabs="[true|false]"</entry>            <entry>delimit columns with groups of spaces instead of tabs (see below)</entry></row>
2822 <row><entry>-summary</entry>       <entry>summary="[true|false]"</entry>           <entry>output terse summary of changes over the last ten entries</entry></row>
2823                                 </tbody>
2824                         </tgroup>
2825                 </table>
2826
2827                 <para>
2828                 The <option>-noTabs</option> output can be easier to read from a shell
2829                 with a fixed-width font.
2830                 Because numeric columns are right-justified, spaces may precede the
2831                 first column value. This option also causes <option>-formatDates</option>
2832                 to render dates in terser format without embedded whitespace.
2833                 </para>
2834
2835                 <para>The table is a tab-separated (barring <option>-noTabs</option>)
2836                 table with the following columns:</para>
2837
2838                 <table id="mineBugHistoryColumns">
2839                         <title>Columns in mineBugHistory output</title>
2840                         <tgroup cols="2" align="left">
2841                                 <thead>
2842                                 <row>
2843                                         <entry>Title</entry>
2844                                         <entry>Meaning</entry>
2845                                 </row>
2846                                         </thead>
2847                                 <tbody>
2848                                           <row><entry>seq</entry><entry>Sequence number (successive integers, starting at 0)</entry></row>
2849                                           <row><entry>version</entry><entry>Version name</entry></row>
2850                                           <row><entry>time</entry><entry>Release timestamp</entry></row>
2851                                           <row><entry>classes</entry><entry>Number of classes analyzed</entry></row>
2852                                           <row><entry>NCSS</entry><entry>Non Commenting Source Statements</entry></row>
2853                                           <row><entry>added</entry><entry>Count of new warnings for a class that existed in the previous version</entry></row>
2854                                           <row><entry>newCode</entry><entry>Count of new warnings for a class that did not exist in the previous version</entry></row>
2855                                           <row><entry>fixed</entry><entry>Count of warnings removed from a class that remains in the current version</entry></row>
2856                                           <row><entry>removed</entry><entry>Count of warnings in the previous version for a class that is not present in the current version</entry></row>
2857                                           <row><entry>retained</entry><entry>Count of warnings that were in both the previous and current version</entry></row>
2858                                           <row><entry>dead</entry><entry>Warnings that were present in earlier versions but in neither the current version or the immediately preceeding version</entry></row>
2859                                           <row><entry>active</entry><entry>Total warnings present in the current version</entry></row>
2860                                 </tbody>
2861                                 </tgroup>
2862                 </table>
2863                 </sect2>
2864
2865                 <sect2 id="defectDensity">
2866                         <title>defectDensity</title>
2867 <para>
2868 This command lists information about defect density (warnings per 1000 NCSS) for the entire project and each class and package.
2869 In can either be invoked with no files specified on the command line (in which case it reads from standard input)
2870 or with one file specified on the command line.</para>
2871 <para>It generates a table with the following columns, and with one
2872 row for the entire project, and one row for each package or class that contains at least
2873 4 warnings.</para>
2874                 <table id="defectDensityColumns">
2875                         <title>Columns in defectDensity output</title>
2876                         <tgroup cols="2" align="left">
2877                                 <thead>
2878                                 <row>
2879                                         <entry>Title</entry>
2880                                         <entry>Meaning</entry>
2881                                 </row>
2882                                         </thead>
2883                                 <tbody>
2884                                           <row><entry>kind</entry><entry>project, package or class</entry></row>
2885                                           <row><entry>name</entry><entry>The name of the project, package or class</entry></row>
2886                                           <row><entry>density</entry><entry>Number of warnings generated per 1000 lines of NCSS.</entry></row>
2887                                           <row><entry>bugs</entry><entry>Number of warnings</entry></row>
2888                                           <row><entry>NCSS</entry><entry>Calculated number of NCSS</entry></row>
2889                                 </tbody>
2890                                 </tgroup>
2891                         </table>
2892                 </sect2>
2893
2894                 <sect2 id="convertXmlToText">
2895                         <title>convertXmlToText</title>
2896
2897                         <para>
2898                                 This command converts a warning collection in XML format to a text
2899                                 format with one line per warning, or to HTML.
2900                         </para>
2901
2902 <para>This functionality may also can be accessed from ant.
2903 First create a taskdef for <command>convertXmlToText</command> in your
2904 build file:
2905 </para>
2906
2907 <programlisting>
2908 <![CDATA[
2909 <taskdef name="convertXmlToText" classname="edu.umd.cs.findbugs.anttask.ConvertXmlToTextTask">
2910     <classpath refid="findbugs.lib" />
2911 </taskdef>
2912 ]]>
2913 </programlisting>
2914
2915 <para>Attributes for this ant task are listed in the following table.</para>
2916
2917                         <table id="convertXmlToTextTable">
2918                         <title>Options for convertXmlToText command</title>
2919                         <tgroup cols="3" align="left">
2920                                 <thead>
2921                                 <row>
2922                                         <entry>Command-line option</entry>
2923                                         <entry>Ant attribute</entry>
2924                                         <entry>Meaning</entry>
2925                                 </row>
2926                                         </thead>
2927                                 <tbody>
2928 <row><entry></entry>                   <entry>input="&lt;filename&gt;"</entry>         <entry>use file as input</entry></row>
2929 <row><entry></entry>                   <entry>output="&lt;filename&gt;"</entry>        <entry>output results to file</entry></row>
2930 <row><entry>-longBugCodes</entry>      <entry>longBugCodes="[true|false]"</entry>      <entry>use the full bug pattern code instead of two-letter abbreviation</entry></row>
2931 <row><entry>-html[:stylesheet]</entry> <entry>format="html:&lt;stylesheet&gt;"</entry> <entry>generate output with specified stylesheet (see below), or default.xsl if unspecified</entry></row>
2932                                 </tbody>
2933                         </tgroup>
2934                     </table>
2935
2936                         <para>
2937                         You may specify plain.xsl, default.xsl, fancy.xsl, fancy-hist.xsl,
2938                         or your own XSL stylesheet for the -html/format option.
2939                         Despite the name of this option, you may specify
2940                         a stylesheet that emits something other than html.
2941                         </para>
2942                 </sect2>
2943
2944                 <sect2 id="setBugDatabaseInfo">
2945                         <title>setBugDatabaseInfo</title>
2946
2947                         <para>
2948                                 This command sets meta-information in a specified warning collection.
2949                                 It takes the following options:
2950                         </para>
2951
2952 <para>This functionality may also can be accessed from ant.
2953 First create a taskdef for <command>setBugDatabaseInfo</command> in your
2954 build file:
2955 </para>
2956
2957 <programlisting>
2958 <![CDATA[
2959 <taskdef name="setBugDatabaseInfo" classname="edu.umd.cs.findbugs.anttask.SetBugDatabaseInfoTask">
2960     <classpath refid="findbugs.lib" />
2961 </taskdef>
2962 ]]>
2963 </programlisting>
2964
2965 <para>Attributes for this ant task are listed in the following table.
2966 To specify an input file either use the <literal>input</literal>
2967 attribute or nest it inside the ant call with a
2968 <literal>&lt;datafile&gt;</literal> element.  For example:
2969 </para>
2970
2971 <programlisting>
2972 <![CDATA[
2973 <setBugDatabaseInfo home="${findbugs.home}" ...>
2974     <datafile name="analyze.xml"/>
2975 </setBugDatabaseInfo>
2976 ]]>
2977 </programlisting>
2978
2979                 <table id="setBugDatabaseInfoOptions">
2980                         <title>setBugDatabaseInfo Options</title>
2981                         <tgroup cols="3" align="left">
2982                                 <thead>
2983                                 <row>
2984                                         <entry>Command-line option</entry>
2985                                         <entry>Ant attribute</entry>
2986                                         <entry>Meaning</entry>
2987                                 </row>
2988                                 </thead>
2989                                 <tbody>
2990                                           <row><entry></entry>                              <entry>input="&lt;file&gt;"</entry>           <entry>use file as input</entry></row>
2991                                           <row><entry></entry>                              <entry>output="&lt;file&gt;"</entry>          <entry>write output to file</entry></row>
2992                                           <row><entry>-name &lt;name&gt;</entry>            <entry>name="&lt;name&gt;"</entry>            <entry>set name for (last) revision</entry></row>
2993                                           <row><entry>-timestamp &lt;when&gt;</entry>       <entry>timestamp="&lt;when&gt;"</entry>       <entry>set timestamp for (last) revision</entry></row>
2994                                           <row><entry>-source &lt;directory&gt;</entry>     <entry>source="&lt;directory&gt;"</entry>     <entry>add specified directory to the source search path</entry></row>
2995                                           <row><entry>-findSource &lt;directory&gt;</entry> <entry>findSource="&lt;directory&gt;"</entry> <entry>find and add all relevant source directions contained within specified directory</entry></row>
2996                                           <row><entry>-suppress &lt;filter file&gt;</entry> <entry>suppress="&lt;filter file&gt;"</entry> <entry>suppress warnings matched by this file (replaces previous suppressions)</entry></row>
2997                                           <row><entry>-withMessages</entry>                 <entry>withMessages="[true|false]"</entry>    <entry>add textual messages to XML</entry></row>
2998                                           <row><entry>-resetSource</entry>                  <entry>resetSource="[true|false]"</entry>     <entry>remove all source search paths</entry></row>
2999                                 </tbody>
3000                                 </tgroup>
3001                         </table>
3002                 </sect2>
3003
3004                 <sect2 id="listBugDatabaseInfo">
3005                         <title>listBugDatabaseInfo</title>
3006
3007                         <para>This command takes a list of zero or more xml bug database filenames on the command line.
3008 If zero file names are provided, it reads from standard input and does not generate
3009 a table header.</para>
3010
3011 <para>There is only one option: <option>-formatDates</option> renders dates
3012         in textual form.
3013         </para>
3014
3015 <para>The output is a table one row per bug database and the following columns:</para>
3016                 <table id="listBugDatabaseInfoColumns">
3017                         <title>listBugDatabaseInfo Columns</title>
3018                         <tgroup cols="2" align="left">
3019                                 <thead>
3020                                 <row>
3021                                         <entry>Column</entry>
3022                                         <entry>Meaning</entry>
3023                                 </row>
3024                                 </thead>
3025                                 <tbody>
3026                                           <row><entry>version</entry><entry>version name</entry></row>
3027                                           <row><entry>time</entry><entry>Release timestamp</entry></row>
3028                                           <row><entry>classes</entry><entry>Number of classes analyzed</entry></row>
3029                                           <row><entry>NCSS</entry><entry>Non Commenting Source Statements analyzed</entry></row>
3030                                           <row><entry>total</entry><entry>Total number of warnings of all kinds</entry></row>
3031                                           <row><entry>high</entry><entry>Total number of high priority warnings of all kinds</entry></row>
3032                                           <row><entry>medium</entry><entry>Total number of medium/normal priority warnings of all kinds</entry></row>
3033                                           <row><entry>low</entry><entry>Total number of low priority warnings of all kinds</entry></row>
3034                                           <row><entry>filename</entry><entry>filename of database</entry></row>
3035 <!--
3036                                           <row><entry></entry><entry></entry></row>
3037                                           <row><entry></entry><entry></entry></row>
3038                                           <row><entry></entry><entry></entry></row>
3039                                           <row><entry></entry><entry></entry></row>
3040                                           <row><entry></entry><entry></entry></row>
3041                                           <row><entry></entry><entry></entry></row>
3042 -->
3043                                 </tbody>
3044                                 </tgroup>
3045                         </table>
3046
3047                 </sect2>
3048
3049         </sect1>
3050
3051         <sect1 id="examples">
3052                 <title>Examples</title>
3053 <sect2 id="unixscriptsexemples">
3054    <title>Mining history using proveded shell scrips</title>
3055 <para>In all of the following, the commands are given in a directory that contains
3056 directories jdk1.6.0-b12, jdk1.6.0-b13, ..., jdk1.6.0-b60.</para>
3057
3058 <para>You can use the command:</para>
3059 <screen>
3060 computeBugHistory jdk1.6.0-b* | filterBugs -bugPattern IL_ | mineBugHistory -formatDates
3061 </screen>
3062 <para>to generate the following output:</para>
3063
3064 <screen>
3065 seq     version time    classes NCSS    added   newCode fixed   removed retained        dead    active
3066 0       jdk1.6.0-b12    "Thu Nov 11 09:07:20 EST 2004"  13128   811569  0       4       0       0       0       0       4
3067 1       jdk1.6.0-b13    "Thu Nov 18 06:02:06 EST 2004"  13128   811570  0       0       0       0       4       0       4
3068 2       jdk1.6.0-b14    "Thu Dec 02 06:12:26 EST 2004"  13145   811786  0       0       2       0       2       0       2
3069 3       jdk1.6.0-b15    "Thu Dec 09 06:07:04 EST 2004"  13174   811693  0       0       1       0       1       2       1
3070 4       jdk1.6.0-b16    "Thu Dec 16 06:21:28 EST 2004"  13175   811715  0       0       0       0       1       3       1
3071 5       jdk1.6.0-b17    "Thu Dec 23 06:27:22 EST 2004"  13176   811974  0       0       0       0       1       3       1
3072 6       jdk1.6.0-b19    "Thu Jan 13 06:41:16 EST 2005"  13176   812011  0       0       0       0       1       3       1
3073 7       jdk1.6.0-b21    "Thu Jan 27 05:57:52 EST 2005"  13177   812173  0       0       0       0       1       3       1
3074 8       jdk1.6.0-b23    "Thu Feb 10 05:44:36 EST 2005"  13179   812188  0       0       0       0       1       3       1
3075 9       jdk1.6.0-b26    "Thu Mar 03 06:04:02 EST 2005"  13199   811770  0       0       0       0       1       3       1
3076 10      jdk1.6.0-b27    "Thu Mar 10 04:48:38 EST 2005"  13189   812440  0       0       0       0       1       3       1
3077 11      jdk1.6.0-b28    "Thu Mar 17 02:54:22 EST 2005"  13185   812056  0       0       0       0       1       3       1
3078 12      jdk1.6.0-b29    "Thu Mar 24 03:09:20 EST 2005"  13117   809468  0       0       0       0       1       3       1
3079 13      jdk1.6.0-b30    "Thu Mar 31 02:53:32 EST 2005"  13118   809501  0       0       0       0       1       3       1
3080 14      jdk1.6.0-b31    "Thu Apr 07 03:00:14 EDT 2005"  13117   809572  0       0       0       0       1       3       1
3081 15      jdk1.6.0-b32    "Thu Apr 14 02:56:56 EDT 2005"  13169   811096  0       0       0       0       1       3       1
3082 16      jdk1.6.0-b33    "Thu Apr 21 02:46:22 EDT 2005"  13187   811942  0       0       0       0       1       3       1
3083 17      jdk1.6.0-b34    "Thu Apr 28 02:49:00 EDT 2005"  13195   813488  0       1       0       0       1       3       2
3084 18      jdk1.6.0-b35    "Thu May 05 02:49:04 EDT 2005"  13457   829837  0       0       0       0       2       3       2
3085 19      jdk1.6.0-b36    "Thu May 12 02:59:46 EDT 2005"  13462   831278  0       0       0       0       2       3       2
3086 20      jdk1.6.0-b37    "Thu May 19 02:55:08 EDT 2005"  13464   831971  0       0       0       0       2       3       2
3087 21      jdk1.6.0-b38    "Thu May 26 03:08:16 EDT 2005"  13564   836565  0       0       0       0       2       3       2
3088 22      jdk1.6.0-b39    "Fri Jun 03 03:10:48 EDT 2005"  13856   849992  0       1       0       0       2       3       3
3089 23      jdk1.6.0-b40    "Thu Jun 09 03:30:28 EDT 2005"  15972   959619  0       2       0       0       3       3       5
3090 24      jdk1.6.0-b41    "Thu Jun 16 03:19:22 EDT 2005"  15972   959619  0       0       0       0       5       3       5
3091 25      jdk1.6.0-b42    "Fri Jun 24 03:38:54 EDT 2005"  15966   958581  0       0       0       0       5       3       5
3092 26      jdk1.6.0-b43    "Thu Jul 14 03:09:34 EDT 2005"  16041   960544  0       0       0       0       5       3       5
3093 27      jdk1.6.0-b44    "Thu Jul 21 03:05:54 EDT 2005"  16041   960547  0       0       0       0       5       3       5
3094 28      jdk1.6.0-b45    "Thu Jul 28 03:26:10 EDT 2005"  16037   960606  0       0       1       0       4       3       4
3095 29      jdk1.6.0-b46    "Thu Aug 04 03:02:48 EDT 2005"  15936   951355  0       0       0       0       4       4       4
3096 30      jdk1.6.0-b47    "Thu Aug 11 03:18:56 EDT 2005"  15964   952387  0       0       1       0       3       4       3
3097 31      jdk1.6.0-b48    "Thu Aug 18 08:10:40 EDT 2005"  15970   953421  0       0       0       0       3       5       3
3098 32      jdk1.6.0-b49    "Thu Aug 25 03:24:38 EDT 2005"  16048   958940  0       0       0       0       3       5       3
3099 33      jdk1.6.0-b50    "Thu Sep 01 01:52:40 EDT 2005"  16287   974937  1       0       0       0       3       5       4
3100 34      jdk1.6.0-b51    "Thu Sep 08 01:55:36 EDT 2005"  16362   979377  0       0       0       0       4       5       4
3101 35      jdk1.6.0-b52    "Thu Sep 15 02:04:08 EDT 2005"  16477   979399  0       0       0       0       4       5       4
3102 36      jdk1.6.0-b53    "Thu Sep 22 02:00:28 EDT 2005"  16019   957900  0       0       1       0       3       5       3
3103 37      jdk1.6.0-b54    "Thu Sep 29 01:54:34 EDT 2005"  16019   957900  0       0       0       0       3       6       3
3104 38      jdk1.6.0-b55    "Thu Oct 06 01:54:14 EDT 2005"  16051   959014  0       0       0       0       3       6       3
3105 39      jdk1.6.0-b56    "Thu Oct 13 01:54:12 EDT 2005"  16211   970835  0       0       0       0       3       6       3
3106 40      jdk1.6.0-b57    "Thu Oct 20 01:55:26 EDT 2005"  16279   971627  0       0       0       0       3       6       3
3107 41      jdk1.6.0-b58    "Thu Oct 27 01:56:30 EDT 2005"  16283   971945  0       0       0       0       3       6       3
3108 42      jdk1.6.0-b59    "Thu Nov 03 01:56:58 EST 2005"  16232   972193  0       0       0       0       3       6       3
3109 43      jdk1.6.0-b60    "Thu Nov 10 01:54:18 EST 2005"  16235   972346  0       0       0       0       3       6       3
3110 </screen>
3111
3112 <para>
3113 We could also generate that information directly, without creating an intermediate db.xml file, using the command
3114 </para>
3115
3116 <screen>
3117 computeBugHistory  jdk1.6.0-b*/jre/lib/rt.xml | filterBugs -bugPattern IL_ db.xml | mineBugHistory -formatDates
3118 </screen>
3119
3120 <para>We can then use that information to display a graph showing the number of infinite recursive loops
3121 found by FindBugs in each build of Sun's JDK1.6.0. The blue area indicates the number of infinite
3122 recursive loops in that build, the red area above it indicates the number of infinite recursive loops that existed
3123 in some previous version but not in the current version (thus, the combined height of the red and blue areas
3124 is guaranteed to never decrease, and goes up whenever a new infinite recursive loop bug is introduced). The height
3125 of the red area is computed as the sum of the fixed, removed and dead values for each version.
3126 The reductions in builds 13 and 14 came after Sun was notified about the bugs found by FindBugs in the JDK.
3127         </para>
3128 <mediaobject>
3129 <imageobject>
3130 <imagedata fileref="infiniteRecursiveLoops.png" />
3131 </imageobject>
3132 </mediaobject>
3133
3134 <para>
3135 Given the db.xml file that contains the results for all the jdk1.6.0 builds, the following command will show the history of high and medium priority correctness warnings:
3136 </para>
3137
3138 <screen>
3139 filterBugs -priority M -category C db.xml | mineBugHistory -formatDates
3140 </screen>
3141
3142 <para>
3143 generating the table:
3144 </para>
3145
3146 <screen>
3147 seq     version time    classes NCSS    added   newCode fixed   removed retained        dead    active
3148 0       jdk1.6.0-b12    "Thu Nov 11 09:07:20 EST 2004"  13128   811569  0       1075    0       0       0       0       1075
3149 1       jdk1.6.0-b13    "Thu Nov 18 06:02:06 EST 2004"  13128   811570  0       0       0       0       1075    0       1075
3150 2       jdk1.6.0-b14    "Thu Dec 02 06:12:26 EST 2004"  13145   811786  3       0       6       0       1069    0       1072
3151 3       jdk1.6.0-b15    "Thu Dec 09 06:07:04 EST 2004"  13174   811693  2       1       3       0       1069    6       1072
3152 4       jdk1.6.0-b16    "Thu Dec 16 06:21:28 EST 2004"  13175   811715  0       0       1       0       1071    9       1071
3153 5       jdk1.6.0-b17    "Thu Dec 23 06:27:22 EST 2004"  13176   811974  0       0       1       0       1070    10      1070
3154 6       jdk1.6.0-b19    "Thu Jan 13 06:41:16 EST 2005"  13176   812011  0       0       0       0       1070    11      1070
3155 7       jdk1.6.0-b21    "Thu Jan 27 05:57:52 EST 2005"  13177   812173  0       0       1       0       1069    11      1069
3156 8       jdk1.6.0-b23    "Thu Feb 10 05:44:36 EST 2005"  13179   812188  0       0       0       0       1069    12      1069
3157 9       jdk1.6.0-b26    "Thu Mar 03 06:04:02 EST 2005"  13199   811770  0       0       2       1       1066    12      1066
3158 10      jdk1.6.0-b27    "Thu Mar 10 04:48:38 EST 2005"  13189   812440  1       0       1       1       1064    15      1065
3159 11      jdk1.6.0-b28    "Thu Mar 17 02:54:22 EST 2005"  13185   812056  0       0       0       0       1065    17      1065
3160 12      jdk1.6.0-b29    "Thu Mar 24 03:09:20 EST 2005"  13117   809468  3       0       8       26      1031    17      1034
3161 13      jdk1.6.0-b30    "Thu Mar 31 02:53:32 EST 2005"  13118   809501  0       0       0       0       1034    51      1034
3162 14      jdk1.6.0-b31    "Thu Apr 07 03:00:14 EDT 2005"  13117   809572  0       0       0       0       1034    51      1034
3163 15      jdk1.6.0-b32    "Thu Apr 14 02:56:56 EDT 2005"  13169   811096  1       1       0       1       1033    51      1035
3164 16      jdk1.6.0-b33    "Thu Apr 21 02:46:22 EDT 2005"  13187   811942  3       0       2       1       1032    52      1035
3165 17      jdk1.6.0-b34    "Thu Apr 28 02:49:00 EDT 2005"  13195   813488  0       1       0       0       1035    55      1036
3166 18      jdk1.6.0-b35    "Thu May 05 02:49:04 EDT 2005"  13457   829837  0       36      2       0       1034    55      1070
3167 19      jdk1.6.0-b36    "Thu May 12 02:59:46 EDT 2005"  13462   831278  0       0       0       0       1070    57      1070
3168 20      jdk1.6.0-b37    "Thu May 19 02:55:08 EDT 2005"  13464   831971  0       1       1       0       1069    57      1070
3169 21      jdk1.6.0-b38    "Thu May 26 03:08:16 EDT 2005"  13564   836565  1       7       2       6       1062    58      1070
3170 22      jdk1.6.0-b39    "Fri Jun 03 03:10:48 EDT 2005"  13856   849992  6       39      5       0       1065    66      1110
3171 23      jdk1.6.0-b40    "Thu Jun 09 03:30:28 EDT 2005"  15972   959619  7       147     11      0       1099    71      1253
3172 24      jdk1.6.0-b41    "Thu Jun 16 03:19:22 EDT 2005"  15972   959619  0       0       0       0       1253    82      1253
3173 25      jdk1.6.0-b42    "Fri Jun 24 03:38:54 EDT 2005"  15966   958581  3       0       1       2       1250    82      1253
3174 26      jdk1.6.0-b43    "Thu Jul 14 03:09:34 EDT 2005"  16041   960544  5       11      15      8       1230    85      1246
3175 27      jdk1.6.0-b44    "Thu Jul 21 03:05:54 EDT 2005"  16041   960547  0       0       0       0       1246    108     1246
3176 28      jdk1.6.0-b45    "Thu Jul 28 03:26:10 EDT 2005"  16037   960606  19      0       2       0       1244    108     1263
3177 29      jdk1.6.0-b46    "Thu Aug 04 03:02:48 EDT 2005"  15936   951355  13      1       1       32      1230    110     1244
3178 30      jdk1.6.0-b47    "Thu Aug 11 03:18:56 EDT 2005"  15964   952387  163     8       7       20      1217    143     1388
3179 31      jdk1.6.0-b48    "Thu Aug 18 08:10:40 EDT 2005"  15970   953421  0       0       0       0       1388    170     1388
3180 32      jdk1.6.0-b49    "Thu Aug 25 03:24:38 EDT 2005"  16048   958940  1       11      1       0       1387    170     1399
3181 33      jdk1.6.0-b50    "Thu Sep 01 01:52:40 EDT 2005"  16287   974937  19      27      16      7       1376    171     1422
3182 34      jdk1.6.0-b51    "Thu Sep 08 01:55:36 EDT 2005"  16362   979377  1       15      3       0       1419    194     1435
3183 35      jdk1.6.0-b52    "Thu Sep 15 02:04:08 EDT 2005"  16477   979399  0       0       1       1       1433    197     1433
3184 36      jdk1.6.0-b53    "Thu Sep 22 02:00:28 EDT 2005"  16019   957900  13      12      16      20      1397    199     1422
3185 37      jdk1.6.0-b54    "Thu Sep 29 01:54:34 EDT 2005"  16019   957900  0       0       0       0       1422    235     1422
3186 38      jdk1.6.0-b55    "Thu Oct 06 01:54:14 EDT 2005"  16051   959014  1       4       7       0       1415    235     1420
3187 39      jdk1.6.0-b56    "Thu Oct 13 01:54:12 EDT 2005"  16211   970835  6       8       37      0       1383    242     1397
3188 40      jdk1.6.0-b57    "Thu Oct 20 01:55:26 EDT 2005"  16279   971627  0       0       0       0       1397    279     1397
3189 41      jdk1.6.0-b58    "Thu Oct 27 01:56:30 EDT 2005"  16283   971945  0       1       1       0       1396    279     1397
3190 42      jdk1.6.0-b59    "Thu Nov 03 01:56:58 EST 2005"  16232   972193  6       0       5       0       1392    280     1398
3191 43      jdk1.6.0-b60    "Thu Nov 10 01:54:18 EST 2005"  16235   972346  0       0       0       0       1398    285     1398
3192 44      jdk1.6.0-b61    "Thu Nov 17 01:58:42 EST 2005"  16202   971134  2       0       4       0       1394    285     1396
3193 </screen>
3194 </sect2>
3195
3196 <sect2 id="incrementalhistory">
3197         <title>Incremental history maintenance</title>
3198
3199 <para>
3200 If db.xml contains the results of running findbugs over builds b12 - b60, we can update db.xml to include the results of analyzing b61 with the commands:
3201 </para>
3202 <screen>
3203 computeBugHistory -output db.xml db.xml jdk1.6.0-b61/jre/lib/rt.xml
3204 </screen>
3205 </sect2>
3206
3207                         </sect1>
3208
3209          <sect1 id="antexemple">
3210             <title>Ant exemple</title>
3211 <para>
3212 Here is a complete ant script example for both running findbugs and running a chain of data-mining tools afterward:
3213 </para>
3214 <screen>
3215 <![CDATA[
3216 <project name="analyze_asm_util" default="findbugs">
3217    <!-- findbugs task definition -->
3218    <property name="findbugs.home" value="/Users/ben/Documents/workspace/findbugs/findbugs" />
3219    <property name="jvmargs" value="-server -Xss1m -Xmx800m -Duser.language=en -Duser.region=EN -Dfindbugs.home=${findbugs.home}" />
3220
3221         <path id="findbugs.lib">
3222       <fileset dir="${findbugs.home}/lib">
3223          <include name="findbugs-ant.jar"/>
3224       </fileset>
3225    </path>
3226
3227    <taskdef name="findbugs" classname="edu.umd.cs.findbugs.anttask.FindBugsTask">
3228       <classpath refid="findbugs.lib" />
3229    </taskdef>
3230
3231    <taskdef name="computeBugHistory" classname="edu.umd.cs.findbugs.anttask.ComputeBugHistoryTask">
3232       <classpath refid="findbugs.lib" />
3233    </taskdef>
3234
3235    <taskdef name="setBugDatabaseInfo" classname="edu.umd.cs.findbugs.anttask.SetBugDatabaseInfoTask">
3236       <classpath refid="findbugs.lib" />
3237    </taskdef>
3238
3239    <taskdef name="mineBugHistory" classname="edu.umd.cs.findbugs.anttask.MineBugHistoryTask">
3240       <classpath refid="findbugs.lib" />
3241    </taskdef>
3242
3243    <!-- findbugs task definition -->
3244    <target name="findbugs">
3245       <antcall target="analyze" />
3246       <antcall target="mine" />
3247    </target>
3248
3249    <!-- analyze task -->
3250    <target name="analyze">
3251       <!-- run findbugs against asm-util -->
3252       <findbugs home="${findbugs.home}"
3253                 output="xml:withMessages"
3254                 timeout="90000000"
3255                 reportLevel="experimental"
3256                 workHard="true"
3257                 effort="max"
3258                 adjustExperimental="true"
3259                 jvmargs="${jvmargs}"
3260                 failOnError="true"
3261                 outputFile="out.xml"
3262                 projectName="Findbugs"
3263                 debug="false">
3264          <class location="asm-util-3.0.jar" />
3265       </findbugs>
3266    </target>
3267
3268    <target name="mine">
3269
3270       <!-- Set info to the latest analysis -->
3271       <setBugDatabaseInfo home="${findbugs.home}"
3272                           withMessages="true"
3273                           name="asm-util-3.0.jar"
3274                           input="out.xml"
3275                           output="out-rel.xml"/>
3276
3277       <!-- Checking if history file already exists (findbugs-hist.xml) -->
3278       <condition property="mining.historyfile.available">
3279          <available file="out-hist.xml"/>
3280       </condition>
3281       <condition property="mining.historyfile.notavailable">
3282          <not>
3283             <available file="out-hist.xml"/>
3284          </not>
3285       </condition>
3286
3287       <!-- this target is executed if the history file do not exist (first run) -->
3288       <antcall target="history-init">
3289         <param name="data.file" value="out-rel.xml" />
3290         <param name="hist.file" value="out-hist.xml" />
3291       </antcall>
3292       <!-- else this one is executed -->
3293       <antcall target="history">
3294         <param name="data.file"         value="out-rel.xml" />
3295         <param name="hist.file"         value="out-hist.xml" />
3296         <param name="hist.summary.file" value="out-hist.txt" />
3297       </antcall>
3298    </target>
3299
3300    <!-- Initializing history file -->
3301    <target name="history-init" if="mining.historyfile.notavailable">
3302       <copy file="${data.file}" tofile="${hist.file}" />
3303    </target>
3304
3305    <!-- Computing bug history -->
3306    <target name="history" if="mining.historyfile.available">
3307       <!-- Merging ${data.file} into ${hist.file} -->
3308       <computeBugHistory home="${findbugs.home}"
3309                          withMessages="true"
3310                          output="${hist.file}">
3311           <dataFile name="${hist.file}"/>
3312           <dataFile name="${data.file}"/>
3313       </computeBugHistory>
3314
3315       <!-- Compute history into ${hist.summary.file} -->
3316       <mineBugHistory home="${findbugs.home}"
3317                       formatDates="true"
3318                       noTabs="true"
3319                       input="${hist.file}"
3320                       output="${hist.summary.file}"/>
3321    </target>
3322
3323 </project>
3324 ]]>
3325 </screen>
3326          </sect1>
3327 </chapter>
3328
3329
3330 <!--
3331    **************************************************************************
3332    License
3333    **************************************************************************
3334 -->
3335
3336 <chapter id="license">
3337 <title>License</title>
3338
3339 <para>
3340 The name FindBugs and the FindBugs logo is trademarked by the University
3341 of Maryland.
3342 FindBugs is free software distributed under the terms of the
3343 <ulink url="http://www.gnu.org/licenses/lgpl.html">Lesser GNU Public License</ulink>.
3344 You should have received a copy of the license in the file <filename>LICENSE.txt</filename>
3345 in the &FindBugs; distribution.
3346 </para>
3347
3348 <para>
3349 You can find the latest version of FindBugs, along with its source code, from the
3350 <ulink url="http://findbugs.sourceforge.net">FindBugs web page</ulink>.
3351 </para>
3352
3353 </chapter>
3354
3355
3356 <!--
3357    **************************************************************************
3358    Acknowledgments
3359    **************************************************************************
3360 -->
3361 <chapter id="acknowledgments">
3362 <title>Acknowledgments</title>
3363
3364 <sect1>
3365 <title>Contributors</title>
3366
3367 <para>&FindBugs; was originally written by Bill Pugh (<email>pugh@cs.umd.edu</email>).
3368 David Hovemeyer (<email>daveho@cs.umd.edu</email>) implemented some of the
3369 detectors, added the Swing GUI, and is a co-maintainer.</para>
3370
3371 <para>Mike Fagan (<email>mfagan@tde.com</email>) contributed the &Ant; build script,
3372 the &Ant; task, and several enhancements and bug fixes to the GUI.</para>
3373
3374 <para>Germano Leichsenring contributed Japanese translations of the bug
3375 summaries.</para>
3376
3377 <para>David Li contributed the Emacs bug report format.</para>
3378
3379 <para>Peter D. Stout contributed recursive detection of Class-Path
3380 attributes in analyzed Jar files, German translations of
3381 text used in the Swing GUI, and other fixes.</para>
3382
3383 <para>Peter Friese wrote the &FindBugs; Eclipse plugin.</para>
3384
3385 <para>Rohan Lloyd contributed several Mac OS X enhancements,
3386 bug detector improvements,
3387 and maintains the Fink package for &FindBugs;.</para>
3388
3389 <para>Hiroshi Okugawa translated the &FindBugs; manual and
3390 more of the bug summaries into Japanese.</para>
3391
3392 <para>Phil Crosby enhanced the Eclipse plugin to add a view
3393 to display the bug details.</para>
3394
3395 <para>Dave Brosius fixed a number of bugs, added user preferences
3396 to the Swing GUI, improved several bug detectors, and
3397 contributed the string concatenation detector.</para>
3398
3399 <para>Thomas Klaeger contributed a number of bug fixes and
3400 bug detector improvements.</para>
3401
3402 <para>Andrei Loskutov made a number of improvements to the
3403 Eclipse plugin.</para>
3404
3405 <para>Brian Goetz contributed a major refactoring of the
3406 visitor classes to improve readability and understandability.</para>
3407
3408 <para> Pete Angstadt fixed several problems in the Swing GUI.</para>
3409
3410 <para>Francis Lalonde provided a task resource file for the
3411 FindBugs Ant task.</para>
3412
3413 <para>Garvin LeClaire contributed support for output in
3414 Xdocs format, for use by Maven.</para>
3415
3416 <para>Holger Stenzhorn contributed improved German translations of items
3417 in the Swing GUI.</para>
3418
3419 <para>Juha Knuutila contributed Finnish translations of items
3420 in the Swing GUI.</para>
3421
3422 <para>Tanel Lebedev contributed Estonian translations of items
3423 in the Swing GUI.</para>
3424
3425 <para>Hanai Shisei (ruimo) contributed full Japanese translations of
3426 bug messages, and text used in the Swing GUI.</para>
3427
3428 <para>David Cotton contributed Fresh translations for bug
3429 messages and for the Swing GUI.</para>
3430
3431 <para>Michael Tamm contributed support for the "errorProperty" attribute
3432 in the Ant task.</para>
3433
3434 <para>Thomas Kuehne improved the German translation of the Swing GUI.</para>
3435
3436 <para>Len Trigg improved source file support for the Emacs output mode.</para>
3437
3438 <para>Greg Bentz provided a fix for the hashcode/equals detector.</para>
3439
3440 <para>K. Hashimoto contributed internationalization fixes and several other
3441         bug fixes.</para>
3442
3443 <para>
3444         Glenn Boysko contributed support for ignoring specified local
3445         variables in the dead local store detector.
3446 </para>
3447
3448 <para>
3449         Jay Dunning contributed a detector to find equality comparisons
3450         of floating-point values, and overhauled the analysis summary
3451         report and its representation in the saved XML format.
3452 </para>
3453
3454 <para>
3455         Olivier Parent contributed updated French translations for bug descriptions and
3456         Swing GUI.
3457 </para>
3458
3459 <para>
3460         Chris Nappin contributed the <filename>plain.xsl</filename>
3461         stylesheet.
3462 </para>
3463
3464 <para>
3465         Etienne Giraudy contributed the <filename>fancy.xsl</filename> and  <filename>fancy-hist.xsl</filename>
3466         stylesheets, and made improvements to the <command>-xml:withMessages</command>
3467         option.
3468 </para>
3469
3470 <para>
3471         Takashi Okamoto fixed bugs in the project preferences dialog
3472         in the Eclipse plugin, and contributed to its internationalization and localization.
3473 </para>
3474
3475 <para>Thomas Einwaller fixed bugs in the project preferences dialog in the Eclipse plugin.</para>
3476
3477 <para>Jeff Knox contributed support for the warningsProperty attribute
3478 in the Ant task.</para>
3479
3480 <para>Peter Hendriks extended the Eclipse plugin preferences,
3481 and fixed a bug related to renaming the Eclipse plugin ID.</para>
3482
3483 <para>Mark McKay contributed an Ant task to launch the findbugs frame.</para>
3484
3485 <para>Dieter von Holten (dvholten) contributed
3486 some German improvements to findbugs_de.properties.</para>
3487
3488
3489 <para>If you have contributed to &FindBugs;, but aren't mentioned above,
3490 please send email to <email>findbugs@cs.umd.edu</email> (and also accept
3491 our humble apologies).</para>
3492
3493 </sect1>
3494
3495 <sect1>
3496 <title>Software Used</title>
3497
3498 <para>&FindBugs; uses several open-source software packages, without which its
3499 development would have been much more difficult.</para>
3500
3501 <sect2>
3502 <title>BCEL</title>
3503 <para>&FindBugs; includes software developed by the Apache Software Foundation
3504 (<ulink url="http://www.apache.org/">http://www.apache.org/</ulink>).
3505 Specifically, it uses the <ulink url="http://jakarta.apache.org/bcel/">Byte Code
3506 Engineering Library</ulink>.</para>
3507 </sect2>
3508
3509 <sect2>
3510 <title>ASM</title>
3511 <para>&FindBugs; uses the <ulink url="http://asm.objectweb.org/">ASM</ulink>
3512 bytecode framework, which is distributed under the following license:</para>
3513
3514 <blockquote>
3515 <para>
3516 Copyright (c) 2000-2005 INRIA, France Telecom
3517 All rights reserved.
3518 </para>
3519
3520 <para>
3521 Redistribution and use in source and binary forms, with or without
3522 modification, are permitted provided that the following conditions
3523 are met:
3524 </para>
3525
3526 <orderedlist numeration="arabic">
3527    <listitem><para>
3528    Redistributions of source code must retain the above copyright
3529    notice, this list of conditions and the following disclaimer.
3530   </para></listitem>
3531    <listitem><para>
3532    Redistributions in binary form must reproduce the above copyright
3533    notice, this list of conditions and the following disclaimer in the
3534    documentation and/or other materials provided with the distribution.
3535   </para></listitem>
3536    <listitem><para>
3537    Neither the name of the copyright holders nor the names of its
3538    contributors may be used to endorse or promote products derived from
3539    this software without specific prior written permission.
3540   </para></listitem>
3541 </orderedlist>
3542
3543 <para>
3544 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
3545 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
3546 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
3547 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
3548 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
3549 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
3550 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
3551 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
3552 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
3553 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
3554 THE POSSIBILITY OF SUCH DAMAGE.
3555 </para>
3556 </blockquote>
3557 </sect2>
3558
3559 <sect2>
3560 <title>DOM4J</title>
3561 <para>&FindBugs; uses <ulink url="http://dom4j.org">DOM4J</ulink>, which is
3562 distributed under the following license:</para>
3563
3564 <blockquote>
3565 <para>
3566 Copyright 2001 (C) MetaStuff, Ltd. All Rights Reserved.
3567 </para>
3568
3569 <para>
3570 Redistribution and use of this software and associated documentation
3571 ("Software"), with or without modification, are permitted provided that
3572 the following conditions are met:
3573 </para>
3574
3575 <orderedlist numeration="arabic">
3576    <listitem><para>
3577    Redistributions of source code must retain copyright statements and
3578    notices. Redistributions must also contain a copy of this document.
3579   </para></listitem>
3580    <listitem><para>
3581    Redistributions in binary form must reproduce the above copyright
3582    notice, this list of conditions and the following disclaimer in the
3583    documentation and/or other materials provided with the distribution.
3584   </para></listitem>
3585    <listitem><para>
3586    The name "DOM4J" must not be used to endorse or promote products
3587    derived from this Software without prior written permission
3588    of MetaStuff, Ltd. For written permission, please contact
3589    <email>dom4j-info@metastuff.com</email>.
3590   </para></listitem>
3591    <listitem><para>
3592    Products derived from this Software may not be called "DOM4J" nor may
3593    "DOM4J" appear in their names without prior written permission of
3594    MetaStuff, Ltd. DOM4J is a registered trademark of MetaStuff, Ltd.
3595   </para></listitem>
3596    <listitem><para>
3597    Due credit should be given to the DOM4J Project (<ulink url="http://dom4j.org/">http://dom4j.org/</ulink>).
3598   </para></listitem>
3599 </orderedlist>
3600
3601 <para>
3602 THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS ``AS IS''
3603 AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
3604 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
3605 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL METASTUFF, LTD. OR ITS
3606 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
3607 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
3608 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
3609 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
3610 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
3611 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
3612 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
3613 </para>
3614 </blockquote>
3615
3616 </sect2>
3617
3618 </sect1>
3619
3620 </chapter>
3621
3622
3623 </book>