manual.xml

JSP页面代码排错

<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
                    "file:../etc/docbook/docbookx.dtd" [
<!ENTITY FindBugs "<application>FindBugs</application>">
<!ENTITY Ant "<application>Ant</application>">
<!ENTITY Saxon "<application>Saxon</application>">
<!ENTITY FBHome "<replaceable>$FINDBUGS_HOME</replaceable>">
<!ENTITY FBHomeWin "<replaceable>&#x25;FINDBUGS_HOME&#x25;</replaceable>">
<!ENTITY nbsp "&#160;">
]>
 
<book lang="en" id="findbugs-manual">
 
<bookinfo>
<title>&FindBugs;&trade; Manual</title>

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

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

<legalnotice>
<para>
This manual is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike License.
To view a copy of this license, visit
<ulink url="http://creativecommons.org/licenses/by-nc-sa/1.0/">http://creativecommons.org/licenses/by-nc-sa/1.0/</ulink>
or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.
</para>
<para>
The name FindBugs and the FindBugs logo are trademarked by the University of Maryland.
</para>
</legalnotice>

<edition>1.3.8</edition>

<pubdate>13:06:06 EDT, 15 March, 2009</pubdate>

</bookinfo>

<!--
   **************************************************************************
   Introduction
   **************************************************************************
-->
 
<chapter id="introduction">
<title>Introduction</title>

<para> &FindBugs;&trade; is a program to find bugs in Java programs.  It looks for instances
of "bug patterns" --- code instances that are likely to be errors.</para>

<para> This document describes version 1.3.8 of &FindBugs;.We
are very interested in getting your feedback on &FindBugs;. Please visit
the <ulink url="http://findbugs.sourceforge.net">&FindBugs; web page</ulink> for
the latest information on &FindBugs;, contact information, and support resources such
as information about the &FindBugs; mailing lists.</para>

<sect1>
<title>Requirements</title>
<para> To use &FindBugs;, you need a runtime environment compatible with
<ulink url="http://java.sun.com/j2se">Java 2 Standard Edition</ulink>, version 1.5 or later.
&FindBugs; is platform independent, and is known to run on GNU/Linux, Windows, and
MacOS X platforms.</para>

<para>You should have at least 512 MB of memory to use &FindBugs;.
To analyze very large projects, more memory may be needed.</para>
</sect1>
 
</chapter>

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

<chapter id="installing">
<title>Installing &FindBugs;&trade;</title>

<para>
This chapter explains how to install &FindBugs;.
</para>

<sect1>
<title>Extracting the Distribution</title>

<para>
The easiest way to install &FindBugs; is to download a binary distribution.
Binary distributions are available in
<ulink url="http://prdownloads.sourceforge.net/findbugs/findbugs-1.3.8.tar.gz?download">gzipped tar format</ulink> and
<ulink url="http://prdownloads.sourceforge.net/findbugs/findbugs-1.3.8.zip?download">zip format</ulink>.
Once you have downloaded a binary distribution, extract it into a directory of your choice.
</para>

<para>
Extracting a gzipped tar format distribution:
<screen>
<prompt>$ </prompt><command>gunzip -c findbugs-1.3.8.tar.gz | tar xvf -</command>
</screen>
</para>

<para>
Extracting a zip format distribution:
<screen>
<prompt>C:\Software></prompt><command>unzip findbugs-1.3.8.zip</command>
</screen>
</para>

<para>
Usually, extracting a binary distribution will create a directory ending in
<filename class="directory">findbugs-1.3.8</filename>. For example, if you extracted
the binary distribution from the <filename class="directory">C:\Software</filename>
directory, then the &FindBugs; software will be extracted into the directory
<filename class="directory">C:\Software\findbugs-1.3.8</filename>.
This directory is the &FindBugs; home directory.  We'll refer to it as
&FBHome; (or &FBHomeWin; for Windows) throughout this manual.
</para>
</sect1>

</chapter>

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

<chapter id="building">
<title>Building &FindBugs;&trade; from Source</title>

<para>
This chapter describes how to build &FindBugs; from source code.  Unless you are
interesting in modifying &FindBugs;, you will probably want to skip to the
<link linkend="running">next chapter</link>.
</para>

<sect1>
<title>Prerequisites</title>

<para>
To compile &FindBugs; from source, you will need the following:
<itemizedlist>
  <listitem>
    <para>
      The <ulink url="http://prdownloads.sourceforge.net/findbugs/findbugs-1.3.8-source.zip?download"
      >&FindBugs; source distribution</ulink>
    </para>
  </listitem>
  <listitem>
    <para>
      <ulink url="http://java.sun.com/j2se/">JDK 1.5.0 beta or later</ulink>
    </para>
  </listitem>
  <listitem>
    <para>
      <ulink url="http://ant.apache.org/">Apache &Ant;</ulink>, version 1.6.3 or later
    </para>
  </listitem>
</itemizedlist>
</para>

<warning>
	<para>
		The version of &Ant; included as <filename>/usr/bin/ant</filename> on
		Redhat Linux systems will <emphasis>not</emphasis> work for compiling
		&FindBugs;.  We recommend you install a binary distribution of &Ant;
		downloaded from the <ulink url="http://ant.apache.org/">&Ant; website</ulink>.
		Make sure that when you run &Ant; your <replaceable>JAVA_HOME</replaceable>
		environment variable points to the directory in which you installed
		JDK 1.5 (or later).
	</para>
</warning>

<para>
If you want to be able to generate formatted versions of the &FindBugs; documentation,
you will also need the following software:
<itemizedlist>
  <listitem>
    <para>
    The <ulink url="http://docbook.sourceforge.net/projects/xsl/index.html">DocBook XSL Stylesheets</ulink>.
    These are required to convert the &FindBugs; manual into HTML format.
    </para>
  </listitem>
  <listitem>
    <para>
      The <ulink url="http://saxon.sourceforge.net/">&Saxon; XSLT Processor</ulink>.
      (Also required for converting the &FindBugs; manual to HTML.)
    </para>
  </listitem>
<!--
  <listitem>
    <para>
    </para>
  </listitem>
-->
</itemizedlist>
</para>

</sect1>

<sect1>
<title>Extracting the Source Distribution</title>
<para>
After you download the source distribution, you'll need to extract it into
a working directory.  A typical command to do this is:

<screen>
<prompt>$ </prompt><command>unzip findbugs-1.3.8-source.zip</command>
</screen>

</para>
</sect1>

<sect1>
<title>Modifying <filename>local.properties</filename></title>
<para>
If you intend to build the FindBugs documentation,
you will need to modify the <filename>local.properties</filename> file
used by the <ulink url="http://ant.apache.org/">&Ant;</ulink>
<filename>build.xml</filename> file to build &FindBugs;.
If you do not want to build the FindBugs documentation, then you
can ignore this file.
</para>
	
<para>
The <filename>local.properties</filename> overrides definitions
in the <filename>build.properties</filename> file.
The <filename>build.properties</filename> file looks something like this:
<programlisting>
<![CDATA[
# User Configuration:
# This section must be modified to reflect your system.

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

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

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

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

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

<para>
The <varname>xsl.stylesheet.home</varname> property specifies the full
path to the directory where you have installed the
<ulink url="http://docbook.sourceforge.net/projects/xsl/">DocBook Modular XSL
Stylesheets</ulink>.  You only need to specify this property if you will be
generating the &FindBugs; documentation.
</para>

<para>
The <varname>saxon.home</varname> property is the full path to the
directory where you installed the <ulink url="http://saxon.sourceforge.net/">&Saxon; XSLT Processor</ulink>.
You only need to specify this property if you will be
generating the &FindBugs; documentation.
</para>

</sect1>

<sect1>
<title>Running &Ant;</title>

<para>
Once you have extracted the source distribution,
made sure that &Ant; is installed,
modified <filename>build.properties</filename> (optional),
and configured the tools (such as &Saxon;),
you are ready to build &FindBugs;.  Invoking &Ant; is a simple matter
of running the command
<screen>
<prompt>$ </prompt><command>ant <replaceable>target</replaceable></command>
</screen>
where <replaceable>target</replaceable> is one of the following:
<variablelist>
  <varlistentry>
    <term><command>build</command></term>
    <listitem>
       <para>
         This target compiles the code for &FindBugs;. It is the default target.
       </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><command>docs</command></term>
    <listitem>
       <para>
       This target formats the documentation.  (It also compiles some of
       the source code as a side-effect.)
       </para>
    </listitem>
  </varlistentry>
  
  <varlistentry>
	<term><command>runjunit</command></term>
	<listitem>
		<para>
			This target compiles and runs the internal JUnit tests included
			in &FindBugs;.  It will print an error message if any unit
			tests fail.
		</para>
	</listitem>
  </varlistentry>
  
  <varlistentry>
	<term><command>bindist</command></term>
	<listitem>
		<para>
			Builds a binary distribution of &FindBugs;.
			The target creates both <filename>.zip</filename> and
			<filename>.tar.gz</filename> archives.
		</para>
	</listitem>
  </varlistentry>
</variablelist>
</para>

<para>
After running an &Ant; command, you should see output similar to
the following (after some other messages regarding the tasks that
&Ant; is running):
<screen>
<computeroutput>
BUILD SUCCESSFUL
Total time: 17 seconds
</computeroutput>
</screen>
</para>

</sect1>

<sect1>
<title>Running &FindBugs;&trade; from a source directory</title>
<para>
The &Ant; build script for &FindBugs; is written such that after 
building the <command>build</command> target, the working directory
is set up just like a binary distribution.  So, the information about
running &FindBugs; in <xref linkend="running" />
applies to source distributions, too.
</para>
</sect1>

</chapter>


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

<chapter id="running">
<title>Running &FindBugs;&trade;</title>

<para>
&FindBugs; has two user interfaces: a graphical user interface (GUI) and a
command line user interface.  This chapter describes 
how to run each of these user interfaces.
</para>

	<warning>
		<para>
			This chapter is in the process of being re-written.
			The rewrite is not complete yet.
		</para>
	</warning>

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

<sect1>
	<title>Quick Start</title>
	<para>
		If you are running &FindBugs; on a  Windows system,
		double-click on the file <filename>&FBHomeWin;\lib\findbugs.jar</filename> to start the &FindBugs; GUI.
	</para>
	
	<para>
		On a Unix, Linux, or Mac OS X system, run the <filename>&FBHome;/bin/findbugs</filename>
		script, or run the command <screen>
<command>java -jar &FBHome;/lib/findbugs.jar</command></screen>
	to run the &FindBugs; GUI.
	</para>
	
	<para>
	Refer to <xref linkend="gui"/> for information on how to use the GUI.
	</para>
</sect1>

<sect1>
	
	<title>Executing &FindBugs;</title>

	<para>
		This section describes how to invoke the &FindBugs; program.
		There are two ways to invoke &FindBugs;: directly, or using a
		wrapper script.
	</para>