<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBk XML V4.1.2//EN" 
 "file:///c:/Applications/cygwin/home/xae-dev/xae/doctypes/docbook/docbookx.dtd" []>


<?xml-stylesheet href="file:///c:/Applications/cygwin/home/jde-dev/jde/doc/src/styles/html/jdebook.xsl" type="text/xsl"  ?> 


<!-- 
<?xml-stylesheet href="file:///d|tpe-dev/tpe/styles/docbook/html/docbook.xsl" type="text/xsl"  ?>
-->

<book>


  <title>JDEE User's Guide</title>

  <bookinfo>

    <releaseinfo>
      <remark>
	Revised for JDEE <productnumber>2.3.3</productnumber>
      </remark>
    </releaseinfo>

    <copyright>
      <year>1997</year>
      <year>1998</year>
      <year>1999</year>
      <year>2000</year>
      <year>2001</year>
      <year>2002</year>
      <year>2003</year>
      <holder>Paul Kinnucan</holder>
    </copyright>
  </bookinfo>

  <chapter>

      <title><anchor id="Intro"/>Introduction</title>
      

    <para>Welcome to the <emphasis>JDEE User's Guide</emphasis>. This
      guide explains how to use the JDEE to develop Java applications and
      applets. The guide assumes that you are familiar with Emacs, the
      Java programming language, and the Java development tools provided
      with the Java Development Kit (JDK) from Sun Microsystems,
      Inc. and compatible tools provided by other vendors.</para>

    <sect3>

	<title><anchor id="AboutJDE"/>About the JDEE</title>
	

      <para>The Java Development Environment for Emacs (JDEE) is an
	Emacs Lisp package that interfaces Emacs to third-party Java
	application development tools, such as those provided by Sun
	Microsystems as part of its JDK. The result is an integrated
	development environment (IDE) comparable in power to many
	commercial Java IDEs. Features include: </para>

      <itemizedlist>

	<listitem>
	  <para>source code editing with syntax highlighting and auto
	    indentation</para>
	</listitem>
	<listitem>
	  <para>automatic completion of class fields and methods    
	  </para>
	</listitem>
	<listitem>
	  <para>compilation with automatic jump from error messages
	    to responsible line in the source code.</para>
	</listitem>
	<listitem>
	  <para>
	    generates class and method skeletons automatically
	  </para>
	</listitem>
	<listitem>
	  <para>run Java application in an interactive (comint)
	    Emacs buffer
	  </para>
	</listitem>
	<listitem>
	  <para>
	    integrated debugging with interactive debug command
	    buffer and automatic display of current source file/line
	    when stepping through code
	  </para>
	</listitem>
	<listitem>
	  <para>
	    browse JDK doc, using the browser of your choice
	  </para>
	</listitem>

	<listitem><para>
	    browse your source code, using the Emacs etags facility
	    or a tree-structured speedbar.
	  </para></listitem>

	<listitem><para>
	    supports latest version of JavaSoft's Java Development
	  </para></listitem>

	<listitem><para>
	    runs on any platform supported by Emacs and Sun's Java SDK (e.g.,
	    Win95/NT and Solaris)
	  </para></listitem>

	<listitem><para>
	    easily and infinitely customizable
	  </para></listitem>

	<listitem><para>
	    works with FSF Emacs and XEmacs
	  </para></listitem>

      </itemizedlist>

    </sect3>


    <sect3>

      <title><anchor id="JDERequirements"/>JDE Requirements</title>
      

      <para>The JDE requires the following software: </para>

      <itemizedlist>

	<listitem>
	  <para><ulink url="http://www.gnu.org/">FSF Emacs</ulink> or
	    <ulink url="http://www.xemacs.org/">XEmacs</ulink> on Unix
	    platforms; the 20.6.1 version (or later) of  
	    <ulink url="ftp://ftp.gnu.org/gnu/windows/emacs/latest">NT/Emacs</ulink> on
	    Windows platforms, for general source file editing and tool integration functions.
	  </para></listitem>

	<listitem><para>
	    <ulink url="http://java.sun.com/j2se">Java
	      Development Kit (JDK)</ulink> or compatible set of Java
	    development tools (compiler, virtual machine, debugger,
	    class libraries, etc.)
	  </para></listitem>

	<listitem><para>
	    Web browser (e.g., Netscape or Internet Explorer) for
	    viewing documentation.
	  </para></listitem>

	<listitem>
	  <para>
	    latest versions of Eric Ludlam's <symbol>speedbar</symbol>, 
	    <symbol>semantic</symbol>, and
	    <symbol>eieio</symbol> packages available for download from
	    <ulink url="http://cedet.sourceforge.net">the CDET home page</ulink>
	  </para></listitem>

	<listitem>
	  <para>
	    The elib package available from the 
	    <ulink url="http://jdee.sunsite.dk">JDE web site</ulink>
	  </para></listitem>


	<listitem>
	  <para>
	    <command>bash</command> or another Unix-style shell highly
	    recommended for Windows95/NT environments. The <ulink
	      url="http://sources.redhat.com/cygwin">cygwin</ulink>
	    Unix emulation package for Windows from Red Hat includes
	    <command>bash</command>.
	  </para>
	</listitem>

      </itemizedlist>

    </sect3>

    <sect3>
	
	<title><anchor id="JDEComponents"/>JDEE Components</title>



      <para>
	The JDEE distribution includes the following files:
      </para>

      <itemizedlist>

	<listitem><para> 


	    <ulink  url="../../../lisp/jde.el"><filename>jde.el</filename></ulink>. 
	    Defines jde-mode, a major Emacs mode for developing Java code.
	  </para></listitem>

	<listitem><para>
	    <ulink url="../../../lisp/jde-run.el"><filename>jde-run.el</filename></ulink>. 
	    Runs Java applications and applets
	  </para></listitem>

	<listitem><para>
	    <ulink url="../../../lisp/jde-db.el"><filename>jde-db.el</filename></ulink>. 
	    Interfaces Emacs to <command>jdb</command>, the command-line debugger that
	    comes with the JDK.
	  </para></listitem>

	<listitem>
	  <para>
	    <ulink
	      url="../../../lisp/jde-gen.el"><filename>jde-gen.el</filename></ulink>. 
	    Contains code generation templates.
	  </para>
	</listitem>

	<listitem>
	  <para>
	    <filename>bsh.jar</filename>. Compiled files for the
	    <ulink url="http://www.beanshell.org/">BeanShell</ulink>,
	    a Java source code interpreter developed by Pat Neimeyer.
	  </para>
	</listitem>

	<listitem>
	  <para>
	    <ulink
	      url="../../../lisp/beanshell.el"><filename>beanshell.el</filename></ulink>. 
	    Provides an Emacs interface to the BeanShell interpreter.
	  </para>
	</listitem>

	<listitem>
	  <para>
	    <ulink
	      url="../../../lisp/jde-wiz.el"><filename>jde-wiz.el</filename></ulink>. 
	    Provides &quot;wizards&quot; that generate skeleton
	    implementations of interfaces and skeleton overrides of
	    methods declared by superclasses.
	  </para></listitem>

	<listitem>
	  <para>
	    <ulink
	      url="../../../lisp/jde-complete.el"><filename>jde-complete.el</filename></ulink>. 
	    Automatic field and method completion package.
	  </para>
	</listitem>

	<listitem><para>
	    <ulink url="../../../lisp/jde-parse.el"><filename>jde-parse.el</filename></ulink>. 
	    Java parser package.</para>
	</listitem>

	<listitem><para>
	    <ulink url="../../../lisp/java.bnf"><filename>java.bnf</filename></ulink>. 
	    Java grammar used to generate the JDE's lisp-based Java parser.
	  </para></listitem>

	<listitem><para>
	    <ulink url="../../../lisp/jde-bug.el"><filename>jde-bug.el
	      </filename></ulink>. 
	    JDEbug user interface package.
	  </para></listitem>

	<listitem><para>
	    <ulink url="../../../lisp/jde-dbs.el"><filename>jde-dbs.el</filename></ulink>. 
	    JDEbug low-level command interface package.
	  </para></listitem>

	<listitem><para>
	    <ulink url="../../../lisp/jde-dbo.el"><filename>jde-dbo.el</filename></ulink>. 
	    JDEbug output processing functions.
	  </para></listitem>

	<listitem>
	  <para>
	    source code, jar files, and documentation for the <ulink
	      url="../../java/">Java components</ulink> of the
	    JDE.</para>
	</listitem>

	<listitem>
	  <para><ulink
	      url="../../../lisp/jtags"><filename>jtags</filename></ulink> 
	    is a bash shell script that tags Java source hierarchies.
	  </para>
	</listitem>

	<listitem>
	  <para>
	    <ulink
	      url="../../../lisp/jtags.csh"><filename>jtags.csh</filename></ulink> 
	    is a c shell script that tags Java source heierarchies.
	  </para>
	</listitem>

      </itemizedlist>
    </sect3>


    <sect3>
	
	<title><anchor id="LatestVersion"/>Latest Version</title>


      <para>See <ulink url="http://jdee.sunsite.dk/rootpage.html#Downloading">
	  Downloading the JDE</ulink> on the JDE website for instructions on
	downloading the most recent version of the JDE. 
      </para>


    </sect3>

    <sect3>
      <title><anchor id="InstallingJDE"/>Installing the JDE</title>
      <para>See the <ulink url="http://jdee.sunsite.dk/install.html">
	JDE Installation Guide</ulink> on the JDE website for information
      on installing the JDE on your system.</para>
    </sect3>

    <sect3>

	
	<title><anchor id="ContactingAuthor"/>Contacting the Author</title>


      <para>Please send bug reports and enhancement suggestions to 
	<ulink url="mailto:pkinnucan@attbi.com">Paul Kinnucan</ulink>.
      </para>
      
    </sect3>

  </chapter>

  <chapter>
    <title><anchor id="RegisterSelectJDK"/>Registering and Selecting a JDK</title>

    <para>The JDEE relies on command-line Java development tools, such
      as those supplied by Sun Microsystems as part of its Java
      Software Development Kit (SDK) also known as a Java Development
      Kit (JDK). Before you can use the JDEE to compile, debug, or run
      an application, you must tell it where the Java compiler,
      debugger, and virtual machine are located on your system. The
      JDEE assumes that the compiler, debugger, and vm are named
      <filename>javac</filename>, <filename>jdb</filename>, and
      <filename>java</filename>, respectively, and that they are
      located on your system's command path. If these tools are not
      located on the system command path or have different names, you
      must tell the JDEE where they are located. The JDEE provides
      customization variables for specifying the locations of
      individual tools.
    </para>
    
    <para>
      However, if you are using one or more versions of Sun's JDK or a
      clone of the Sun JDK, the easiest way to specify the location of
      the external development tools is to register the version of the
      JDK that you intend to use. It is especially advantageous to
      register a JDK, if you intend to use multiple versions of the
      JDK. The reason? Registering each version of the JDK allows you
      to change JDKs by changing a single customization variable. The
      following sections explain how to register and select
      JDKs.
    </para>

    <sect3>

      <title><anchor id="RegisterJDK"/>Registering a JDK</title>

      <para>To register a version of the JDK with the JDEE:</para>

      <orderedlist>
	<listitem>
	  <para>Start Emacs.</para>
	</listitem>
	<listitem>
	  <para>Type <command>M-x customize-variable</command> and
	    press <command>Enter</command></para>
	  <para>Emacs prompts you to enter the name of a variable
	  to customize.</para>
	</listitem>
	<listitem>
	  <para>Enter <varname>jde-jdk-registry</varname> and
	  press <command>Enter</command>.</para>
	  <para>The <varname>jde-jdk-registry</varname> customization
	  buffer appears.</para>
	  <screenshot>
	    <mediaobject>
	      <imageobject>
		<imagedata fileref="images/regjdk1.gif"/>
	      </imageobject>
	    </mediaobject>
	  </screenshot>
	</listitem>
	<listitem>
	  <para>Click the <command>INS</command> button.</para>
	  <para>The entry for the JDK appears.</para>
	  <screenshot>
	    <mediaobject>
	      <imageobject>
		<imagedata fileref="images/regjdk2.gif"/>
	      </imageobject>
	    </mediaobject>
	  </screenshot>
	</listitem>
	<listitem>
	  <para>Enter the version number of the JDK and the path of the directory
	  in which the JDK is installed.</para>
	</listitem>
	<listitem>
	  <para>Repeat the preceding steps until you have entered the versions and
	  paths of all versions of the JDK that you wish to use with the JDEE.</para>
	  <screenshot>
	    <mediaobject>
	      <imageobject>
		<imagedata fileref="images/regjdk3.gif"/>
	      </imageobject>
	    </mediaobject>
	  </screenshot>	  
	</listitem>
	<listitem>
	  <para>Click the <command>State</command> button.</para>
	  <para>The <command>State</command> menu appears.</para>
	</listitem>
	<listitem>
	  <para>Select <command>Save for Future Sessions</command> from
	    the <command>State</command> menu.</para>
	</listitem>
	<listitem>
	  <para>Click the <command>Finish</command> button to dismiss
	  the customization buffer.</para>
	</listitem>
      </orderedlist>

    </sect3>

    <sect3>
      <title><anchor id="SelectingJDK"/>Selecting a JDK</title>
      <para>To select a JDK:</para>
      <orderedlist>
	<listitem>
	  <para>Type <command>M-x customize-variable</command> and
	    press <command>Enter</command></para>
	  <para>Emacs prompts you to enter the name of a variable
	  to customize.</para>
	</listitem>
	<listitem>
	  <para>Enter <varname>jde-jdk</varname> and
	  press <command>Enter</command>.</para>
	  <para>The <varname>jde-jdk</varname> customization
	  buffer appears.</para>
	  <screenshot>
	    <mediaobject>
	      <imageobject>
		<imagedata fileref="images/seljdk1.gif"/>
	      </imageobject>
	    </mediaobject>
	  </screenshot>
	  <para>The buffer lists the JDKs that you have previously registered 
	    (see <ulink url="#RegisterJDK">Registering a JDK</ulink>).</para>
	</listitem>
	<listitem>
	  <para>Click the radio button next to the version of the JDK you
	  want to use.</para>
	</listitem>
	<listitem>
	  <para>Click the <command>State</command> button.</para>
	  <para>The <command>State</command> menu appears.</para>
	</listitem>
	<listitem>
	  <para>Select <command>Save for Future Sessions</command> from
	    the <command>State</command> menu.</para>
	</listitem>
	<listitem>
	  <para>Click the <command>Finish</command> button to dismiss
	  the customization buffer.</para>
	</listitem>
      </orderedlist>
      <note>
	<para>This procedure saves your JDK selection in your
	  <filename>.emacs</filename> file so that it applies to all
	  projects. You can configure the JDEE to use different JDKs
	  for different projects by saving your customization in a
	  project file. See <ulink url="#UsingProjectFiles">Using
	    Project Files</ulink> or more information.</para>
      </note>
    </sect3>

  </chapter>

  <chapter>

      <title><anchor id="EditingJavaSourceFiles"/>Editing Java Source Files</title>
      


    <para>
      To edit an existing Java source file, load it into an Emacs
      buffer by executing <command>C-x C-f</command>. Loading a Java source file
      into a buffer causes the buffer to enter into <function>jde-mode</function>,
      a variant of <function>java-mode</function>, which is in turn a variant of
      the standard Emacs <function>cc-mode</function> for editing source files
      written in C and related languages. <function>jde-mode</function> offers all the
      specialized source file editing commands of <function>cc-mode</function> plus
      functions for creating, compiling, building, running, and debugging Java source files.
      You can invoke the commands by selecting them from the <guimenu>JDE</guimenu>
      menu that <function>jde-mode</function> displays on the Emacs menu bar or by
      typing the commands in the Emacs minibuffer.
    </para>

    <para>
      <screenshot>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="images/jdemenu.gif" width="544" depth="350"/>
	  </imageobject>
	  <textobject>
	    <phrase>Screenshot showing the JDE menu.</phrase>
	  </textobject>
	</mediaobject>
      </screenshot>
    </para>

  </chapter>


  <chapter>

	
    <title><anchor id="DocumentingCode"/>Documenting Code</title>

    <para>
      The JDE provides complete support for generating HTML
      documentation for Java classes from comments inserted into the
      source code for those classes.
    </para>

    <para>See also</para>
    <para><ulink url="#DisplayingDoc">Displaying Java
	Documentation</ulink></para>

    <sect3>

	  
      <title><anchor id="InsertingComments"/>Inserting Javadoc
	Comments</title>

      <para>
	To insert a skeleton javadoc comment for a class or method,
	position point in the first line of the method or class and
	select <guimenuitem>JDE-&gt;Document</guimenuitem> from the
	Emacs menubar  or type <command>C-c C-v j</command>.
      </para>

      <para>
	To customize the javadoc skeletons, select
	<guimenuitem>JDE-&gt;Options-&gt;Project-&gt;Javadoc</guimenuitem> 
	from the Emacs menubar.
      </para>

      <note>
	<title>Thanks...</title>
	<para>
	  to <ulink url="mailto:david@dponce.com">David Ponce</ulink>
	  for developing the JDE's javadoc comment generation
	  facility.
	</para>
      </note>

    </sect3>

    <sect3>

	  
      <title><anchor id="GeneratingJavadoc"/>Generating the
	Documentation</title>


      <para>
	To generate documentation for the current project, open any
	source file in the project and select <guimenuitem>Make
	  Doc</guimenuitem> from the <guimenu>JDE</guimenu> menu or
	enter <command>M-x jde-javadoc-make</command>.
      </para>

      <para>
	The <command>jde-javadoc-make</command> command runs the JDK's
	javadoc program to generate the documentation. The
	<command>javadoc</command> command must be on your system's
	command path.
      </para>

      <para>
	  The <command>jde-javadoc-make</command> command uses
	<varname>jde-global-classpath</varname> as the
	<varname>-classpath</varname> and <varname>jde-sourcepath
	</varname> as the <varname>-sourcepath</varname> option for
	generating the doc. You can specify all other javadoc options
	via JDE customization variables. To specify the options,
	select <menuchoice><guimenu>Project</guimenu> 
	  <guisubmenu>Options</guisubmenu><guimenuitem>Javadoc</guimenuitem></menuchoice> 
	
	
	  from the 
	  <menuchoice><guimenu>JDE</guimenu></menuchoice> menu. Use
	  <varname>jde-javadoc-gen-packages</varname> to specify the
	  packages, classes, or source files for which you want to
	  generate javadoc. If this variable is
	  <varname>nil</varname>, the
	  <command>jde-javadoc-make</command> generates javadoc for
	  the Java source file in the current buffer.
      </para>

      <note>
	<para>
	  Thanks to <ulink url="mailto:sakliban@cs.wustl.edu">Sergey A
	    Klibanov </ulink> for developing the JDE's javadoc
	  generation facility.
	</para>
      </note>

    </sect3>

  </chapter>

  <chapter>

    <title><anchor id="Abbrevs"/>Abbreviations</title>

    <para>
      The JDEE allows you to use abbreviations for Java keywords and
      control flow constructs. The following sections explain how to
      use these abbreviations.
    </para>


    <sect3>

	  
      <title><anchor id="KeywordAbbrevs"/>Keyword
	Abbreviations</title>

      <para>The JDEE defines a set of abbreviations for Java keywords.
	When you type one of these abbreviations followed by a space
	in a Java source buffer, the JDE optionally expands the
	abbreviation into the keyword. For example, when the
	abbreviation mode is enabled, you need only type
	<varname>fa</varname> followed by a space to enter the Java
	keyword <varname>false</varname>. To enable or disable
	abbreviation mode, select <menuchoice><guimenu
						moreinfo="none">JDE</guimenu> 
	  
	  
	  <guisubmenu
	    moreinfo="none">Project</guisubmenu><guisubmenu>Options
	  </guisubmenu><guimenuitem>General</guimenuitem></menuchoice>
	and toggle the boolean variable
	<varname>jde-enable-abbrev-mode</varname>. To change, remove,
	or add an abbreviation, edit the variable
	<varname>jde-mode-abbreviations</varname> in the project
	customization buffer.</para>

      <note><para>The JDE's Java keyword expansion facility is based
	  on the Emacs <varname>abbrev-mode</varname> facility. For
	  more information, see the Emacs user manual.</para></note>

    </sect3>

    <sect3>

	  
      <title><anchor id="ControlFlowAbbrevs"/>Control Flow
	Abbreviations</title>

      <para>The JDEE defines abbreviations for Java control flow
	structures, such as if-then-else. When you enter the
	abbreviation followed by a space, the JDE expands the
	abbreviation into a corresponding control structure
	template.</para>

      <example>
	<title>Expanding a Control Flow Abbreviation</title>

	<para>The if-then-else abbreviation</para>

	<programlisting>
	  ife
	</programlisting>

	<para>expands to the control flow structure</para>

	<programlisting>
	  if ( ) { } // end of if () else } // end of if ()else
	</programlisting>
      </example>

      <sect4>
	<title>Control Flow Abbreviations</title>

	<para>The JDE defines the following abbreviations for control
	  structures.</para>

	<table>
	  <title>Control Flow Abbreviations</title>
	  <tgroup cols="2">
	    <colspec colnum="1"></colspec>
	    <colspec colnum="2"></colspec>
	    <thead>
	      <row><entry>Statement</entry><entry>Abbreviation</entry></row>
	    </thead>
	    <tbody>
	      <row>
		<entry><varname>if-then</varname></entry>
		<entry><varname>if</varname></entry>
	      </row>
	      <row>
		<entry><varname>else</varname></entry>
		<entry><varname>else</varname></entry>
	      </row>
	      <row>
		<entry><varname>if-then-else</varname></entry>
		<entry><varname>ife</varname></entry>
	      </row>
	      <row>
		<entry><varname>else-if</varname></entry>
		<entry><varname>eif</varname></entry>
	      </row>
	      <row>
		<entry><varname>while</varname></entry>
		<entry><varname>while</varname></entry>
	      </row>
	      <row>
		<entry><varname>for</varname></entry>
		<entry><varname>for</varname></entry>
	      </row>
	      <row>
		<entry><varname>for (int
		    I=0;I&lt;UL;I++)</varname></entry>
		<entry><varname>fori</varname></entry>
	      </row>
	      <row>
		<entry><varname>for (Iterator i = c.iterator();
		    i.hasNext();)</varname></entry>
		<entry><varname>foriter</varname></entry>
	      </row>
	      <row>
		<entry><varname>main method</varname></entry>
		<entry><varname>main</varname></entry>
	      </row>
	      <row>
		<entry><varname>switch</varname></entry>
		<entry><varname>switch</varname></entry>
	      </row>
	      <row>
		<entry><varname>case</varname></entry>
		<entry><varname>case</varname></entry>
	      </row>
	      <row>
		<entry><varname>try</varname></entry>
		<entry><varname>try</varname></entry>
	      </row>
	      <row>
		<entry><varname>catch</varname></entry>
		<entry><varname>catch</varname></entry>
	      </row>
	      <row>
		<entry><varname>try finally</varname></entry>
		<entry><varname>tryf</varname></entry>
	      </row>
	      <row>
		<entry><varname>finally</varname></entry>
		<entry><varname>finally</varname></entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>        

	<note>
	  <para>
	    You must enable the JDE's Java keyword abbreviation mode
	    to use the control flow abbreviations. See <ulink
	      url="#JavaKeywordCompletion">Java Keyword
	      Completion</ulink> for more information.
	  </para>
	</note>

      </sect4>

      <sect4>
	<title>Left Brace Placement</title>
	  
	<para>
	  The JDE's Java control flow templates support two options
	  for opening brace placement: placement on the first line of
	  the template (Kerningham &amp; Ritchie Style, the default)
	  and placement on a separate line. Type <command>M-x
	    customize-variable jde-gen-k&amp;r</command> to specify
	  the style you prefer.
	</para>

      </sect4>

      <sect4>

	<title>Customizing the Control Flow Templates</title>

	<para>You can customize the templates to suit any indentation
	  style. To customize the templates, select 
	    <menuchoice>
	    <guimenu>Project</guimenu>
	    <guisubmenu>Options</guisubmenu>
	    <guimenuitem>Autocode</guimenuitem>
	  </menuchoice> from the JDE menu.</para>

      </sect4>

      <sect4>

	<title>Adding Your Own Control Flow Templates</title>
	<para>
	  Use the <function>jde-gen-define-abbrev-template</function>
	  function to define your own control flow abbreviation in
	  your  <filename>.emacs</filename> file. For example, the
	  following code defines an abbreviation  for an else clause.
	</para>
	<programlisting>
	  (jde-gen-define-abbrev-template "melse" '('> "else {" '> 'n
	  '> 'r 'n "}"))
	</programlisting>
	<para>The <function
	    moreinfo="none">jde-gen-define-abbrev-template</function>
	  function takes two arguments. The first argument is a string
	  that specifies the abbreviation. The section argument is a
	  list defining the text that replaces the abbreviation. The
	  list can contain any of the following elements.</para>
	<table>
	  <title>Template Elements</title>
	  <tgroup cols="2">
	    <thead>
	      <row>
		<entry>Element</entry>
		<entry>Usage</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry>A string.</entry>
		<entry>The string is inserted into the buffer at
		  point.</entry>
	      </row>
	      <row>
		<entry>The symbol <varname>'p</varname>.</entry>
		<entry>This position is saved in
		  <varname>tempo-marks</varname>.</entry>
	      </row>
	      <row>
		<entry>The symbol <varname>'r</varname>.</entry>
		<entry>If <varname>tempo-insert</varname> is called
		  with <varname>ON-REGION</varname> non-nil the
		  current region is placed here. Otherwise it works
		  like 'p.</entry>
	      </row>
	      <row>
		<entry><varname>(p PROMPT &lt;NAME&gt;
		    &lt;NOINSERT&gt;)</varname></entry>
		<entry>If <varname>tempo-interactive</varname> is
		  non-nil, the user is prompted in the minbuffer with
		  <varname>PROMPT</varname> for a string to be
		  inserted. If the optional parameter
		  <varname>NAME</varname> is non-nil, the text is
		  saved for later insertion with the
		  <varname>s</varname> tag. If there already is
		  something saved under <varname>NAME</varname> that
		  value is used instead and no prompting is made. If
		  <varname>NOINSERT</varname> is provided and non-nil,
		  nothing is inserted, but text is still saved when a
		  <varname>NAME</varname> is provided. For clarity,
		  the symbol <varname>'noinsert</varname> should be
		  used as argument.</entry>
	      </row>
	      <row>
		<entry><varname>(P PROMPT &lt;NAME&gt;
		    &lt;NOINSERT&gt;)</varname></entry>
		<entry>Works just like the previous element, but
		  forces <varname>tempo-interactive</varname> to be
		  true.</entry>
	      </row>
	      <row>
		<entry><varname>(r PROMPT &lt;NAME&gt;
		    &lt;NOINSERT&gt;)</varname></entry>
		<entry>Like the previous, but if
		  <varname>tempo-interactive</varname> is
		  <varname>nil</varname> and
		  <varname>tempo-insert</varname> is called with
		  <varname>ON-REGION</varname> non-nil, the current
		  region is placed here. This usually happens when you
		  call the template function with a prefix
		  argument.</entry>
	      </row>
	      <row>
		<entry><varname>(s NAME)</varname></entry>
		<entry>Inserts text previously read with the
		  <varname>(p ..)</varname> construct. Finds the
		  insertion saved under <varname>NAME</varname> and
		  inserts it. Acts like <varname>'p</varname> if
		  <varname>tempo-interactive</varname> is
		  <varname>nil</varname>.</entry>
	      </row>
	      <row>
		<entry><varname>'&amp;</varname></entry>
		<entry>If there is only whitespace between the line
		  start and point, nothing happens. Otherwise a
		  newline is inserted.</entry>
	      </row>
	      <row>
		<entry><varname>'%</varname></entry>
		<entry>If there is only whitespace between point and
		  end-of-line nothing happens. Otherwise a newline is
		  inserted.</entry>
	      </row>
	      <row>
		<entry><varname>'n</varname></entry>
		<entry>Inserts a newline.</entry>
	      </row>
	      <row>
		<entry><varname>'&gt;</varname></entry>
		<entry>The line is indented using
		  <varname>indent-according-to-mode</varname>. Note
		  that you often should place this item after the text
		  you want on the line.</entry>
	      </row>
	      <row>
		<entry><varname>'n&gt;</varname></entry>
		<entry>Inserts a newline and indents line.</entry>
	      </row>
	      <row>
		<entry><varname>'r&gt;</varname></entry>
		<entry>Like <varname>r</varname>, but it also indents
		  the region.</entry>
	      </row>
	      <row>
		<entry><varname>'o</varname></entry>
		<entry>Like <varname>'%</varname> but leaves the point
		  before the new line.</entry>
	      </row>
	      <row>
		<entry>Anything else.</entry>
		<entry>It is evaluated and the result is treated as an
		  element to be inserted. One additional tag is useful
		  for these cases. If an expression returns a list
		  <varname>'(l foo bar)</varname>, the elements after
		  <varname>'l</varname> will be inserted according to
		  the usual rules. This makes it possible to return
		  several elements from one expression.</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>

      </sect4>

      <sect4>
	<title>Enabling Variable Content</title>

	<para>Some templates optionally prompt you for items to insert
	  into the template. To enable  prompting, set the variable
	  <varname>tempo-interactive</varname> to a
	  non-<varname>nil</varname> value in your
	  <filename>.emacs</filename> file.</para>
      </sect4>

      <sect4>
	<title>Disabling the Control Flow Abbreviations</title>

	<para>To disable the control flow abbreviations, set the
	  variable <varname>jde-gen-cflow-enable</varname> off.</para>

	<note>
	  <title>Thanks to...</title>

	  <para>Thanks to Eric D. Friedman &gt;friedman@lmi.net&lt;
	    for contributing the control flow templates.</para>
	</note>

      </sect4>

    </sect3>

  </chapter>

  <chapter>

	
      <title><anchor id="CodeCompletion"/>Completing Expressions</title>

      <para>
	Both Emacs and the JDEE provide commands for completing incomplete
	expressions. Emacs provides commands that work for any expression
	but only if the completions exist in an open buffer. The JDEE
	provides completion commands that work for any Java method or field
	name that exists on <varname>jde-global-classpath</varname>.
	The following sections explain how to use completion facilities
	supplied by the JDEE and by Emacs itself.
	
      </para>

      <sect3>
	  
      <title><anchor id="FieldAndMethodCompletion"/>Completing Method
	and Field Names</title>


      <para>
	The JDEE provides comamnds that can complete an incomplete
	field or method name. All the methods determine the set of
	possible completions for an incomplete field or method name at
	point. They differ in how they present the completions to you
	for selection. The commands include:</para>

      <itemizedlist>
	<listitem>
	  <para><command>jde-complete-in-line</command></para>
	  <para>This command uses the first completion that it finds
	    to complete the method or field name at point. If multiple
	    completions exist, it allows you to cycle through the
	    completions, each completion replacing the previous in the
	    source buffer.  See <ulink url="#InLineCompletion">Using
	      In-Line Completion</ulink> for more information.
	  </para>
	</listitem>
	<listitem>
	  <para><command>jde-complete-menu</command></para>
	  <para>
	    This command displays a menu of possible completions for
	    the incomplete method or field name at point. It enters
	    the completion that you select in the source buffer. See
	    <ulink url="#MenuCompletion">Using Menu-Based
	      Completion</ulink> for more information.
	  </para>
	</listitem>
	<listitem>
	  <para><command>jde-complete-minibuf</command></para>
	  <para>
	    This command uses the minibuffer to display possible
	    completions for the incomplete method or field name at
	    point. The comamnd enters the completion that you select
	    in the source buffer. See <ulink
	      url="#MinibufferCompletion">Using Minibuffer-Based
	      Completion</ulink> for more information.</para>
	</listitem>
	<listitem>
	  <para><command>jde-complete</command></para>
	  <para>This is the JDEE's user-definable "standard"
	    completion command. It delegates completion to one of the
	    JDEE's other completion commands
	    (<command>jde-complete-menu</command> by default) or to a
	    custom completion function that you specify (see <ulink
	      url="SelectCompletionMethod">Selecting a Completion
	      Method</ulink> for more information.) The
	    <command>jde-complete</command> command is bound by
	    default to the key combination <command>C-c C-v
	      C-.</command>. If you prefer another binding, use the
	    customization variable <varname>jde-key-bindings</varname>
	    to change the binding.
	  </para>
	</listitem>
      </itemizedlist>

      <para>
	The JDEE's field and method completion commands use the
	Beanshell to run Java code that in turn uses Java's reflection
	(class introspection) capability to determine the fields and
	methods defined for the class of object at point. The commands
	start the Beanshell if it is not running. This can cause a
	noticeable delay in completion the first time it is used in a
	session. The response can also be slow for classes containing
	many methods and fields.
      </para>

      <note>
	<para>See <ulink url="#SpeedingUpCompletion">Speeding Up Completion</ulink>
	for some tips on how you can dramatically speed up field and
	method completion.</para>
      </note>

      <para>
	Completion works only for compiled classes that reside in the
	classpath defined by <varname>jde-global-classpath</varname>,
	if set, otherwise by the <varname>CLASSPATH</varname>
	environment variable when the Beanshell starts. Thus, if the
	JDEE is unable to complete a method or field, make sure that
	the class that defines the field or method is compiled and
	exists on the classpath defined by
	<varname>jde-global-classpath</varname>, if set, otherwise by
	the <varname>CLASSPATH</varname> environment variable.
      </para>


      <para>
	The JDEE completion commands work for all of the following
	cases.
      </para>

      <itemizedlist>
	<listitem>
	  <para>objects referenced by variables declared in the
	    current buffer</para>
	</listitem>
	<listitem>
	  <para>static fields and methods</para>
	</listitem>
	<listitem>
	  <para>
	    fields and methods of objects defined by the current class
	    and its parent
	  </para>
	  <para>
	    Names of fields and methods of the current class must
	    start with <varname>this</varname> or <varname>.</varname>
	    (period). Names of fields and methods declared by the
	    parent of the current class must start with
	    <varname>super</varname>.
	  </para>
	  <para>For example, this command completes</para>
	  <programlisting>
	    . ^ this. ^ super. ^
	  </programlisting>
	</listitem>

	<listitem>
	  <para>
	    objects referenced by the fields of objects referenced by
	    variables declared in the current class or its parent or
	    by static fields
	  </para>
	  <para>For example, this command completes</para>
	  <programlisting>
	    System.out.prin ^
	  </programlisting>
	</listitem>

	<listitem>
	  <para>
	    objects returned by methods of objects referenced by
	    variables defined in the current 
	  </para>
	  <para>
	    For example, this command completes
	  </para>
	  <programlisting>
	    Toolkit.getDefaultToolkit().get ^
	  </programlisting>
	</listitem>

	<listitem>
	  <para>
	    objects referenced by method parameters</para>
	  <para>
	    For example, this command completes
	  </para>
	  <programlisting>
	    void setColor(String color) { color.get ^ }
	  </programlisting>
	</listitem>
      </itemizedlist>



      <sect4>
	<title><anchor id="SelectStdCompletionMethod"/> Selecting a
	  Completion Method</title>

	<para>The JDEE's generic completion command,
	  <command>jde-complete</command> delegates completion to one
	  of several specific completion commands supplied by the JDEE
	  or to a custom completion method that you supply. This
	  allows you to customize <command>jde-complete</command> to
	  use the completion method that you prefer.</para>
	  
	<para>To specify your preferred completion method:</para>

	<orderedlist>


	  <listitem>
	    <para>Open a customization buffer for
	      <varname>jde-complete-function</varname>.</para>
	  
	    <screenshot>
	      <mediaobject>
		<imageobject>
		  <imagedata fileref="images/completion_sel_method.gif"/>
		</imageobject>
	      </mediaobject>
	    </screenshot>
	  </listitem>

	  <listitem>
	    <para>Select the completion command that implements the
	      completion method you prefer.</para>
	  </listitem>

	  <listitem>
	    <para>If you selected <varname>Custom</varname> as your
	      preferred completion function, enter the name of the
	      custom completion function in the adjacent edit field,
	      replacing the existing contents
	      (<varname>ignore</varname> by default.).
	    </para>
	  </listitem>

	  <listitem>
	    <para>Save your selection in your
	      <filename>.emacs</filename> or project file.
	    </para>
	  </listitem>
	
	</orderedlist>

      </sect4>


      <sect4>
	<title><anchor id="MenuCompletion"/>Using Menu-Based
	  Completion</title>
	<para>The <command>jde-complete-menu</command> displays a
	  popup menu of completions for the method or field name at
	  point. Selecting a completion from the menu causes the
	  command to use it to complete the method or field at point.
	  This section assumes that you have selected
	  <command>jde-complete-menu</command> as your standard
	  completion command.
	</para>

	<para>To select completions from a menu:</para>

	<orderedlist>
	  <listitem>
	    <para>Position point immediately following the partially
	      complete field or method name.</para>

	    <screenshot>
	      <mediaobject>
		<imageobject>
		  <imagedata fileref="./images/completion_menu1.gif"/>
		</imageobject>
	      </mediaobject>
	    </screenshot>

	  </listitem>

	  <listitem>
	    <para>Type the <command>C-c C-v C-.</command> key combination.</para>

	    <para>A menu of completions pops up.</para>

	    <screenshot>
	      <mediaobject>
		<imageobject>
		  <imagedata fileref="./images/completion_menu2.gif"/>
		</imageobject>
	      </mediaobject>
	    </screenshot>

	  </listitem>

	  <listitem>
	    <para>Select the desired completion from the menu.</para>

	    <para>The JDEE inserts the completion at point in the
	      buffer.</para>

	    <screenshot>
	      <mediaobject>
		<imageobject>
		  <imagedata fileref="./images/completion_menu3.gif"/>
		</imageobject>
	      </mediaobject>
	    </screenshot>

	  </listitem>

	</orderedlist>

      </sect4>


      <sect4>

	<title><anchor id="InLineCompletion"/>Using In-Line
	  Completion</title>

	<para>
	  The <command>jde-complete-in-line</command> command allows
	  you to select completions at the point of insertion in the
	  source buffer. The command finds all the fields and methods
	  that complete the name at point. It then inserts the first
	  potential completion in the buffer at point. Repeatedly
	  executing the command causes  the JDEE to cycle through the
	  other potential completions. If the completion is a method
	  name, the command completes the method name and displays the
	  method signature in the minibuffer.
	</para>

	<para>
	  The <command>jde-complete-in-line</command> command is bound
	  to <command>C-c C-v .</command>. You can use this
	  combination to invoke the command or <command>C-c C-v
	    C-.</command>, if you have selected this command as your
	  preferred completion method. The following examples use the
	  <command>C-c C-v .</command> combination.	    
	</para>


	<example>
	  <title>Completing a String Method Name</title>
	  <para>
	      Typing
	    <keycombo><keysym>C-c</keysym><keysym>C-v</keysym><keysym>.</keysym></keycombo>
	  </para>

	  <programlisting>
	    String s; s.get ^
	  </programlisting>
	  <para>
	    completes the method name at point as follows</para>

	  <programlisting>
	    String s; s.getClass( ^
	  </programlisting>

	  <para>and displays</para>

	  <programlisting>
	    java.lang.Class getClass()
	  </programlisting>

	  <para>in the minibuffer. Repeatedly typing
	    <keycombo><keysym>C-c</keysym><keysym>C-v</keysym><keysym>.</keysym></keycombo> 
	    cycles through all the other get methods for the Java
	    <varname>String</varname> class.</para>
	</example> 

      </sect4>


      <sect4>
	<title><anchor id="SpeedingUpCompletion"/>Speeding Up Completion</title>

	<para>Here are two ways you can significantly speed up field
	  and method completion:
	</para>
	<itemizedlist>

	  <listitem>
	    <para>Byte-compile the eieio and JDEE packages.</para>

	    <para>The beanshell package, the Emacs interface to the
	      BeanShell, is based on the eieio object-oriented Lisp
	      package for Emacs. Completion uses the BeanShell heavily
	      to determine the class of the field or method at point.
	      Thus compiling eieio and beanshell.el improves
	      completion's performance, dramatically in my tests.
	    </para>

	  </listitem>
   
	  <listitem>
	    <para>Import by class, not by package, in your Java files.
	    </para>

	    <para>Every package import, e.g.,
	      <filename>java.util.*</filename>, requires invoking the
	      BeanShell to determine the fully qualified name of the
	      class at point (see
	      <function>jde-parse-get-qualified-name</function>).
	      A Beanshell invocation is by far the most time-consuming
	      operation required for completion. Thus eliminating the
	      use of package-level imports can significantly
	      speed up completion.
	    </para>	  

	  </listitem>

	</itemizedlist>  

      </sect4>


    </sect3>

    <sect3>

	  
	<title><anchor id="DynamicKeywordCompletion"/>Dynamic Keyword Completion</title>

	<para>Emacs provides dynamic completion commands that attempt
	  to find completions for the word at point in the current
	  buffer or other buffers.
	</para> 

	<example>
	  <title>Using Dynamic Completion</title>

	  <para>
	    Suppose that the current source buffer contains the class
	    names <varname>Component</varname> and
	    <varname>Container</varname>. Now suppose you enter
	    <varname>Co</varname> somewhere in the buffer and type
	    <keycombo><keycap>M</keycap><keycap>/</keycap></keycombo>.
	    
	    The text <varname>Component</varname> replaces
	    <varname>Co</varname> in the buffer. 
	  </para>

	  <para>Typing
	    <keycombo><keycap>M</keycap><keycap>/</keycap></keycombo>
	    again changes <varname>Component</varname> to
	    <varname>Container</varname>. In this way, you can cycle
	    through all the possible completions for
	    <varname>Co</varname> in the current buffer.
	  </para> 
	</example>

      <sect4>
	<title>Dynamic Completion Commands</title>

	<para>Emacs provides two dynamic completion commands.</para>
	<para>
	    The <command>dabbrev-expand</command> command is bound to
	  the key combination
	  <keycombo><keycap>M</keycap><keycap>/</keycap></keycombo>
	    by default. It searches the current buffer for completions
	    of the word at point and, if none are found, other buffers
	    of the same type. For example, if the current buffer is a
	    Java source buffer, it searches other Java source buffers
	    for completions if none are found in the active buffer.
	</para>

	<para>
	  The <command>hippie-expand</command> command provides more
	  extensive search capabilities. See the docstrings for these
	  functions for more information.
	</para>

      </sect4>

    </sect3>

  </chapter>

  <chapter>

	
    <title><anchor id="GeneratingCode"/>Generating Code</title>

    <para>The JDE provides the following code generation capabilities.</para>

      <itemizedlist>
	<listitem><para>Code wizards</para></listitem>
	<listitem><para>Code templates</para></listitem>
      </itemizedlist>

      <sect3>

	 
      <title><anchor id="CodeWizards"/>Code Wizards</title>

      <para>
	The JDE provides a set of procedural code generators called
	code wizards. They include:
      </para>

      <table>
	<title>Code Wizards</title>
	<tgroup cols="2">
	  <thead>
	    <row>
	      <entry><para>Wizard</para></entry>
	      <entry><para>Generates...</para></entry>
	    </row>
	  </thead>
	  <tbody>
	    <row>
	      <entry>
		<para><ulink url="#ImportWizard">Import
		    Wizard</ulink></para>
	      </entry>
	      <entry>
		<para> An import statement for the class at point.
		</para>
	      </entry>
	    </row>
	    <row>
	      <entry>
		<para><ulink url="#MethodOverrideWizard">Method
		    Override Wizard</ulink></para>
	      </entry>
	      <entry>
		<para> A method that overrides a method inherited by
		  the class containing point. </para>
	      </entry>
	    </row>
	    <row>
	      <entry>
		<para><ulink url="#InterfaceWizard">Interface
		    Wizard</ulink></para>
	      </entry>
	      <entry>
		<para>Implementation of an interface in the class
		  containing point. </para>
	      </entry>
	    </row>
	    <row>
	      <entry>
		<para><ulink url="#DelegateWizard">Delegate
		    Wizard</ulink></para>
	      </entry>
	      <entry>
		<para> Methods that delegate tasks to a specified
		  class. </para>
	      </entry>
	    </row>
	    <row>
	      <entry>
		<para><ulink url="#AbstractClassWizard">Abstract Class
		    Wizard</ulink></para>
	      </entry>
	      <entry>
		<para>Implementations of the abstract methods
		  inherited by the class containing point. </para>
	      </entry>
	    </row>
	    <row>
	      <entry>
		<para><ulink url="#GetSetWizard">Get/Set
		    Wizard</ulink></para>
	      </entry>
	      <entry>
		<para>Get and set methods for the private fields of
		  the class containing point. </para>
	      </entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>

      <note>
	<para>
	  Some of the wizards use the BeanShell to run Java code. A
	  wizard starts the Beanshell interpreter if it is not already
	  running. Thus, you may experience a slight delay when
	  invoking a wizard for the first time in a session.
	</para>
      </note>

      <sect4>

	    
	<title><anchor id="ImportWizard"/>Import Wizard</title>

	<para>
	  The import wizard generates an import statement for the
	  class name at point if an import statement does not already
	  exist for that class. The wizard generates the import
	  statement at the head of the source buffer.
	</para>

	<para>
	    To import the class at point, select <menuchoice>
	    <guimenu>JDE</guimenu>
	    <guisubmenu>Wizards</guisubmenu><guimenuitem>Import
	      Class</guimenuitem></menuchoice> from the Emacs menubar
	  or type
	  <keycombo><keysym>C-c</keysym><keysym>C-v</keysym><keysym>C-z</keysym></keycombo>.
	</para> <para> The import wizard searches the current
	  classpath for classes that match the class name at point,
	  which may be unqualified. If the import wizard finds more
	  than one class of the same unqualified name on the current
	  classpath, it prompts you to select one of the classes to
	  import. </para>

	<note>
	  <para>
	    The classpath that the import wizard searches for import
	    candidates is the classpath specified by
	    <varname>jde-global-classpath</varname> when the BeanShell
	    was last started.
	  </para>
	</note>

	<para>
	  The customization variable
	  <varname>jde-wiz-import-excluded-packages</varname> allows
	  you to specify a list of packages to exclude from
	  consideration for import into the current source file. If
	  the import wizard finds any classes on the classpath that
	  belong to the list of prohibited packages, it removes them
	  from the list of classes considered for import.
	</para>

	<note>
	  <title>Thanks to ...</title> 
	  <para><ulink url="mailto:trigg@cs.waikato.ac.nz">Len
	      Trigg</ulink> for contributing the initial
	    implementation of the import wizard.</para>
	</note>


      </sect4>

      <sect4>

	    
	<title><anchor id="MethodOverrideWizard"/>Method Override
	  Wizard</title>

	<para>
	  The method override wizard generates a skeleton method that
	  overrides a similarly named method defined by a superclass.
	</para>

	<para>To override a method of a superclass: </para>

	<orderedlist>

	  <listitem>
	    <para>
	      Position the Emacs point at the location in the buffer
	      where you want the generated method to appear.
	    </para>
	    <para>
	      The point must be within the class that is overriding
	      the   method. 
	    </para>
	    <para>
		<screenshot>
		<mediaobject>
		  <imageobject>
		    <imagedata fileref="images/OverrideMeth1.gif" width="472" depth="328"/>
		  </imageobject>
		  <textobject>
		    <phrase>Screen capture showing point inside a
		      class.</phrase>
		  </textobject>
		</mediaobject>
		</screenshot>
	    </para>
	  </listitem>


	  <listitem>
	    <para>
	      Select
	      <menuchoice><guisubmenu>Wizards</guisubmenu><guimenuitem>Override 
		  Method</guimenuitem>
	      </menuchoice> from the
	      <menuchoice><guimenu>JDE</guimenu>
	      </menuchoice> menu or enter
	      <keycombo><keycap>M</keycap><keycap>x</keycap>
		</keycombo> <varname>jde-wiz-overrided-method</varname>. 
	    </para>
	    <para>
		<screenshot>
		<mediaobject>
		  <imageobject>
		    <imagedata fileref="images/OverrideMeth2.gif"/>
		  </imageobject>
		  <textobject><phrase>Screen shot showing
		      <menuchoice><guimenu>Wizards</guimenu>
		      </menuchoice> menu.</phrase>
		  </textobject>
		</mediaobject>
		</screenshot>
	    </para>

	    <para>
	      The JDE prompts you to enter the name of the method to
	      be overridden in the minibuffer. 
	    </para>
	    <para>
		<screenshot>
		<mediaobject>
		  <imageobject>
		    <imagedata fileref="images/OverrideMeth3.gif"/>
		  </imageobject>
		  <textobject><phrase>Screen shot showing prompt for
		      method name. </phrase>
		  </textobject>
		</mediaobject>
		</screenshot>
	    </para>

	    <para>
	      The name must be the name of a method defined by an
	      ancestor of the class in which the Emacs point is
	      located. The compiled class of the ancestor must be on
	      the classpath specified by
	      <varname>jde-global-classpath</varname>. 
	    </para>
	  </listitem>

	  <listitem>
	    <para>
	      Enter the name of the method to be overridden. 
	    </para>
	    <para>
	      If the  ancestors of the class in which you are
	      overriding the method define more than one method of the
	      same name, the wizard displays a dialog buffer that
	      lists the methods. For example, Java's awt class
	      hierarchy defines several variants of the method
	      <varname>repaint</varname>. If you specify
	      <varname>repaint</varname> as the method to override,
	      the JDE displays the following dialog buffer: 
	    </para>
	    <para>
		<screenshot>
		<mediaobject>
		  <imageobject>
		    <imagedata fileref="images/OverrideMeth4.gif"/>
		  </imageobject>
		  <textobject><phrase>Screen shot showing dialog
		      buffer for selecting method. </phrase>
		  </textobject>
		</mediaobject>
		</screenshot>
	    </para>

	    <para>
	      The dialog buffer lists the signature of each variant of
	      the method you specified. Next to each signature is a
	      radio button. The radio button of the currently selected
	      signature contains an asterisk. To select another
	      signature, right-click the radio button next to the
	      variant. To confirm your selection and dismiss the
	      dialog, right-click the <guibutton>[Ok]</guibutton>
	      button. 
	    </para>

	  </listitem>
	  <listitem>
	    <para>
	      Select the method variant you want to override and click
	      the <guibutton>[Ok]</guibutton> button. 
	    </para>
	    <para>The   wizard inserts a skeleton implementation of
	      the selected method at the current point in the Java
	      source buffer.</para>

	    <para>
		<screenshot>
		<mediaobject>
		  <imageobject>
		    <imagedata fileref="images/OverrideMeth5.gif"/>
		  </imageobject>
		  <textobject><phrase>Screen shot showing the inserted
		      method. </phrase>
		  </textobject>
		</mediaobject>
		</screenshot>
	    </para>

	    <para>
	      The wizard also inserts import statements for any
	      classes referenced by the method that are not already
	      imported by the containing class either explicitly or
	      implicitly. The wizard inserts the import statements at
	      the head of the source buffer after any existing import
	      statements, or any package statement, or the first blank
	      line in the buffer. 
	    </para>
	    <note><para>
		The method override wizard uses the BeanShell to
		create the interface implementation. If the BeanShell
		is not currently running, the wizard starts the
		BeanShell. Thus, if the BeanShell is not already
		running, you may experience a short pause the first
		time you   override a method.
	      </para>
	    </note>
	  </listitem>
	</orderedlist>

      </sect4>

      <sect4>

	    
	<title><anchor id="InterfaceWizard"/>Interface Wizard</title>

	<para>
	  This wizard creates a skeleton implementation of any
	  interface defined on the classpath specified by
	  <varname>jde-global-classpath</varname>.
	</para>

	<para>To create an implementation of an interface: </para>

	<orderedlist>
	  <listitem>
	    <para>
	      If the interface is to be implemented by a new class,
	      create the class in a buffer.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Position the Emacs point at the point in the class where
	      you want the implementation of the interface's methods
	      to appear.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Select
	      <menuchoice><guimenu>JDE</guimenu><guisubmenu>Wizards</guisubmenu>
		<guimenuitem>Implement Interface</guimenuitem>
	      </menuchoice> or enter 
	      <keycombo><keycap>M</keycap><keycap>x
		</keycap></keycombo><varname>jde-wiz-implement-interface</varname>. 
	      
	      
	      
	      
	    </para>
	    <para>
	      The JDE prompts you   to enter the name of the interface
	      to be implemented. 
	    </para>
	  </listitem>
	  <listitem>
	    <para>Enter the fully qualified name of the interface, for
	      example,
	      <classname>java.awt.Event.MouseListener</classname>.</para>
	    <para>
	      The wizard inserts skeleton implementations of the
	      methods declared by the interface at the current point
	      in the current buffer. It inserts import statements for
	      any classes required by the interface at the head of the
	      current buffer (only if import statements do not already
	      exist for the required classes). It also updates or
	      creates an implements clause for the class.
	    </para>
	  </listitem>
	</orderedlist>

	<note><para>
	    The interface wizard uses the BeanShell to create the
	    interface implementation. If the BeanShell is not
	    currently running, it starts the BeanShell. Thus, if the
	    BeanShell is not already running, you may experience a
	    short pause the first time you use the wizard. </para>
	</note>

	<note>
	  <title>Thanks to ...</title>
	  <para><ulink url="mailto:friedman@lmi.net">Eric
	      Friedman</ulink> for creating the framework for the
	    interface, method override, and abstract class wizards and
	    for contributing the initial implementation of the
	    interface wizard.</para>
	</note>
	
      </sect4>

      <sect4>

	   
	<title><anchor id="DelegateWizard"/>Delegate Wizard</title>


	<para>
	  This wizard generates methods that delegate calls to a class
	  in the current buffer to an attribute of the class, i.e., to
	  an object that is a field of the current class. For example,
	  if the current buffer contains class
	  <classname>A</classname> and  <classname>A</classname> has
	  an   attribute, <varname>A.b</varname>, that is an instance
	  of class <classname>B</classname>,  this wizard generates
	  all the public methods of class <classname>B</classname> in
	  <classname>A</classname> and delegates   handling of those
	  methods to <varname>b</varname>.
	</para>

	<note><title>Thanks to...</title>
	  <para>
	    <ulink url="mailto:cfhart@Z-TEL.com">Charles Hart</ulink>
	    for contributing this wizard.
	  </para>
	</note>

      </sect4>

      <sect4>
	<title><anchor id="GetSetWizard"/>Get/Set Wizard</title>

	<para>
	    This wizard generates get and set methods for the private
	  fields of the class at point, but only if the fields do not
	  already have get or set methods. To generate the methods,
	  move point to the point in the class where you want the get
	  and set methods to appear. Then select
	  <menuchoice><guimenu>JDE</guimenu><guisubmenu>Code
	      Generation</guisubmenu>
	    <guisubmenu>Wizards</guisubmenu>
	    <guimenuitem>Generate Get/Set Methods...</guimenuitem>
	  </menuchoice> or enter 
	    <keycombo><keycap>M</keycap><keycap>x  </keycap></keycombo> &nbsp;
	    <varname>jde-wiz-get-set-methods</varname>
	</para>

	<note>
	  <title>Thanks to...</title>
	  <para>
	    <ulink url="mailto:jslopez@forumsys.com">Javier
	      Lopez</ulink> and <ulink
	      url="mailto:sandip.chitale@brokat.com">Sandip
	      Chitale</ulink> for contributing this wizard.
	  </para>
	</note>


      </sect4>

    </sect3>

    <sect3>

	  
	<title><anchor id="CodeTemplates"/>Code Templates</title>

      <sect4>

	    
	    <title><anchor id="BufferTemplates"/>Buffer Templates</title>

	  <para>These commands create buffers containing a skeleton Java class.
	    Each command prompts you to enter the path to a new Java source
	    file. They then create a buffer for the new file and insert a
	    template for a class of the same name as the newly created file.
	    In particular, the command </para>

	  <itemizedlist>
	    <listitem>
	      <para>
		<menuchoice><guimenu>Files</guimenu><guisubmenu>JDE New</guisubmenu><guimenuitem>Class</guimenuitem></menuchoice> creates a buffer containing a generic Java public class.
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		<menuchoice><guimenu>Files</guimenu><guisubmenu>JDE New</guisubmenu><guimenuitem>Console</guimenuitem></menuchoice> creates a buffer containing the main class of a
		Java console application.
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		<menuchoice><guimenu>Files</guimenu><guisubmenu>JDE New</guisubmenu><guimenuitem>Other</guimenuitem></menuchoice> prompts you to create any of the above buffers or a
		custom (user-defined) buffer.
	      </para>
	    </listitem>

	  </itemizedlist>

	  <para>
	    You can create an empty Java class buffer by selecting 
	    <menuchoice><guimenu>Files</guimenu><guisubmenu>Open</guisubmenu></menuchoice> 
	    (<keycombo><keycap>C</keycap><keycap>x</keycap></keycombo>&nbsp;<keysym>f</keysym>) and
	    entering the path for a new file whose root name is the same as
	    the class you want to create and whose extension is <filename>.java.</filename>
	  </para>

	<sect5>
	  <title>Specifying Boilerplate Text</title>

	  <para>
	    You can specify boilerplate text (for example, a copyright
	    notice) to be inserted at the head of class source files
	    created by the JDE. The JDE provides two ways to specify
	    the boilerplate text. The simplest way is to enter the
	    lines of boilerplate text as the value of the
	    customization variable
	    <varname>jde-gen-buffer-boilerplate</varname>. Another way
	    to specify the text is to set the value of the
	    customization variable
	    <varname>jde-gen-boilerplate-function</varname>to a
	    function that generates the boilerplate text. (The default
	    value of this variable is
	    <varname>jde-gen-create-buffer-boilerplate</varname>,
	    which returns the value of the boilerplate variable,
	    <varname>jde-gen-buffer-boilerplate</varname>). The
	    functional approach allows you to generate boilerplate
	    text dynamically by evaluating the appropriate Lisp code.
	    By saving the values of boilerplate variables in project
	    files, you can specify different boilerplate text for each
	    project. 
	  </para>

	</sect5>

	<sect5>
	    <title>Customization Variables</title>

	    <para>The following JDE customization variables control creation of
	      autocoded Java source buffers: 
	    </para>

	    <table>
	      <title></title>
	      <tgroup cols="3">
		<colspec colnum="1"></colspec>
		<colspec colnum="2"></colspec>
		<colspec colnum="3"></colspec>
		<thead>
		  <row>
		    <entry>Variable</entry>
		    <entry>Group</entry>
		    <entry>Usage</entry>
		  </row>
		    </thead>
		<tbody>
		  <row>
		    <entry><varname>jde-gen-class-buffer-template</varname></entry>
		    <entry>Autocode</entry>
		    <entry>Template for a generic public class buffer.</entry>
		  </row>
		  <row>
		    <entry><varname>jde-gen-console-buffer-template</varname></entry>
		    <entry>Autocode</entry>
		    <entry>Template for a console application buffer.</entry>
		  </row>
		  <row>
		    <entry><varname>jde-gen-jfc-app-buffer-template</varname></entry>
		    <entry>Autocode</entry>
		    <entry>Template for a JFC (Swing) application.</entry>
		  </row>
		  <row>
		    <entry><varname>jde-gen-junit-test-class-buffer-template</varname></entry>
		    <entry>Autocode</entry>
		    <entry>Template for a JUnit test case class. This template requires
		    the <ulink url="http://www.junit.org">JUnit</ulink> test framework.</entry>
		  </row>

		  <row>
		    <entry><varname>jde-gen-buffer-templates</varname></entry>
		    <entry>Autocode</entry>
		    <entry>Specifies templates available to create
		      Java buffers.</entry>
		  </row>
		  <row>
		    <entry><varname>jde-gen-buffer-boilerplate</varname></entry>
		    <entry>Autocode</entry>
		    <entry>Specifies lines of text to be inserted
		      at the head of class files.</entry>
		  </row>
		  <row>
		    <entry><varname>jde-gen-boilerplate-function</varname></entry>
		    <entry>Autocode</entry>
		    <entry>Specifies a function that returns a string
		      of boilerplate text. The default value is
		      <varname>jde-gen-create-buffer-boilerplate</varname>, which returns
                      the value of <varname>jde-gen-buffer-boilerplate</varname>.</entry>
		  </row>
		</tbody>
	      </tgroup>
	    </table>

	    <para>
	      See <ulink url="#CustomizingTemplates">Customizing
		Templates</ulink> for information on how to customize
	      the class creation templates. </para>

	</sect5>

      </sect4>

      <sect4>

	    
	<title><anchor id="PointTemplates"/>Point Templates</title>


	<para>The following commands insert templates at the current
	  point in the buffer: </para>

	<itemizedlist>
	  <listitem>
	    <para>
	      <menuchoice><guimenu>JDE</guimenu><guisubmenu>Generate</guisubmenu>
		<guimenuitem>Get/Set Pair </guimenuitem></menuchoice>
		generates an instance variable and a get and set method  .
		for that variable
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <menuchoice><guimenu>JDE</guimenu><guisubmenu>Generate</guisubmenu>
		<guimenuitem>Println </guimenuitem></menuchoice>
	      generates a
	      <programlisting>System.out.println(...);</programlisting> 
	      statement.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <menuchoice><guimenu>JDE</guimenu><guisubmenu>Generate</guisubmenu>
		<guimenuitem>Action </guimenuitem></menuchoice>
		generates and registers an action listener for a
		specified component.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <menuchoice><guimenu>JDE</guimenu><guisubmenu>Generate</guisubmenu>
		<guisubmenu>Listener</guisubmenu><guimenuitem>Window
		</guimenuitem></menuchoice> 
		generates and registers a window listener for a specified
		window.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <menuchoice><guimenu>JDE</guimenu><guisubmenu>Generate</guisubmenu>
		<guisubmenu>Listener</guisubmenu><guimenuitem>Mouse
		</guimenuitem></menuchoice>
		generates and registers a mouse listener for a specified
		component.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <menuchoice><guimenu>JDE</guimenu><guisubmenu>Generate</guisubmenu>
		<guimenuitem>Other </guimenuitem></menuchoice>
		allows you to select any of the above templates or a
		custom (user-defined) template.
	    </para>
	  </listitem>
	</itemizedlist>

	<para>The following variables control generation of code at
	  point: 
	</para>

	<table>
	  <title></title>
	  <tgroup cols="3">
	    <colspec colnum="1"></colspec>
	    <colspec colnum="2"></colspec>
	    <colspec colnum="3"></colspec>
	    <thead>
	      <row>
		<entry>Variable</entry>
		<entry>Group</entry>     
		<entry>Usage</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry><varname>jde-gen-get-set-var-template</varname></entry>
		<entry>Autocode</entry>
		<entry>Defines a get/set method pair template.</entry>
	      </row>
	      <row>
		<entry><varname>jde-gen-listener-action-template</varname></entry>
		<entry>Autocode</entry>
		<entry>Defines an action listener template.</entry>
	      </row>
	      <row>
		<entry><varname>jde-gen-listener-window-template</varname></entry>
		<entry>Autocode</entry>
		<entry>Defines a window listener template.</entry>
	      </row>
	      <row>
		<entry><varname>jde-gen-listener-mouse-template</varname></entry>
		<entry>Autocode</entry>
		<entry>Defines a mouse listener template.</entry>
	      </row>
	      <row>
		<entry><varname>jde-gen-inner-class-template</varname></entry>
		<entry>Autocode</entry>
		<entry>Defines a template for creating a class inside
		  another class or inside an existing source
		  buffer.</entry>
	      </row>
	      <row>
		<entry><varname>jde-gen-code-templates</varname></entry>
		<entry>Autocode</entry>
		<entry>Specifies available code templates.</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>

	<para>See</para>

	<itemizedlist>
	  <listitem>
	    <para>
	      <ulink url="#CustomizingTemplates">Customizing
		Templates</ulink> for information on how to customize
	      templates provided by the JDE.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <ulink url="#CreatingTemplates">Creating
		Templates</ulink> for information on how to create
	      templates from scratch.
	    </para>
	  </listitem>
	</itemizedlist>

      </sect4>

      <sect4>

	   
	<title><anchor id="CustomizingTemplates"/>Customizing
	  Templates</title>

	<para>You can customize the JDE's standard code templates,
	  using the Emacs customization feature. </para>

	<para>To customize an autocode template: </para>

	<orderedlist>
	  <listitem>
	    <para>Select <menuchoice>
		<guimenu>JDE</guimenu>
		<guisubmenu>Options</guisubmenu>
		<guimenuitem>Autocode</guimenuitem></menuchoice></para>
	    <para>The JDE displays a customization buffer containing
	      the autocode templates. </para>
	  </listitem>
	  <listitem>
	    <para>Edit the template to suit your needs.</para> 
	    <para>The JDE uses the template format defined by
	      <filename>tempo.el</filename> to represent class
	      templates. Each template consists of a list of strings,
	      symbols, and functions, each of which represents content
	      to be inserted successively into the buffer at the
	      current point. The strings represent fixed content. The
	      symbols and functions represent variable content. See
	      the docstring for the function
	      <varname>tempo-define-template</varname> for more
	      information, including the meaning of special symbols
	      such as <varname>'n</varname>. </para>
	  </listitem>
	  <listitem>
	    <para>Select the state button associated with the
	      template.</para> 
	    <para>A menu pops up with a list of options for saving
	      your changes. </para>
	  </listitem>
	  <listitem>
	    <para>Save your changes.</para> 
	    <para>Select 
	      <menuchoice><guimenuitem>Save for Future
		  Sessions</guimenuitem></menuchoice> if you want 
		your changes to apply to all projects. If you want your changes to apply
	      only to the current projects, select <menuchoice>
		<guimenuitem>Set for Current
		  Session</guimenuitem></menuchoice>. Then select 
	      <menuchoice>
		<guimenu>JDE</guimenu>
		<guisubmenu>Options</guisubmenu>
		<guimenuitem>Save Project</guimenuitem></menuchoice>
	      to save your changes in the current project's project
	      file.</para>
	  </listitem>
	</orderedlist>

      </sect4>

      <sect4>

	    
	    <title><anchor id="CreatingTemplates"/>Creating Templates</title>

	  <para>The JDE considers any command (interactive function) that
	    inserts code into a buffer at point to be a template. The JDE
	    uses the Emacs tempo library to create built-in templates.
	    You can use tempo to create your own, add-on templates (see below
	    and the doc for the <varname>tempo-define-template </varname>for
	    more information) or create templates from scratch.
	    In either case, once you have created a template, you can add it
	    to the JDE's lists of available code and/or buffer templates, 
	    using the JDE's <varname>jde-gen-code-templates</varname> and/or 
	    <varname>jde-gen-buffer-templates</varname>
	    variables, respectively. Adding a template to these lists enables
	    you to invoke the templates from the JDE menus. When adding a
	    template, you need to specify a unique title for the template.
	    These titles enable you to specify the templates when invoking
	    them, using the JDE's custom code template commands  
	    (<menuchoice><guimenu>Files</guimenu>
	      <guisubmenu>JDE New</guisubmenu>
	      <guimenuitem>Custom</guimenuitem></menuchoice>  and  
	    <menuchoice><guimenuitem>JDE</guimenuitem>
	      <guisubmenu>Generate</guisubmenu>
	      <guimenuitem>Custom</guimenuitem></menuchoice>). You can use
	    auto completion to enter a template title when invoking a custom
	    code generation command. Note that you can specify different sets
	    of templates for different projects, by setting and saving the
	    template list variables in project files. See the following
	    sections for more information: </para>

	  <itemizedlist>
	    <listitem>
	      <para><ulink url="#DefiningTemplate">Defining a Template and
		  Template Insertion Function</ulink></para>
	    </listitem>
	    <listitem>
	      <para><ulink url="#RegisterTemplate">Registering Custom
		  Templates</ulink></para>
	    </listitem>
	    <listitem>
	      <para><ulink url="#AssignKeyToTemplate">Assigning Keys To
		  emplates</ulink></para>
	    </listitem>
	  </itemizedlist>

	  <sect5>

	      
	  <title><anchor id="DefiningTemplate"/>Defining a Template
	    and Template Insertion Function</title>


	  <para>The <varname>tempo-define-template</varname> macro
	    enables you to define a template and a function that
	    inserts that template at the current point in the current
	    buffer. You specify the template as a list oftemplate
	    elements where each element is text, a special symbol, or
	    a Lisp expression. The function inserts each text element
	    exactly as specified in the buffer; it replaces special
	    symbols with some text (e.g., user input), and it replaces
	    Lisp expressions with the text that results from
	    evaluating them. </para>

	  <para>For example, the following Lisp code </para>

	  <programlisting>
	    (tempo-define-template &quot;foo&quot;
	    ;; template name
	    '(&quot;System.out.println(\&quot;foo\&quot;);&quot;)
	    ;;template definition &quot;f&quot;
	    ;; abbreviation &quot;Inserts a print foo message&quot;)
	    ;; template documentation
	  </programlisting>

	  <para>defines a template for Java code that always prints
	    &quot;foo&quot; to standard out: </para>

	  <programlisting>
	    System.out.println(&quot;foo&quot;);
	  </programlisting>

	  <para>Notice that the template definition uses the Lisp
	    string escape character to specify the string
	    &quot;foo&quot;.  This is necessary when you want to
	    include quoted strings in a template definition.)
	  </para>

	  <para>The sample Lisp form also defines an interactive
	    template function <varname>tempo-template-foo</varname>.
	    Now suppose you insert the sample code in your
	    <filename>.emacs</filename> file. After Emacs starts up,
	    whenever you enter the command <keycombo>
	      <keycap>M</keycap><keycap>x</keycap></keycombo>
	    <varname>tempo-template-foo,</varname> Emacs inserts
	  </para>

	  <programlisting>
	    System.out.println(&quot;foo&quot;);
	  </programlisting>

	  <para>at the current point in your Java source buffer (or
	    any buffer, tempo doesn't care). </para>

	  <para>The preceding example is admittedly not vary useful
	    because it always prints the same text. You can create
	    more useful templates, using special tempo template
	    symbols and lisp forms. This approach, for example, allows
	    you to create a template that can print any user-defined
	    text to standard out: </para>

	  <programlisting>
	    (tempo-define-template &quot;debug&quot;
	    ;; template name '(&quot;if (debug)&quot; n&gt;
	    ;; insert new line plus indent
	    &quot;System.out.println(&quot; (p &quot;Enter debug
	    message:&quot;)       ;; Prompts for debug message
	    &quot;);&quot;) &quot;d&quot;
	    ;; abbreviation &quot;Inserts a print debug message&quot;)
	    ;; template documentation 
	  </programlisting>

	  <para>The template function produced by this example prompts
	    you to enter the text to be printed when inserting the
	    function into a buffer. In particular, it inserts </para>

	  <programlisting>
	    if (debug) System.out.println(DEBUG-MESSAGE);
	  </programlisting>

	  <para>where <varname>DEBUG-MESSAGE</varname> is any text
	    that you enter. For example, suppose you enter </para>

	  <programlisting>
	    &quot;Selected color = &quot; + color
	  </programlisting>

	  <para>at the prompt. The template function inserts </para>

	  <programlisting>
	    if (debug) System.out.println(&quot;Selected color =
	    &quot; + color);
	  </programlisting>

	  <para>at the current point in the buffer. </para>

	  <para>See the documentation for
	    <varname>tempo-define-template</varname> (type
	    <keycombo><keycap>c</keycap><keycap>h</keycap></keycombo>&nbsp;<keysym>f</keysym>&nbsp;
	      <varname>tempo-define-template</varname>) for more
	    information on creating templates. </para>

	</sect5>

	<sect5>

	      
	  <title><anchor id="RegisterTemplate"/>Registering Custom
	    Templates</title>


	  <para>You can register templates that you create with the
	    JDE. When you register a template with the JDE, it appears
	    among the list of templates that you can select when you
	    select <menuchoice>
	      <guimenu>JDE</guimenu><guisubmenu>Generate</guisubmenu>
	      <guimenuitem>Other....</guimenuitem></menuchoice>. You
	    register a template by customizing the JDE variable
	    <varname>jde-gen-code-templates</varname>. The value of
	    this variable is a list of the template functions that the
	    JDE command  <menuchoice>
	      <guimenu>JDE</guimenu><guisubmenu>Generate</guisubmenu>
	      <guimenuitem>Other....</guimenuitem></menuchoice> can
	    invoke. To register a custom template, add its name to the
	    list. For example, the following screen shows the
	    customization buffer for
	    <varname>jde-gen-code-templates</varname> after it has
	    been customized to include the template defined in the
	    previous example. </para>

	  <para>
	      <screenshot>
	      <mediaobject>
		<imageobject>
		  <imagedata fileref="images/RegisterTemplate.gif"/>
		</imageobject>
		<textobject>
		  <phrase>Screenshot showing customization buffer for
		    registering templates.</phrase>
		</textobject>
	      </mediaobject>
	      </screenshot>
	  </para>

	  <para>To insert a template that you have registered </para>

	  <procedure>
	    <step performance="required">
	      <para>Select <menuchoice>
		  <guimenu>JDE</guimenu><guisubmenu>Generate</guisubmenu>
		  <guimenuitem>Other....</guimenuitem></menuchoice></para>
	      <para>The JDE displays the prompt</para>
	      <programlisting>
		Enter template:
	      </programlisting>
	      <para>in the minibuffer. </para>
	    </step>
	    <step>
	      <para>Enter the template's name and press
		<keycap>Enter</keycap></para>
	      <para>or,</para>
	      <para>press the <keycap>Tab</keycap> key to display a
		list of templates in a completion buffer: </para>
	      <para>
		  <screenshot>
		  <mediaobject>
		    <imageobject>
		      <imagedata fileref="images/TemplateList.gif"/>
		    </imageobject>
		    <textobject>
		      <phrase>Screenshot showing template completion
			buffer.</phrase>
		    </textobject>
		  </mediaobject>
		  </screenshot>
	      </para>
	      <para>Select the template you want by double-clicking
		its name.</para>

	    </step>
	  </procedure>

	</sect5>

	<sect5>

	      
	  <title><anchor id="AssignKeyToTemplate"/>Assigning Keys to
	    Templates</title>

	  <para>You can assign templates to keyboard keys to speed use
	    of frequently used templates. For example, insert this
	    form </para>

	  <programlisting>
	    (global-set-key [f9] 'jde-gen-to-string-method)
	  </programlisting>

	  <para>in your <filename>.emacs</filename> file to assign the
	    <keycap>F9</keycap> function key to the JDE template that
	    generates a skeleton <varname>toString</varname> method.
	  </para>

	</sect5>
      </sect4>
    </sect3>
    
  </chapter>

  <chapter>
    <title><anchor id="CheckStyle"/>Checking Coding Style</title>
    <para>The <menuchoice>
	<guimenu>JDE</guimenu>
	<guimenuitem>Check Style</guimenuitem>
      </menuchoice> command (<keycombo>
	<keysym>M</keysym>
	<keysym>x</keysym>
      </keycombo> <command>jde-checkstyle</command>) command checks
      the current buffer for conformity to a Java coding standard. The
      default standard is that specified by Sun Microsystems. Execute
      <command>jde-checkstyle-customize</command> to customize the
      command to support your own coding standard.
    </para>
    <para>The command displays a list of stylistic faults in a popup
    buffer. Click the error message to display the line that violates
    the standard.</para>
  </chapter>

  <chapter>
    <title><anchor id="CompilingJavaPrograms"/>Compiling Java Programs</title>
      
    <para>To compile the source file in the current buffer, select
      <menuchoice>
	<guimenuitem>JDE</guimenuitem>
	<guimenuitem>Compile</guimenuitem></menuchoice>, type
      <keycombo>
	<keycombo>
	  <keycap>C</keycap>
	  <keycap>c</keycap></keycombo><keycombo>
	  <keycap>C</keycap><keycap>v</keycap></keycombo>
	<keycombo>
	  <keycap>C</keycap><keycap>c</keycap></keycombo></keycombo>,
      or execute <command>M-x jde-compile</command>. The compiler uses
      the version of <filename>javac</filename> included in the
      currently selected JDK or on your system command path by
      default. However, you can configure the JDEE to use another
      compiler for the current project or all projects (see <ulink
	url="#SpecifyingCompiler">Specifying a Compiler</ulink>). The
      JDEE also allows you to configure the JDEE to invoke the
      compiler with various <ulink
	url="#CompilationOptions">compilation options</ulink>.
    </para>

    <sect3>

      <title><anchor id="CompileBuffer"/>Compilation Buffer</title>

      <para>
	The compile command displays the output of the compiler in a
	separate compilation buffer.
      </para>

      <screenshot>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="images/compile_buffer.gif"/>
	  </imageobject>
	  <textobject>
	    <phrase>Image showing compilation buffer with
	      errors.</phrase>
	  </textobject>
	</mediaobject>
      </screenshot>

      <para>
	If a compilation buffer does not exist, the compile command
	creates the buffer; otherwise, it reuses the existing compile
	output buffer. The compilation buffer operates in
	<varname>compilation-mode</varname>, a standard Emacs buffer
	mode. This mode greatly simplify locating compilation errors
	in the Java source code. For example, to find the line that
	cause a compilation error, simply click the error message in
	the compilation buffer. 
      </para>
    
    </sect3>

    <sect3>
      <title><anchor id="SpecifyingCompiler"/>Specifying a Compiler</title>

      <para>The JDEE supports the following Java compilers.</para>

      <itemizedlist>
	<listitem>
	  <para><filename>javac</filename></para>
	  <para>
	    This is the compiler that comes with Sun's JDK and the
	    JDK's clones. Note that <filename>javac</filename>
	    compiler is itself implemented in Java. The
	    <filename>javac</filename> executable that comes with the
	    JDK simply starts a vm to run <filename>javac</filename>.
	    The executable passes its command-line arguments to
	    <filename>javac</filename>'s main method.
	  </para>
	</listitem>
	<listitem>
	  <para>javac compile server</para>
	  <para>This is a JDEE feature that uses the BeanShell to
	  invoke the javac compiler on a source file, thus avoiding
	  the need to start a vm everytime you want to compile
	  a file. This option greatly reduces the time required
	  to compile individual files by eliminating the vm startup
	  time, which is usually much longer than the time required
	  to compile a file.</para>
	</listitem>
	<listitem>
	  <para><filename>jikes</filename></para>
	  <para>
	    Developed by IBM, this compiler is implemented in
	  C++ and hence avoids the vm startup time that slows
	  down javac.
	  </para>
	</listitem>
      </itemizedlist>
      


      <para>
	To specify one of these compilers for the current project or
	all projects:
</para>

      <orderedlist>
	<listitem>
	  <para>Type <command>M-x customize-variable</command> and
	    press <command>Enter</command></para>
	  <para>Emacs prompts you to enter the name of a variable
	  to customize.</para>
	</listitem>
	<listitem>
	  <para>Enter <varname>jde-compiler</varname> and
	  press <command>Enter</command>.</para>
	  <para>The <varname>jde-compiler</varname> customization
	  buffer appears.</para>
	  <screenshot>
	    <mediaobject>
	      <imageobject>
		<imagedata fileref="images/spec_compiler.gif"/>
	      </imageobject>
	    </mediaobject>
	  </screenshot>
	</listitem>
	<listitem>
	  <para>Select the compiler that you want to use for the
	  current project or all projects.</para>
	  <para>
	    You can skip the next step if you selected the compile server
	    or if you selected javac and you want to use the version of
	    javac that comes with the currently selected JDK, or you have
	    selected the javac executable or jikes and the executable for
	    the selected compiler is in your system's command path.
	  </para>
	</listitem>
	<listitem>
	  <para>Enter the path to the executable for the selected
	    compiler.
	  </para>
	</listitem>
	<listitem>
	  <para>If you want your selection to apply only to the current
	    project, select <command>Save for Current Session</command>
	    from the <command>State</command> menu. Otherwise select
	    <command>Save for Future Sessions</command>.</para>
	</listitem>
	<listitem>
	  <para>Select <command>Finish</command> to dismiss the
	  customization buffer.</para>
	</listitem>
	<listitem>
	  <para>If you want the selection to apply to the current
	    project, select <command>Project-&gt;Project
	      File-&gt;Save</command> from the <command>JDE</command>
	    menu.</para>
	</listitem>
      </orderedlist>
    </sect3>

    <sect3>

      <title><anchor id="CompilationOptions"/>Compilation Options</title>
	
      <para>The JDEE allows you to specify compilation options by
	setting  compilation variables. You must use the Emacs
	customization feature. To use the customization feature,
	select <menuchoice>
	  <guimenu>JDE</guimenu>
	  <guisubmenu>Options</guisubmenu>
	  <guimenuitem>Compile</guimenuitem></menuchoice>.  (See
	<ulink url="#ConfiguringJDE">Configuring  the JDEE</ulink> for
	more information on using the customization  feature). To save
	the compilation settings in the project  file 
	(see <ulink
	  url="#UsingProjectFiles">Using Project Files</ulink>)  
	for the current source buffer, select <menuchoice>
	  <guimenuitem>JDE</guimenuitem>
	  <guisubmenu>Options</guisubmenu>
	  <guimenuitem>Update  Project</guimenuitem></menuchoice>.
      </para>
      
      <sect4>

	  
	<title><anchor id="SetCompileOptionsInteractively"/> Setting
	  Compile Options Interactively</title>
	
	<para>If you set the customization variable
	  <varname>jde-read-compile-args</varname>  to a
	  non-<varname>nil</varname> value, the JDEE compile command
	  prompts you to enter compilation options in the minibuffer.
	  It appends the  options that you enter to the options
	  specified via customization  variables. The JDEE saves the
	  arguments that you enter in a  minibuffer history list. You
	  can recall previously entered  options by pressing the up or
	  down arrows on your keyboard. </para>
	
	<note>
	  <para>The JDEE uses the values of the JDEE customization
	    variables to set the compiler's command-line option
	    switches. The JDEE assumes that the compiler you are using
	    (specified by the  customization variable
	    <varname>jde-compiler</varname>) has the same set of
	    command-line switches as the version of
	    <varname>javac</varname> or jikes that you have selected.
	    If the command-line  switch for a particular option
	    supported by the compiler  your are using is not the same
	    as that specified by <varname>javac</varname> or jikes,
	    you must use the variable
	    <varname>jde-compile-option-command-line-args</varname> to
	    select the option.</para>
	</note>
      </sect4>

      <sect4>

	  
	<title><anchor id="CompilerCustomizationVariables"/>
	  Compiler Customization Variables</title>
	
	<para>The following table lists the JDEE compilation variables and
	  the functions used to set them.</para>
	
	<table>
	  <title></title>
	  <tgroup cols="3">
	    <colspec colnum="1" align="left"/>
	    <colspec colnum="2" align="left"/>
	    <colspec colnum="3" align="left"/>
	    <thead>
	      <row>
		<entry><para>Name</para></entry>
		<entry><para>Group</para></entry>
		<entry><para>Usage</para></entry>
	      </row>
	    </thead>
	    <tbody valign="top">
	      <row>
		<entry><para><varname>jde-compiler</varname></para></entry>
		<entry>Project</entry>
		<entry>
		  <para>Specifies the compiler (javac server, by default)
		    to use to compile the code in  the current source buffer.
		  </para>
		</entry>
	      </row>
	      <row>
		<entry>
		  <para>
		    <varname>jde-compile-option-command-line-args</varname>
		  </para>
		</entry>
		<entry >Compile</entry>
		<entry >Specifies a string of
		  command-line arguments to be passed to the compiler.</entry>
	      </row>
	      <row>
		<entry ><varname>jde-global-classpath</varname></entry>
		<entry >Project</entry>
		<entry >Specify class paths
		  for compile, run, and debug commands.</entry>
	      </row>
	      <row>
		<entry ><varname>jde-read-compile-args</varname></entry>
		<entry >Project</entry>
		<entry >Specify whether to read compile
		  options from the minibuffer.</entry>
	      </row>
	      <row>
		<entry ><varname>jde-compile-option-classpath</varname></entry>
		<entry >Compile&nbsp;</entry>
		<entry >Specifies the
		  classpath for compile command. If set, this variable
		  overrides <varname>jde-global-classpath</varname>.&nbsp;</entry>
	      </row>
	      <row>
		<entry ><varname>jde-compile-option-sourcepath</varname></entry>
		<entry  >Compile</entry>
		<entry >Specifies the path of source files
		  for classes required to compile the current class.</entry>
	      </row>
	      <row>
		<entry ><varname>jde-quote-classpath</varname></entry>
		<entry >Project&nbsp;</entry>
		<entry >Quote the classpath
		  argument.</entry>
	      </row>
	      <row>
		<entry ><varname>jde-compile-option-directory</varname></entry>
		<entry >Compile&nbsp;</entry>
		<entry >Specifies the
		  directory into which to place the compiled class.&nbsp;</entry>
	      </row>
	      <row>
		<entry ><varname>jde-compile-option-deprecation</varname></entry>
		<entry >Compile&nbsp;</entry>
		<entry >Warn of use or
		  override of a deprecated member or class&nbsp;</entry>
	      </row>
	      <row>
		<entry ><varname>jde-compile-option-debug</varname></entry>
		<entry >Compile&nbsp;</entry>
		<entry >Generate information
		  about local variables for debug tools.&nbsp;</entry>
	      </row>
	      <row>
		<entry ><varname>jde-compile-option-optimize</varname></entry>
		<entry >Compile&nbsp;</entry>
		<entry >Directs the compiler
		  to try to generate faster varname.&nbsp;</entry>
	      </row>
	      <row>
		<entry ><varname>jde-compile-option-depend</varname></entry>
		<entry >Compile</entry>
		<entry >Analyze dependencies.</entry>
	      </row>
	      <row>
		<entry ><varname>jde-compile-option-depend-switch</varname></entry>
		<entry >Compile</entry>
		<entry >Command line switch that causes the
		  compiler to analyze dependencies.</entry>
	      </row>
	      <row>
		<entry ><varname>jde-compile-option-vm-args</varname></entry>
		<entry >Compile&nbsp;</entry>
		<entry >Specify command-line
		  arguments for Java interpreter used to run the compiler.&nbsp;</entry>
	      </row>
	      <row>
		<entry ><varname>jde-compile-option-verbose-path</varname></entry>
		<entry >Compile&nbsp;</entry>
		<entry >Print verbose messages.</entry>
	      </row>
	      <row>
		<entry ><varname>jde-compile-option-verbose</varname></entry>
		<entry >Compile</entry>
		<entry >List directories searched to
		  compile current class.</entry>
	      </row>
	      <row>
		<entry ><varname>jde-compile-option-nowarn</varname></entry>
		<entry >Compile&nbsp;</entry>
		<entry >Turn off warnings.</entry>
	      </row>
	      <row>
		<entry ><varname>jde-compile-option-encoding</varname></entry>
		<entry >Compile&nbsp;</entry>
		<entry >Specify the source
		  file encoding name, such as EUCJIS\SJIS.&nbsp;</entry>
	      </row>
	      <row>
		<entry ><varname>jde-compile-option-target</varname></entry>
		<entry >Compile</entry>
		<entry >Generate code compatible with a
		  specified vm version.</entry>
	      </row>
	      <row>
		<entry ><varname>jde-compile-option-bootclasspath</varname></entry>
		<entry >Compile</entry>
		<entry>Specify classpath of standard
		  libraries for target vm.</entry>
	      </row>
	      <row>
		<entry><varname>jde-compile-option-bootclasspath</varname></entry>
		<entry>Compile</entry>
		<entry>Specify path of directories
		  containing extensions for target vm.</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>
      </sect4>
    </sect3>
  </chapter>

  <chapter>

    <title><anchor id="BuildingJavaApplications"/>Building Java Applications</title>
      
    <para>The <menuchoice>
	<guimenu>JDE</guimenu><guimenuitem>Build</guimenuitem></menuchoice>
      command builds an application. By default this command invokes the
      Unix-style make utility to build the application. You can configure
      the build command to invoke the Ant build system or a custom build
      function.
    </para>

    <sect3>
      <title><anchor id="SelectBuildMethod"/>Selecting a Build Method</title>

      <para>To select a build method:</para>

      <orderedlist>
	<listitem>
	  <para>Type <command>M-x customize-variable</command> and
	    press <command>Enter</command></para>
	  <para>Emacs prompts you to enter the name of a variable
	  to customize.</para>
	</listitem>
	<listitem>
	  <para>Enter <varname>jde-build-function</varname> and
	  press <command>Enter</command>.</para>
	  <para>The <varname>jde-build-function</varname> customization
	  buffer appears.</para>
	  <screenshot>
	    <mediaobject>
	      <imageobject>
		<imagedata fileref="images/build_fcn_cust_buff.gif"/>
	      </imageobject>
	    </mediaobject>
	  </screenshot>
	</listitem>
	<listitem>
	  <para>Select the build function that you want to use.</para>
	</listitem>
	<listitem>
	  <para>If you want your selection to apply only to the current
	    project, select <command>Save for Current Session</command>
	    from the <command>State</command> menu. Otherwise select
	    <command>Save for Future Sessions</command>.</para>
	</listitem>
	<listitem>
	  <para>Select <command>Finish</command> to dismiss the
	  customization buffer.</para>
	</listitem>
	<listitem>
	  <para>If you want the selection to apply to the current
	    project, select <command>Project-&gt;Project
	      File-&gt;Save</command> from the <command>JDE</command>
	    menu.</para>
	</listitem>
      </orderedlist>
     </sect3>

    <sect3>

      <title><anchor id="BuildWithMake"/>Building with Make</title>

      <para>
	The <command>jde-make</command> command uses a make utility,
	such as  GNU make, to rebuild a project. You must supply the
	makefiles used to build your projects. See <ulink
	  url="#SampleMakefile">Sample Makefile</ulink> for an example
	of a makefile for building a Java project. David Ponce's
	<ulink
	  url="http://perso.wanadoo.fr/david.ponce/">JMaker</ulink>
	package generates makefiles automatically for JDEE projects.
	It uses JDEE variables to determine classpaths, compiler
	options, and other information needed to create projects.
	JMaker recursively creates makefiles for all the Java packages
	in a project plus a toplevel makefile that invokes the other
	makefiles to build the entire project.
      </para>

      <sect4>

	
	<title><anchor id="MakeOptions"/>Make Options</title>

	
	<para>
	  The following customization variables  allow you to specify
	  various <command>jde-make</command> options:
	</para>
      
	<table>
	  <title></title>
	  <tgroup cols="4">
	    <colspec colnum="1" align="left"/>
	    <colspec colnum="2" align="left"/>
	    <colspec colnum="3" align="left"/>
	    <colspec colnum="4" align="left"/>
	    <thead>
	      <row>
		<entry>Name</entry>
		<entry>Group</entry>
		<entry>Default</entry>
		<entry>Usage</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry
		  valign="top"><varname>jde-make-program</varname></entry>
		<entry valign="top">Project</entry>
		<entry>make</entry>
		<entry>
		  <para>Specifies the pathname on your system of the
		    make utility that the <command>jde-make</command>
		    uses to build your project. </para>
		</entry>
	      </row>
	      <row>
		<entry
		  valign="top"><varname>jde-make-args</varname></entry>
		<entry valign="top">Project</entry>
		<entry></entry>
		<entry>
		  <para> Specifies a string of command-line arguments
		    (for  example, &quot;<varname>-f mymakefile
		      all</varname>&quot;) to be passed to  the make
		    utility. </para>
		</entry>
	      </row>
	      <row>
		<entry
		  valign="top"><varname>jde-read-make-args</varname></entry>
		<entry valign="top">Project</entry>
		<entry><varname>nil</varname></entry>
		<entry>
		  <para> If nonnil, this variable causes the
		    <command>jde-make</command> command to prompt you
		    to enter command-line arguments in the minibuffer.
		    <command>jde-make</command> passes these arguments
		    along with the arguments specified by
		    <varname>jde-make-args</varname> to the make
		    utility. </para>
		</entry>
	      </row>
	      <row>
		<entry
		  valign="top"><varname>jde-make-working-directory</varname></entry>
		<entry valign="top">Project</entry>
		<entry></entry>
		<entry>
		  <para> Specifies the directory from which
		    <command>jde-make</command> runs the make utility.
		  </para>
		</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>

      </sect4>
 
      <sect4>

	 
	<title><anchor id="SampleMakefile"/>Sample Makefile</title>
	  
	<para>The following is a sample makefile that you can use as a
	  model for creating makefiles to build Java projects. </para>
	
	<programlisting>
	  JDK = d:/jdk1.2/lib/classes.zip 
	  JMATH = d:/jmath/src
	  CLASSPATH = $(JMATH);$(JDK) 
	  COMPILER = javac VM = java
	  COPTIONS = -g -deprecation 
	  ROPTIONS = 
          CLASSES = Test.class \
	            JMathError.class \ 
                    JMathException.class \ 
                    LinearSystem.class

	  .SUFFIXES: .java .class 
          all : $(CLASSES) 
            # Rebuild (if necessary) and run the JMath test suite. run: $(CLASSES)
	    $(VM) -classpath &quot;$(CLASSPATH)&quot; jmath.Test 

          # Remove all class files from the project directory. 
          clean: rm *.class 
          
          # Implicit rule for making Java class files from Java 
          # source files. 
          .java.class: $(COMPILER) $(COPTIONS) -classpath &quot;$(CLASSPATH)&quot; $? 
	</programlisting>
      </sect4>

    </sect3>

    <sect3>

      <title><anchor id="BuildWithAnt"/>Building with Ant</title>

      <para>
	The <command>jde-ant-build</command> command uses the <ulink
	  url="http://jakarta.apache.org/ant/">Apache Ant</ulink>
	build tool to build a Java project.
      </para>

      <para>The following variables allow you to control the build
	process.</para>

      <table>
	<title>Ant Options</title>
	<tgroup cols="4">
	  <colspec colnum="1" align="left"/>
	  <colspec colnum="2" align="left"/>
	  <colspec colnum="3" align="left"/>
	  <colspec colnum="4" align="left"/>
	  <thead>
	    <row>
	      <entry>Name</entry>
	      <entry>Group</entry>
	      <entry>Default</entry>
	      <entry>Usage</entry>
	    </row>
	  </thead>
	  <tbody>
	    <row>
	      <entry
		valign="top"><varname>jde-ant-invocation-method</varname></entry>
	      <entry valign="top">Ant</entry>
	      <entry>script</entry>
	      <entry>
		<para> Specifies how to invoke ant. Ant can be invoked
		  in one of three ways. The first is via the ant
		  script/program that comes with ant. The second is
		  via java and the third is via the Ant Server.
		</para>
	      </entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-ant-home</varname></entry>
	      <entry valign="top">Ant</entry>
	      <entry></entry>
	      <entry>
		<para> Directory where ant is installed. </para>
	      </entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-ant-user-jar-files</varname></entry>
	      <entry valign="top">Ant</entry>
	      <entry><varname>nil</varname></entry>
	      <entry>
		<para> Specifies jar files that hold user-defined
		  tasks. </para>
	      </entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-ant-program</varname></entry>
	      <entry valign="top">Ant</entry>
	      <entry><para>ant</para></entry>
	      <entry>
		<para> Specifies name of ant program/script. </para>
	      </entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-ant-args</varname></entry>
	      <entry valign="top">Ant</entry>
	      <entry><para>-emacs</para></entry>
	      <entry>
		<para> Specifies arguments to be passed to the Ant
		  program. </para>
	      </entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-ant-buildfile</varname></entry>
	      <entry valign="top">Ant</entry>
	      <entry><para>build.xml</para></entry>
	      <entry>
		<para> Specifies the default buildfile to use. </para>
	      </entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-ant-read-buildfile</varname></entry>
	      <entry valign="top">Ant</entry>
	      <entry><para>off</para></entry>
	      <entry>
		<para> Specify whether to prompt for a buildfile. If
		  non-nil, the jde-ant-build command prompts you for
		  an ant buildfile.  Note that
		  <varname>jde-ant-read-buildfile</varname> and
		  <varname>jde-ant-enable-find</varname> are
		  incompatible and that
		  <varname>jde-ant-read-buildfile</varname> will
		  override the former. </para>
	      </entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-ant-read-target</varname></entry>
	      <entry valign="top">Ant</entry>
	      <entry><para>off</para></entry>
	      <entry>
		<para> Specify whether to prompt for a build target.
		  If non-nil, the jde-ant-build command prompts you
		  for an ant target. </para>
	      </entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-ant-interactive-buildfile</varname></entry>
	      <entry valign="top">Ant</entry>
	      <entry><para>off</para></entry>
	      <entry>
		<para> Default buildfile to use when prompting
		  interactively. </para>
	      </entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-ant-read-args</varname></entry>
	      <entry valign="top">Ant</entry>
	      <entry><para>off</para></entry>
	      <entry>
		<para> Specify whether to prompt for additional
		  arguments to pass to Ant. If non-nil, the
		  <command>jde-ant-build</command> command prompts you
		  for the additional arguments. </para>
	      </entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-ant-enable-find</varname></entry>
	      <entry valign="top">Ant</entry>
	      <entry><para>off</para></entry>
	      <entry>
		<para> Specify whether jde-ant find the
		  <filename>build.xml</filename> file based on your
		  current directory. If non-nil, we will search up the
		  directory hierarchy from the current directory for
		  the build definition file. Also note that, if
		  non-nil, this will relax the requirement for an
		  explicit jde project file.  In order for this to
		  work <varname>jde-ant-read-buildfile</varname> must
		  be nil.</para>
	      </entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-ant-complete-target</varname></entry>
	      <entry valign="top">Ant</entry>
	      <entry><para>off</para></entry>
	      <entry>
		<para> Specify whether to enable completion of build
		  target names in the minibuffer. If non-nil, the
		  <command>jde-ant-build</command> command allows you
		  to use tab completion in the minibuffer to specify
		  the build target name.  This list of valid build
		  targets is determined by parsing the Ant build file.
		  This option has no effect if
		  <varname>jde-ant-read-target</varname> is
		  nil.</para>
	      </entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-ant-use-global-classpath</varname></entry>
	      <entry valign="top">Ant</entry>
	      <entry><para>off</para></entry>
	      <entry>
		<para>Specify whether to enable use of
		  <varname>jde-global-classpath</varname> when running
		  <filename>jde-ant</filename>.</para>
	      </entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-ant-target-regexp</varname></entry>
	      <entry valign="top">Ant</entry>
	      <entry>
		<para>
		  &lt;\s-*target\s-[^...]*?name\s-*=\s-*\"\s-*\([^\"]+\) 
		</para>
	      </entry>
	      <entry>
		<para>Regular expression used to match target names in
		  Ant build files.</para>
	      </entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-ant-build-hook</varname></entry>
	      <entry valign="top">Ant</entry>
	      <entry><para>nil</para></entry>
	      <entry>
		<para>List of hook functions run by
		  <command>jde-ant-build</command> (see
		  <varname>run-hooks</varname> in the Emacs
		  documentation for more information).</para>
	      </entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>

    </sect3>
    
  </chapter>

  <chapter>

      
    <title><anchor id="RunningJavaApps"/>Running Java
      Applications</title>

      
    <para>The JDE allows you to run a Java application as an Emacs
      subprocess. You can run multiple applications concurrently, but
      only one instance of each application at a time. The JDE
      displays each application's standard and error output in an
      Emacs command interface (<varname>comint</varname>) buffer. You
      can interact with applications that accept command line input
      via the <varname>comint</varname> buffer. When interacting with
      an application, you can use any of
      <varname>comint-mode</varname>'s extensive set of command-line
      history commands to speed interaction. To run an application,
      enter </para>
    
    <programlisting>
      M-x jde-run
    </programlisting>
    
    <para>or select <menuchoice><guimenu>Java</guimenu>
	<guimenuitem>Run App</guimenuitem></menuchoice> from the Emacs
      menubar or type <keycombo>
	<keycap>C</keycap><keycap>c</keycap></keycombo>&nbsp;<keycombo>
	<keycap>C</keycap><keycap>v</keycap></keycombo>&nbsp;<keycombo>
	<keycap>C</keycap><keycap>r</keycap></keycombo>. </para>
    
    <sect3>
      <title><anchor id="SpecifyingMainClass"/>Specifying the
	Application's Main Class</title>

      <para>The term <emphasis>main class</emphasis> refers to the
	class that contains the application's main method. The JDE's
	Run App command assumes by default that the class in the
	current buffer is the application's main class. This can be
	inconvenient if you have an application that has multiple
	classes. You may want to be able to run the application from
	any buffer containing one of the application's classes. To do
	this, set the variable
	<varname>jde-run-application-class</varname> to the
	<emphasis>fully qualified name</emphasis> of the application's
	main class.</para>

      <para>You can temporarily override the setting of
	<varname>jde-run-application-class</varname> by typing
	<varname>C-u -</varname> before executing the <command
	  moreinfo="none">jde-run</command> command, for example, by
	typing <varname>C-u - C-c C-r</varname>. This causes the JDE to
	prompt you to enter the <emphasis>fully qualified
	  name</emphasis> of the application's main class (as well
	application arguments if any).</para> 

    </sect3>

    <sect3>


	
      <title><anchor id="SpecifyingStartupDirectory"/>Specifying a
	Startup Directory</title>
	
      <para>The JDE can start an application from any directory that
	you specify. By default, the JDE starts an application from
	the default directory of the current source buffer. The
	default directory of the current source buffer is the
	directory containing the source file displayed in the buffer.
	You can specify another directory as the startup directory by
	setting the JDE customization variable
	<varname>jde-run-working-directory</varname>.</para>
      
      <para>To set this variable, </para>
      
      <procedure>

	<step>
	  <para>Display its customization panel.</para> 
	  <para>You can do this by  typing </para>
	  <para><keycombo>
	      <keycap>M</keycap><keycap>x</keycap></keycombo>&nbsp;<varname>customize-variable</varname>&nbsp;<varname>jde-run-working-directory</varname></para>
	  <para>or selecting <menuchoice><guimenu>JDE</guimenu>
	      <guisubmenu>Options</guisubmenu><guimenuitem>Project</guimenuitem> 
	      
	      
	      
	    </menuchoice> to display the project customization  panel
	    and searching this panel for
	    <varname>jde-run-working-directory</varname>.
	  </para>
	  <para>
	    <screenshot>
	      <mediaobject>
		<imageobject>
		  <imagedata fileref="images/WorkingDirectory.gif"/>
		</imageobject>
		<textobject>
		  <phrase>Screenshow showing customization buffer for
		    <varname>jde-run-working-directory</varname>.</phrase>
		</textobject>
	      </mediaobject>
	    </screenshot>
	  </para>
	</step>

	<step>
	  <para>Enter the working directory in the variable's edit
	    field. </para></step>

	<step>
	  <para>Save the new setting.</para> 
	  <para>To save the edited bindings,  right click the
	    <guibutton>[State]</guibutton>  button and choose
	    <menuchoice>
	      <guimenuitem>Set for current
		session</guimenuitem></menuchoice> if you want the
	    settings to apply only  to the current project or
	    <menuchoice>
	      <guimenuitem>Save for  future
		sessions</guimenuitem></menuchoice> if you want the
	    settings to  apply to all projects. In either case, you
	    should save  the new settings in you project file if your
	    project has  a project file. To save the new settings in
	    your project  file, switch to a source buffer and choose
	    <menuchoice><guimenu>JDE</guimenu>
	      <guisubmenu>Options</guisubmenu><guimenuitem>Save
		Project</guimenuitem></menuchoice>.</para>
	</step>

      </procedure>

    </sect3>

    <sect3>

	
      <title><anchor id="RunVMArgs"/> Setting VM Command-Line
	Arguments</title>
	
      <para>If you set the customization variable
	<varname>jde-run-read-vm-args</varname>  to a
	non-<varname>nil</varname> value, the JDE compile command
	prompts you to enter virtual machine options in the
	minibuffer. It appends  the options that you enter to the
	options specified via  customization variables. The JDE saves
	the arguments that you  enter in a minibuffer history list.
	You can recall previously  entered options by pressing the up
	or down arrows on your  keyboard. </para>

    </sect3>

    <sect3>

	
      <title><anchor id="RunAppArgs"/> Setting Command-Line
	Application Arguments</title>

      <para>Specifying a prefix argument before the
	<command>jde-run</command>, e.g., <varname>C-u C-c C-v
	  C-r</varname> causes the command to prompt you to enter
	arguments to be passed to the application's main
	method. The command appends the options that you enter to the
	arguments specified via  the customization variable
	<varname>jde-run-option-application-args</varname>.  The JDE
	saves the arguments that you enter in a minibuffer  history
	list. You can recall previously entered options by  pressing
	the up or down arrows on your keyboard. </para>

      <para>If you set the customization variable
	<varname>jde-run-read-app-args</varname>  to a
	non-<varname>nil</varname> value, the JDE run command
	prompts you to enter command-line application arguments 
	by default, i.e., you do not have to specify a prefix
	argument each time you execute the command.</para>
    </sect3>

    <sect3>
      <title><anchor id="NavigatingExceptionTraces"/>Navigating
	Exception Traces</title>

      <para>If an exception occurs while your program is running, the
	Java vm outputs an exception trace. This trace appears in the
	run buffer for the application.</para>

      <para>
	<screenshot>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="images/excepttrace.gif"/>
	    </imageobject>
	    <textobject>
	      <phrase>Screenshot showing an exception trace in the
	      JDE's run buffer.</phrase>
	    </textobject>
	  </mediaobject>
	</screenshot>
      </para>
    </sect3>

    <para>To view the source line corresponding to a point in the
      exception stack trace, right-click the corresponding stack trace
      line in the run buffer. You can move up and down the stack trace
      by typing the key combinations <varname>C-c C-v C-[</varname> or
      <varname>C-c C-v C-]</varname>.</para>
      


    <sect3>
	
      <title><anchor id="RunOptions"/>Run Customization Variables
      </title>
	
      <para>The JDE allows you to specify run-time options by setting
	run variables.You can use the Emacs customization feature to
	set run-time variables interactively. To use the customization
	feature, select
	<menuchoice>
	  <guimenu>JDE</guimenu><guisubmenu>Project</guisubmenu><guisubmenu>Options</guisubmenu><guimenuitem>Run</guimenuitem></menuchoice>. 
	(See <ulink url="#ConfiguringJDE">Configuring  the JDE</ulink>
	for more information on using the customization  feature). To
	save the compilation settings in the project file (see <ulink
	  url="#UsingProjectFiles">Using Project Files</ulink>) for
	the  current source buffer, select <menuchoice>
	  <guimenu>JDE</guimenu>
	  <guisubmenu> Project</guisubmenu><guisubmenu>Project
	    File</guisubmenu><guimenuitem>Save
	    Project</guimenuitem></menuchoice>.
      </para>
      
      <para>The following table lists the JDE run variables and the
	functions used to set them. &nbsp; </para>
      
      <table>
	<title></title>
	<tgroup cols="3">
	  <colspec colnum="1"/>
	  <colspec colnum="2"/>
	  <colspec colnum="3"/>
	  <thead>
	    <row>
	      <entry>Variable</entry>
	      <entry>Group</entry>
	      <entry>Usage</entry>
	    </row>
	  </thead>
	  <tbody>
	    <row>
	      <entry
		valign="top"><varname>jde-run-mode-hook</varname></entry>
	      <entry valign="top">Project</entry>
	      <entry valign="top">List of hook functions run by
		<varname>jde-run-mode</varname></entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-run-working-directory</varname></entry>
	      <entry valign="top">Project</entry>
	      <entry>Startup directory for running or debugging Java
		applications.</entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-run-application-class</varname></entry>
	      <entry valign="top">Project&nbsp;</entry>
	      <entry valign="top">Name of the Java class to run. The
		command <varname>jde-run-set-app</varname> sets the
		buffer-local value of this variable.&nbsp;</entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-run-java-vm</varname></entry>
	      <entry valign="top">Project&nbsp;</entry>
	      <entry valign="top">Specify Java interpreter for
		non-Windows platforms. The command
		<varname>jde-run-set-vm</varname> sets the
		buffer-local value of this variable.&nbsp;</entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-run-java-vm-w</varname></entry>
	      <entry valign="top">Project&nbsp;</entry>
	      <entry valign="top">Specify Java interpreter for Windows
		platforms. The command
		<varname>jde-run-set-vm-w</varname> sets the
		buffer-local value of this variable.&nbsp;</entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-global-classpath</varname></entry>
	      <entry valign="top">Project&nbsp;</entry>
	      <entry valign="top">Specify class paths for compile,
		run, and debug commands. The command<varname>
		  jde-set-global-classpath</varname> sets the
		buffer-local value of this variable.&nbsp;</entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-run-classic-mode-vm</varname></entry>
	      <entry valign="top">Project</entry>
	      <entry>Specifies that the JDE should run the JDK's
		classic version of the Java virtual machine (as
		opposed to the HotSpot version). This option applies
		only to versions of the JDK that include both a
		classic and a HotSpot vm.</entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-run-read-vm-args</varname></entry>
	      <entry valign="top">Project</entry>
	      <entry>Specifies whether to read vm arguments from
		the&nbsp; minibuffer.</entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-run-option-classpath</varname></entry>
	      <entry valign="top">Run&nbsp;</entry>
	      <entry valign="top">Specifies the classpath for&nbsp;
		the Java interpreter. This option overrides the
		jde-global-classpath option.&nbsp;</entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-run-option-verbose</varname></entry>
	      <entry valign="top">Run&nbsp;</entry>
	      <entry valign="top">Print messages about the running
		process.&nbsp;</entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-run-option-properties</varname></entry>
	      <entry valign="top">Run&nbsp;</entry>
	      <entry valign="top">Specify property values.</entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-run-option-heap-size</varname></entry>
	      <entry valign="top">Run&nbsp;</entry>
	      <entry valign="top">Specify the initial and maximum size
		of the interpreter heap.&nbsp;</entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-run-option-stack-size</varname></entry>
	      <entry valign="top">Run&nbsp;</entry>
	      <entry valign="top">Specify size of the C and Java
		stacks.</entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-run-option-garbage-</varname>&nbsp; 
		<varname>collection</varname>&nbsp;</entry>
	      <entry valign="top">Run</entry>
	      <entry valign="top">Specify garbage collection
		options.&nbsp;</entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-run-option-java-profile</varname></entry>
	      <entry valign="top">Run&nbsp;</entry>
	      <entry valign="top">Enable Java profiling.</entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-run-option-heap-profile</varname></entry>
	      <entry valign="top">Run&nbsp;</entry>
	      <entry valign="top">Output heap profiling data.</entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-run-option-verify</varname></entry>
	      <entry valign="top">Run&nbsp;</entry>
	      <entry valign="top">Verify classes.</entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-run-option-vm-args</varname></entry>
	      <entry valign="top">Run&nbsp;</entry>
	      <entry valign="top">Specify command-line arguments to be
		passed to the Java vm. The command jde-run-set-args
		sets the buffer-local value of this
		variable.&nbsp;</entry>
	    </row>
	    <row>
	      <entry
		valign="top"><varname>jde-run-option-application-args</varname></entry>
	      <entry valign="top">Run&nbsp;</entry>
	      <entry valign="top">Specify command-line arguments to
		pass to the application. The command
		<varname>jde-run-set-app-args </varname>sets the
		buffer-local value of this variable.&nbsp;</entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>
      
    </sect3>

  </chapter>

  <chapter>

     
      <title><anchor id="WorkingWithApplets"/> Working with Applets</title>
      
    <para>The JDE provides specialized commands for running and
      debugging applets.</para>
    
    <sect3>
      
	
      <title><anchor id="RunningApplets"/>Running Applets</title>
	
      <para>To run an applet:</para>
      
      <procedure>

	<step>
	  <para>Open the applet's source file in a buffer. </para>
	</step>

	<step>
	  <para>Choose <menuchoice>
	      <guimenu>JDE</guimenu><guimenuitem>Run
		Applet</guimenuitem>
	    </menuchoice>. </para>
	  <para>The JDE searches for an html file in the directory
	    containing the applet source file and displays the first
	    file it finds, using your system's default browser. If
	    the JDE cannot find an html page in the applet's source
	    file directory, it signals an error by default.
	  </para>
	</step>

      </procedure>
      
      <para>The  <menuchoice><guimenu>JDE</guimenu>
	  <guimenuitem>Run Applet</guimenuitem></menuchoice> command
	assumes by default that the directory containing the  applet's
	source also contains an html page for testing that  applet. If
	this is not true in your case, you have two options.  You can
	either specify the path of the applet file via the JDE
	customization variable <varname>jde-run-applet-doc</varname>
	or you can use  the <varname>jde-run-applet</varname> command
	to run your applet. If the
	<varname>jde-run-applet-doc</varname>  variable is not a null
	string, <menuchoice><guimenu>JDE</guimenu>
	  <guimenuitem>Run Applet</guimenuitem></menuchoice> displays
	the
	document that the variable  specifies instead of searching the source
	file directory for a  document to display. The
	<varname>jde-run-applet</varname> command prompts  you to enter in the
	minibuffer the path of an html file to  display. If you enter nothing,
	the command defaults to the  behavior of  <menuchoice><guimenu>JDE</guimenu>
	  <guimenuitem>Run Applet</guimenuitem></menuchoice>.</para>
      
      <para>The run commands chooses the viewer as follows. If
	<varname>jde-run-applet-viewer</varname> is a null string (the
	default) or browse-url, the JDE uses browse-url to launch the
	applet doc in your system's default browser. Otherwise, the
	menu command uses comint to launch the viewer (e.g.,
	appletviewer) specified by
	<varname>jde-run-applet-viewer</varname>.</para>
    </sect3>

    <sect3>
      
	
      <title><anchor id="DebuggingApplets"/>Debugging Applets</title>
	
      <para>To debug an applet:</para>
      
      <procedure>

	<step>
	  <para>Open the applet's source file in a buffer.</para>
	</step>

	<step>
	  <para>Choose  <menuchoice><guimenu>JDE</guimenu>
	      <guimenuitem>Debug
		Applet</guimenuitem></menuchoice>.</para>
	  <para>The JDE searches for an html file in the directory
	    containing the applet source file. If the JDE cannot find
	    an html page in the applet's source file directory, it
	    signals an error by default. Otherwise, it runs
	    appletviewer in debug mode on the first file that it
	    finds.</para>
	  <para>The Emacs window splits into two panes.</para>
	</step>
      </procedure>
      
      <para>The top pane shows the applet's source file with the debug
	cursor pointing to the first line of the applet's init file.
	The bottom pane displays the debugger's command line
	interface. You can now set breakpoints, single-step, or
	continue running the applet. See <ulink
	  url="#DebuggingApps">Debugging Applications</ulink> for more
	information.</para>
      
      <para>If you want to specify the document to be used to test the
	applet, customize the variable jde-run-applet-doc or execute
	<varname>M-x jde-db-applet</varname>. This command prompts you
	to enter the test document's name.</para>
    </sect3>

    <sect3>

	
      <title><anchor id="AppletOptions"/>Applet Customization
	Variables</title>
	
      <para>The JDE allows you to specify run-time options for applets
	by setting JDE configuration variables.You must use the Emacs
	customization feature to set applet run-time variables . To
	use the customization feature, select <menuchoice>
	  <guimenu>JDE</guimenu><guisubmenu>Options</guisubmenu><guimenuitem>Run</guimenuitem></menuchoice>. 
	(See <ulink url="#ConfiguringJDE">Configuring the JDE</ulink>
	for more information on using the customization feature). In
	some cases, the JDE also provides functions for setting the
	buffer-local values of the compilation variables. To save the
	compilation settings in the project file (see <ulink
	  url="#UsingProjectFiles">Using Project Files</ulink>) for
	the current source buffer, select
	<menuchoice><guimenu>JDE</guimenu><guisubmenu>Options</guisubmenu><guimenuitem>Update 
	    Project</guimenuitem></menuchoice>. </para>
      
      <para>The following table lists the JDE applet run-time
	variables and the functions used to set them.  </para>
      
      <table>
	<title></title>
	<tgroup cols="3">
	  <thead>
	    <row>
	      <entry>Variable</entry>
	      <entry>Group</entry>
	      <entry>Usage</entry>
	    </row >
	  </thead>
	  <tbody>
	    <row>
	      <entry
		valign="top"><varname>jde-run-applet-viewer</varname></entry>
	      <entry valign="top">Project&nbsp;</entry>
	      <entry valign="top">Specify name of viewer to use to
		display page containing the applet. The command
		<varname>jde-run-set-applet-viewer</varname> sets the
		buffer-local value of this variable.&nbsp;</entry>
	    </row >
	    <row>
	      <entry
		valign="top"><varname>jde-run-applet-doc</varname></entry>
	      <entry valign="top">Project&nbsp;</entry>
	      <entry valign="top">Specify name of document containing
		applet to be viewed. The command
		<varname>jde-run-set-applet-doc</varname> sets the
		buffer-local value of this variable.&nbsp;</entry>
	    </row >
	  </tbody>
	</tgroup>
      </table>
    </sect3>

  </chapter>

  <chapter>

      
      <title><anchor id="DebuggingApps"/>Debugging Applications</title>
      
    <para>The JDE provides two options for debugging Java applications.</para>
    
    <itemizedlist>
      <listitem>
	<para>An Emacs interface to <command>jdb</command>, the command-line
	  debugger that comes with the JDK. See <ulink url="../jdb-ug/jdb-ug-frame.html"
						       type="jdb-ug">Debugging with jdb</ulink> for more
	  information. </para>
      </listitem>

      <listitem>
	<para>
	  JDEbug, a Java debugger developed specifically for use  with the JDE.
	  See <ulink url="../jdebug-ug/jdebug-ug.html"  type="jdebug-ug">JDEbug
	    User's Guide</ulink> for more information</para>.
      </listitem>
    </itemizedlist>
    
    <para>JDEbug provides more debugging features but requires a JDK 1.2
      or higher vm. You must use <command>jdb</command> to debug applications
      running on earlier vms.</para>

  </chapter>


  <chapter>
    
    <title><anchor id="SpecifyingClasspaths"/>Specifying
      Classpaths</title>

    <para>The JDE provides customization variables that permit you to
      specify a classpath for the JDE's compile, run, debug,
      Beanshell, and other commands. The following table lists these
      variables.</para>

    <table>
      <title>Classpath Variables</title>
      <tgroup cols="2">
	<thead>
	  <row>
	    <entry>Variable</entry>
	    <entry>Applies To ...</entry>
	  </row>
	</thead>
	<tbody>
	  <row>
	    <entry><para><varname>jde-global-classpath</varname></para></entry>
	    <entry><para>All JDE commands that use a
		classpath.</para></entry>
	  </row>
	  <row>
	    <entry><para><varname>jde-compile-option-classpath</varname></para></entry>
	    <entry><para>Compile command</para></entry>
	  </row>
	  <row>
	    <entry><para><varname>jde-run-option-classpath</varname></para></entry>
	    <entry><para>Run App command</para></entry>
	  </row>
	  <row>
	    <entry><para><varname>jde-db-option-classpath</varname></para></entry>
	    <entry><para>Debug App command</para></entry>
	  </row>
	</tbody>
      </tgroup>
    </table>

    <para>The <varname>jde-global-classpath</varname> variable is so
      named because it specifies a classpath that is used by all JDE
      commands unless overridden by a classpath variable specific to a
      particular command. For example, the JDE's
      <command>Compile</command> command uses
      <varname>jde-global-classpath</varname> unless the value of
      <varname>jde-compile-option-classpath</varname> is set.
      Typically you want to use the same classpath to compile, run,
      and debug an application. So typically
      <varname>jde-global-classpath</varname> is the only variable you
      need to set.</para>



    <sect3>
      <title><anchor id="SettingClasspathVar"/>Setting a Classpath
	Variable</title>
      <para>As with other JDE customization variables, you must use
	Emacs' <command moreinfo="none">customize-variable</command>
	command to set the JDE's classpath variables. You can use
	relative paths, cygwin paths, and paths with tilde notation
	and environment variables as values of JDE classpath
	variables. See <ulink url="#SpecifyingPaths">Specifying
	  Paths</ulink> for more information.
      </para>

      <para>
	When setting a classpath variable, you must enter each path as
	a separate entry in the customization buffer. Do not enter the
	paths as semicolon or colon-separated lists of paths. The
	following examples show the right and wrong way to specify a
	classpath.</para>

      <example>
	<title>Wrong Way to Specify a Classpath</title>
	<programlisting format="linespecific">
          jde-global-classpath: [Hide] 
          [INS] [DEL] Path: c:/jde-dev/jmath/classes;c:/jde-dev/jmath/src 
          [INS] 
            [State]: this option has been set and saved.
	</programlisting>
      </example>

      <example>
	<title>Right Way to Specify a Classpath</title>
	<programlisting format="linespecific">
          jde-global-classpath: [Hide] 
          [INS] [DEL] Path: c:/jde-dev/jmath/classes 
          [INS] [DEL] Path: c:/jde-dev/jmath/src 
          [INS] 
            [State]: this option has been set and saved.
	</programlisting>
      </example>
    </sect3>

    <sect3>
      <title><anchor id="ClassLibraries"/>Including Class
	Libraries</title>
      <para>
	If you store your class libraries as jar or zip files in
	separate directory, you need specify only the path of the
	directory in a JDE classpath variable. Whenever the JDE
	encounters a library directory in a classpath variable, it
	expands the classpath to include all the jar and zip files in
	the library directory.
      </para>

      <para>
	For example, suppose you organize your project directory as
	follows:
      </para>
	
      <para> <programlisting format="linespecific"> myproj classes lib
	  src </programlisting>
      </para> 

      <para>
	where the <filename>src</filename> directory contains all of
	your source files, the <filename>lib</filename> directory all
	of your jar and zip files,  and the
	<filename>classes</filename> directory all of the classes
	compiled from the <filename>src</filename> directory. Further,
	suppose you store your project file (see <ulink
	  url="#UsingProjectFiles">Using Project Files</ulink>) at the
	root of your project directory. Then, you can specify
	<varname>jde-global-classpath</varname> simply as follows.
      </para>

      <para>
	<programlisting format="linespecific"> jde-global-classpath:
	  [Hide] [INS] [DEL] Path: ./classes [INS] [DEL] Path: ./src
	  [INS] [DEL] Path: ./lib [INS] [State]: this option has been
	  set and saved. </programlisting>
      </para>

      <para>
	If you do not want the JDE to expand library directories, set
	the variable <varname>jde-expand-classpath-p</varname> off.
	The JDE expands directories whose names match the regular
	expressions specified by
	<varname>jde-lib-directory-names</varname>. The default values
	of this variable are <filename>^lib</filename> and
	<filename>^jar</filename>. So by default, the JDE expands
	names that begin with the string <filename>lib</filename> or
	<filename>lib</filename>, e.g., <filename>lib</filename>,
	<filename>libraries</filename>, etc. However, you can
	customize <varname>jde-lib-directory-names</varname> to
	reflect any library naming scheme you prefer.
      </para>

    </sect3>
   

  </chapter>

  <chapter>

     
      <title><anchor id="UsingProjectFiles"/>Using Project Files</title>
      
    <para>A project file is a Lisp file that the JDE loads and evaluates
      whenever you open a Java source file belonging to a specific
      project. Project files allow you to save and restore project-specific
      JDE configurations. For example, you can use a project file to
      set the value of the <varname>jde-global-classpath</varname> variable to a
      project-specific classpath automatically whenever you load a file
      belonging to that project. </para>
    
    <sect3>

     
      <title><anchor id="FindingProjectFiles"/> How the JDE Finds Project Files</title>
      
      <para>To simplify the task of finding project files, the JDE makes
	two assumptions. First, it assumes that all Java source files
	relating to a particular project live in a single directory tree.
	Second, it assumes that all project files have the same file name.
	The name assumed by default is <filename>prj.el</filename>. You can use the JDE
	configuration variable <varname>jde-project-file-name</varname> to specify
	another name.</para>

      <para>
	When you open a Java source file, the JDE looks for
	project files in the directory tree containing the source file.  
	If the JDE finds one or more project files, it loads the
        project files in the following manner.
      </para>

      <para>       
	The JDE  first sets all the JDE variables to their
	Emacs startup values (i.e., the default value or the value
	saved in your <filename>.emacs</filename> file). It then loads
	all the project files in the directory tree containing the
	current source buffer, starting with the topmost file.
      </para>

      <para>
	What this means is that you can use project files to extend
	and/or override the settings in your
	<filename>.emacs</filename> file and in other project files.
	For example, your <filename>.emacs</filename> file can specify
	settings that are common to all your projects. You can put
	settings common to a group of projects at the top of the
	directory tree containing the projects, settings common to
	each project at the top of the directory containing each
	projects, and so on.
      </para>       
 
    </sect3>

    <sect3>

	
      <title><anchor id="ProjectFileContents"/> Project File
	Contents</title>

	
      <para>A project file can contain any Lisp code that can be
	evaluated correctly as the last step in creating a Java source
	buffer. For example, a project file can contain code that sets
	the value of JDE configuration variables. In general, a
	project file can  contain any code that could be implemented
	as a <varname>jde-mode</varname> hook function. In fact, you
	can think of a project file as a project-specific
	<varname>jde-mode</varname> hook function. </para>
    </sect3>

    <sect3>

	
      <title><anchor id="CreatingProjectFiles"/>Creating a Project
	File</title>
	
      <para>The easiest way to create a project file is to use the
	<varname>jde-save-project </varname> command (<menuchoice>
	  <guimenu>JDE</guimenu>
	  <guisubmenu>Project</guisubmenu><guisubmenu>Project
	    File</guisubmenu><guimenuitem>Save
	    Project</guimenuitem></menuchoice>). This command  saves
	the current values of all customized JDE configuration
	variables  in the project file for the selected Java buffer.
	(To be precise,  the command inserts Lisp code in the project
	file that restores  the current settings of the configuration
	variables; if such code  already exists in the file, it
	replaces it with updated code.) If  the project file does not
	exist, the command creates the project  file. Thus, to create
	a project file that sets JDE configuration  variables to
	project-specific values:
      </para>
      
      <procedure>
	<step>
	  <para>Open any source file belonging to the project.</para>
	</step>
	<step>
	  <para>Set the values of the JDE configuration variables to
	    the appropriate values for the project to which the source
	    file belongs.</para>
	</step>
	<step>
	  <para>See <ulink url="#ConfiguringJDE">Configuring the
	      JDE</ulink>  for information on how to set the values of
	    the JDE  configuration variables.</para>
	</step>
	<step>
	  <para>Select <menuchoice>
	      <guimenu>JDE</guimenu>
	      <guisubmenu>Project</guisubmenu><guisubmenu>Project
		File</guisubmenu><guimenuitem>Save
		Project</guimenuitem></menuchoice>.
	  </para>
	</step>
	<step performance="required">
	  <para> The JDE prompts you to enter the path to a directory
	    in which to store the project file.
	  </para>	
	</step>
	<step performance="required">
	  <para>
	    Enter the directory where you want to store the project
	    file or press <keycap>Enter</keycap> to store the project
	    file in the current directory.
	  </para>	
	</step>
      </procedure>
      
      <para>Once you have created the project file, you can insert
	additional configuration code into the file if desired. Note
	that the <varname>jde-save-project</varname> command edits
	rather than replaces existing project files. Thus, you can use
	the command to update configuration variable settings without
	disturbing any other configuration code that you have inserted
	manually into the project file. 
      </para>
    </sect3>

    <sect3>
      <title><anchor id="CreatingPortableProjects"/>Creating Portable Projects</title>
      <para>
	You can use relative paths and environment variables to 
	construct portable project files. For example, suppose your
	project directory has the following structure:
      </para>
      <para>
	<programlisting>      
    myprj
      classes
        pkg1
        pkg2
      src
        pkg1
        pkg2
      prj.el
	</programlisting>      
      </para>  
      <para>      
	Further suppose that your project uses beans  from a 
	shared library specified by the environment variable
	<varname>BEANS</varname>. With this setup, 
	you can specify <varname>jde-global-classpath</varname> as
      </para>
      <para>
	<programlisting>      
      ./src
      ./classes
      $BEANS/lib/dials.jar
	</programlisting>      
      </para>
      <para>  
	and <varname>jde-compile-option-directory</varname> as
      </para>
      <para>      
	<programlisting>      
      ./classes
	</programlisting>      
      </para>
      <para>  
	This causes the JDE to store classes compiled from your src
	directory in the classes directory.  Note that you have not
	used any absolute paths in creating your project file. This
	means you can move your project anywhere without having to update
	the project file.
      </para>
 
    </sect3>

    <sect3>
      <title><anchor id="DisablingContextSwitching"/>Disabling Context Switching</title>
      <para>When you select a buffer that belongs to another
	project, the JDE loads the project file for that project
	and may update the class list for the project. This 
        causes a slight delay before you can begin using the
	new buffer. The delay can be irritating if you need
        to switch frequently among open projects, for example,
	when copying or diffing code from different projects.
	Accordingly, the JDE provides ways for you to disable
	context-switching either permanently or  temporarily.
     </para>

      <para>To disable context-switching permanently, toggle
	the customizat variable 
	<varname>jde-project-context-switching-enabled-p</varname>
	off. Be sure to use customize to do this and save the
	customization in your <filename moreinfo="none">
	  .emacs</filename> or <filename moreinfo="none">prj.el</filename>
	file. Note that you can use the JDE's project file loading
	command, <command>JDE->Project->Project File->Load</command>,
	to switch contexts manually.
      </para>

      <para>
	To disable context-switching temporarily during a session,
	select <command>
	JDE->Project->Auto Switch</command> or enter
	<varname>M-x jde-toggle-project-context-switching</varname>. To reenable
	context-switching, execute the same command again.
      </para>
    </sect3>

    <sect3>
      <title><anchor id="ProjectHooks"/>Project Hook Functions</title>
      <para>The variable <varname>jde-project-hooks</varname> lists
	functions that execute after the JDEE loads a project file. By
	writing hook functions and adding them to this list, you can
	specify actions to be taken every time the JDEE switches from
	one project to another.</para>
    </sect3>

  </chapter>

  <chapter>

      
      <title><anchor id="DisplayingDoc"/> Displaying Java Documentation</title>

      
    <para>
      The JDE provides commands for displaying the JDK API documentation
      and context-sensitive help for classes.
    </para>
    
    <sect3>

	
      <title><anchor id="BrowsingJDKDoc"/> Browsing JDK
	Documentation</title>

	
      <para>The <varname>jde-browse-jdk-doc</varname> command
	(<menuchoice>
	  <guimenu>JDE</guimenu><guimenuitem>Help</guimenuitem>
	  <guimenuitem>JDK</guimenuitem></menuchoice>, <keycombo>
	  <keycap>C</keycap><keycap>c</keycap></keycombo>&nbsp;
	<keycombo>
	  <keycap>C</keycap><keycap>v</keycap></keycombo>&nbsp;<keycombo>
	  <keycap>C</keycap><keycap>n</keycap></keycombo>) opens the
	JDK documentation in a browser. By default, this command
	displays the JDK documentation page at JavaSoft's web site. To
	display a different copy, set the variable
	<varname>jde-jdk-doc-url</varname> to the url of the index
	page of the copy you want to be displayed. </para>
    </sect3>

    <sect3>

	
      <title><anchor id="ClassHelp"/> Context-Sensitive Class
	Help</title>

	
      <para>The JDK provides context-sensitive help for Java classes.
	To use this facility, you must first customize the variable
	<varname>jde-help-docsets</varname> to specify the location of
	class documentation on your system. The JDE class help
	facility supports javadoc documentation by default but it
	works with other types of documentation as well.</para>
      
      <para>Once you have specified the location of class
	documentation on your system, you can get help for the class
	at point in the current buffer by selecting <menuchoice>
	  <guimenu>JDE</guimenu><guisubmenu>Help</guisubmenu><guimenuitem>Symbol 
	    at Point</guimenuitem></menuchoice> . </para>
    </sect3>

  </chapter>

  <chapter>
    
      <title><anchor id="BrowsingSourceCode"/>Browsing Source Code</title>
      
    <para>The JDE provides the following facilities for browsing Java source code:</para>
    
    <itemizedlist>
      <listitem>
	<para><ulink url="#ClassesMenu">Classes index menu</ulink></para>
      </listitem>
      <listitem>
	<para><ulink url="#Speedbar">Speedbar</ulink></para></listitem>
      <listitem>
	<para><ulink url="#Tags">Etags</ulink></para></listitem>
    </itemizedlist>
    

    <sect3>

	
      <title><anchor id="ClassesMenu"/> Classes Index Menu</title>
	
	
      <para>The <menuchoice><guimenu>Classes</guimenu></menuchoice>
	index menu appears by default in the Emacs menubar whenever a
	Java source buffer is active. The menu consists of a cascading
	list of all classes, methods, fields, and imports defined in
	the current buffer plus the package to which the current
	buffer belongs. Selecting any item scrolls the buffer to the
	statement that defines the item.</para>
      
      <para><screenshot>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="images/classes_menu1.gif"/>
	    </imageobject>
	    <textobject>
	      <phrase>Screenshot showing Classes menu.</phrase>
	    </textobject>
	  </mediaobject>
	</screenshot>
      </para>
      <para>The top-level menu contains an entry for each each class
	defined by the active buffer followed by entries for the
	imports and package of the current buffer. Selecting the entry
	for a class displays a submenu listing the inner classes,
	methods, and fields defined by the class. Selecting the entry
	for an inner class displays another submenu for that class,
	and so on. Selecting the
	<menuchoice><guimenu>imports</guimenu></menuchoice> entry on
	the top-level menu displays a submenu listing all the classes
	and packages imported by the active buffer.</para>    

      <sect4>

	  
	<title><anchor id="SpecialIndexEntries"/> Special Index
	  Entries</title>

	<para>The index menu includes the following special index
	  entries:</para>
	
	<itemizedlist>

	  <listitem>
	    <para><menuchoice><guimenu>*Rescan*</guimenu></menuchoice></para>
	    <para>Selecting this item causes the JDE to rebuild the
	      index menu.  You should rebuild the menu whenever you
	      edit the buffer.
	    </para>
	  </listitem>

	  <listitem>
	    <para><menuchoice><guimenu>*class
		  def*</guimenu></menuchoice></para>
	    <para>Selecting this item takes you to the start of the
	      definition of  the class on whose submenu it appears.
	      Turn the variable
	      <varname>jde-imenu-include-classdef</varname> off to
	      suppress inclusion  of these items in the menu. </para>
	  </listitem>

	</itemizedlist>
      </sect4>

      <sect4>

	  
	<title><anchor id="AlphabetClassesMenu"/>Alphabetizing the
	  Classes Menu</title>
	
	<para>By default the
	  <menuchoice><guimenu>Classes</guimenu></menuchoice> menu
	  lists methods and fields in the order in which the active
	  buffer defines them. Use the variable
	  <varname>jde-imenu-sort</varname> to customize the menu to
	  list methods and fields alphabetically in either ascending
	  or descending order.</para>
      </sect4>

      <sect4>

	  
	<title><anchor id="SuppressingSignatures"/>Suppressing Method
	  Signatures and Field Types</title>
	  
	<para>By default the
	  <menuchoice><guimenu>Classes</guimenu></menuchoice> menu
	  displays the signatures of methods and the types of fields
	  displayed in the active buffer. The method signatures enable
	  you to distinguish overloaded method names. The menu can
	  also display the names of methods and fields without
	  signatures and types. Use the variable
	  <varname>jde-imenu-include-signature</varname> to turn
	  signature and type display off or on. </para>
      </sect4>

      <sect4>
	  
	<title><anchor id="DisablingClassesMenu"/>Disabling the
	  Classes Menu</title>
	  

	<para>Set the variable <varname>jde-imenu-enable</varname> off
	  to disable the
	  <menuchoice><guimenu>Classes</guimenu></menuchoice> menu.
	  When disabled, the menu does not appear in the Emacs
	  menubar.</para>
      </sect4>

      <sect4>
	<title>Using the Keyboard to Navigate the Classes Menu</title>
	<para>
	  Execute <command>M-x imenu</command> to use the keyboard 
	  to navigate the Classes menu. Emacs displays the 
	  top-level items on the Classes menu in a buffer and
	  prompts you to enter the name of an an item in the
	  minibuffer. Enter the name of the item to select it.
	  Note that you can use completion to avoid having to
	  type the whole name. If you select a submenu, Emacs
	  displays the contents of the submenu and prompts
	  you to enter a selection in the keyboard. If you
	  select an index entry, Emacs scrolls the buffer
	  to the indexed point in the buffer.
	</para>
      </sect4>

    </sect3>

    <sect3>

	
	<title><anchor id="Speedbar"/> Using the Speedbar</title>
	
      <para>To display the speedbar, select <menuchoice>
	  <guimenu>JDE</guimenu>
	  <guimenuitem> Speedbar</guimenuitem></menuchoice>. The
	speedbar opens in a separate frame.</para>

      <para><screenshot>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="images/speedbar1.gif"/>
	    </imageobject>
	    <textobject>
	      <phrase>Screenshot showing the speedbar.</phrase>
	    </textobject>
	  </mediaobject>
	</screenshot>
      </para>

      <para>The speedbar displays a list of the files and
	subdirectories in the directory containing the file displayed
	in the current buffer. The speedbar highlights the file
	displayed in the current buffer.</para>

      <para>Click on the expand (+) button in front of any file. The
	node for the  file expands</para>
      
       <para>
	<screenshot>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="images/speedbar2.gif"/>
	    </imageobject>
	    <textobject>
	      <phrase>Screenshot showing a speedbar entry.</phrase>
	    </textobject>
	  </mediaobject>
	</screenshot>
      </para>

      <para>to show up to three entries, depending on the contents of
	the source file. </para>
      
      <sect4>
	 
	<title><anchor id="Package"/>Package</title>

	<para>
	  This item expands to show the package to which the file
	  belongs.
	</para>
	
	<para><screenshot>
	    <mediaobject>
	      <imageobject>
		<imagedata fileref="images/speedbar3.gif"/>
	      </imageobject>
	      <textobject>
		<phrase>Screenshot showing a speedbar entry.</phrase>
	      </textobject>
	    </mediaobject>
	  </screenshot>
	</para>

	<para>
	  Clicking on the package scrolls the buffer to the
	  corresponding package declaration.
	</para>
      </sect4>
      
      <sect4>

	  
	<title><anchor id="Types"/>Types</title>

	<para>
	  This item expands to show the classes in the selected file.
	</para>

	<para><screenshot>
	    <mediaobject>
	      <imageobject>
		<imagedata fileref="images/speedbar4.gif"/>
	      </imageobject>
	      <textobject>
		<phrase>Screenshot showing a speedbar entry.</phrase>
	      </textobject>
	    </mediaobject>
	  </screenshot>
	</para>

	<para>
	  Each class expands to show the constructors, methods,
	  fields, and inner classes defined by the class and the
	  class's parent, if any. Inner classes also expand and their
	  inner classes, and so on. The constructors and methods
	  expand to show arguments and argument types and return
	  types. Fields expand to show their type.
	</para>
	
	<para>
	  Clicking on any class, inner class, method, constructor, or
	  field scrolls the buffer to show that item.
	</para>
      </sect4>

      <sect4>

	  
	<title><anchor id="Dependencies"/>Dependencies</title>
	
	This item expands to show the classes and packages imported by the current source file.
	
	<para><screenshot>
	    <mediaobject>
	      <imageobject>
		<imagedata fileref="images/speedbar5.gif"/>
	      </imageobject>
	      <textobject>
		<phrase>Screenshot showing a speedbar entry.</phrase>
	      </textobject>
	    </mediaobject>
	  </screenshot>
	</para>

	<para>Click on class or package to scroll the buffer to the
	  corresponding import statement.</para>
      </sect4>

      <sect4>

	  
	<title><anchor id="UpdatingSpeedbar"/>Updating the
	  Speedbar</title>
	
	<para>If you make changes to a source buffer, you must update
	  the speedbar view to reflect the changes. To update the
	  speedbar view of a buffer:</para>
	
	<procedure>
	  <step>
	    <para>
	      Collapse the speedbar view of the buffer.
	    </para>
	    <para>
	      This is necessary only if the speedbar view is expanded.
	      To collapse the speedbar view, click the collapse button
	      (-) next to the buffer's file name in the speedbar view.
	    </para>
	  </step>
	  <step>
	    <para>Hold the shift key down while clicking the expand
	      button (+) next to the buffer's name  in the speedbar
	      view.  </para>
	  </step>
	</procedure>
      </sect4>
    </sect3>

  </chapter>

  <chapter>
    <title><anchor id="SearchSource"/>Searching Source Code</title>

    <para>The JDEE provides commands that enable you to find</para>

    <itemizedlist>
      <listitem>
	<para>
	  All occurences of strings matching a regular expression anywhere
	  in your project's source path (see <ulink url="#FindExpressions">Finding
	  Expressions</ulink>)
	</para>
      </listitem>
      <listitem>
	<para>
	  Source code that defines the method, field,
	  or other symbol at point (see <ulink url="#FindSymbolDef">Finding
	  Symbol Definitions</ulink>)
	</para>
      </listitem>
      <listitem>
	<para>Source code for the class at point (see <ulink url="#FindClasses">Finding
	  Classes</ulink>)</para>
      </listitem>
      <listitem>
	<para>Source for the parent of the class at point</para>
      </listitem>
      <listitem>
	<para>Source for an interface implemented by the class at point</para>
      </listitem>
      <listitem>
	<para>All methods that invoke a specifed method (see <ulink url="#Xref">Cross-Referencing 
	    Classes</ulink>)</para>
      </listitem>
    </itemizedlist>

    <sect3>
      <title><anchor id="FindExpressions"/>Finding Expressions</title>
      <para>The JDEE provides two commands for finding occurrences of strings
      in Java source and other types of text files:</para>

      <itemizedlist>
	<listitem>
	  <para><command>JDE->Find->Expression</command> 
	    (<function>jde-find</function>)</para>
	  <para>
	    This command uses the minibuffer to prompt you for the
	    search expression and the paths to be searched. You can
	    use customization variables to specify values for the
	    search paths and other search options. The default values
	    for the customization variables search the Java source 
            files on the classpaths and sourcepaths for your project.
	    See <ulink url="#FindExpressionMinibuf">Using the Minibuffer-Based
	    Find Command</ulink> for more information.
	  </para>
	</listitem>
	<listitem>
	  <para><command>JDE->Find->Expression...</command> 
	    (<function>jde-find-dlg</function>)</para>	
	  <para>This command uses a text dialog buffer to
	    prompt you for search arguments. The dialog buffer
	    allows you to specify all search options
	    interactively. It is thus useful for performing
	    searches that have special requirements.
	    See <ulink url="#FindExpressionDlg">Using the Dialog-Based
	    Find Command</ulink> for more information. </para>  
	</listitem>
      </itemizedlist>

      <para>
	Both commands use the Unix <command>grep</command> and
	<command>find</command> utilities to perform the searches that
	you specify. Before executing a search, both commands search
	your system for copies of <command>grep</command> and
	<command>find</command> and signal an error if the utilities
	are missing. All Unix systems include copies of
	<command>grep</command> and <command>find</command>. Versions
	of these utilities are available for Microsoft Windows, e.g.,
	as part of the Cygwin Unix emulation package for Microsoft
	Windows. If you want to use the JDEE's <command>find</command>
	commands on Windows, you must install copies of
	<command>grep</command> and <command>find</command> on your
	system and either include them in your system's command path
	or use the variables <varname>grep-command</varname> and
	<varname>find-program</varname> to specify their respective
	locations on your system.
      </para>

      <note>
	<para> 
	  Microsoft Windows/NT and Windows 2000 provide a
	  <command>find</command> utility that is incompatible with
	  the Unix <command>find</command> utility. To ensure that the
	  JDEE finds the right version, you should either put the
	  Unix-style <command>find</command> command ahead of the
	  Windows <command>find</command> command in your system
	  command path or use the <varname>find-program</varname>
	  variable to specify the Unix-style command's location.
	</para>     
      </note>

      <sect4>
	<title><anchor id="FindExpressionMinibuf"/>Using the
	  Minibuffer-Based Find (jde-find) Command</title>

	<para>To find an expression with the minibuffer-based find
	  command:</para>

	<orderedlist>
	  <listitem>
	    <para>
	      Select 
	      <menuchoice>
		<shortcut>
		  <keycombo>
		    <keysym>C-c</keysym>
		    <keysym>C-v</keysym>
		    <keysym>C-f</keysym>
		  </keycombo>
		</shortcut>
		<guimenu>Find</guimenu>
		<guimenuitem>Expression</guimenuitem>
	      </menuchoice>
	      from the <guimenu>JDE</guimenu> menu
	      or execute the <command>jde-find</command> command.
	    </para>
	    <para>The JDEE prompts you to enter a regular expression.</para>
	    <screenshot>
	      <mediaobject>
		<imageobject>
		  <imagedata fileref="images/find_minibuf_prompt_regex.gif"/>
		</imageobject>
		<textobject>
		  <phrase>Screenshot showing the regular expression prompt.</phrase>
		</textobject>
	      </mediaobject>
	    </screenshot>
	  </listitem>
	  <listitem>
	    <para>Enter a regular expression that matches the
	      expressions you want to find and press <keycap>Enter</keycap>.</para>
	    <para>The JDEE prompts you to enter a list of directories to search.</para>
	    <screenshot>
	      <mediaobject>
		<imageobject>
		  <imagedata fileref="images/find_minibuf_prompt_dirs.gif"/>
		</imageobject>
		<textobject>
		  <phrase>Screenshot showing the directories prompt.</phrase>
		</textobject>
	      </mediaobject>
	    </screenshot>
	    <para>The prompt may list a default search path. The JDEE determines the
	      default path by testing each of the following variables in the order
	      listed.</para>
	    <itemizedlist>
	      <listitem>
		<para><varname>jde-sourcepath</varname></para>
	      </listitem>
	      <listitem>
		<para><varname>jde-compile-option-sourcepath</varname></para>
	      </listitem>
	      <listitem>
		<para><varname>jde-compile-option-classpath</varname></para>
	      </listitem>
	      <listitem>
		<para><varname>jde-global-classpath</varname></para>
	      </listitem>
	    </itemizedlist>
	    <para>The JDEE uses the directories
	      specified by the first path variable that has a nonnil
	      value as the default search path.</para>
	  </listitem>
	  <listitem>
	    <para>Edit the default search path, if desired, in the minibuffer
	      and press <keycap>Enter</keycap>.</para>
	    <para>The JDEE executes the find command that you have specified
	    and displays the command's output in a popup grep-mode buffer.</para>
	    <screenshot>
	      <mediaobject>
		<imageobject>
		  <imagedata fileref="images/find_minibuf_result.gif"/>
		</imageobject>
		<textobject>
		  <phrase>Screenshot showing the search results.</phrase>
		</textobject>
	      </mediaobject>
	    </screenshot>
	  </listitem>	  
	</orderedlist>

	<para>The search results buffer lists each instance of a string
	that matches the specified regular expression in the specified
	search path. For each match, the listing shows the file
	and line number of the match, highlighted in red, and a snippet
	of the text in which the match occurred.
	</para>
	<para>To visit the file containing the match, click the
	match message in the grep buffer with the middle mouse button
	or move point to the message and press <keycap>Enter</keycap></para>
      </sect4>

      <sect4>
	<title><anchor id="FindExpressionCustomize"/>Customizing the
	  Minibuffer-Based Find Command</title>
	<para>
	  The following variables allow you to customize the 
	  minibuffer-based search command:
	</para>

	<table>
	  <tgroup cols="3">
	    <thead>
	      <row>
		<entry>Variable</entry>
		<entry>Default Value</entry>
		<entry>Description</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry><varname>jde-find-case-sensitive</varname></entry>
		<entry><literal>nil</literal></entry>
		<entry>Specifies whether the <command>jde-find</command> command
		  performs a case-sensitive search. If non-nil, the
		  search is case-sensitive; otherwise the search
		  ignores case.</entry>		
	      </row>
	      <row>
		<entry><varname>jde-find-granularity</varname></entry>
		<entry><literal>Character</literal></entry>
		<entry>Specifies the granularity of the expression
		  search conducted by <command>jde-find</command>: <literal>Character</literal>
		  (expression starting on any character), <literal>Word</literal> (match
		  words only), <literal>Line</literal> (match lines only).</entry>	
	      </row>
	      <row>
		<entry><varname>jde-find-file-regexp</varname></entry>
		<entry><literal>*.java</literal></entry>
		<entry>Specifies the regular expression that the
		  <command>jde-find</command> command uses to select
		  files to be searched. You can use any regular
		  expression supported by the <literal>-name</literal>
		  option of the GNU <command>find</command>
		  command.</entry>	
	      </row>
	    </tbody>
	  </tgroup>
	</table>
      </sect4>

      <sect4>
	<title><anchor id="FindExpressionDlg"/>Using the Dialog-Based Find (jde-find-dlg) Command</title>

	<para>To find an expression with the dialog-based find command:</para>

	<orderedlist>
	  <listitem>
	    <para>	    
	      Select 
	      <menuchoice>
		<guimenu>Find</guimenu>
		<guimenuitem>Expression...</guimenuitem>
	      </menuchoice>
	      from the <guimenu>JDE</guimenu> menu
	      or execute the <command>jde-find</command> command.
	    </para>

	    <para>The <guilabel>Find Expression Options</guilabel> buffer appears.</para>

	    <screenshot>
	      <mediaobject>
		<imageobject>
		  <imagedata fileref="images/find_options_buffer.gif"/>
		</imageobject>
		<textobject>
		  <phrase>Screenshot showing the Find Expression Options buffer.</phrase>
		</textobject>
	      </mediaobject>
	    </screenshot>

	  </listitem>
	  <listitem>
	    <para>Edit the buffer to reflect the search options that you desire.</para>
	    <note>
	      <para>The options you select will appear the
		next time you execute the <command>jde-find-dlg</command> command.</para>
	    </note>
	  </listitem>
	  <listitem>
	    <para>Select the <guibutton>Ok</guibutton> button.</para>
	  </listitem>
	</orderedlist>

	<para>The <command>jde-find-dlg</command> invokes the
	  <command>find</command> and <command>grep</command> commands
	  with the options you specified and displays the results in a
	  buffer.
	</para>
      </sect4>

    </sect3>

    <sect3>
      <title><anchor id="FindSymbolDef"/>Finding Symbol Definitions</title>
      <para>To find the source code that defines the class, interface,
	method, or field at point, select 
	<menuchoice>
	  <shortcut>
	    <keycombo><keysym>C</keysym><keysym>c</keysym></keycombo>&nbsp;
	    <keycombo><keysym>C</keysym>
	      <keysym>v</keysym></keycombo>&nbsp;
	    <keycombo><keysym>C</keysym><keysym>y</keysym></keycombo>
	  </shortcut>
	  <guimenu>Find</guimenu>
	  <guimenuitem>Symbol Definition</guimenuitem>
	      </menuchoice> from the <guimenu>JDE</guimenu> menu or
	execute <keycombo>
	  <keysym>M</keysym><keysym>x</keysym></keycombo>
	<function>jde-open-class-at-point</function>. The JDEE
	displays a buffer containing the source code that defines the
	symbol at point in the original buffer.</para>

      <note>
	<para>This command requires that the symbol definition be
	  located on <varname>jde-sourcepath</varname> and that the
	  class referenced at point be located on
	  <varname>jde-global-classpath</varname>. The command uses
	  the beanshell to determine the fully qualified name of the
	  class referenced at point. If the beanshell is not running,
	  it launches the beanshell.</para>
      </note>
    </sect3>


    <sect3>

	
      <title><anchor id="FindClasses"/>Finding Classes</title>
	
      <para>The <function>jde-open-class-source</function> command
	finds and opens the Java source file for the class whose
	qualified or unqualified name appears at point.</para>

      <note>
	<para>The JDE uses Java reflection to determine the fully
	  qualified name of the class at point. Therefore, the class
	  must be on <varname>jde-global-classpath</varname>.</para>
      </note>

      <para>If more than one class with the same name exists on
	<varname>jde-global-classpath</varname>, this command prompts
	you to select one of the classes. The following conditions
	must be true for this command to work. First, a class file for
	this class must exist on the classpath specified by
	<varname>jde-global-classpath</varname>. Secondly, the source
	for the class must exist on one of the paths specified by
	<varname>jde-sourcepath</varname>. This command uses the
	Beanshell to determine the fully qualified name of the class
	to be found. It starts the Beanshell if necessary. Thus, the
	command may respond somewhat slowly the first time you it in a
	session. </para>

    </sect3>


    <sect3>
      <title><anchor id="Xref"/>Cross-Referencing Classes</title>


      <para>JDE includes a facility for creating and utilizing a
	cross-referencing database to enable you to quickly locate all
	the callers of any particular function.  This functionality is
	very useful for quickly figuring how unfamiliar code works,
	and useful for doing certain tasks such as renaming functions.
	Be advised that this only finds direct callers, and cannot
	detect calls via Java's reflection mechanism.  The
	cross-reference database must be kept in sync with the project
	code, however the database generation is generally quick. The
	remainder of this section explains how to configure and use
	the cross-referencer.</para>

      <note>The JDEE's cross-referencing facility was developed by Andrew Hyatt.</note>


      <sect4>
	<title><anchor id="ConfigXRef"/>Configuring the Cross-Referencer</title>

	<para>JDE's cross-referencing database is built by examining
	  class files for a particular project.  To this end, JDE
	  needs to know where the built class files for a project
	  live.  This is usually a subset of the classpath.
	</para>

	<para>Then select JDE->Options->Project->General, and go to
	  the "Jde Built Class Path" option.  Insert one path for each
	  place where built classes wind up.  You can add both
	  directories and zip files (jar/bar/etc).  Any file entered
	  will be assumed to be a zip file.</para>

	<para>Now that you have the built class path defined, you can
	  configure the cross-referencer that uses it.  Type M-x
	  jde-xref-customize. The following are a list the variables
	  that can be set, and what they do:
	</para>

	<itemizedlist>
	  <listitem>
	    <para><varname>jde-xref-db-base-directory</varname></para> 

	    <para>The cross-referencer creates a database to
	      store the cross-reference information. This variable
	      defines a directory where that information resides. It
	      might, for example, be at the base of your project tree,
	      in a directory called xrefdb
	    </para>	    
	  </listitem>

	  <listitem>
	    <para><varname>jde-xref-store-prefixes</varname></para>

	    <para>To reduce database size,
	      it's useful to ignore all information that doesn't refer
	      to code you care about. For example, most people don't
	      need to know who calls java.lang.System.out.println.  To
	      not store this information, insert a package prefix for
	      each package you are interested in. Typically, this may
	      be just one string, for example "com.mycompany", to
	      store only code that references com.mycompany
	      classes.</para>
	  </listitem>

	  <listitem>
	    <para><varname>jde-xref-cache-size</varname></para>
	    <para>The caller database can be quite large. However, it
	      is useful for efficiency reasons to keep part of it in
	      memory. This variable deterines how many packages to
	      keep in memory simulatenously. The higher this is, the
	      faster things will be, but also the more memory will be
	      taken up by the cross-reference information.
	    </para>	  
	  </listitem>

	</itemizedlist>
      </sect4>

      <sect4>

	<title><anchor id="BuildingXRefDB"/>Building the Cross-Reference Database</title>


	<para>The next step into getting the cross-reference
	  functionality working is to build the cross-reference
	  database.  The project must be fully built for this to work,
	  since it takes cross-reference information directly from the
	  built classes.
	</para>

	<para>To build the database, type <command>M-x jde-xref-make-xref-db</command></para>

	<para>If all the settings are properly configured, JDE will go
	  off and create the cross-reference database.  This can take
	  from a few seconds to several minutes depending on the size
	  of your project. Large class files may take long to parse,
	  so if it seems to be "stuck", please give it time.
	</para>

	<para>When it is done, it will save the database in the base
	  directory specified in the jde-xref customization group.
	</para>

      </sect4>

      <sect4>

	<title><anchor id="UsingXRefDB"/>Using the Cross-Reference Database</title>
	

	<para>There are several basic operations that use the
	  cross-reference database:
	</para>


	<itemizedlist>

	  <listitem>

	    <para><command>M-x jde-xref-first-caller (C-c C-v a)</command>
	    </para>

	    <para> If your cursor is in the body of a function, then
	      this will go to the first in a sequence of callers to
	      this function.  If there are no callers, there will be a
	      message saying so.
	    </para>

	  </listitem>


	  <listitem>
	    <para><command>M-x jde-xref-next-caller (C-c C-v n)</command></para>

	    <para> After calling <command>jde-xref-first-caller</command>, you can go to
	      each of the callers in sequence with this function.  The
	      first caller function creates a list of callers and goes
	      to the first one.  This navigates to the next caller on
	      the list.  You can keep calling this until there are no
	      more callers, in which case there will be a message
	      saying so.
	    </para>
	  </listitem>

	  <listitem>
	    <para><command>M-x jde-xref-display-call-tree</command>
	    </para>

	    <para>This displays an interactive tree view of the
	      function you are in, and it's callers.  Each level down
	      will show you who calls the parent function.  In this
	      way you can quickly get an overview of the context in
	      which the current function is used in.  Each item in the
	      tree will take you to it's definition if it is clicked
	      on.
	    </para></listitem>

	  <listitem>

	    <para><command>M-x jde-xref-list-uncalled-functions</command></para>

	    <para> Called from a java file, this lists all the
	      functions in the file that have no apparent callers.
	      It's important to remember that because of Java
	      reflection, there is no guarantee that the functions are
	      truly uncalled.  It only means they are not called
	      directly.
	    </para>
	  </listitem>

	</itemizedlist>

	<para>All of these functions have two modes, a strict and
	  non-strict mode. In non-strict mode, the default, more
	  potential callers are treated as callers, including those
	  that call an interface that the function implements, or who
	  call a superclass's function you are overriding. For
	  example, if you are in Foo.doSomething(), and foo implements
	  IFoo, and a caller calls IFoo.doSomething(), then this is
	  treated as a caller in non-strict mode.  Also, if you are in
	  Foo.doSomething, and Foo's superclass is Bar, and there is a
	  Bar.doSomething(), then Bar.doSomething() is treated as a
	  caller in non-strict mode.  In strict mode, however, the
	  caller must specify the function directly for it to be
	  considered a hit.   To run these functions with strict mode,
	  type C-u M-x and then the function-name.  So C-u M-x
	  jde-xref-list-uncalled-functions will list only functions
	  that are uncalled directly.
	</para>

      </sect4>


      <sect4>

	<title><anchor id="UpdatingXRefDB"/>Updating the Cross-Reference Database</title>


	<para>As the code changes, the cross-referencer must be kept
	  up to date, or else the jde-xref functions will start taking
	  you to incorrect places in files, and the callers list
	  itself will become incorrect.  As you change the code, you
	  can call M-x jde-xref-update after a recompile, and it will
	  go through and recompute just the part of the database you
	  have changed.
	</para>

	<para>Another, easier way to update, for those of us who leave
	  their emacs running all the time, is to add a line such as
	  this in their .emacs
	</para>

	<programlisting>
	  (run-at-time "11:00pm" 86400 'jde-xref-make-xref-db)
	</programlisting>

      </sect4>


    </sect3>


    <sect3>
      
	
      <title><anchor id="Tags"/>Tags</title>
	
      <para>To use the <varname>etags</varname> facility, you must
	first construct a  TAGS file that indexes every symbol in your
	source code. The JDE  package contains two shell scripts that
	you can use to tag your  source code, one for
	<command>csh</command> shells and the other for
	<command>bash</command>.  The <command>bash</command> version
	is called <command>jtags</command>; the <command>csh</command>
	version, <command>jtags.csh</command>. </para>
      
      <sect4>

	  
	  <title><anchor id="TaggingCode"/> Tagging Java Source Code</title>

	  
	  
	<para>To tag your source code, first copy the appropriate shell
	  script to a directory in your Emacs path. Then start a shell (<keycombo>
	    <keycap>M</keycap><keycap>x</keycap> </keycombo>&nbsp;
	  shell). Change to the top-level directory containing your
	  source code and then enter <command>jtags</command>. The <command>jtags</command>
	  script tags every <filename>.java</filename> file in the current directory
	  and in all descendants of the current directory, storing the
	  result in a file called <filename>TAGS</filename> in the top-level directory.
	</para>
      </sect4>

      <sect4>
	
	  
	  <title><anchor id="FindingSymbols"/>Finding the Definition of a Symbol</title>
	  
	  
	<para>To find the definition of a symbol, put your cursor anywhere
	  in the symbol and enter
	  <keycombo><keycap>M</keycap><keycap>.</keycap></keycombo>. Emacs
	  responds by locating
	  and opening (if necessary) the file containing the definition and
	  positioning the point at the definition. (The first time you type
	  <keycombo><keycap>M</keycap><keycap>.</keycap></keycombo>, Emacs
	  prompts you to load the <filename>TAGS</filename> file.) </para>
      </sect4>

    </sect3>

  </chapter>

  <chapter>
    
      
      <title><anchor id="CustomizingJDE"/>Customizing the JDE</title>

      
    <para>
      This section describes various ways you can customize the JDE.
    </para>
    
    <sect3>

	
	<title><anchor id="CustomizationVariables"/>Customization Variables</title>
	
      <para>
	JDE customization variables allow you to specify compile, run, debug,
	and other JDE options. </para>

      <note>
	<para> The traditional way of customizing Emacs is to use
	  <varname>setq</varname> forms to set the values of customization
	  variables in the Emacs initialization (<filename>.emacs</filename>)
	  file. This method does <emphasis>not</emphasis> work for JDE
	  customization variables. To set a JDE customization variable, you
	  <emphasis>must</emphasis> use  the customization buffer for a variable
	  (see the Emacs online manual for information on the  customization
	  feature). This is because the JDE context switching code resets all
	  JDE customization variables to their default or customized (via a
	  custom buffer) values whenever you open a Java source file or switch
	  projects.
	</para>  
      </note>

      <para>  The following section explains  how to use the Emacs
	customization  feature to set the value of a JDE customization
	variable.</para>

      <sect4>

	
	<title><anchor id="SettingVariable"/> Setting a Variable</title>
	

	<para>
	  To set a JDE customization variable:
	</para>
      
	<procedure>
	  <step>
	    <para>Determine the name of the variable you want to customize.</para>
	    <para>  Refer to the section of this guide that documents the feature
	      you want to customize for the name of the corresponding variable.  Or
	    type <keycombo><keycap>C</keycap><keycap>h</keycap></keycombo>&nbsp;
	    <keysym>v</keysym> followed by the JDE group prefix
	    (<varname>jde-</varname>) or subgroup prefix (e.g., 
	    <varname>jde-compile-option-</varname>, 
	    see <ulink url="#JDECustomizationGroups">JDE Customization Groups</ulink>). 
	    Emacs displays all  variables belonging to the JDE group or subgroup. You 
	    can then browse this list, using Emacs search, completion,  and
	    documentation display command, to find the applicable  variable.
	    </para>
	  </step>

	  <step>
	  <para>Display a customization buffer for the variable. </para>
	  <para>  If you know the name of the variable, the easiest way to
	    display a   customization buffer for the variable is to select 
	    <menuchoice><guimenu>Help</guimenu><guisubmenu>Customize</guisubmenu>
	      <guimenuitem>Specific Option...</guimenuitem></menuchoice> from the
	    Emacs  menubar or type <keycombo><keycap>M</keycap><keycap>x</keycap>
	    </keycombo>&nbsp;<varname>customize-variable</varname>.
	    If you know the  group to which the variable belongs (.e.g., compile
	    options), you  can display the customization buffer for the group. This
	    is useful when  you want to customize several related variables. See 
	    <ulink url="#JDECustomizationGroups">JDE Customization Groups</ulink> for 
	    more information. 
	  </para>
	</step>

	<step>
	  <para>Edit the value for the variable displayed in the customization
	    buffer. </para>
	</step>

	<step>
	  <para>Save the value for the variable in your <filename>.emacs</filename> 
	    or <filename>.prj</filename> file. 
	  </para>
	  <para>If you want the setting to apply to all projects that do not
	    have a project file  (see <ulink url="#UsingProjectFiles">Using Project
	      Files</ulink>), you should save the variable in your 
	    <filename>.emacs</filename> file. To save the variable in your
	    <filename>.emacs</filename> file, select  <menuchoice><guimenuitem>Save
		for Future Sessions</guimenuitem></menuchoice> from the
	    <menuchoice><guimenu>State</guimenu></menuchoice> menu for the
	    variable in the customization buffer.
	  </para>
	  <para>  If you want the setting to apply only to a particular project,
	    you should save  the setting in the <filename>.prj</filename> file for
	    that project. To do this, open a source  file from that project, select
	    <menuchoice><guimenuitem>Set for Current Session</guimenuitem>
	    </menuchoice> from the <menuchoice><guimenu>State</guimenu>
	    </menuchoice> menu for the variable, select the source buffer, and
	    select  <menuchoice><guimenu>JDE</guimenu>
	      <guisubmenu>Project</guisubmenu><guisubmenu>Project Files</guisubmenu>
	      <guimenuitem>Save</guimenuitem></menuchoice>
	    (<keycombo><keycap>C</keycap><keycap>c</keycap></keycombo>&nbsp;
	    <keycombo><keycap>C</keycap><keycap>v</keycap></keycombo>&nbsp;
	    <keycombo><keycap>C</keycap><keycap>p</keycap></keycombo>) 
	    from the Emacs menubar.
	  </para>
	  <note>
	    <para>  If a project file does exist for the
	      project, the JDE will prompt  you to enter a name for the project. It
	      then creates a project file for the project with  the name that you
	      enter.    
	    </para>
	  </note>  
	</step>
	</procedure>
      
      </sect4>

      <sect4>
	<title><anchor id="SpecifyingPaths"/>Specifying Paths</title>
	<para>You can use paths containing environment variables and
	  or a tilde (~), cygwin paths, and  relative paths as a value
	  of any JDE customization variable that requires a
	  path.</para>

	<sect5>
	  <title><anchor id="EnvVarsInPaths"/>Environment Variables</title>
	  <para>The JDE accepts paths that contain envirnoment variables, for
	    example, </para>

	  <para>
	    <programlisting format="linespecific">
	      $JDK_HOME/src
	    </programlisting>
	  </para>

	  <para>
	    The JDE replaces the environment variables with their
	    actual values before passing the paths to commands (e.g.,
	    javac) that require them. You must use Unix notation
	    (i.e., <varname>$VARNAME</varname> or
	    <varname>${VARNAME}</varname>) to  specify an environment
	    variable in a path even on Windows.
	</para>
	
	</sect5>

	<sect5>
	  <title><anchor id="TildeNotation"/>Tilde (~) Notation</title>
	  <para>The JDE accepts paths that begin with a tilde, for example,
	    <filename>~/myproj/classes</filename>. The JDE replaces the tilde
	    with the path to your home directory.</para>
	</sect5>

	<sect5>
	  <title><anchor id="RelativePaths"/>Relative Paths</title>
	  <para>A relative path is a path that begins with a period, for 
	  example, <filename>./src</filename>. If 
	  <varname>jde-resolve-relative-paths</varname> is
	  set to a non-nil value (the default), the JDE converts a relative 
	  path to an absolute path by appending the relative path to the
	  path of the project file that set the path variable, or if no such
	  file exists, to the path of the current Java source buffer.</para>

	  <para>
	    You can use your <filename>.emacs</filename> file to
	    specify default relative paths for projects. For example,
	    setting <varname>jde-global-classpath</varname> to
	    <filename>./classes</filename> in your
	    <filename>.emacs</filename> file specifies that the
	    default location of class files is in a subdirectory of
	    the project file directory named <filename>classes</filename>.
	  </para>
	</sect5>

	<sect5>
	  <title><anchor id="CygwinPaths"/>Cygwin Paths</title>
	  <para>You can use cygwin style paths in JDE classpath variables
	  on Windows. The JDE converts such paths to DOS paths before
	  using them, using a conversion function that you can specify.</para>
	
	  <para>The jde-cgywin-path-converter variable allows you
	  to choose the path conversion function used by the JDE.</para>

	  <itemizedlist>
	    <listitem>
	      <para><function moreinfo="none">
		jde-cygwin-path-converter-internal</function></para>
	      <para>This is the default path conversion function used by
	      the JDE. It converts any paths of the form <varname>//[a-z]/</varname>
	      or <varname>//cygdrive/[a-z]/</varname> to the corresponding DOS form. For
	      example it converts  <varname>/c/jde/java/classes</varname> to 
	      <varname>c:/jde/java/classes</varname>.	    
	      </para>
	    </listitem>
	    <listitem>
	      <para><function moreinfo="none">jde-cygwin-path-converter-cygpath</function></para>
	      <para>This function invokes the cygwin
		<function>cygpath</function> utility to perform the
		path conversion. The advantage is that the cygwin path
		utility can recognize and convert Unix style paths
		that represent mount points in the cygwin mount table.
		For example, suppose that you have mounted
		<varname>d:/javadev</varname> as
		<varname>/javadev</varname> in the cygwin mount table.
		Then choosing <function
		  moreinfo="none">jde-cygwin-path-converter-cygpath</function> 
		allows you to use paths beginning with
		<varname>/javadev</varname> in JDE classpaths. The
		drawback is that the conversion is slow as it requires
		running the cygwin utility for each Unix-style path to
		be converted.</para>
	    </listitem>
	    <listitem>
	      <para>A custom conversion function that you supply.</para>
	    </listitem>
	  </itemizedlist>

	</sect5>

      </sect4>

      <sect4>

	
	<title><anchor id="JDECustomizationGroups"/> JDE Customization Groups</title>

	
	<para>The JDE defines a top-level customization group, the JDE
	  Group, for JDE customization variables. The JDE Group itself
	  contains the following subgroups:</para>
      

	<sect5>

	  
	  <title><anchor id="CompileOptionGroup"/> Compile Option
	    Group</title>

	  
	  <para>Specifies compile options corresponding to the
	  command-line arguments (e.g., -d) accepted by the JDK
	  compiler, javac. When  you execute the JDE compile command,
	  the JDE uses the settings of  this group to construct a list
	  of command-line arguments that it  passes to the Java
	  compiler that the JDE uses to compile Java  source programs.
	  The compiler is itself an option that you can  specify (see
	  the Project Option Group). You can specify command-line
	  arguments directly by setting the value of the
	  <varname>jde-compile-option-command-line-args</varname>
	  variable. You can display the customization buffer for the
	  Compile Option Group by selecting
	  <menuchoice><guimenu>JDE</guimenu><guisubmenu>
	      Project</guisubmenu>-<guisubmenu>Options</guisubmenu>
	  <guimenuitem>Compile</guimenuitem></menuchoice> from  the
	  <productname>Emacs</productname> menubar. </para>
	 </sect5>

	<sect5>

	  
	  <title><anchor id="CompileOptionGroup"/>Run Option Group</title>

	  
	  <para>Specifies run-time options corresponding to the
	    command-line arguments (for example, -classpath) accepted
	    by the JDK virtual machine, java. When you execute the JDE
	    Run command,&nbsp; the JDE uses the settings of this group
	    to construct a list of command-line arguments that it
	    passes to the Java interpreter used by the JDE to run
	    applications. This group also contains options for
	    specifying non-java command-line arguments (in case you
	    want to use a VM that accepts a different set of arguments
	    than java does) and for specifying arguments to be passed
	    to the application (as opposed to the virtual machine
	    interpreting the application.) You can display the
	    customization buffer for the Run Option Group by selecting
	    <menuchoice><guimenu>JDE</guimenu>
	      <guisubmenu>Project</guisubmenu>-<guisubmenu>Options</guisubmenu> 
	    <guimenuitem>Run</guimenuitem></menuchoice> from  the
	    <productname>Emacs</productname> menubar. </para>
	</sect5>

	<sect5>
	  
	  <title><anchor id="DebugOptionGroup"/>Debug Option Group</title>
	  
	  <para>Specifies run-time options corresponding to the command-line
	  arguments (for example, -classpath) accepted by the JDK debugger,
	  jdb. jdb accepts the same command-line arguments as java. However,
	  the JDE maintains two parallel sets of configuration variables
	  for these programs in case you want to use a different set of
	  options for running a program in debug mode then you use for
	  running it normally. When you execute the JDE Debug command,
	  the JDE uses the settings of this group to construct a list of
	  command-line arguments that it passes to the Java debugger used
	  by the JDE to run applications in debug mode. You can display the
	  customization buffer for the Debug Option Group by selecting 
	  <menuchoice><guimenu>JDE</guimenu>
	    <guisubmenu>Project</guisubmenu>-<guisubmenu>Options</guisubmenu>
	  <guimenuitem>Debug</guimenuitem></menuchoice>
	  from  the <productname>Emacs</productname> menubar. </para>
	</sect5>

	<sect5>

	 
	  <title> <anchor id="AutocodeGroup"/>Autocode Group</title>

	  
	  <para>Specifies templates used to generate code automatically. </para>
	</sect5>

	<sect5>

	  
	  <title><anchor id="GeneralGroup"/> General Options Group</title>

	  
	<para>Specify all other JDE options. You can display the
	  customization buffer for the General Option Group by selecting 
	  <menuchoice><guimenu>JDE</guimenu>
	    <guisubmenu>Project</guisubmenu>-<guisubmenu>Options</guisubmenu>
	  <guimenuitem>General</guimenuitem></menuchoice>
	  from  the <productname>Emacs</productname> menubar. </para>
	</sect5>
	
      </sect4>

    </sect3>

    <sect3>
      
      <title><anchor id="Customizingjde_mode"/> Customizing jde-mode</title>

      
      <para>The JDE defines a major mode, named jde-mode, for editing
	Java source files. This mode derives from the standard Emacs
	Java source editing mode java-mode. In particular, it inherits
	all the functions and customization variables defined by
	java-mode and adds its own customization variables. When you
	load a Java source file, Emacs runs a JDE mode initialization
	function called jde-mode. The jde-mode function in turn calls
	the Java mode intialization function, java-mode. The last
	thing that jde-mode does before returning is to call a JDE
	mode function, if it exists. You can customize the JDE by
	defining a JDE mode hook function in your .emacs file. The
	following is an example of how to do this: </para>
    

    <programlisting>
      (defun my-jde-mode-hook ()
      (message &quot;my-jde-mode-hook function executed&quot;))
       (add-hook 'jde-mode-hook 'my-jde-mode-hook)
       </programlisting>

    <para>The preceding example defines a JDE mode hook function named
      my-jde-mode-hook and adds it to the list of JDE mode hook
      functions, using the Emacs Lisp function add-hook. Now, whenever
      you open a Java source file, jde-mode invokes the function my-jde-mode-hook.
      Of course, the hook function defined in this example is trivial.
      A real-world example might do something more useful, such as
      setting a custom indentation style. </para>
    

    <sect4>

	
	<title><anchor id="Keybindings"/> Customizing Key Bindings</title>

	
      <para>A key binding establishes an equivalence between a keystroke
	or a sequence of keystrokes and an interactive Lisp function. The
	keystroke or keystroke combination causes Emacs to execute the
	function to which the keystroke (combination) is bound. For
	example, the JDE by default binds the keystroke  <keycombo><keycap>C</keycap><keycap>c</keycap></keycombo>&nbsp;<keycombo><keycap>C</keycap><keycap>v</keycap></keycombo>&nbsp;<keycombo><keycap>C</keycap><keycap>c</keycap></keycombo>
	to the function <varname>jde-compile</varname>. You can use the JDE
	customization facility to change the standard JDE bindings or
	create bindings for functions that do not have default bindings. </para>
      
      <para>To customize key bindings: </para>
      
      <procedure>
	<step>
	  <para>Open a buffer on the JDE customization variable <varname>jde-key-bindings</varname>.</para>
	  <para>You can do this by typing
	    <keycombo><keycap>M</keycap><keycap>x</keycap>
	    </keycombo>&nbsp;<varname>customize-variable</varname>&nbsp;
	    <varname>jde-key-bindings</varname> or by selecting <menuchoice>
	      <guimenu>JDE</guimenu><guisubmenu>Options</guisubmenu><guimenuitem>Project</guimenuitem></menuchoice>  and searching the
	    resulting JDE project customization  buffer for
	    <varname>jde-key-bindings</varname>. </para>
	  <para>The key bindings panel looks like this: </para>

	  <para><screenshot>
	      <mediaobject>
		<imageobject>
		  <imagedata fileref="images/keybindings.gif"/>
		</imageobject>
		<textobject>
		  <phrase>Screenshot showing key bindings buffer.</phrase>
		</textobject>
	      </mediaobject>
	    </screenshot>
	  </para>

	</step>
	<step>
	  <para>Edit the buffer to specify altered or new bindings. </para>
	  <para>For example, to add a binding, right click the
	    <guibutton>[INS]</guibutton> button, then enter the key  stroke in the
	    <guilabel>Key</guilabel> field and  the interactive function (command)
	    to which it is bound  in the <guilabel>Command</guilabel> field.</para>
	</step>

	<step>
	  <para>Save the edited bindings. </para>
	  <para>To save the edited bindings, right click the
	    <guibutton>[State]</guibutton> button and choose <menuchoice>
	      <guimenuitem>Set for current session</guimenuitem></menuchoice> if you
	    want the settings to apply only to the current project or
	    <menuchoice><guimenuitem>Save for future
		sessions</guimenuitem></menuchoice>if  you want the settings to apply
	    to all projects. In either  case, you should save the new settings in
	    you project  file if your project has a project file. To save the new
	    settings in your project file, switch to a source buffer  and choose
	    <menuchoice><guimenu>JDE</guimenu><guisubmenu> Options</guisubmenu><guimenuitem>Save Project</guimenuitem></menuchoice>  from the Emacs menubar. 
	  </para>
	  </step>
	</procedure>
      </sect4>
    </sect3>

  </chapter>

  <chapter>
    <title><anchor id="Plugins"/>Creating and Installing Plugins</title>

    <para>Plugins are independently developed applications intended
	for use with the JDEE and distributed in the form of a (g)zip or 
	jar file. The following sections explain how to create and install
	plugins.
    </para>

    <sect3>

      <title><anchor id="InstallingPlugins"/>Installing a Plugin</title>
	
      <para>To install a plugin:</para>

      <orderedlist>
	<listitem>
	  <para>Copy the zip or jar file containing the plugin in to
	    the JDEE's plugins directory.</para>

	  <note>
	    <para>By default the JDEE plugin directory is a
	      subdirectory of the JDEE directory named
	      <filename>plugins</filename>. If you want to keep your
	      plugins in another directory, set
	      <varname>jde-plugins-directory</varname> to the path of
	      that directory.</para>
	    </note>

	</listitem>

	<listitem>

	  <para>Execute <command>M-h jde-pi-install-plugins</command>.</para>
	    <para>This command installs any plugins at the top level of the plugins
	    directory in the plugins directory.</para>

	</listitem>

      </orderedlist>

      <para>If the plugin adds any menu items to the JDEE's plugins menu
	(named <guimenu>JDEpi</guimenu>), you should now be able to see the 
	  items on the plugins menu.</para>
	
    </sect3>

    <sect3>

      <title><anchor id="CreatingPlugins"/>Creating a Plugin</title>

      <para>The following sections explain how to create a JDEE plugin.</para>

      <sect4>

	<title><anchor id="PluginRequirements"/>Plugin Requirements</title>

	<para>A JDEE plugin must meet the following requirements:</para>

	<sect5>

	  <title>Packaging</title>

	    <para>The plugin must be distributed as a compressed file that can be 
	    decompressed by Java's jar program. Compressed file formats that meet this
	    requirement include zip, gzip, and jar.
	    </para>

	</sect5>

	<sect5>

	  <title>Directory Structure</title>

	  <para>Decompressing the plugin should create a subdirectory in the
	    current directory whose name is the plugin's name and that contains 
	    at least one directory named <filename>lisp</filename>. The
	    plugin directory can contain any number of other directories.
	    The other directories can have any names. However, it would be
	    nice if plugins standardized on the following directory structure
	    and names.
	  </para>

	  <programlisting>

   plugin
     bsh
      doc
      scripts
     help
       info
       html
       src      (e.g., xml files used to generate info and html)
     java
       class
       doc
       lib      (e.g, jar files)
       src
     lisp
	  </programlisting>


	</sect5>

	<sect5>

	  <title>Bootstrap File</title>

	  <para>The plugin's lisp directory must contain a Lisp file
	    named <filename>jde-PLUGIN.el </filename>where PLUGIN is
	    the same as the plugin's toplevel directory name. This
	    file is called a bootstrap file because it is the only
	    file directly loaded by the JDEE. It is responsible for
	    registering the plugin with the JDEE and loading any other
	    Lisp files required by the plugin.</para>
	  
	</sect5>

      </sect4>

      <sect4>

	<title><anchor id="RegisteringPlugin"/>Registering a Plugin</title>

	<para>A plugin's bootstrap file must register the plugin with
	  the JDEE when it is loaded. The bootstrap file should do
	  this by invoking the JDEE's
	  <function>jde-pi-register</function> function. This function
	  takes a single argument: an instance of
	  <varname>jde-plugin</varname> class that optionally
	  specifies the plugin's menu and its contribution to the
	  classpath of the instance of the BeanShell run by the
	  JDEE. </para>

      </sect4>

      <sect4>
	<title>Running Java Code from a Plugin</title>

	<para>A plugin can use the JDEE's instance of the BeanShell to
	invoke Java methods and display their output in an Emacs
	buffer. The JDEE provides the following functions for this
	purpose:</para>

	<itemizedlist>

	  <listitem>
	    <para><function>jde-jeval</function></para>
	    <para>Evaluate a Java statement in the JDEE's BeanShell
	      instance and return the resulting BeanShell
	      output.</para>
	  </listitem>

	  <listitem>
	    <para><function>jde-jeval-r</function></para>
	    <para>Evaluate a Java statement in the JDEE's BeanShell
	      instance, use the Emacs Lisp interpreter to evaluate the
	      resulting BeanShell output, and return the result. This
	      function assumes that the Java statement emits Emacs
	      Lisp code, i.e., that the Java code was developed
	      specifically to cause Emacs to do something.
	    </para>
	  </listitem>

	  <listitem>
	    <para><function>jde-jeval-cm</function></para>
	    <para>Evaluate a Java statement in the JDEE's BeanShell
	      instance and display the resulting BeanShell output in
	      an Emacs compilation buffer. This function is intended
	      to run Java applications, such as style checkers, that
	      output error messages keyed to specific lines in a
	      source file.
	    </para>
	  </listitem>

	</itemizedlist>

	<para>See the doc strings for these functions for more information.</para>

	
      </sect4>


     <sect4>

	<title><anchor id="BootstrapExample"/>Bootstrap File Example</title>

	<para>
	  The following is an example of the bootstrap file
	for a plugin named pi1.</para>

	<programlisting>

  ;; jde-pi1.el
  (defun jde-pi1-cmd ()
    (interactive)
    (message "plugin 1"))

  (jde-pi-register
   (jde-plugin 
    "pi1"
    :bsh-cp (list
	   (expand-file-name "lib/lib1.jar" (jde-pi-get-plugin-dir "pi1"))
	   (expand-file-name "lib/lib2.jar" (jde-pi-get-plugin-dir "pi1")))
    :menu-spec (list (list "Pi1" ["cmd" jde-pi1-cmd :active t]))))


  (provide 'jde-pi1)

	</programlisting>

      </sect4>
	
    </sect3>

  </chapter>

</book>



<!-- 
Local Variables: 
mode: xae
sgml-indent-step: 2
sgml-indent-data: t
sgml-set-face: t
sgml-insert-missing-element-comment: nil
End:
 -->