cgit.sxemacs.org Git - packages/blob - xemacs-packages/jde/doc/src/jde-ug/jde-ug-content.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2
   3 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBk XML V4.4CR2//EN"
   4  "file:///c:/home/xae-dev/xae/doctypes/docbook/docbookx.dtd" []>
   5
   6
   7 <?xml-stylesheet href="file:///c:/home/jde-dev/jde/doc/src/styles/html/jdebook.xsl" type="text/xsl"  ?>
   8
   9
  10 <!--
  11 <?xml-stylesheet href="file:///d|tpe-dev/tpe/styles/docbook/html/docbook.xsl" type="text/xsl"  ?>
  12 -->
  13
  14 <book>
  15
  16
  17  <title>JDEE User's Guide</title>
  18
  19   <bookinfo>
  20
  21     <releaseinfo>
  22       <remark>
  23         Revised for JDEE <productnumber>2.3.6</productnumber>
  24       </remark>
  25     </releaseinfo>
  26
  27     <copyright>
  28       <year>1997</year>
  29       <year>1998</year>
  30       <year>1999</year>
  31       <year>2000</year>
  32       <year>2001</year>
  33       <year>2002</year>
  34       <year>2003</year>
  35       <year>2004</year>
  36       <year>2005</year>
  37       <holder>Paul Kinnucan</holder>
  38     </copyright>
  39   </bookinfo>
  40
  41   <chapter>
  42
  43       <title><anchor id="Intro"/>Introduction</title>
  44
  45
  46     <para>Welcome to the <emphasis>JDEE User's Guide</emphasis>. This
  47       guide explains how to use the JDEE to develop Java applications and
  48       applets. The guide assumes that you are familiar with Emacs, the
  49       Java programming language, and Java development tools provided
  50       by Sun Microsystems, Inc.</para>
  51
  52     <note>
  53       <para>
  54         This guide and the JDEE user interface use the term &quot;JDK&quot; to
  55         refer to Sun's Java 2 Software Development Kit (SDK) and its
  56         predecessors.
  57       </para>
  58     </note>
  59
  60     <sect3>
  61
  62         <title><anchor id="AboutJDE"/>About the JDEE</title>
  63
  64
  65       <para>The Java Development Environment for Emacs (JDEE) is an
  66         Emacs Lisp package that interfaces Emacs to third-party Java
  67         application development tools, such as those provided by Sun
  68         Microsystems as part of its JDK. The result is an integrated
  69         development environment (IDE) comparable in power to many
  70         commercial Java IDEs. Features include: </para>
  71
  72       <itemizedlist>
  73
  74         <listitem>
  75           <para>source code editing with syntax highlighting and auto
  76             indentation</para>
  77         </listitem>
  78         <listitem>
  79           <para>automatic completion of class fields and methods
  80           </para>
  81         </listitem>
  82         <listitem>
  83           <para>compilation with automatic jump from error messages
  84             to responsible line in the source code.</para>
  85         </listitem>
  86         <listitem>
  87           <para>
  88             generates class and method skeletons automatically
  89           </para>
  90         </listitem>
  91         <listitem>
  92           <para>run Java application in an interactive (comint)
  93             Emacs buffer
  94           </para>
  95         </listitem>
  96         <listitem>
  97           <para>
  98             integrated debugging with interactive debug command
  99             buffer and automatic display of current source file/line
 100             when stepping through code
 101           </para>
 102         </listitem>
 103         <listitem>
 104           <para>
 105             browse JDK doc, using the browser of your choice
 106           </para>
 107         </listitem>
 108
 109         <listitem><para>
 110             browse your source code, using the Emacs etags facility
 111             or a tree-structured speedbar.
 112           </para></listitem>
 113
 114         <listitem><para>
 115             supports latest version of JavaSoft's Java Development
 116           </para></listitem>
 117
 118         <listitem><para>
 119             runs on any platform supported by Emacs and Sun's Java SDK (e.g.,
 120             Win95/NT and Solaris)
 121           </para></listitem>
 122
 123         <listitem><para>
 124             easily and infinitely customizable
 125           </para></listitem>
 126
 127         <listitem><para>
 128             works with FSF Emacs and XEmacs
 129           </para></listitem>
 130
 131       </itemizedlist>
 132
 133     </sect3>
 134
 135
 136     <sect3>
 137
 138       <title><anchor id="JDERequirements"/>JDE Requirements</title>
 139
 140
 141       <para>The JDE requires the following software: </para>
 142
 143       <itemizedlist>
 144
 145         <listitem>
 146           <para><ulink url="http://www.gnu.org/">FSF Emacs</ulink> or
 147             <ulink url="http://www.xemacs.org/">XEmacs</ulink> on Unix
 148             platforms; the 20.6.1 version (or later) of
 149             <ulink url="ftp://ftp.gnu.org/gnu/windows/emacs/latest">NT/Emacs</ulink> on
 150             Windows platforms, for general source file editing and tool integration functions.
 151           </para></listitem>
 152
 153         <listitem><para>
 154             <ulink url="http://java.sun.com/j2se">Java
 155               Development Kit (JDK)</ulink> or compatible set of Java
 156             development tools (compiler, virtual machine, debugger,
 157             class libraries, etc.)
 158           </para></listitem>
 159
 160         <listitem><para>
 161             Web browser (e.g., Netscape or Internet Explorer) for
 162             viewing documentation.
 163           </para></listitem>
 164
 165         <listitem>
 166           <para>
 167             latest versions of Eric Ludlam's <symbol>speedbar</symbol>,
 168             <symbol>semantic</symbol>, and
 169             <symbol>eieio</symbol> packages available for download from
 170             <ulink url="http://cedet.sourceforge.net">the CDET home page</ulink>
 171           </para></listitem>
 172
 173         <listitem>
 174           <para>
 175             The elib package available from the
 176             <ulink url="http://jdee.sunsite.dk">JDE web site</ulink>
 177           </para></listitem>
 178
 179
 180         <listitem>
 181           <para>
 182             <command>bash</command> or another Unix-style shell highly
 183             recommended for Windows95/NT environments. The <ulink
 184               url="http://sources.redhat.com/cygwin">cygwin</ulink>
 185             Unix emulation package for Windows from Red Hat includes
 186             <command>bash</command>.
 187           </para>
 188         </listitem>
 189
 190       </itemizedlist>
 191
 192     </sect3>
 193
 194     <sect3>
 195
 196         <title><anchor id="JDEComponents"/>JDEE Components</title>
 197
 198
 199
 200       <para>
 201         The JDEE distribution includes the following files:
 202       </para>
 203
 204       <itemizedlist>
 205
 206         <listitem><para>
 207
 208
 209             <ulink  url="../../../lisp/jde.el"><filename>jde.el</filename></ulink>.
 210             Defines jde-mode, a major Emacs mode for developing Java code.
 211           </para></listitem>
 212
 213         <listitem><para>
 214             <ulink url="../../../lisp/jde-run.el"><filename>jde-run.el</filename></ulink>.
 215             Runs Java applications and applets
 216           </para></listitem>
 217
 218         <listitem><para>
 219             <ulink url="../../../lisp/jde-db.el"><filename>jde-db.el</filename></ulink>.
 220             Interfaces Emacs to <command>jdb</command>, the command-line debugger that
 221             comes with the JDK.
 222           </para></listitem>
 223
 224         <listitem>
 225           <para>
 226             <ulink
 227               url="../../../lisp/jde-gen.el"><filename>jde-gen.el</filename></ulink>.
 228             Contains code generation templates.
 229           </para>
 230         </listitem>
 231
 232         <listitem>
 233           <para>
 234             <filename>bsh.jar</filename>. Compiled files for the
 235             <ulink url="http://www.beanshell.org/">BeanShell</ulink>,
 236             a Java source code interpreter developed by Pat Neimeyer.
 237           </para>
 238         </listitem>
 239
 240         <listitem>
 241           <para>
 242             <ulink
 243               url="../../../lisp/beanshell.el"><filename>beanshell.el</filename></ulink>.
 244             Provides an Emacs interface to the BeanShell interpreter.
 245           </para>
 246         </listitem>
 247
 248         <listitem>
 249           <para>
 250             <ulink
 251               url="../../../lisp/jde-wiz.el"><filename>jde-wiz.el</filename></ulink>.
 252             Provides &quot;wizards&quot; that generate skeleton
 253             implementations of interfaces and skeleton overrides of
 254             methods declared by superclasses.
 255           </para></listitem>
 256
 257         <listitem>
 258           <para>
 259             <ulink
 260               url="../../../lisp/jde-complete.el"><filename>jde-complete.el</filename></ulink>.
 261             Automatic field and method completion package.
 262           </para>
 263         </listitem>
 264
 265         <listitem><para>
 266             <ulink url="../../../lisp/jde-parse.el"><filename>jde-parse.el</filename></ulink>.
 267             Java parser package.</para>
 268         </listitem>
 269
 270         <listitem><para>
 271             <ulink url="../../../lisp/java.bnf"><filename>java.bnf</filename></ulink>.
 272             Java grammar used to generate the JDE's lisp-based Java parser.
 273           </para></listitem>
 274
 275         <listitem><para>
 276             <ulink url="../../../lisp/jde-bug.el"><filename>jde-bug.el
 277               </filename></ulink>.
 278             JDEbug user interface package.
 279           </para></listitem>
 280
 281         <listitem><para>
 282             <ulink url="../../../lisp/jde-dbs.el"><filename>jde-dbs.el</filename></ulink>.
 283             JDEbug low-level command interface package.
 284           </para></listitem>
 285
 286         <listitem><para>
 287             <ulink url="../../../lisp/jde-dbo.el"><filename>jde-dbo.el</filename></ulink>.
 288             JDEbug output processing functions.
 289           </para></listitem>
 290
 291         <listitem>
 292           <para>
 293             source code, jar files, and documentation for the <ulink
 294               url="../../java/">Java components</ulink> of the
 295             JDE.</para>
 296         </listitem>
 297
 298         <listitem>
 299           <para><ulink
 300               url="../../../lisp/jtags"><filename>jtags</filename></ulink>
 301             is a bash shell script that tags Java source hierarchies.
 302           </para>
 303         </listitem>
 304
 305         <listitem>
 306           <para>
 307             <ulink
 308               url="../../../lisp/jtags.csh"><filename>jtags.csh</filename></ulink>
 309             is a c shell script that tags Java source heierarchies.
 310           </para>
 311         </listitem>
 312
 313       </itemizedlist>
 314     </sect3>
 315
 316
 317     <sect3>
 318
 319         <title><anchor id="LatestVersion"/>Latest Version</title>
 320
 321
 322       <para>See <ulink url="http://jdee.sunsite.dk/rootpage.html#Downloading">
 323           Downloading the JDE</ulink> on the JDE website for instructions on
 324         downloading the most recent version of the JDE.
 325       </para>
 326
 327
 328     </sect3>
 329
 330     <sect3>
 331       <title><anchor id="InstallingJDE"/>Installing the JDE</title>
 332       <para>See the <ulink url="http://jdee.sunsite.dk/install.html">
 333         JDE Installation Guide</ulink> on the JDE website for information
 334       on installing the JDE on your system.</para>
 335     </sect3>
 336
 337     <sect3>
 338
 339
 340         <title><anchor id="ContactingAuthor"/>Contacting the Author</title>
 341
 342
 343       <para>Please send bug reports and enhancement suggestions to
 344         <ulink url="mailto:pkinnucan@comcast.net">Paul Kinnucan</ulink>.
 345       </para>
 346
 347     </sect3>
 348
 349   </chapter>
 350
 351   <chapter>
 352     <title><anchor id="RegisterSelectJDK"/>Registering and Selecting a JDK</title>
 353
 354     <para>The JDEE relies on command-line Java development tools, such
 355       as those supplied by Sun Microsystems as part of its Java 2
 356       Software Development Kit (SDK) also known as a Java Development
 357       Kit (JDK). Before you can use the JDEE to compile, debug, or run
 358       an application, you must tell it where the Java compiler,
 359       debugger, and virtual machine are located on your system. The
 360       JDEE assumes that the compiler, debugger, and vm are named
 361       <filename>javac</filename>, <filename>jdb</filename>, and
 362       <filename>java</filename>, respectively, and that they are
 363       located on your system's command path. If these tools are not
 364       located on the system command path or have different names, you
 365       must tell the JDEE where they are located. The JDEE provides
 366       customization variables for specifying the locations of
 367       individual tools.
 368     </para>
 369
 370     <para>
 371       However, if you are using one or more versions of Sun's JDK or a
 372       clone of the Sun JDK, the easiest way to specify the location of
 373       the external development tools is to register the version of the
 374       JDK that you intend to use. It is especially advantageous to
 375       register a JDK, if you intend to use multiple versions of the
 376       JDK. The reason? Registering each version of the JDK allows you
 377       to change JDKs by changing a single customization variable. The
 378       following sections explain how to register and select
 379       JDKs.
 380     </para>
 381
 382     <sect3>
 383
 384       <title><anchor id="RegisterJDK"/>Registering a JDK</title>
 385
 386       <para>To register a version of the JDK with the JDEE:</para>
 387
 388       <orderedlist>
 389         <listitem>
 390           <para>Start Emacs.</para>
 391         </listitem>
 392         <listitem>
 393           <para>Type <command>M-x customize-variable</command> and
 394             press <command>Enter</command></para>
 395           <para>Emacs prompts you to enter the name of a variable
 396           to customize.</para>
 397         </listitem>
 398         <listitem>
 399           <para>Enter <varname>jde-jdk-registry</varname> and
 400           press <command>Enter</command>.</para>
 401           <para>The <varname>jde-jdk-registry</varname> customization
 402           buffer appears.</para>
 403           <screenshot>
 404             <mediaobject>
 405               <imageobject>
 406                 <imagedata fileref="images/regjdk1.gif"/>
 407               </imageobject>
 408             </mediaobject>
 409           </screenshot>
 410         </listitem>
 411         <listitem>
 412           <para>Click the <command>INS</command> button.</para>
 413           <para>The entry for the JDK appears.</para>
 414           <screenshot>
 415             <mediaobject>
 416               <imageobject>
 417                 <imagedata fileref="images/regjdk2.gif"/>
 418               </imageobject>
 419             </mediaobject>
 420           </screenshot>
 421         </listitem>
 422         <listitem>
 423           <para>Enter the version number of the JDK and the path of the directory
 424           in which the JDK is installed.</para>
 425         </listitem>
 426         <listitem>
 427           <para>Repeat the preceding steps until you have entered the versions and
 428           paths of all versions of the JDK that you wish to use with the JDEE.</para>
 429           <screenshot>
 430             <mediaobject>
 431               <imageobject>
 432                 <imagedata fileref="images/regjdk3.gif"/>
 433               </imageobject>
 434             </mediaobject>
 435           </screenshot>
 436         </listitem>
 437         <listitem>
 438           <para>Click the <command>State</command> button.</para>
 439           <para>The <command>State</command> menu appears.</para>
 440         </listitem>
 441         <listitem>
 442           <para>Select <command>Save for Future Sessions</command> from
 443             the <command>State</command> menu.</para>
 444           <note>
 445             <para>This saves the setting of <varname>jde-jdk-registry</varname>
 446               in your <filename>.emacs</filename> file.</para>
 447           </note>
 448         </listitem>
 449         <listitem>
 450           <para>Click the <command>Finish</command> button to dismiss
 451           the customization buffer.</para>
 452         </listitem>
 453       </orderedlist>
 454
 455     </sect3>
 456
 457     <sect3>
 458       <title><anchor id="SelectingJDK"/>Selecting a JDK</title>
 459       <para>To select a JDK:</para>
 460       <orderedlist>
 461         <listitem>
 462           <para>Type <command>M-x customize-variable</command> and
 463             press <command>Enter</command></para>
 464           <para>Emacs prompts you to enter the name of a variable
 465           to customize.</para>
 466         </listitem>
 467         <listitem>
 468           <para>Enter <varname>jde-jdk</varname> and
 469           press <command>Enter</command>.</para>
 470           <para>The <varname>jde-jdk</varname> customization
 471           buffer appears.</para>
 472           <screenshot>
 473             <mediaobject>
 474               <imageobject>
 475                 <imagedata fileref="images/seljdk1.gif"/>
 476               </imageobject>
 477             </mediaobject>
 478           </screenshot>
 479           <para>The buffer lists the JDKs that you have previously registered
 480             (see <ulink url="#RegisterJDK">Registering a JDK</ulink>).</para>
 481         </listitem>
 482         <listitem>
 483           <para>Click the radio button next to the version of the JDK you
 484           want to use.</para>
 485         </listitem>
 486         <listitem>
 487           <para>Click the <command>State</command> button.</para>
 488           <para>The <command>State</command> menu appears.</para>
 489         </listitem>
 490         <listitem>
 491           <para>Select <command>Save for Future Sessions</command> from
 492             the <command>State</command> menu.</para>
 493         </listitem>
 494         <listitem>
 495           <para>Click the <command>Finish</command> button to dismiss
 496           the customization buffer.</para>
 497         </listitem>
 498       </orderedlist>
 499       <note>
 500         <para>This procedure saves your JDK selection in your
 501           <filename>.emacs</filename> file so that it applies to all
 502           projects. You can configure the JDEE to use different JDKs
 503           for different projects by saving your customization in a
 504           project file. See <ulink url="#UsingProjectFiles">Using
 505             Project Files</ulink> or more information.</para>
 506       </note>
 507     </sect3>
 508
 509   </chapter>
 510
 511   <chapter>
 512
 513       <title><anchor id="EditingJavaSourceFiles"/>Editing Java Source Files</title>
 514
 515
 516
 517     <para>
 518       To edit an existing Java source file, load it into an Emacs
 519       buffer by executing <command>C-x C-f</command>. Loading a Java source file
 520       into a buffer causes the buffer to enter into <function>jde-mode</function>,
 521       a variant of <function>java-mode</function>, which is in turn a variant of
 522       the standard Emacs <function>cc-mode</function> for editing source files
 523       written in C and related languages. <function>jde-mode</function> offers all the
 524       specialized source file editing commands of <function>cc-mode</function> plus
 525       functions for creating, compiling, building, running, and debugging Java source files.
 526       You can invoke the commands by selecting them from the <guimenu>JDE</guimenu>
 527       menu that <function>jde-mode</function> displays on the Emacs menu bar or by
 528       typing the commands in the Emacs minibuffer.
 529     </para>
 530
 531     <para>
 532       <screenshot>
 533         <mediaobject>
 534           <imageobject>
 535             <imagedata fileref="images/jdemenu.gif" width="544" depth="350"/>
 536           </imageobject>
 537           <textobject>
 538             <phrase>Screenshot showing the JDE menu.</phrase>
 539           </textobject>
 540         </mediaobject>
 541       </screenshot>
 542     </para>
 543
 544   </chapter>
 545
 546
 547   <chapter>
 548
 549
 550     <title><anchor id="DocumentingCode"/>Documenting Code</title>
 551
 552     <para>
 553       The JDE provides complete support for generating HTML
 554       documentation for Java classes from comments inserted into the
 555       source code for those classes.
 556     </para>
 557
 558     <para>See also</para>
 559     <para><ulink url="#DisplayingDoc">Displaying Java
 560         Documentation</ulink></para>
 561
 562     <sect3>
 563
 564
 565       <title><anchor id="InsertingComments"/>Inserting Javadoc
 566         Comments</title>
 567
 568       <para>
 569         To insert a skeleton javadoc comment for a class or method,
 570         position point in the first line of the method or class and
 571         select <guimenuitem>JDE-&gt;Document</guimenuitem> from the
 572         Emacs menubar  or type <command>C-c C-v j</command>.
 573       </para>
 574
 575       <para>
 576         To customize the javadoc skeletons, select
 577         <guimenuitem>JDE-&gt;Options-&gt;Project-&gt;Javadoc</guimenuitem>
 578         from the Emacs menubar.
 579       </para>
 580
 581       <note>
 582         <title>Thanks...</title>
 583         <para>
 584           to <ulink url="mailto:david@dponce.com">David Ponce</ulink>
 585           for developing the JDE's javadoc comment generation
 586           facility.
 587         </para>
 588       </note>
 589
 590     </sect3>
 591
 592     <sect3>
 593
 594
 595       <title><anchor id="GeneratingJavadoc"/>Generating the
 596         Documentation</title>
 597
 598
 599       <para>
 600         To generate documentation for the current project, open any
 601         source file in the project and select <guimenuitem>Make
 602           Doc</guimenuitem> from the <guimenu>JDE</guimenu> menu or
 603         enter <command>M-x jde-javadoc-make</command>.
 604       </para>
 605
 606       <para>
 607         The <command>jde-javadoc-make</command> command runs the JDK's
 608         javadoc program to generate the documentation. The
 609         <command>javadoc</command> command must be on your system's
 610         command path.
 611       </para>
 612
 613       <para>
 614           The <command>jde-javadoc-make</command> command uses
 615         <varname>jde-global-classpath</varname> as the
 616         <varname>-classpath</varname> and <varname>jde-sourcepath
 617         </varname> as the <varname>-sourcepath</varname> option for
 618         generating the doc. You can specify all other javadoc options
 619         via JDE customization variables. To specify the options,
 620         select <menuchoice><guimenu>Project</guimenu>
 621           <guisubmenu>Options</guisubmenu><guimenuitem>Javadoc</guimenuitem></menuchoice>
 622
 623
 624           from the
 625           <menuchoice><guimenu>JDE</guimenu></menuchoice> menu. Use
 626           <varname>jde-javadoc-gen-packages</varname> to specify the
 627           packages, classes, or source files for which you want to
 628           generate javadoc. If this variable is
 629           <varname>nil</varname>, the
 630           <command>jde-javadoc-make</command> generates javadoc for
 631           the Java source file in the current buffer.
 632       </para>
 633
 634       <note>
 635         <para>
 636           Thanks to <ulink url="mailto:sakliban@cs.wustl.edu">Sergey A
 637             Klibanov </ulink> for developing the JDE's javadoc
 638           generation facility.
 639         </para>
 640       </note>
 641
 642     </sect3>
 643
 644   </chapter>
 645
 646   <chapter>
 647
 648     <title><anchor id="Abbrevs"/>Abbreviations</title>
 649
 650     <para>
 651       The JDEE allows you to use abbreviations for Java keywords and
 652       control flow constructs. The following sections explain how to
 653       use these abbreviations.
 654     </para>
 655
 656
 657     <sect3>
 658
 659
 660       <title><anchor id="KeywordAbbrevs"/>Keyword
 661         Abbreviations</title>
 662
 663       <para>The JDEE defines a set of abbreviations for Java keywords.
 664         When you type one of these abbreviations followed by a space
 665         in a Java source buffer, the JDE optionally expands the
 666         abbreviation into the keyword. For example, when the
 667         abbreviation mode is enabled, you need only type
 668         <varname>fa</varname> followed by a space to enter the Java
 669         keyword <varname>false</varname>. To enable or disable
 670         abbreviation mode by default for a project, select
 671         <menuchoice><guimenu moreinfo="none">JDE</guimenu>
 672           <guisubmenu
 673             moreinfo="none">Project</guisubmenu><guisubmenu>Options
 674           </guisubmenu><guimenuitem>General</guimenuitem></menuchoice>
 675         and toggle the boolean variable
 676         <varname>jde-enable-abbrev-mode</varname>. To toggle
 677         abbreviation mode on or off during a session, select
 678         <menuchoice>
 679           <guimenu>JDE</guimenu>
 680           <guisubmenu>Code Generation</guisubmenu>
 681           <guisubmenu>Modes</guisubmenu>
 682           <guimenuitem>Abbrev</guimenuitem>
 683         </menuchoice>. To change, remove, or add an abbreviation, edit
 684         the variable <varname>jde-mode-abbreviations</varname> in the
 685         project customization buffer.</para>
 686
 687       <note><para>The JDE's Java keyword expansion facility is based
 688           on the Emacs <varname>abbrev-mode</varname> facility. For
 689           more information, see the Emacs user manual.</para></note>
 690
 691     </sect3>
 692
 693     <sect3>
 694
 695
 696       <title><anchor id="ControlFlowAbbrevs"/>Control Flow
 697         Abbreviations</title>
 698
 699       <para>The JDEE defines abbreviations for Java control flow
 700         structures, such as if-then-else. When you enter the
 701         abbreviation followed by a space, the JDE expands the
 702         abbreviation into a corresponding control structure
 703         template.</para>
 704
 705       <example>
 706         <title>Expanding a Control Flow Abbreviation</title>
 707
 708         <para>The if-then-else abbreviation</para>
 709
 710         <programlisting>
 711           ife
 712         </programlisting>
 713
 714         <para>expands to the control flow structure</para>
 715
 716         <programlisting>
 717           if ( ) { } // end of if () else } // end of if ()else
 718         </programlisting>
 719       </example>
 720
 721       <sect4>
 722         <title>Control Flow Abbreviations</title>
 723
 724         <para>The JDE defines the following abbreviations for control
 725           structures.</para>
 726
 727         <table>
 728           <title>Control Flow Abbreviations</title>
 729           <tgroup cols="2">
 730             <colspec colnum="1"></colspec>
 731             <colspec colnum="2"></colspec>
 732             <thead>
 733               <row><entry>Statement</entry><entry>Abbreviation</entry></row>
 734             </thead>
 735             <tbody>
 736               <row>
 737                 <entry><varname>if-then</varname></entry>
 738                 <entry><varname>if</varname></entry>
 739               </row>
 740               <row>
 741                 <entry><varname>else</varname></entry>
 742                 <entry><varname>else</varname></entry>
 743               </row>
 744               <row>
 745                 <entry><varname>if-then-else</varname></entry>
 746                 <entry><varname>ife</varname></entry>
 747               </row>
 748               <row>
 749                 <entry><varname>else-if</varname></entry>
 750                 <entry><varname>eif</varname></entry>
 751               </row>
 752               <row>
 753                 <entry><varname>while</varname></entry>
 754                 <entry><varname>while</varname></entry>
 755               </row>
 756               <row>
 757                 <entry><varname>for</varname></entry>
 758                 <entry><varname>for</varname></entry>
 759               </row>
 760               <row>
 761                 <entry><varname>for (int
 762                     I=0;I&lt;UL;I++)</varname></entry>
 763                 <entry><varname>fori</varname></entry>
 764               </row>
 765               <row>
 766                 <entry><varname>for (Iterator i = c.iterator();
 767                     i.hasNext();)</varname></entry>
 768                 <entry><varname>foriter</varname></entry>
 769               </row>
 770               <row>
 771                 <entry><varname>main method</varname></entry>
 772                 <entry><varname>main</varname></entry>
 773               </row>
 774               <row>
 775                 <entry><varname>switch</varname></entry>
 776                 <entry><varname>switch</varname></entry>
 777               </row>
 778               <row>
 779                 <entry><varname>case</varname></entry>
 780                 <entry><varname>case</varname></entry>
 781               </row>
 782               <row>
 783                 <entry><varname>try</varname></entry>
 784                 <entry><varname>try</varname></entry>
 785               </row>
 786               <row>
 787                 <entry><varname>catch</varname></entry>
 788                 <entry><varname>catch</varname></entry>
 789               </row>
 790               <row>
 791                 <entry><varname>try finally</varname></entry>
 792                 <entry><varname>tryf</varname></entry>
 793               </row>
 794               <row>
 795                 <entry><varname>finally</varname></entry>
 796                 <entry><varname>finally</varname></entry>
 797               </row>
 798             </tbody>
 799           </tgroup>
 800         </table>
 801
 802         <note>
 803           <para>
 804             You must enable the JDE's Java keyword abbreviation mode
 805             to use the control flow abbreviations. See <ulink
 806               url="#JavaKeywordCompletion">Java Keyword
 807               Completion</ulink> for more information.
 808           </para>
 809         </note>
 810
 811       </sect4>
 812
 813       <sect4>
 814         <title>Left Brace Placement</title>
 815
 816         <para>
 817           The JDE's Java control flow templates support two options
 818           for opening brace placement: placement on the first line of
 819           the template (Kerningham &amp; Ritchie Style, the default)
 820           and placement on a separate line. Type <command>M-x
 821             customize-variable jde-gen-k&amp;r</command> to specify
 822           the style you prefer.
 823         </para>
 824
 825       </sect4>
 826
 827       <sect4>
 828
 829         <title>Customizing the Control Flow Templates</title>
 830
 831         <para>You can customize the templates to suit any indentation
 832           style. To customize the templates, select
 833             <menuchoice>
 834             <guimenu>Project</guimenu>
 835             <guisubmenu>Options</guisubmenu>
 836             <guimenuitem>Autocode</guimenuitem>
 837           </menuchoice> from the JDE menu.</para>
 838
 839       </sect4>
 840
 841       <sect4>
 842
 843         <title>Adding Your Own Control Flow Templates</title>
 844         <para>
 845           Use the <function>jde-gen-define-abbrev-template</function>
 846           function to define your own control flow abbreviation in
 847           your  <filename>.emacs</filename> file. For example, the
 848           following code defines an abbreviation  for an else clause.
 849         </para>
 850         <programlisting>
 851           (jde-gen-define-abbrev-template "melse" '('> "else {" '> 'n
 852           '> 'r 'n "}"))
 853         </programlisting>
 854         <para>The <function
 855             moreinfo="none">jde-gen-define-abbrev-template</function>
 856           function takes two arguments. The first argument is a string
 857           that specifies the abbreviation. The section argument is a
 858           list defining the text that replaces the abbreviation. The
 859           list can contain any of the following elements.</para>
 860         <table>
 861           <title>Template Elements</title>
 862           <tgroup cols="2">
 863             <thead>
 864               <row>
 865                 <entry>Element</entry>
 866                 <entry>Usage</entry>
 867               </row>
 868             </thead>
 869             <tbody>
 870               <row>
 871                 <entry>A string.</entry>
 872                 <entry>The string is inserted into the buffer at
 873                   point.</entry>
 874               </row>
 875               <row>
 876                 <entry>The symbol <varname>'p</varname>.</entry>
 877                 <entry>This position is saved in
 878                   <varname>tempo-marks</varname>.</entry>
 879               </row>
 880               <row>
 881                 <entry>The symbol <varname>'r</varname>.</entry>
 882                 <entry>If <varname>tempo-insert</varname> is called
 883                   with <varname>ON-REGION</varname> non-nil the
 884                   current region is placed here. Otherwise it works
 885                   like 'p.</entry>
 886               </row>
 887               <row>
 888                 <entry><varname>(p PROMPT &lt;NAME&gt;
 889                     &lt;NOINSERT&gt;)</varname></entry>
 890                 <entry>If <varname>tempo-interactive</varname> is
 891                   non-nil, the user is prompted in the minbuffer with
 892                   <varname>PROMPT</varname> for a string to be
 893                   inserted. If the optional parameter
 894                   <varname>NAME</varname> is non-nil, the text is
 895                   saved for later insertion with the
 896                   <varname>s</varname> tag. If there already is
 897                   something saved under <varname>NAME</varname> that
 898                   value is used instead and no prompting is made. If
 899                   <varname>NOINSERT</varname> is provided and non-nil,
 900                   nothing is inserted, but text is still saved when a
 901                   <varname>NAME</varname> is provided. For clarity,
 902                   the symbol <varname>'noinsert</varname> should be
 903                   used as argument.</entry>
 904               </row>
 905               <row>
 906                 <entry><varname>(P PROMPT &lt;NAME&gt;
 907                     &lt;NOINSERT&gt;)</varname></entry>
 908                 <entry>Works just like the previous element, but
 909                   forces <varname>tempo-interactive</varname> to be
 910                   true.</entry>
 911               </row>
 912               <row>
 913                 <entry><varname>(r PROMPT &lt;NAME&gt;
 914                     &lt;NOINSERT&gt;)</varname></entry>
 915                 <entry>Like the previous, but if
 916                   <varname>tempo-interactive</varname> is
 917                   <varname>nil</varname> and
 918                   <varname>tempo-insert</varname> is called with
 919                   <varname>ON-REGION</varname> non-nil, the current
 920                   region is placed here. This usually happens when you
 921                   call the template function with a prefix
 922                   argument.</entry>
 923               </row>
 924               <row>
 925                 <entry><varname>(s NAME)</varname></entry>
 926                 <entry>Inserts text previously read with the
 927                   <varname>(p ..)</varname> construct. Finds the
 928                   insertion saved under <varname>NAME</varname> and
 929                   inserts it. Acts like <varname>'p</varname> if
 930                   <varname>tempo-interactive</varname> is
 931                   <varname>nil</varname>.</entry>
 932               </row>
 933               <row>
 934                 <entry><varname>'&amp;</varname></entry>
 935                 <entry>If there is only whitespace between the line
 936                   start and point, nothing happens. Otherwise a
 937                   newline is inserted.</entry>
 938               </row>
 939               <row>
 940                 <entry><varname>'%</varname></entry>
 941                 <entry>If there is only whitespace between point and
 942                   end-of-line nothing happens. Otherwise a newline is
 943                   inserted.</entry>
 944               </row>
 945               <row>
 946                 <entry><varname>'n</varname></entry>
 947                 <entry>Inserts a newline.</entry>
 948               </row>
 949               <row>
 950                 <entry><varname>'&gt;</varname></entry>
 951                 <entry>The line is indented using
 952                   <varname>indent-according-to-mode</varname>. Note
 953                   that you often should place this item after the text
 954                   you want on the line.</entry>
 955               </row>
 956               <row>
 957                 <entry><varname>'n&gt;</varname></entry>
 958                 <entry>Inserts a newline and indents line.</entry>
 959               </row>
 960               <row>
 961                 <entry><varname>'r&gt;</varname></entry>
 962                 <entry>Like <varname>r</varname>, but it also indents
 963                   the region.</entry>
 964               </row>
 965               <row>
 966                 <entry><varname>'o</varname></entry>
 967                 <entry>Like <varname>'%</varname> but leaves the point
 968                   before the new line.</entry>
 969               </row>
 970               <row>
 971                 <entry>Anything else.</entry>
 972                 <entry>It is evaluated and the result is treated as an
 973                   element to be inserted. One additional tag is useful
 974                   for these cases. If an expression returns a list
 975                   <varname>'(l foo bar)</varname>, the elements after
 976                   <varname>'l</varname> will be inserted according to
 977                   the usual rules. This makes it possible to return
 978                   several elements from one expression.</entry>
 979               </row>
 980             </tbody>
 981           </tgroup>
 982         </table>
 983
 984       </sect4>
 985
 986       <sect4>
 987         <title>Enabling Variable Content</title>
 988
 989         <para>Some templates optionally prompt you for items to insert
 990           into the template. To enable  prompting, set the variable
 991           <varname>tempo-interactive</varname> to a
 992           non-<varname>nil</varname> value in your
 993           <filename>.emacs</filename> file.</para>
 994       </sect4>
 995
 996       <sect4>
 997         <title>Disabling the Control Flow Abbreviations</title>
 998
 999         <para>To disable the control flow abbreviations, set the
1000           variable <varname>jde-gen-cflow-enable</varname> off.</para>
1001
1002         <note>
1003           <title>Thanks to...</title>
1004
1005           <para>Thanks to Eric D. Friedman &gt;friedman@lmi.net&lt;
1006             for contributing the control flow templates.</para>
1007         </note>
1008
1009       </sect4>
1010
1011     </sect3>
1012
1013   </chapter>
1014
1015   <chapter>
1016
1017
1018       <title><anchor id="CodeCompletion"/>Completing Expressions</title>
1019
1020       <para>
1021         Both Emacs and the JDEE provide commands for completing incomplete
1022         expressions. Emacs provides commands that work for any expression
1023         but only if the completions exist in an open buffer. The JDEE
1024         provides completion commands that work for any Java method or field
1025         name that exists on <varname>jde-global-classpath</varname>.
1026         The following sections explain how to use completion facilities
1027         supplied by the JDEE and by Emacs itself.
1028
1029       </para>
1030
1031       <sect3>
1032
1033       <title><anchor id="FieldAndMethodCompletion"/>Completing Method
1034         and Field Names</title>
1035
1036
1037       <para>
1038         The JDEE provides comamnds that can complete an incomplete
1039         field or method name. All the methods determine the set of
1040         possible completions for an incomplete field or method name at
1041         point. They differ in how they present the completions to you
1042         for selection. The commands include:</para>
1043
1044       <itemizedlist>
1045         <listitem>
1046           <para><command>jde-complete-in-line</command></para>
1047           <para>This command uses the first completion that it finds
1048             to complete the method or field name at point. If multiple
1049             completions exist, it allows you to cycle through the
1050             completions, each completion replacing the previous in the
1051             source buffer.  See <ulink url="#InLineCompletion">Using
1052               In-Line Completion</ulink> for more information.
1053           </para>
1054         </listitem>
1055         <listitem>
1056           <para><command>jde-complete-menu</command></para>
1057           <para>
1058             This command displays a menu of possible completions for
1059             the incomplete method or field name at point. It enters
1060             the completion that you select in the source buffer. See
1061             <ulink url="#MenuCompletion">Using Menu-Based
1062               Completion</ulink> for more information.
1063           </para>
1064         </listitem>
1065         <listitem>
1066           <para><command>jde-complete-minibuf</command></para>
1067           <para>
1068             This command uses the minibuffer to display possible
1069             completions for the incomplete method or field name at
1070             point. The comamnd enters the completion that you select
1071             in the source buffer. See <ulink
1072               url="#MinibufferCompletion">Using Minibuffer-Based
1073               Completion</ulink> for more information.</para>
1074         </listitem>
1075         <listitem>
1076           <para><command>jde-complete</command></para>
1077           <para>This is the JDEE's user-definable "standard"
1078             completion command. It delegates completion to one of the
1079             JDEE's other completion commands
1080             (<command>jde-complete-menu</command> by default) or to a
1081             custom completion function that you specify (see <ulink
1082               url="SelectCompletionMethod">Selecting a Completion
1083               Method</ulink> for more information.) The
1084             <command>jde-complete</command> command is bound by
1085             default to the key combination <command>C-c C-v
1086               C-.</command>. If you prefer another binding, use the
1087             customization variable <varname>jde-key-bindings</varname>
1088             to change the binding.
1089           </para>
1090         </listitem>
1091       </itemizedlist>
1092
1093       <para>
1094         The JDEE's field and method completion commands use the
1095         Beanshell to run Java code that in turn uses Java's reflection
1096         (class introspection) capability to determine the fields and
1097         methods defined for the class of object at point. The commands
1098         start the Beanshell if it is not running. This can cause a
1099         noticeable delay in completion the first time it is used in a
1100         session. The response can also be slow for classes containing
1101         many methods and fields.
1102       </para>
1103
1104       <note>
1105         <para>See <ulink url="#SpeedingUpCompletion">Speeding Up Completion</ulink>
1106         for some tips on how you can dramatically speed up field and
1107         method completion.</para>
1108       </note>
1109
1110       <para>
1111         Completion works only for compiled classes that reside in the
1112         classpath defined by <varname>jde-global-classpath</varname>,
1113         if set, otherwise by the <varname>CLASSPATH</varname>
1114         environment variable when the Beanshell starts. Thus, if the
1115         JDEE is unable to complete a method or field, make sure that
1116         the class that defines the field or method is compiled and
1117         exists on the classpath defined by
1118         <varname>jde-global-classpath</varname>, if set, otherwise by
1119         the <varname>CLASSPATH</varname> environment variable.
1120       </para>
1121
1122
1123       <para>
1124         The JDEE completion commands work for all of the following
1125         cases.
1126       </para>
1127
1128       <itemizedlist>
1129         <listitem>
1130           <para>objects referenced by variables declared in the
1131             current buffer</para>
1132         </listitem>
1133         <listitem>
1134           <para>static fields and methods</para>
1135         </listitem>
1136         <listitem>
1137           <para>
1138             fields and methods of objects defined by the current class
1139             and its parent
1140           </para>
1141           <para>
1142             Names of fields and methods of the current class must
1143             start with <varname>this</varname> or <varname>.</varname>
1144             (period). Names of fields and methods declared by the
1145             parent of the current class must start with
1146             <varname>super</varname>.
1147           </para>
1148           <para>For example, this command completes</para>
1149           <programlisting>
1150             . ^ this. ^ super. ^
1151           </programlisting>
1152         </listitem>
1153
1154         <listitem>
1155           <para>
1156             objects referenced by the fields of objects referenced by
1157             variables declared in the current class or its parent or
1158             by static fields
1159           </para>
1160           <para>For example, this command completes</para>
1161           <programlisting>
1162             System.out.prin ^
1163           </programlisting>
1164         </listitem>
1165
1166         <listitem>
1167           <para>
1168             objects returned by methods of objects referenced by
1169             variables defined in the current
1170           </para>
1171           <para>
1172             For example, this command completes
1173           </para>
1174           <programlisting>
1175             Toolkit.getDefaultToolkit().get ^
1176           </programlisting>
1177         </listitem>
1178
1179         <listitem>
1180           <para>
1181             objects referenced by method parameters</para>
1182           <para>
1183             For example, this command completes
1184           </para>
1185           <programlisting>
1186             void setColor(String color) { color.get ^ }
1187           </programlisting>
1188         </listitem>
1189       </itemizedlist>
1190
1191
1192
1193       <sect4>
1194         <title><anchor id="SelectStdCompletionMethod"/> Selecting a
1195           Completion Method</title>
1196
1197         <para>The JDEE's generic completion command,
1198           <command>jde-complete</command> delegates completion to one
1199           of several specific completion commands supplied by the JDEE
1200           or to a custom completion method that you supply. This
1201           allows you to customize <command>jde-complete</command> to
1202           use the completion method that you prefer.</para>
1203
1204         <para>To specify your preferred completion method:</para>
1205
1206         <orderedlist>
1207
1208
1209           <listitem>
1210             <para>Open a customization buffer for
1211               <varname>jde-complete-function</varname>.</para>
1212
1213             <screenshot>
1214               <mediaobject>
1215                 <imageobject>
1216                   <imagedata fileref="images/completion_sel_method.gif"/>
1217                 </imageobject>
1218               </mediaobject>
1219             </screenshot>
1220           </listitem>
1221
1222           <listitem>
1223             <para>Select the completion command that implements the
1224               completion method you prefer.</para>
1225           </listitem>
1226
1227           <listitem>
1228             <para>If you selected <varname>Custom</varname> as your
1229               preferred completion function, enter the name of the
1230               custom completion function in the adjacent edit field,
1231               replacing the existing contents
1232               (<varname>ignore</varname> by default.).
1233             </para>
1234           </listitem>
1235
1236           <listitem>
1237             <para>Save your selection in your
1238               <filename>.emacs</filename> or project file.
1239             </para>
1240           </listitem>
1241
1242         </orderedlist>
1243
1244       </sect4>
1245
1246
1247       <sect4>
1248         <title><anchor id="MenuCompletion"/>Using Menu-Based
1249           Completion</title>
1250         <para>The <command>jde-complete-menu</command> displays a
1251           popup menu of completions for the method or field name at
1252           point. Selecting a completion from the menu causes the
1253           command to use it to complete the method or field at point.
1254           This section assumes that you have selected
1255           <command>jde-complete-menu</command> as your standard
1256           completion command.
1257         </para>
1258
1259         <para>To select completions from a menu:</para>
1260
1261         <orderedlist>
1262           <listitem>
1263             <para>Position point immediately following the partially
1264               complete field or method name.</para>
1265
1266             <screenshot>
1267               <mediaobject>
1268                 <imageobject>
1269                   <imagedata fileref="./images/completion_menu1.gif"/>
1270                 </imageobject>
1271               </mediaobject>
1272             </screenshot>
1273
1274           </listitem>
1275
1276           <listitem>
1277             <para>Type the <command>C-c C-v C-.</command> key combination.</para>
1278
1279             <para>A menu of completions pops up.</para>
1280
1281             <screenshot>
1282               <mediaobject>
1283                 <imageobject>
1284                   <imagedata fileref="./images/completion_menu2.gif"/>
1285                 </imageobject>
1286               </mediaobject>
1287             </screenshot>
1288
1289           </listitem>
1290
1291           <listitem>
1292             <para>Select the desired completion from the menu.</para>
1293
1294             <para>The JDEE inserts the completion at point in the
1295               buffer.</para>
1296
1297             <screenshot>
1298               <mediaobject>
1299                 <imageobject>
1300                   <imagedata fileref="./images/completion_menu3.gif"/>
1301                 </imageobject>
1302               </mediaobject>
1303             </screenshot>
1304
1305           </listitem>
1306
1307         </orderedlist>
1308
1309       </sect4>
1310
1311
1312       <sect4>
1313
1314         <title><anchor id="InLineCompletion"/>Using In-Line
1315           Completion</title>
1316
1317         <para>
1318           The <command>jde-complete-in-line</command> command allows
1319           you to select completions at the point of insertion in the
1320           source buffer. The command finds all the fields and methods
1321           that complete the name at point. It then inserts the first
1322           potential completion in the buffer at point. Repeatedly
1323           executing the command causes  the JDEE to cycle through the
1324           other potential completions. If the completion is a method
1325           name, the command completes the method name and displays the
1326           method signature in the minibuffer.
1327         </para>
1328
1329         <para>
1330           The <command>jde-complete-in-line</command> command is bound
1331           to <command>C-c C-v .</command>. You can use this
1332           combination to invoke the command or <command>C-c C-v
1333             C-.</command>, if you have selected this command as your
1334           preferred completion method. The following examples use the
1335           <command>C-c C-v .</command> combination.
1336         </para>
1337
1338
1339         <example>
1340           <title>Completing a String Method Name</title>
1341           <para>
1342               Typing
1343             <keycombo><keysym>C-c</keysym><keysym>C-v</keysym><keysym>.</keysym></keycombo>
1344           </para>
1345
1346           <programlisting>
1347             String s; s.get ^
1348           </programlisting>
1349           <para>
1350             completes the method name at point as follows</para>
1351
1352           <programlisting>
1353             String s; s.getClass( ^
1354           </programlisting>
1355
1356           <para>and displays</para>
1357
1358           <programlisting>
1359             java.lang.Class getClass()
1360           </programlisting>
1361
1362           <para>in the minibuffer. Repeatedly typing
1363             <keycombo><keysym>C-c</keysym><keysym>C-v</keysym><keysym>.</keysym></keycombo>
1364             cycles through all the other get methods for the Java
1365             <varname>String</varname> class.</para>
1366         </example>
1367
1368       </sect4>
1369
1370
1371       <sect4>
1372         <title><anchor id="SpeedingUpCompletion"/>Speeding Up Completion</title>
1373
1374         <para>Here are two ways you can significantly speed up field
1375           and method completion:
1376         </para>
1377         <itemizedlist>
1378
1379           <listitem>
1380             <para>Byte-compile the eieio and JDEE packages.</para>
1381
1382             <para>The beanshell package, the Emacs interface to the
1383               BeanShell, is based on the eieio object-oriented Lisp
1384               package for Emacs. Completion uses the BeanShell heavily
1385               to determine the class of the field or method at point.
1386               Thus compiling eieio and beanshell.el improves
1387               completion's performance, dramatically in my tests.
1388             </para>
1389
1390           </listitem>
1391
1392           <listitem>
1393             <para>Import by class, not by package, in your Java files.
1394             </para>
1395
1396             <para>Every package import, e.g.,
1397               <filename>java.util.*</filename>, requires invoking the
1398               BeanShell to determine the fully qualified name of the
1399               class at point (see
1400               <function>jde-parse-get-qualified-name</function>).
1401               A Beanshell invocation is by far the most time-consuming
1402               operation required for completion. Thus eliminating the
1403               use of package-level imports can significantly
1404               speed up completion.
1405             </para>
1406
1407           </listitem>
1408
1409         </itemizedlist>
1410
1411       </sect4>
1412
1413
1414     </sect3>
1415
1416     <sect3>
1417
1418
1419         <title><anchor id="DynamicKeywordCompletion"/>Dynamic Keyword Completion</title>
1420
1421         <para>Emacs provides dynamic completion commands that attempt
1422           to find completions for the word at point in the current
1423           buffer or other buffers.
1424         </para>
1425
1426         <example>
1427           <title>Using Dynamic Completion</title>
1428
1429           <para>
1430             Suppose that the current source buffer contains the class
1431             names <varname>Component</varname> and
1432             <varname>Container</varname>. Now suppose you enter
1433             <varname>Co</varname> somewhere in the buffer and type
1434             <keycombo><keycap>M</keycap><keycap>/</keycap></keycombo>.
1435
1436             The text <varname>Component</varname> replaces
1437             <varname>Co</varname> in the buffer.
1438           </para>
1439
1440           <para>Typing
1441             <keycombo><keycap>M</keycap><keycap>/</keycap></keycombo>
1442             again changes <varname>Component</varname> to
1443             <varname>Container</varname>. In this way, you can cycle
1444             through all the possible completions for
1445             <varname>Co</varname> in the current buffer.
1446           </para>
1447         </example>
1448
1449       <sect4>
1450         <title>Dynamic Completion Commands</title>
1451
1452         <para>Emacs provides two dynamic completion commands.</para>
1453         <para>
1454             The <command>dabbrev-expand</command> command is bound to
1455           the key combination
1456           <keycombo><keycap>M</keycap><keycap>/</keycap></keycombo>
1457             by default. It searches the current buffer for completions
1458             of the word at point and, if none are found, other buffers
1459             of the same type. For example, if the current buffer is a
1460             Java source buffer, it searches other Java source buffers
1461             for completions if none are found in the active buffer.
1462         </para>
1463
1464         <para>
1465           The <command>hippie-expand</command> command provides more
1466           extensive search capabilities. See the docstrings for these
1467           functions for more information.
1468         </para>
1469
1470       </sect4>
1471
1472       <sect4>
1473         <title>Electric Return</title>
1474         <para>In electric return mode, pressing the
1475           <keycap>Enter</keycap> key causes the JDEE to close open
1476           braces at the end of a line. To enable or disable this
1477           mode by default, customize <varname>jde-electric-return-p</varname>.
1478           To turn the mode on or off during  a session, select <menuchoice>
1479             <guimenu>JDE</guimenu>
1480             <guisubmenu>Code Generation</guisubmenu>
1481             <guisubmenu>Modes</guisubmenu>
1482             <guimenuitem>Electric Return</guimenuitem>
1483           </menuchoice>.</para>
1484       </sect4>
1485
1486     </sect3>
1487
1488   </chapter>
1489
1490   <chapter>
1491
1492
1493     <title><anchor id="GeneratingCode"/>Generating Code</title>
1494
1495     <para>The JDE provides the following code generation capabilities.</para>
1496
1497       <itemizedlist>
1498         <listitem><para>Code wizards</para></listitem>
1499         <listitem><para>Code templates</para></listitem>
1500       </itemizedlist>
1501
1502
1503     <sect3>
1504       <title><anchor id="GeneratingImportStatements"/>Generating Import Statements</title>
1505
1506       <para>The JDEE provides a set of commands that generate and
1507       organize import statements in the current buffer. The commands
1508       automate the following tasks:</para>
1509
1510       <itemizedlist>
1511         <listitem>
1512           <para>Generate an import statement for the class at point (see
1513             <ulink url="#ImportingClasses">Importing Classes</ulink>).</para>
1514         </listitem>
1515         <listitem>
1516           <para>Generate import statements for all classes in the current
1517             buffer that need import statements (see
1518             <ulink url="#ImportingAllClasses">Importing All Classes</ulink>).</para>
1519         </listitem>
1520         <listitem>
1521           <para>Expand a package import statement into specific class imports (see
1522             <ulink url="#ExpandingPackageImports">Expanding Package Imports</ulink>).</para>
1523         </listitem>
1524         <listitem>
1525           <para>Collapse class imports into a package import statement (see
1526             <ulink url="#CollapsingClassImports">Collapsing Class Imports</ulink>).</para>
1527         </listitem>
1528         <listitem>
1529           <para>Group import statements (see
1530             <ulink url="#GroupingImports">Grouping Imports</ulink>).</para>
1531         </listitem>
1532         <listitem>
1533           <para>Sort import statements alphabetically (see
1534             <ulink url="#SortingImports">Sorting Imports</ulink>).</para>
1535         </listitem>
1536         <listitem>
1537           <para>Delete superfluous import statements (see
1538             <ulink url="#DeletingImports">Deleting Imports</ulink>).</para>
1539         </listitem>
1540       </itemizedlist>
1541
1542
1543       <sect4>
1544
1545
1546         <title><anchor id="ImportingClasses"/>Importing Classes</title>
1547
1548         <para>
1549           The <menuchoice>
1550             <guimenu>JDE</guimenu>
1551             <guisubmenu>Import</guisubmenu><guimenuitem>Class</guimenuitem></menuchoice>&nbsp;
1552           (<command>jde-import-find-and-import</command>,
1553           <keycombo><keycap>C</keycap><keycap>c</keycap></keycombo>&nbsp;
1554           <keycombo><keycap>C</keycap><keycap>v</keycap></keycombo>&nbsp;
1555           <keycombo><keycap>C</keycap><keycap>z</keycap></keycombo>)&nbsp;command
1556           generates an import statement for the
1557           class at point in the current buffer. It inserts the import
1558           statement at the head of the buffer.
1559         </para>
1560
1561         <para>This command uses the BeanShell to search the classpath
1562           of the current project for classes that match the name of
1563           the class at point. The class name may be unqualified.</para>
1564
1565         <note>
1566           <para>
1567             The classpath that the import wizard searches for import
1568             candidates is the classpath specified by the value of
1569             <varname>jde-global-classpath</varname> for the current
1570             project.
1571           </para>
1572         </note>
1573
1574
1575         <para>If the command finds more than one class of the same
1576           unqualified name on the current classpath, it prompts you to
1577           select one of the classes to import.</para>
1578
1579
1580         <para>
1581           The customization variable
1582           <varname>jde-import-excluded-classes</varname> allows
1583           you to specify rules for excluding classes from
1584           consideration for import into the current source file. If
1585           the import command finds any classes on the classpath that
1586           belong to the list of prohibited classes, it removes them
1587           from the list of classes considered for import into the
1588           current buffer.
1589         </para>
1590
1591         <para>You can use either regular expressions or Lisp functions to
1592           specify class exclusion rules. For each rule, you can also
1593           specify that all classes whose unqualified names match the
1594           rule be excluded from consideration for import. This is
1595           useful for preventing the JDEE from importing alternate
1596           implementations of standard Java classes that do not need to
1597           be imported.</para>
1598
1599         <para>For example, the default setting for
1600           <varname>jde-import-excluded-classes</varname> includes a
1601           rule to exclude all classes belonging to the
1602           <varname>java.lang</varname> package because every Java
1603           class implicitly imports this package. The default setting
1604           for <varname>jde-import-excluded-classes</varname> also
1605           excludes all unqualified synonyms of classes belonging to
1606           the <varname>java.lang</varname> package. This prevents
1607           importation of alternate implementations of these classes,
1608           e.g., alternate implementations of
1609           <varname>java.lang.String</varname>, included in some
1610           commonly used class libraries and intended for internal use.
1611           See the docstring for
1612           <varname>jde-import-excluded-classes</varname> for more
1613           information.</para>
1614
1615         <note>
1616           <title>Thanks to ...</title>
1617           <para><ulink url="mailto:len@reeltwo.com">Len
1618               Trigg</ulink> for contributing the initial
1619             implementation of the import wizard and to
1620             Martin Schwarmberger for significantly
1621             enhancing the import wizard.
1622           </para>
1623         </note>
1624
1625
1626       </sect4>
1627
1628       <sect4>
1629
1630
1631         <title><anchor id="ImportingAllClasses"/>Importing All Classes</title>
1632
1633         <para>The <menuchoice>
1634             <guimenu>JDE</guimenu>
1635             <guisubmenu>Code Generation</guisubmenu>
1636             <guisubmenu>Import</guisubmenu>
1637             <guimenuitem>All</guimenuitem>
1638           </menuchoice> (<command>jde-import-all</command>,
1639           <keycombo>
1640             <keycap>C</keycap>
1641             <keycap>c </keycap>
1642           </keycombo>
1643
1644           <keycombo>
1645             <keycap>C</keycap>
1646             <keycap>v </keycap>
1647           </keycombo>
1648           <keycap>z</keycap>
1649           ) imports all the classes that need to be
1650           imported into the current buffer.
1651           </para>
1652
1653         <para>
1654           The command imports all classes that meet the following
1655           conditions:</para>
1656
1657         <itemizedlist>
1658           <listitem>
1659             <para>The class's base name begins with an uppercase letter.</para>
1660           </listitem>
1661           <listitem>
1662             <para>The class's base name contains at least one noninitial
1663             lowercase letter.</para>
1664           </listitem>
1665           <listitem>
1666             <para>The class is not already imported into the buffer.</para>
1667           </listitem>
1668           <listitem>
1669             <para>The class is not in
1670               <varname>jde-import-excluded-classes</varname>.</para>
1671           </listitem>
1672           <listitem>
1673             <para>The class exists on the current classpath.</para>
1674           </listitem>
1675         </itemizedlist>
1676
1677         <para>If more than one import candidate with the same base
1678           name exists on the classpath, the JDEE displays a dialog
1679           that allows you to select one of the candidates.</para>
1680
1681
1682         <note>
1683           <para>You can use the <menuchoice>
1684             <guimenu>JDE</guimenu>
1685             <guisubmenu>Code Generation</guisubmenu>
1686             <guisubmenu>Import</guisubmenu>
1687             <guimenuitem>Import All Unique</guimenuitem>
1688           </menuchoice> (<command>jde-import-all-unique</command>
1689           ) command to avoid the dialog box. This command imports all classes
1690           whose unqualified names appear only once on the classpath.</para>
1691         </note>
1692
1693
1694         <note>
1695           <title>Thanks to ...</title>
1696           <para><ulink url="mailto:p.lord@russet.org.uk">Phillip
1697               Lord</ulink> for contributing the initial implementation
1698             of the Import All Wizard.</para>
1699         </note>
1700
1701
1702
1703       </sect4>
1704
1705       <sect4>
1706         <title><anchor id="ExpandingPackageImports"/>Expanding Package Imports</title>
1707         <para>To expand a package import statement, select <menuchoice>
1708             <guimenu>JDE</guimenu>
1709             <guisubmenu>Code Generation</guisubmenu>
1710             <guisubmenu>Import</guisubmenu>
1711             <guisubmenu>Expand Package Imports</guisubmenu>
1712           </menuchoice>
1713           (<command>jde-import-expand-imports</command>). This command replaces
1714           a package import statement, e.g.,
1715         </para>
1716
1717         <para><programlisting>
1718   import java.io.*;
1719           </programlisting></para>
1720         <para>with import statements for the members of that package referenced
1721         by the current buffer, e.g.,</para>
1722         <para><programlisting>
1723   import java.io.BufferedReader;
1724   import java.io.InputStreamReader;
1725   import java.io.IOException;
1726           </programlisting></para>
1727
1728      </sect4>
1729
1730
1731       <sect4>
1732         <title><anchor id="CollapsingClassImports"/>Collapsing Class Imports</title>
1733         <para>To collapse class import statements in  the current buffer into
1734           package imports, select <menuchoice>
1735             <guimenu>JDE</guimenu>
1736             <guisubmenu>Code Generation</guisubmenu>
1737             <guisubmenu>Import</guisubmenu>
1738             <guisubmenu>Collapse Class Imports</guisubmenu>
1739           </menuchoice> (<command>jde-import-collapse-imports</command>). This command
1740           collapses imports for any package that contains as many as or more than the
1741           number of imports specified by <varname>jde-import-collapse-imports-threshhold</varname>.
1742           The default value of this variable is 2. This causes this command to collapse
1743           imports for any package from which the current buffer imports two or more classes.
1744           For example, this command, by default, collapses
1745         </para>
1746         <programlisting>
1747   import java.io.BufferedReader;
1748   import java.io.InputStreamReader;
1749   import java.io.IOException;
1750 </programlisting>
1751         <para>to</para>
1752         <programlisting>
1753   import java.io.*;
1754 </programlisting>
1755       </sect4>
1756
1757       <sect4>
1758         <title><anchor id="GroupingImports"/>Grouping Imports</title>
1759         <para>To organize import statements into groups of related imports, select
1760           <menuchoice>
1761             <guimenu>JDE</guimenu>
1762             <guisubmenu>Code Generation</guisubmenu>
1763             <guisubmenu>Import</guisubmenu>
1764             <guisubmenu>Organize Imports</guisubmenu>
1765           </menuchoice> (<command>jde-import-organize</command>). By default this command
1766           groups import statements into two groups separated by a blank line. The first
1767           group contains all imports from the java and javax packages. The other group
1768           contains imports from all other packages. The imports are sorted alphabetically
1769           in ascending order in each group, e.g.,
1770         </para>
1771         <programlisting>
1772   import java.io.InputStreamReader;
1773   import java.util.Hashtable;
1774   import javax.swing.JFrame;
1775   import javax.swing.JPanel;
1776
1777   import jmath.LinearSystem;
1778   import jmath.Test;
1779 </programlisting>
1780         <para>The following variables allow you to customize the organization of imports
1781         into groups:</para>
1782         <itemizedlist>
1783           <listitem>
1784             <para><varname>jde-import-group-function</varname></para>
1785             <para>This variable allows you to specify a function that assigns imports
1786               to groups. The default group function is <function>jde-import-group-of</function>,
1787             which uses rules specified by the following variable to assign imports to
1788             groups.</para>
1789           </listitem>
1790           <listitem>
1791             <para><varname>jde-import-group-rules</varname></para>
1792             <para>This variable specifies a list of rules for assigning import statements to
1793               group, e.g., <filename>'(("^javax\\." . "Swing"))</filename>,
1794               Each rule consists of two parts: a regular expression and an optional
1795               group name specifier. The <function>jde-import-group-of</function> function assigns
1796             an import statement to the group if it matches the regular expression. The group name
1797             specifier is either a string that specifies the name or an index to a component of the regular
1798             expression to be used as the group name.</para>
1799           </listitem>
1800           <listitem>
1801             <para><varname>jde-import-insert-group-names</varname></para>
1802             <para>Specifies whether to insert an import group's name in the buffer.</para>
1803           </listitem>
1804           <listitem>
1805             <para><varname>jde-import-default-group-name</varname></para>
1806             <para>Specifies the default name for an import group.</para>
1807           </listitem>
1808           <listitem>
1809             <para><varname>jde-import-blank-line-between-groups</varname></para>
1810             <para>Specifies whether to insert a blank line between import groups.</para>
1811           </listitem>
1812           <listitem>
1813             <para><varname>jde-import-sorted-groups</varname></para>
1814             <para>Specifies whether and how to sort groups of packages. Options include
1815             no sorting, in the order specified by grouping rules, or in ascending or
1816             descending alphabetical order.</para>
1817           </listitem>
1818         </itemizedlist>
1819       </sect4>
1820
1821       <sect4>
1822         <title><anchor id="DeletingUnneededImports"/>Deleting Unneeded Imports</title>
1823
1824         <para>
1825           To delete superfluous import statements from the current buffer, select
1826           <menuchoice>
1827             <guimenu>JDE</guimenu>
1828             <guisubmenu>Code Generation</guisubmenu>
1829             <guisubmenu>Import</guisubmenu>
1830             <guisubmenu>Delete Unneeded</guisubmenu>
1831           </menuchoice>
1832           (<command>jde-import-kill-extra-imports</command>). This command deletes all
1833           import statements for classes that are not actually referenced by the class
1834           in the current buffer.
1835         </para>
1836
1837       </sect4>
1838
1839
1840     </sect3>
1841
1842     <sect3>
1843
1844
1845       <title><anchor id="CodeWizards"/>Code Wizards</title>
1846
1847       <para>
1848         The JDE provides a set of procedural code generators called
1849         code wizards. They include:
1850       </para>
1851
1852       <table>
1853         <title>Code Wizards</title>
1854         <tgroup cols="2">
1855           <thead>
1856             <row>
1857               <entry><para>Wizard</para></entry>
1858               <entry><para>Generates...</para></entry>
1859             </row>
1860           </thead>
1861           <tbody>
1862             <row>
1863               <entry>
1864                 <para><ulink url="#MethodOverrideWizard">Method
1865                     Override Wizard</ulink></para>
1866               </entry>
1867               <entry>
1868                 <para> A method that overrides a method inherited by
1869                   the class containing point. </para>
1870               </entry>
1871             </row>
1872             <row>
1873               <entry>
1874                 <para><ulink url="#InterfaceWizard">Interface
1875                     Wizard</ulink></para>
1876               </entry>
1877               <entry>
1878                 <para>Implementation of an interface in the class
1879                   containing point. </para>
1880               </entry>
1881             </row>
1882             <row>
1883               <entry>
1884                 <para><ulink url="#DelegateWizard">Delegate
1885                     Wizard</ulink></para>
1886               </entry>
1887               <entry>
1888                 <para> Methods that delegate tasks to a specified
1889                   class. </para>
1890               </entry>
1891             </row>
1892             <row>
1893               <entry>
1894                 <para><ulink url="#AbstractClassWizard">Abstract Class
1895                     Wizard</ulink></para>
1896               </entry>
1897               <entry>
1898                 <para>Implementations of the abstract methods
1899                   inherited by the class containing point. </para>
1900               </entry>
1901             </row>
1902             <row>
1903               <entry>
1904                 <para><ulink url="#GetSetWizard">Get/Set
1905                     Wizard</ulink></para>
1906               </entry>
1907               <entry>
1908                 <para>Get and set methods for the private fields of
1909                   the class containing point. </para>
1910               </entry>
1911             </row>
1912           </tbody>
1913         </tgroup>
1914       </table>
1915
1916       <note>
1917         <para>
1918           Some of the wizards use the BeanShell to run Java code. A
1919           wizard starts the Beanshell interpreter if it is not already
1920           running. Thus, you may experience a slight delay when
1921           invoking a wizard for the first time in a session.
1922         </para>
1923       </note>
1924
1925
1926       <sect4>
1927
1928
1929         <title><anchor id="MethodOverrideWizard"/>Method Override
1930           Wizard</title>
1931
1932         <para>
1933           The method override wizard generates a skeleton method that
1934           overrides a similarly named method defined by a superclass.
1935         </para>
1936
1937         <para>To override a method of a superclass: </para>
1938
1939         <orderedlist>
1940
1941           <listitem>
1942             <para>
1943               Position the Emacs point at the location in the buffer
1944               where you want the generated method to appear.
1945             </para>
1946             <para>
1947               The point must be within the class that is overriding
1948               the   method.
1949             </para>
1950             <para>
1951                 <screenshot>
1952                 <mediaobject>
1953                   <imageobject>
1954                     <imagedata fileref="images/OverrideMeth1.gif" width="472" depth="328"/>
1955                   </imageobject>
1956                   <textobject>
1957                     <phrase>Screen capture showing point inside a
1958                       class.</phrase>
1959                   </textobject>
1960                 </mediaobject>
1961                 </screenshot>
1962             </para>
1963           </listitem>
1964
1965
1966           <listitem>
1967             <para>
1968               Select
1969               <menuchoice><guisubmenu>Wizards</guisubmenu><guimenuitem>Override
1970                   Method</guimenuitem>
1971               </menuchoice> from the
1972               <menuchoice><guimenu>JDE</guimenu>
1973               </menuchoice> menu or enter
1974               <keycombo><keycap>M</keycap><keycap>x</keycap>
1975                 </keycombo> <varname>jde-wiz-overrided-method</varname>.
1976             </para>
1977             <para>
1978                 <screenshot>
1979                 <mediaobject>
1980                   <imageobject>
1981                     <imagedata fileref="images/OverrideMeth2.gif"/>
1982                   </imageobject>
1983                   <textobject><phrase>Screen shot showing
1984                       <menuchoice><guimenu>Wizards</guimenu>
1985                       </menuchoice> menu.</phrase>
1986                   </textobject>
1987                 </mediaobject>
1988                 </screenshot>
1989             </para>
1990
1991             <para>
1992               The JDE prompts you to enter the name of the method to
1993               be overridden in the minibuffer.
1994             </para>
1995             <para>
1996                 <screenshot>
1997                 <mediaobject>
1998                   <imageobject>
1999                     <imagedata fileref="images/OverrideMeth3.gif"/>
2000                   </imageobject>
2001                   <textobject><phrase>Screen shot showing prompt for
2002                       method name. </phrase>
2003                   </textobject>
2004                 </mediaobject>
2005                 </screenshot>
2006             </para>
2007
2008             <para>
2009               The name must be the name of a method defined by an
2010               ancestor of the class in which the Emacs point is
2011               located. The compiled class of the ancestor must be on
2012               the classpath specified by
2013               <varname>jde-global-classpath</varname>.
2014             </para>
2015           </listitem>
2016
2017           <listitem>
2018             <para>
2019               Enter the name of the method to be overridden.
2020             </para>
2021             <para>
2022               If the  ancestors of the class in which you are
2023               overriding the method define more than one method of the
2024               same name, the wizard displays a dialog buffer that
2025               lists the methods. For example, Java's awt class
2026               hierarchy defines several variants of the method
2027               <varname>repaint</varname>. If you specify
2028               <varname>repaint</varname> as the method to override,
2029               the JDE displays the following dialog buffer:
2030             </para>
2031             <para>
2032                 <screenshot>
2033                 <mediaobject>
2034                   <imageobject>
2035                     <imagedata fileref="images/OverrideMeth4.gif"/>
2036                   </imageobject>
2037                   <textobject><phrase>Screen shot showing dialog
2038                       buffer for selecting method. </phrase>
2039                   </textobject>
2040                 </mediaobject>
2041                 </screenshot>
2042             </para>
2043
2044             <para>
2045               The dialog buffer lists the signature of each variant of
2046               the method you specified. Next to each signature is a
2047               radio button. The radio button of the currently selected
2048               signature contains an asterisk. To select another
2049               signature, right-click the radio button next to the
2050               variant. To confirm your selection and dismiss the
2051               dialog, right-click the <guibutton>[Ok]</guibutton>
2052               button.
2053             </para>
2054
2055           </listitem>
2056           <listitem>
2057             <para>
2058               Select the method variant you want to override and click
2059               the <guibutton>[Ok]</guibutton> button.
2060             </para>
2061             <para>The   wizard inserts a skeleton implementation of
2062               the selected method at the current point in the Java
2063               source buffer.</para>
2064
2065             <para>
2066                 <screenshot>
2067                 <mediaobject>
2068                   <imageobject>
2069                     <imagedata fileref="images/OverrideMeth5.gif"/>
2070                   </imageobject>
2071                   <textobject><phrase>Screen shot showing the inserted
2072                       method. </phrase>
2073                   </textobject>
2074                 </mediaobject>
2075                 </screenshot>
2076             </para>
2077
2078             <para>
2079               The wizard also inserts import statements for any
2080               classes referenced by the method that are not already
2081               imported by the containing class either explicitly or
2082               implicitly. The wizard inserts the import statements at
2083               the head of the source buffer after any existing import
2084               statements, or any package statement, or the first blank
2085               line in the buffer.
2086             </para>
2087             <note><para>
2088                 The method override wizard uses the BeanShell to
2089                 create the interface implementation. If the BeanShell
2090                 is not currently running, the wizard starts the
2091                 BeanShell. Thus, if the BeanShell is not already
2092                 running, you may experience a short pause the first
2093                 time you   override a method.
2094               </para>
2095             </note>
2096           </listitem>
2097         </orderedlist>
2098
2099       </sect4>
2100
2101       <sect4>
2102
2103
2104         <title><anchor id="InterfaceWizard"/>Interface Wizard</title>
2105
2106         <para>
2107           This wizard creates a skeleton implementation of any
2108           interface defined on the classpath specified by
2109           <varname>jde-global-classpath</varname>.
2110         </para>
2111
2112         <para>To create an implementation of an interface: </para>
2113
2114         <orderedlist>
2115           <listitem>
2116             <para>
2117               If the interface is to be implemented by a new class,
2118               create the class in a buffer.
2119             </para>
2120           </listitem>
2121           <listitem>
2122             <para>
2123               Position the Emacs point at the point in the class where
2124               you want the implementation of the interface's methods
2125               to appear.
2126             </para>
2127           </listitem>
2128           <listitem>
2129             <para>
2130               Select
2131               <menuchoice><guimenu>JDE</guimenu><guisubmenu>Wizards</guisubmenu>
2132                 <guimenuitem>Implement Interface</guimenuitem>
2133               </menuchoice> or enter
2134               <keycombo><keycap>M</keycap><keycap>x
2135                 </keycap></keycombo><varname>jde-wiz-implement-interface</varname>.
2136
2137
2138
2139
2140             </para>
2141             <para>
2142               The JDE prompts you   to enter the name of the interface
2143               to be implemented.
2144             </para>
2145           </listitem>
2146           <listitem>
2147             <para>Enter the fully qualified name of the interface, for
2148               example,
2149               <classname>java.awt.Event.MouseListener</classname>.</para>
2150             <para>
2151               The wizard inserts skeleton implementations of the
2152               methods declared by the interface at the current point
2153               in the current buffer. It inserts import statements for
2154               any classes required by the interface at the head of the
2155               current buffer (only if import statements do not already
2156               exist for the required classes). It also updates or
2157               creates an implements clause for the class.
2158             </para>
2159           </listitem>
2160         </orderedlist>
2161
2162         <note><para>
2163             The interface wizard uses the BeanShell to create the
2164             interface implementation. If the BeanShell is not
2165             currently running, it starts the BeanShell. Thus, if the
2166             BeanShell is not already running, you may experience a
2167             short pause the first time you use the wizard. </para>
2168         </note>
2169
2170         <note>
2171           <title>Thanks to ...</title>
2172           <para><ulink url="mailto:friedman@lmi.net">Eric
2173               Friedman</ulink> for creating the framework for the
2174             interface, method override, and abstract class wizards and
2175             for contributing the initial implementation of the
2176             interface wizard.</para>
2177         </note>
2178
2179       </sect4>
2180
2181       <sect4>
2182
2183
2184         <title><anchor id="DelegateWizard"/>Delegate Wizard</title>
2185
2186
2187         <para>
2188           This wizard generates methods that delegate calls to a class
2189           in the current buffer to an attribute of the class, i.e., to
2190           an object that is a field of the current class. For example,
2191           if the current buffer contains class
2192           <classname>A</classname> and  <classname>A</classname> has
2193           an   attribute, <varname>A.b</varname>, that is an instance
2194           of class <classname>B</classname>,  this wizard generates
2195           all the public methods of class <classname>B</classname> in
2196           <classname>A</classname> and delegates   handling of those
2197           methods to <varname>b</varname>.
2198         </para>
2199
2200         <note><title>Thanks to...</title>
2201           <para>
2202             <ulink url="mailto:cfhart@Z-TEL.com">Charles Hart</ulink>
2203             for contributing this wizard.
2204           </para>
2205         </note>
2206
2207       </sect4>
2208
2209       <sect4>
2210         <title><anchor id="GetSetWizard"/>Get/Set Wizard</title>
2211
2212         <para>
2213             This wizard generates get and set methods for the private
2214           fields of the class at point, but only if the fields do not
2215           already have get or set methods. To generate the methods,
2216           move point to the point in the class where you want the get
2217           and set methods to appear. Then select
2218           <menuchoice><guimenu>JDE</guimenu><guisubmenu>Code
2219               Generation</guisubmenu>
2220             <guisubmenu>Wizards</guisubmenu>
2221             <guimenuitem>Generate Get/Set Methods...</guimenuitem>
2222           </menuchoice> or enter
2223             <keycombo><keycap>M</keycap><keycap>x  </keycap></keycombo> &nbsp;
2224             <varname>jde-wiz-get-set-methods</varname>
2225         </para>
2226
2227         <note>
2228           <title>Thanks to...</title>
2229           <para>
2230             <ulink url="mailto:jslopez@forumsys.com">Javier
2231               Lopez</ulink> and <ulink
2232               url="mailto:sandip.chitale@brokat.com">Sandip
2233               Chitale</ulink> for contributing this wizard.
2234           </para>
2235         </note>
2236
2237
2238       </sect4>
2239
2240     </sect3>
2241
2242     <sect3>
2243
2244
2245         <title><anchor id="CodeTemplates"/>Code Templates</title>
2246
2247       <sect4>
2248
2249
2250             <title><anchor id="BufferTemplates"/>Buffer Templates</title>
2251
2252           <para>These commands create buffers containing a skeleton Java class.
2253             Each command prompts you to enter the path to a new Java source
2254             file. They then create a buffer for the new file and insert a
2255             template for a class of the same name as the newly created file.
2256             In particular, the command </para>
2257
2258           <itemizedlist>
2259             <listitem>
2260               <para>
2261                 <menuchoice><guimenu>Files</guimenu><guisubmenu>JDE New</guisubmenu><guimenuitem>Class</guimenuitem></menuchoice> creates a buffer containing a generic Java public class.
2262               </para>
2263             </listitem>
2264
2265             <listitem>
2266               <para>
2267                 <menuchoice><guimenu>Files</guimenu><guisubmenu>JDE New</guisubmenu><guimenuitem>Console</guimenuitem></menuchoice> creates a buffer containing the main class of a
2268                 Java console application.
2269               </para>
2270             </listitem>
2271
2272             <listitem>
2273               <para>
2274                 <menuchoice><guimenu>Files</guimenu><guisubmenu>JDE New</guisubmenu><guimenuitem>Other</guimenuitem></menuchoice> prompts you to create any of the above buffers or a
2275                 custom (user-defined) buffer.
2276               </para>
2277             </listitem>
2278
2279           </itemizedlist>
2280
2281           <para>
2282             You can create an empty Java class buffer by selecting
2283             <menuchoice><guimenu>Files</guimenu><guisubmenu>Open</guisubmenu></menuchoice>
2284             (<keycombo><keycap>C</keycap><keycap>x</keycap></keycombo>&nbsp;<keysym>f</keysym>) and
2285             entering the path for a new file whose root name is the same as
2286             the class you want to create and whose extension is <filename>.java.</filename>
2287           </para>
2288
2289         <sect5>
2290           <title>Specifying Boilerplate Text</title>
2291
2292           <para>
2293             You can specify boilerplate text (for example, a copyright
2294             notice) to be inserted at the head of class source files
2295             created by the JDE. The JDE provides two ways to specify
2296             the boilerplate text. The simplest way is to enter the
2297             lines of boilerplate text as the value of the
2298             customization variable
2299             <varname>jde-gen-buffer-boilerplate</varname>. Another way
2300             to specify the text is to set the value of the
2301             customization variable
2302             <varname>jde-gen-boilerplate-function</varname>to a
2303             function that generates the boilerplate text. (The default
2304             value of this variable is
2305             <varname>jde-gen-create-buffer-boilerplate</varname>,
2306             which returns the value of the boilerplate variable,
2307             <varname>jde-gen-buffer-boilerplate</varname>). The
2308             functional approach allows you to generate boilerplate
2309             text dynamically by evaluating the appropriate Lisp code.
2310             By saving the values of boilerplate variables in project
2311             files, you can specify different boilerplate text for each
2312             project.
2313           </para>
2314
2315         </sect5>
2316
2317         <sect5>
2318             <title>Customization Variables</title>
2319
2320             <para>The following JDE customization variables control creation of
2321               autocoded Java source buffers:
2322             </para>
2323
2324             <table>
2325               <title></title>
2326               <tgroup cols="3">
2327                 <colspec colnum="1"></colspec>
2328                 <colspec colnum="2"></colspec>
2329                 <colspec colnum="3"></colspec>
2330                 <thead>
2331                   <row>
2332                     <entry>Variable</entry>
2333                     <entry>Group</entry>
2334                     <entry>Usage</entry>
2335                   </row>
2336                     </thead>
2337                 <tbody>
2338                   <row>
2339                     <entry><varname>jde-gen-class-buffer-template</varname></entry>
2340                     <entry>Autocode</entry>
2341                     <entry>Template for a generic public class buffer.</entry>
2342                   </row>
2343                   <row>
2344                     <entry><varname>jde-gen-console-buffer-template</varname></entry>
2345                     <entry>Autocode</entry>
2346                     <entry>Template for a console application buffer.</entry>
2347                   </row>
2348                   <row>
2349                     <entry><varname>jde-gen-jfc-app-buffer-template</varname></entry>
2350                     <entry>Autocode</entry>
2351                     <entry>Template for a JFC (Swing) application.</entry>
2352                   </row>
2353                   <row>
2354                     <entry><varname>jde-gen-junit-test-class-buffer-template</varname></entry>
2355                     <entry>Autocode</entry>
2356                     <entry>Template for a JUnit test case class. This template requires
2357                     the <ulink url="http://www.junit.org">JUnit</ulink> test framework.</entry>
2358                   </row>
2359
2360                   <row>
2361                     <entry><varname>jde-gen-buffer-templates</varname></entry>
2362                     <entry>Autocode</entry>
2363                     <entry>Specifies templates available to create
2364                       Java buffers.</entry>
2365                   </row>
2366                   <row>
2367                     <entry><varname>jde-gen-buffer-boilerplate</varname></entry>
2368                     <entry>Autocode</entry>
2369                     <entry>Specifies lines of text to be inserted
2370                       at the head of class files.</entry>
2371                   </row>
2372                   <row>
2373                     <entry><varname>jde-gen-boilerplate-function</varname></entry>
2374                     <entry>Autocode</entry>
2375                     <entry>Specifies a function that returns a string
2376                       of boilerplate text. The default value is
2377                       <varname>jde-gen-create-buffer-boilerplate</varname>, which returns
2378                       the value of <varname>jde-gen-buffer-boilerplate</varname>.</entry>
2379                   </row>
2380                 </tbody>
2381               </tgroup>
2382             </table>
2383
2384             <para>
2385               See <ulink url="#CustomizingTemplates">Customizing
2386                 Templates</ulink> for information on how to customize
2387               the class creation templates. </para>
2388
2389         </sect5>
2390
2391       </sect4>
2392
2393       <sect4>
2394
2395
2396         <title><anchor id="PointTemplates"/>Point Templates</title>
2397
2398
2399         <para>The following commands insert templates at the current
2400           point in the buffer: </para>
2401
2402         <itemizedlist>
2403           <listitem>
2404             <para>
2405               <menuchoice><guimenu>JDE</guimenu><guisubmenu>Generate</guisubmenu>
2406                 <guimenuitem>Get/Set Pair </guimenuitem></menuchoice>
2407                 generates an instance variable and a get and set method  .
2408                 for that variable
2409             </para>
2410           </listitem>
2411           <listitem>
2412             <para>
2413               <menuchoice><guimenu>JDE</guimenu><guisubmenu>Generate</guisubmenu>
2414                 <guimenuitem>Println </guimenuitem></menuchoice>
2415               generates a
2416               <programlisting>System.out.println(...);</programlisting>
2417               statement.
2418             </para>
2419           </listitem>
2420           <listitem>
2421             <para>
2422               <menuchoice><guimenu>JDE</guimenu><guisubmenu>Generate</guisubmenu>
2423                 <guimenuitem>Action </guimenuitem></menuchoice>
2424                 generates and registers an action listener for a
2425                 specified component.
2426             </para>
2427           </listitem>
2428           <listitem>
2429             <para>
2430               <menuchoice><guimenu>JDE</guimenu><guisubmenu>Generate</guisubmenu>
2431                 <guisubmenu>Listener</guisubmenu><guimenuitem>Window
2432                 </guimenuitem></menuchoice>
2433                 generates and registers a window listener for a specified
2434                 window.
2435             </para>
2436           </listitem>
2437           <listitem>
2438             <para>
2439               <menuchoice><guimenu>JDE</guimenu><guisubmenu>Generate</guisubmenu>
2440                 <guisubmenu>Listener</guisubmenu><guimenuitem>Mouse
2441                 </guimenuitem></menuchoice>
2442                 generates and registers a mouse listener for a specified
2443                 component.
2444             </para>
2445           </listitem>
2446           <listitem>
2447             <para>
2448               <menuchoice><guimenu>JDE</guimenu><guisubmenu>Generate</guisubmenu>
2449                 <guimenuitem>Other </guimenuitem></menuchoice>
2450                 allows you to select any of the above templates or a
2451                 custom (user-defined) template.
2452             </para>
2453           </listitem>
2454         </itemizedlist>
2455
2456         <para>The following variables control generation of code at
2457           point:
2458         </para>
2459
2460         <table>
2461           <title></title>
2462           <tgroup cols="3">
2463             <colspec colnum="1"></colspec>
2464             <colspec colnum="2"></colspec>
2465             <colspec colnum="3"></colspec>
2466             <thead>
2467               <row>
2468                 <entry>Variable</entry>
2469                 <entry>Group</entry>
2470                 <entry>Usage</entry>
2471               </row>
2472             </thead>
2473             <tbody>
2474               <row>
2475                 <entry><varname>jde-gen-get-set-var-template</varname></entry>
2476                 <entry>Autocode</entry>
2477                 <entry>Defines a get/set method pair template.</entry>
2478               </row>
2479               <row>
2480                 <entry><varname>jde-gen-listener-action-template</varname></entry>
2481                 <entry>Autocode</entry>
2482                 <entry>Defines an action listener template.</entry>
2483               </row>
2484               <row>
2485                 <entry><varname>jde-gen-listener-window-template</varname></entry>
2486                 <entry>Autocode</entry>
2487                 <entry>Defines a window listener template.</entry>
2488               </row>
2489               <row>
2490                 <entry><varname>jde-gen-listener-mouse-template</varname></entry>
2491                 <entry>Autocode</entry>
2492                 <entry>Defines a mouse listener template.</entry>
2493               </row>
2494               <row>
2495                 <entry><varname>jde-gen-inner-class-template</varname></entry>
2496                 <entry>Autocode</entry>
2497                 <entry>Defines a template for creating a class inside
2498                   another class or inside an existing source
2499                   buffer.</entry>
2500               </row>
2501               <row>
2502                 <entry><varname>jde-gen-code-templates</varname></entry>
2503                 <entry>Autocode</entry>
2504                 <entry>Specifies available code templates.</entry>
2505               </row>
2506             </tbody>
2507           </tgroup>
2508         </table>
2509
2510         <para>See</para>
2511
2512         <itemizedlist>
2513           <listitem>
2514             <para>
2515               <ulink url="#CustomizingTemplates">Customizing
2516                 Templates</ulink> for information on how to customize
2517               templates provided by the JDE.
2518             </para>
2519           </listitem>
2520           <listitem>
2521             <para>
2522               <ulink url="#CreatingTemplates">Creating
2523                 Templates</ulink> for information on how to create
2524               templates from scratch.
2525             </para>
2526           </listitem>
2527         </itemizedlist>
2528
2529       </sect4>
2530
2531       <sect4>
2532
2533
2534         <title><anchor id="CustomizingTemplates"/>Customizing
2535           Templates</title>
2536
2537         <para>You can customize the JDE's standard code templates,
2538           using the Emacs customization feature. </para>
2539
2540         <para>To customize an autocode template: </para>
2541
2542         <orderedlist>
2543           <listitem>
2544             <para>Select <menuchoice>
2545                 <guimenu>JDE</guimenu>
2546                 <guisubmenu>Options</guisubmenu>
2547                 <guimenuitem>Autocode</guimenuitem></menuchoice></para>
2548             <para>The JDE displays a customization buffer containing
2549               the autocode templates. </para>
2550           </listitem>
2551           <listitem>
2552             <para>Edit the template to suit your needs.</para>
2553             <para>The JDE uses the template format defined by
2554               <filename>tempo.el</filename> to represent class
2555               templates. Each template consists of a list of strings,
2556               symbols, and functions, each of which represents content
2557               to be inserted successively into the buffer at the
2558               current point. The strings represent fixed content. The
2559               symbols and functions represent variable content. See
2560               the docstring for the function
2561               <varname>tempo-define-template</varname> for more
2562               information, including the meaning of special symbols
2563               such as <varname>'n</varname>. </para>
2564           </listitem>
2565           <listitem>
2566             <para>Select the state button associated with the
2567               template.</para>
2568             <para>A menu pops up with a list of options for saving
2569               your changes. </para>
2570           </listitem>
2571           <listitem>
2572             <para>Save your changes.</para>
2573             <para>Select
2574               <menuchoice><guimenuitem>Save for Future
2575                   Sessions</guimenuitem></menuchoice> if you want
2576                 your changes to apply to all projects. If you want your changes to apply
2577               only to the current projects, select <menuchoice>
2578                 <guimenuitem>Set for Current
2579                   Session</guimenuitem></menuchoice>. Then select
2580               <menuchoice>
2581                 <guimenu>JDE</guimenu>
2582                 <guisubmenu>Options</guisubmenu>
2583                 <guimenuitem>Save Project</guimenuitem></menuchoice>
2584               to save your changes in the current project's project
2585               file.</para>
2586           </listitem>
2587         </orderedlist>
2588
2589       </sect4>
2590
2591       <sect4>
2592
2593
2594             <title><anchor id="CreatingTemplates"/>Creating Templates</title>
2595
2596           <para>The JDE considers any command (interactive function) that
2597             inserts code into a buffer at point to be a template. The JDE
2598             uses the Emacs tempo library to create built-in templates.
2599             You can use tempo to create your own, add-on templates (see below
2600             and the doc for the <varname>tempo-define-template </varname>for
2601             more information) or create templates from scratch.
2602             In either case, once you have created a template, you can add it
2603             to the JDE's lists of available code and/or buffer templates,
2604             using the JDE's <varname>jde-gen-code-templates</varname> and/or
2605             <varname>jde-gen-buffer-templates</varname>
2606             variables, respectively. Adding a template to these lists enables
2607             you to invoke the templates from the JDE menus. When adding a
2608             template, you need to specify a unique title for the template.
2609             These titles enable you to specify the templates when invoking
2610             them, using the JDE's custom code template commands
2611             (<menuchoice><guimenu>Files</guimenu>
2612               <guisubmenu>JDE New</guisubmenu>
2613               <guimenuitem>Custom</guimenuitem></menuchoice>  and
2614             <menuchoice><guimenuitem>JDE</guimenuitem>
2615               <guisubmenu>Generate</guisubmenu>
2616               <guimenuitem>Custom</guimenuitem></menuchoice>). You can use
2617             auto completion to enter a template title when invoking a custom
2618             code generation command. Note that you can specify different sets
2619             of templates for different projects, by setting and saving the
2620             template list variables in project files. See the following
2621             sections for more information: </para>
2622
2623           <itemizedlist>
2624             <listitem>
2625               <para><ulink url="#DefiningTemplate">Defining a Template and
2626                   Template Insertion Function</ulink></para>
2627             </listitem>
2628             <listitem>
2629               <para><ulink url="#RegisterTemplate">Registering Custom
2630                   Templates</ulink></para>
2631             </listitem>
2632             <listitem>
2633               <para><ulink url="#AssignKeyToTemplate">Assigning Keys To
2634                   emplates</ulink></para>
2635             </listitem>
2636           </itemizedlist>
2637
2638           <sect5>
2639
2640
2641           <title><anchor id="DefiningTemplate"/>Defining a Template
2642             and Template Insertion Function</title>
2643
2644
2645           <para>The <varname>tempo-define-template</varname> macro
2646             enables you to define a template and a function that
2647             inserts that template at the current point in the current
2648             buffer. You specify the template as a list oftemplate
2649             elements where each element is text, a special symbol, or
2650             a Lisp expression. The function inserts each text element
2651             exactly as specified in the buffer; it replaces special
2652             symbols with some text (e.g., user input), and it replaces
2653             Lisp expressions with the text that results from
2654             evaluating them. </para>
2655
2656           <para>For example, the following Lisp code </para>
2657
2658           <programlisting>
2659             (tempo-define-template &quot;foo&quot;
2660             ;; template name
2661             '(&quot;System.out.println(\&quot;foo\&quot;);&quot;)
2662             ;;template definition &quot;f&quot;
2663             ;; abbreviation &quot;Inserts a print foo message&quot;)
2664             ;; template documentation
2665           </programlisting>
2666
2667           <para>defines a template for Java code that always prints
2668             &quot;foo&quot; to standard out: </para>
2669
2670           <programlisting>
2671             System.out.println(&quot;foo&quot;);
2672           </programlisting>
2673
2674           <para>Notice that the template definition uses the Lisp
2675             string escape character to specify the string
2676             &quot;foo&quot;.  This is necessary when you want to
2677             include quoted strings in a template definition.)
2678           </para>
2679
2680           <para>The sample Lisp form also defines an interactive
2681             template function <varname>tempo-template-foo</varname>.
2682             Now suppose you insert the sample code in your
2683             <filename>.emacs</filename> file. After Emacs starts up,
2684             whenever you enter the command <keycombo>
2685               <keycap>M</keycap><keycap>x</keycap></keycombo>
2686             <varname>tempo-template-foo,</varname> Emacs inserts
2687           </para>
2688
2689           <programlisting>
2690             System.out.println(&quot;foo&quot;);
2691           </programlisting>
2692
2693           <para>at the current point in your Java source buffer (or
2694             any buffer, tempo doesn't care). </para>
2695
2696           <para>The preceding example is admittedly not vary useful
2697             because it always prints the same text. You can create
2698             more useful templates, using special tempo template
2699             symbols and lisp forms. This approach, for example, allows
2700             you to create a template that can print any user-defined
2701             text to standard out: </para>
2702
2703           <programlisting>
2704             (tempo-define-template &quot;debug&quot;
2705             ;; template name '(&quot;if (debug)&quot; n&gt;
2706             ;; insert new line plus indent
2707             &quot;System.out.println(&quot; (p &quot;Enter debug
2708             message:&quot;)       ;; Prompts for debug message
2709             &quot;);&quot;) &quot;d&quot;
2710             ;; abbreviation &quot;Inserts a print debug message&quot;)
2711             ;; template documentation
2712           </programlisting>
2713
2714           <para>The template function produced by this example prompts
2715             you to enter the text to be printed when inserting the
2716             function into a buffer. In particular, it inserts </para>
2717
2718           <programlisting>
2719             if (debug) System.out.println(DEBUG-MESSAGE);
2720           </programlisting>
2721
2722           <para>where <varname>DEBUG-MESSAGE</varname> is any text
2723             that you enter. For example, suppose you enter </para>
2724
2725           <programlisting>
2726             &quot;Selected color = &quot; + color
2727           </programlisting>
2728
2729           <para>at the prompt. The template function inserts </para>
2730
2731           <programlisting>
2732             if (debug) System.out.println(&quot;Selected color =
2733             &quot; + color);
2734           </programlisting>
2735
2736           <para>at the current point in the buffer. </para>
2737
2738           <para>See the documentation for
2739             <varname>tempo-define-template</varname> (type
2740             <keycombo><keycap>c</keycap><keycap>h</keycap></keycombo>&nbsp;<keysym>f</keysym>&nbsp;
2741               <varname>tempo-define-template</varname>) for more
2742             information on creating templates. </para>
2743
2744         </sect5>
2745
2746         <sect5>
2747
2748
2749           <title><anchor id="RegisterTemplate"/>Registering Custom
2750             Templates</title>
2751
2752
2753           <para>You can register templates that you create with the
2754             JDE. When you register a template with the JDE, it appears
2755             among the list of templates that you can select when you
2756             select <menuchoice>
2757               <guimenu>JDE</guimenu><guisubmenu>Generate</guisubmenu>
2758               <guimenuitem>Other....</guimenuitem></menuchoice>. You
2759             register a template by customizing the JDE variable
2760             <varname>jde-gen-code-templates</varname>. The value of
2761             this variable is a list of the template functions that the
2762             JDE command  <menuchoice>
2763               <guimenu>JDE</guimenu><guisubmenu>Generate</guisubmenu>
2764               <guimenuitem>Other....</guimenuitem></menuchoice> can
2765             invoke. To register a custom template, add its name to the
2766             list. For example, the following screen shows the
2767             customization buffer for
2768             <varname>jde-gen-code-templates</varname> after it has
2769             been customized to include the template defined in the
2770             previous example. </para>
2771
2772           <para>
2773               <screenshot>
2774               <mediaobject>
2775                 <imageobject>
2776                   <imagedata fileref="images/RegisterTemplate.gif"/>
2777                 </imageobject>
2778                 <textobject>
2779                   <phrase>Screenshot showing customization buffer for
2780                     registering templates.</phrase>
2781                 </textobject>
2782               </mediaobject>
2783               </screenshot>
2784           </para>
2785
2786           <para>To insert a template that you have registered </para>
2787
2788           <procedure>
2789             <step performance="required">
2790               <para>Select <menuchoice>
2791                   <guimenu>JDE</guimenu><guisubmenu>Generate</guisubmenu>
2792                   <guimenuitem>Other....</guimenuitem></menuchoice></para>
2793               <para>The JDE displays the prompt</para>
2794               <programlisting>
2795                 Enter template:
2796               </programlisting>
2797               <para>in the minibuffer. </para>
2798             </step>
2799             <step>
2800               <para>Enter the template's name and press
2801                 <keycap>Enter</keycap></para>
2802               <para>or,</para>
2803               <para>press the <keycap>Tab</keycap> key to display a
2804                 list of templates in a completion buffer: </para>
2805               <para>
2806                   <screenshot>
2807                   <mediaobject>
2808                     <imageobject>
2809                       <imagedata fileref="images/TemplateList.gif"/>
2810                     </imageobject>
2811                     <textobject>
2812                       <phrase>Screenshot showing template completion
2813                         buffer.</phrase>
2814                     </textobject>
2815                   </mediaobject>
2816                   </screenshot>
2817               </para>
2818               <para>Select the template you want by double-clicking
2819                 its name.</para>
2820
2821             </step>
2822           </procedure>
2823
2824         </sect5>
2825
2826         <sect5>
2827
2828
2829           <title><anchor id="AssignKeyToTemplate"/>Assigning Keys to
2830             Templates</title>
2831
2832           <para>You can assign templates to keyboard keys to speed use
2833             of frequently used templates. For example, insert this
2834             form </para>
2835
2836           <programlisting>
2837             (global-set-key [f9] 'jde-gen-to-string-method)
2838           </programlisting>
2839
2840           <para>in your <filename>.emacs</filename> file to assign the
2841             <keycap>F9</keycap> function key to the JDE template that
2842             generates a skeleton <varname>toString</varname> method.
2843           </para>
2844
2845         </sect5>
2846       </sect4>
2847     </sect3>
2848
2849   </chapter>
2850
2851   <chapter>
2852     <title><anchor id="CheckStyle"/>Checking Coding Style</title>
2853     <para>The <menuchoice>
2854         <guimenu>JDE</guimenu>
2855         <guimenuitem>Check Style</guimenuitem>
2856       </menuchoice> command (<keycombo>
2857         <keysym>M</keysym>
2858         <keysym>x</keysym>
2859       </keycombo> <command>jde-checkstyle</command>) command checks
2860       the current buffer for conformity to a Java coding standard. The
2861       default standard is that specified by Sun Microsystems. Execute
2862       <command>jde-checkstyle-customize</command> to customize the
2863       command to support your own coding standard.
2864     </para>
2865     <para>The command displays a list of stylistic faults in a popup
2866     buffer. Click the error message to display the line that violates
2867     the standard.</para>
2868   </chapter>
2869
2870   <chapter>
2871     <title><anchor id="CompilingJavaPrograms"/>Compiling Java Programs</title>
2872
2873     <para>To compile the source file in the current buffer, select
2874       <menuchoice>
2875         <guimenuitem>JDE</guimenuitem>
2876         <guimenuitem>Compile</guimenuitem></menuchoice>, type
2877       <keycombo>
2878         <keycombo>
2879           <keycap>C</keycap>
2880           <keycap>c</keycap></keycombo><keycombo>
2881           <keycap>C</keycap><keycap>v</keycap></keycombo>
2882         <keycombo>
2883           <keycap>C</keycap><keycap>c</keycap></keycombo></keycombo>,
2884       or execute <command>M-x jde-compile</command>. The compiler uses
2885       the version of <filename>javac</filename> included in the
2886       currently selected JDK or on your system command path by
2887       default. However, you can configure the JDEE to use another
2888       compiler for the current project or all projects (see <ulink
2889         url="#SpecifyingCompiler">Specifying a Compiler</ulink>). The
2890       JDEE also allows you to configure the JDEE to invoke the
2891       compiler with various <ulink
2892         url="#CompilationOptions">compilation options</ulink>.
2893     </para>
2894
2895     <sect3>
2896
2897       <title><anchor id="CompileBuffer"/>Compilation Buffer</title>
2898
2899       <para>
2900         The compile command displays the output of the compiler in a
2901         separate compilation buffer.
2902       </para>
2903
2904       <screenshot>
2905         <mediaobject>
2906           <imageobject>
2907             <imagedata fileref="images/compile_buffer.gif"/>
2908           </imageobject>
2909           <textobject>
2910             <phrase>Image showing compilation buffer with
2911               errors.</phrase>
2912           </textobject>
2913         </mediaobject>
2914       </screenshot>
2915
2916       <para>
2917         If a compilation buffer exists from a previous compilation, the compile command
2918         reuses the existing buffer; otherwise, it creates a compilation buffer. By default,
2919         if no errors occur in the compilation, the JDEE deletes the compilation buffer
2920         two seconds after the compilation finishes. You can disable this feature by
2921         setting the variable <varname>jde-compile-enable-kill-buffer</varname> off (i.e., to
2922         <code>nil</code>).
2923       </para>
2924
2925       <sect4>
2926         <title>Compilation Mode</title>
2927         <para>The compilation buffer operates in
2928         <varname>compilation-mode</varname>, a standard Emacs buffer
2929         mode. This mode greatly simplify locating compilation errors
2930         in the Java source code. For example, to find the line that
2931         cause a compilation error, simply click the error message in
2932         the compilation buffer.</para>
2933       </sect4>
2934
2935     </sect3>
2936
2937     <sect3>
2938       <title><anchor id="SpecifyingCompiler"/>Specifying a Compiler</title>
2939
2940       <para>The JDEE supports the following Java compilers.</para>
2941
2942       <itemizedlist>
2943         <listitem>
2944           <para><filename>javac</filename></para>
2945           <para>
2946             This is the compiler that comes with Sun's JDK and the
2947             JDK's clones. Note that <filename>javac</filename>
2948             compiler is itself implemented in Java. The
2949             <filename>javac</filename> executable that comes with the
2950             JDK simply starts a vm to run <filename>javac</filename>.
2951             The executable passes its command-line arguments to
2952             <filename>javac</filename>'s main method.
2953           </para>
2954         </listitem>
2955         <listitem>
2956           <para>javac compile server</para>
2957           <para>This is a JDEE feature that uses the BeanShell to
2958           invoke the javac compiler on a source file, thus avoiding
2959           the need to start a vm everytime you want to compile
2960           a file. This option greatly reduces the time required
2961           to compile individual files by eliminating the vm startup
2962           time, which is usually much longer than the time required
2963           to compile a file.</para>
2964         </listitem>
2965         <listitem>
2966           <para><filename>jikes</filename></para>
2967           <para>
2968             Developed by IBM, this compiler is implemented in
2969           C++ and hence avoids the vm startup time that slows
2970           down javac.
2971           </para>
2972         </listitem>
2973       </itemizedlist>
2974
2975
2976
2977       <para>
2978         To specify one of these compilers for the current project or
2979         all projects:
2980 </para>
2981
2982       <orderedlist>
2983         <listitem>
2984           <para>Type <command>M-x customize-variable</command> and
2985             press <command>Enter</command></para>
2986           <para>Emacs prompts you to enter the name of a variable
2987           to customize.</para>
2988         </listitem>
2989         <listitem>
2990           <para>Enter <varname>jde-compiler</varname> and
2991           press <command>Enter</command>.</para>
2992           <para>The <varname>jde-compiler</varname> customization
2993           buffer appears.</para>
2994           <screenshot>
2995             <mediaobject>
2996               <imageobject>
2997                 <imagedata fileref="images/spec_compiler.gif"/>
2998               </imageobject>
2999             </mediaobject>
3000           </screenshot>
3001         </listitem>
3002         <listitem>
3003           <para>Select the compiler that you want to use for the
3004           current project or all projects.</para>
3005           <para>
3006             You can skip the next step if you selected the compile server
3007             or if you selected javac and you want to use the version of
3008             javac that comes with the currently selected JDK, or you have
3009             selected the javac executable or jikes and the executable for
3010             the selected compiler is in your system's command path.
3011           </para>
3012         </listitem>
3013         <listitem>
3014           <para>Enter the path to the executable for the selected
3015             compiler.
3016           </para>
3017         </listitem>
3018         <listitem>
3019           <para>If you want your selection to apply only to the current
3020             project, select <command>Save for Current Session</command>
3021             from the <command>State</command> menu. Otherwise select
3022             <command>Save for Future Sessions</command>.</para>
3023         </listitem>
3024         <listitem>
3025           <para>Select <command>Finish</command> to dismiss the
3026           customization buffer.</para>
3027         </listitem>
3028         <listitem>
3029           <para>If you want the selection to apply to the current
3030             project, select <command>Project-&gt;Project
3031               File-&gt;Save</command> from the <command>JDE</command>
3032             menu.</para>
3033         </listitem>
3034       </orderedlist>
3035     </sect3>
3036
3037     <sect3>
3038
3039       <title><anchor id="CompilationOptions"/>Compilation Options</title>
3040
3041       <para>The JDEE allows you to specify compilation options by
3042         setting  compilation variables. You must use the Emacs
3043         customization feature. To use the customization feature,
3044         select <menuchoice>
3045           <guimenu>JDE</guimenu>
3046           <guisubmenu>Options</guisubmenu>
3047           <guimenuitem>Compile</guimenuitem></menuchoice>.  (See
3048         <ulink url="#ConfiguringJDE">Configuring  the JDEE</ulink> for
3049         more information on using the customization  feature). To save
3050         the compilation settings in the project  file
3051         (see <ulink
3052           url="#UsingProjectFiles">Using Project Files</ulink>)
3053         for the current source buffer, select <menuchoice>
3054           <guimenuitem>JDE</guimenuitem>
3055           <guisubmenu>Options</guisubmenu>
3056           <guimenuitem>Update  Project</guimenuitem></menuchoice>.
3057       </para>
3058
3059       <sect4>
3060
3061
3062         <title><anchor id="SetCompileOptionsInteractively"/> Setting
3063           Compile Options Interactively</title>
3064
3065         <para>If you set the customization variable
3066           <varname>jde-read-compile-args</varname>  to a
3067           non-<varname>nil</varname> value, the JDEE compile command
3068           prompts you to enter compilation options in the minibuffer.
3069           It appends the  options that you enter to the options
3070           specified via customization  variables. The JDEE saves the
3071           arguments that you enter in a  minibuffer history list. You
3072           can recall previously entered  options by pressing the up or
3073           down arrows on your keyboard. </para>
3074
3075         <note>
3076           <para>The JDEE uses the values of the JDEE customization
3077             variables to set the compiler's command-line option
3078             switches. The JDEE assumes that the compiler you are using
3079             (specified by the  customization variable
3080             <varname>jde-compiler</varname>) has the same set of
3081             command-line switches as the version of
3082             <varname>javac</varname> or jikes that you have selected.
3083             If the command-line  switch for a particular option
3084             supported by the compiler  your are using is not the same
3085             as that specified by <varname>javac</varname> or jikes,
3086             you must use the variable
3087             <varname>jde-compile-option-command-line-args</varname> to
3088             select the option.</para>
3089         </note>
3090       </sect4>
3091
3092       <sect4>
3093
3094
3095         <title><anchor id="CompilerCustomizationVariables"/>
3096           Compiler Customization Variables</title>
3097
3098         <para>The following table lists the JDEE compilation variables and
3099           the functions used to set them.</para>
3100
3101         <table>
3102           <title></title>
3103           <tgroup cols="3">
3104             <colspec colnum="1" align="left"/>
3105             <colspec colnum="2" align="left"/>
3106             <colspec colnum="3" align="left"/>
3107             <thead>
3108               <row>
3109                 <entry><para>Name</para></entry>
3110                 <entry><para>Group</para></entry>
3111                 <entry><para>Usage</para></entry>
3112               </row>
3113             </thead>
3114             <tbody valign="top">
3115               <row>
3116                 <entry><para><varname>jde-compiler</varname></para></entry>
3117                 <entry>Project</entry>
3118                 <entry>
3119                   <para>Specifies the compiler (javac server, by default)
3120                     to use to compile the code in  the current source buffer.
3121                   </para>
3122                 </entry>
3123               </row>
3124               <row>
3125                 <entry>
3126                   <para>
3127                     <varname>jde-compile-option-command-line-args</varname>
3128                   </para>
3129                 </entry>
3130                 <entry >Compile</entry>
3131                 <entry >Specifies a string of
3132                   command-line arguments to be passed to the compiler.</entry>
3133               </row>
3134               <row>
3135                 <entry ><varname>jde-global-classpath</varname></entry>
3136                 <entry >Project</entry>
3137                 <entry >Specify class paths
3138                   for compile, run, and debug commands.</entry>
3139               </row>
3140               <row>
3141                 <entry ><varname>jde-read-compile-args</varname></entry>
3142                 <entry >Project</entry>
3143                 <entry >Specify whether to read compile
3144                   options from the minibuffer.</entry>
3145               </row>
3146               <row>
3147                 <entry ><varname>jde-compile-option-classpath</varname></entry>
3148                 <entry >Compile&nbsp;</entry>
3149                 <entry >Specifies the
3150                   classpath for compile command. If set, this variable
3151                   overrides <varname>jde-global-classpath</varname>.&nbsp;</entry>
3152               </row>
3153               <row>
3154                 <entry ><varname>jde-compile-option-sourcepath</varname></entry>
3155                 <entry  >Compile</entry>
3156                 <entry >Specifies the path of source files
3157                   for classes required to compile the current class.</entry>
3158               </row>
3159               <row>
3160                 <entry ><varname>jde-quote-classpath</varname></entry>
3161                 <entry >Project&nbsp;</entry>
3162                 <entry >Quote the classpath
3163                   argument.</entry>
3164               </row>
3165               <row>
3166                 <entry ><varname>jde-compile-option-directory</varname></entry>
3167                 <entry >Compile&nbsp;</entry>
3168                 <entry >Specifies the
3169                   directory into which to place the compiled class.&nbsp;</entry>
3170               </row>
3171               <row>
3172                 <entry ><varname>jde-compile-option-deprecation</varname></entry>
3173                 <entry >Compile&nbsp;</entry>
3174                 <entry >Warn of use or
3175                   override of a deprecated member or class&nbsp;</entry>
3176               </row>
3177               <row>
3178                 <entry ><varname>jde-compile-option-debug</varname></entry>
3179                 <entry >Compile&nbsp;</entry>
3180                 <entry >Generate information
3181                   about local variables for debug tools.&nbsp;</entry>
3182               </row>
3183               <row>
3184                 <entry ><varname>jde-compile-option-optimize</varname></entry>
3185                 <entry >Compile&nbsp;</entry>
3186                 <entry >Directs the compiler
3187                   to try to generate faster varname.&nbsp;</entry>
3188               </row>
3189               <row>
3190                 <entry ><varname>jde-compile-option-depend</varname></entry>
3191                 <entry >Compile</entry>
3192                 <entry >Analyze dependencies.</entry>
3193               </row>
3194               <row>
3195                 <entry ><varname>jde-compile-option-depend-switch</varname></entry>
3196                 <entry >Compile</entry>
3197                 <entry >Command line switch that causes the
3198                   compiler to analyze dependencies.</entry>
3199               </row>
3200               <row>
3201                 <entry ><varname>jde-compile-option-vm-args</varname></entry>
3202                 <entry >Compile&nbsp;</entry>
3203                 <entry >Specify command-line
3204                   arguments for Java interpreter used to run the compiler.&nbsp;</entry>
3205               </row>
3206               <row>
3207                 <entry ><varname>jde-compile-option-verbose-path</varname></entry>
3208                 <entry >Compile&nbsp;</entry>
3209                 <entry >Print verbose messages.</entry>
3210               </row>
3211               <row>
3212                 <entry ><varname>jde-compile-option-verbose</varname></entry>
3213                 <entry >Compile</entry>
3214                 <entry >List directories searched to
3215                   compile current class.</entry>
3216               </row>
3217               <row>
3218                 <entry ><varname>jde-compile-option-nowarn</varname></entry>
3219                 <entry >Compile&nbsp;</entry>
3220                 <entry >Turn off warnings.</entry>
3221               </row>
3222               <row>
3223                 <entry ><varname>jde-compile-option-encoding</varname></entry>
3224                 <entry >Compile&nbsp;</entry>
3225                 <entry >Specify the source
3226                   file encoding name, such as EUCJIS\SJIS.&nbsp;</entry>
3227               </row>
3228               <row>
3229                 <entry ><varname>jde-compile-option-target</varname></entry>
3230                 <entry >Compile</entry>
3231                 <entry >Generate code compatible with a
3232                   specified vm version.</entry>
3233               </row>
3234               <row>
3235                 <entry ><varname>jde-compile-option-bootclasspath</varname></entry>
3236                 <entry >Compile</entry>
3237                 <entry>Specify classpath of standard
3238                   libraries for target vm.</entry>
3239               </row>
3240               <row>
3241                 <entry><varname>jde-compile-option-bootclasspath</varname></entry>
3242                 <entry>Compile</entry>
3243                 <entry>Specify path of directories
3244                   containing extensions for target vm.</entry>
3245               </row>
3246             </tbody>
3247           </tgroup>
3248         </table>
3249       </sect4>
3250     </sect3>
3251   </chapter>
3252
3253   <chapter>
3254
3255     <title><anchor id="BuildingJavaApplications"/>Building Java Applications</title>
3256
3257     <para>The <menuchoice>
3258         <guimenu>JDE</guimenu><guimenuitem>Build</guimenuitem></menuchoice>
3259       command builds an application. By default this command invokes the
3260       Unix-style make utility to build the application. You can configure
3261       the build command to invoke the Ant build system or a custom build
3262       function.
3263     </para>
3264
3265     <sect3>
3266       <title><anchor id="SelectBuildMethod"/>Selecting a Build Method</title>
3267
3268       <para>To select a build method:</para>
3269
3270       <orderedlist>
3271         <listitem>
3272           <para>Type <command>M-x customize-variable</command> and
3273             press <command>Enter</command></para>
3274           <para>Emacs prompts you to enter the name of a variable
3275           to customize.</para>
3276         </listitem>
3277         <listitem>
3278           <para>Enter <varname>jde-build-function</varname> and
3279           press <command>Enter</command>.</para>
3280           <para>The <varname>jde-build-function</varname> customization
3281           buffer appears.</para>
3282           <screenshot>
3283             <mediaobject>
3284               <imageobject>
3285                 <imagedata fileref="images/build_fcn_cust_buff.gif"/>
3286               </imageobject>
3287             </mediaobject>
3288           </screenshot>
3289         </listitem>
3290         <listitem>
3291           <para>Select the build function that you want to use.</para>
3292         </listitem>
3293         <listitem>
3294           <para>If you want your selection to apply only to the current
3295             project, select <command>Save for Current Session</command>
3296             from the <command>State</command> menu. Otherwise select
3297             <command>Save for Future Sessions</command>.</para>
3298         </listitem>
3299         <listitem>
3300           <para>Select <command>Finish</command> to dismiss the
3301           customization buffer.</para>
3302         </listitem>
3303         <listitem>
3304           <para>If you want the selection to apply to the current
3305             project, select <command>Project-&gt;Project
3306               File-&gt;Save</command> from the <command>JDE</command>
3307             menu.</para>
3308         </listitem>
3309       </orderedlist>
3310      </sect3>
3311
3312     <sect3>
3313
3314       <title><anchor id="BuildWithMake"/>Building with Make</title>
3315
3316       <para>
3317         The <command>jde-make</command> command uses a make utility,
3318         such as  GNU make, to rebuild a project. You must supply the
3319         makefiles used to build your projects. See <ulink
3320           url="#SampleMakefile">Sample Makefile</ulink> for an example
3321         of a makefile for building a Java project. David Ponce's
3322         <ulink
3323           url="http://perso.wanadoo.fr/david.ponce/">JMaker</ulink>
3324         package generates makefiles automatically for JDEE projects.
3325         It uses JDEE variables to determine classpaths, compiler
3326         options, and other information needed to create projects.
3327         JMaker recursively creates makefiles for all the Java packages
3328         in a project plus a toplevel makefile that invokes the other
3329         makefiles to build the entire project.
3330       </para>
3331
3332       <sect4>
3333
3334
3335         <title><anchor id="MakeOptions"/>Make Options</title>
3336
3337
3338         <para>
3339           The following customization variables  allow you to specify
3340           various <command>jde-make</command> options:
3341         </para>
3342
3343         <table>
3344           <title></title>
3345           <tgroup cols="4">
3346             <colspec colnum="1" align="left"/>
3347             <colspec colnum="2" align="left"/>
3348             <colspec colnum="3" align="left"/>
3349             <colspec colnum="4" align="left"/>
3350             <thead>
3351               <row>
3352                 <entry>Name</entry>
3353                 <entry>Group</entry>
3354                 <entry>Default</entry>
3355                 <entry>Usage</entry>
3356               </row>
3357             </thead>
3358             <tbody>
3359               <row>
3360                 <entry
3361                   valign="top"><varname>jde-make-program</varname></entry>
3362                 <entry valign="top">Project</entry>
3363                 <entry>make</entry>
3364                 <entry>
3365                   <para>Specifies the pathname on your system of the
3366                     make utility that the <command>jde-make</command>
3367                     uses to build your project. </para>
3368                 </entry>
3369               </row>
3370               <row>
3371                 <entry
3372                   valign="top"><varname>jde-make-args</varname></entry>
3373                 <entry valign="top">Project</entry>
3374                 <entry></entry>
3375                 <entry>
3376                   <para> Specifies a string of command-line arguments
3377                     (for  example, &quot;<varname>-f mymakefile
3378                       all</varname>&quot;) to be passed to  the make
3379                     utility. </para>
3380                 </entry>
3381               </row>
3382               <row>
3383                 <entry
3384                   valign="top"><varname>jde-read-make-args</varname></entry>
3385                 <entry valign="top">Project</entry>
3386                 <entry><varname>nil</varname></entry>
3387                 <entry>
3388                   <para> If nonnil, this variable causes the
3389                     <command>jde-make</command> command to prompt you
3390                     to enter command-line arguments in the minibuffer.
3391                     <command>jde-make</command> passes these arguments
3392                     along with the arguments specified by
3393                     <varname>jde-make-args</varname> to the make
3394                     utility. </para>
3395                 </entry>
3396               </row>
3397               <row>
3398                 <entry
3399                   valign="top"><varname>jde-make-working-directory</varname></entry>
3400                 <entry valign="top">Project</entry>
3401                 <entry></entry>
3402                 <entry>
3403                   <para> Specifies the directory from which
3404                     <command>jde-make</command> runs the make utility.
3405                   </para>
3406                 </entry>
3407               </row>
3408             </tbody>
3409           </tgroup>
3410         </table>
3411
3412       </sect4>
3413
3414       <sect4>
3415
3416
3417         <title><anchor id="SampleMakefile"/>Sample Makefile</title>
3418
3419         <para>The following is a sample makefile that you can use as a
3420           model for creating makefiles to build Java projects. </para>
3421
3422         <programlisting>
3423           JDK = d:/jdk1.2/lib/classes.zip
3424           JMATH = d:/jmath/src
3425           CLASSPATH = $(JMATH);$(JDK)
3426           COMPILER = javac VM = java
3427           COPTIONS = -g -deprecation
3428           ROPTIONS =
3429           CLASSES = Test.class \
3430                     JMathError.class \
3431                     JMathException.class \
3432                     LinearSystem.class
3433
3434           .SUFFIXES: .java .class
3435           all : $(CLASSES)
3436             # Rebuild (if necessary) and run the JMath test suite. run: $(CLASSES)
3437             $(VM) -classpath &quot;$(CLASSPATH)&quot; jmath.Test
3438
3439           # Remove all class files from the project directory.
3440           clean: rm *.class
3441
3442           # Implicit rule for making Java class files from Java
3443           # source files.
3444           .java.class: $(COMPILER) $(COPTIONS) -classpath &quot;$(CLASSPATH)&quot; $?
3445         </programlisting>
3446       </sect4>
3447
3448     </sect3>
3449
3450     <sect3>
3451
3452       <title><anchor id="BuildWithAnt"/>Building with Ant</title>
3453
3454       <para>
3455         The <command>jde-ant-build</command> command uses the <ulink
3456           url="http://jakarta.apache.org/ant/">Apache Ant</ulink>
3457         build tool to build a Java project.
3458       </para>
3459
3460       <para>The following variables allow you to control the build
3461         process.</para>
3462
3463       <table>
3464         <title>Ant Options</title>
3465         <tgroup cols="4">
3466           <colspec colnum="1" align="left"/>
3467           <colspec colnum="2" align="left"/>
3468           <colspec colnum="3" align="left"/>
3469           <colspec colnum="4" align="left"/>
3470           <thead>
3471             <row>
3472               <entry>Name</entry>
3473               <entry>Group</entry>
3474               <entry>Default</entry>
3475               <entry>Usage</entry>
3476             </row>
3477           </thead>
3478           <tbody>
3479             <row>
3480               <entry
3481                 valign="top"><varname>jde-ant-invocation-method</varname></entry>
3482               <entry valign="top">Ant</entry>
3483               <entry>script</entry>
3484               <entry>
3485                 <para> Specifies how to invoke ant. Ant can be invoked
3486                   in one of three ways. The first is via the ant
3487                   script/program that comes with ant. The second is
3488                   via java and the third is via the Ant Server.
3489                 </para>
3490               </entry>
3491             </row>
3492             <row>
3493               <entry
3494                 valign="top"><varname>jde-ant-home</varname></entry>
3495               <entry valign="top">Ant</entry>
3496               <entry></entry>
3497               <entry>
3498                 <para> Directory where ant is installed. </para>
3499               </entry>
3500             </row>
3501             <row>
3502               <entry
3503                 valign="top"><varname>jde-ant-user-jar-files</varname></entry>
3504               <entry valign="top">Ant</entry>
3505               <entry><varname>nil</varname></entry>
3506               <entry>
3507                 <para> Specifies jar files that hold user-defined
3508                   tasks. </para>
3509               </entry>
3510             </row>
3511             <row>
3512               <entry
3513                 valign="top"><varname>jde-ant-program</varname></entry>
3514               <entry valign="top">Ant</entry>
3515               <entry><para>ant</para></entry>
3516               <entry>
3517                 <para> Specifies name of ant program/script. </para>
3518               </entry>
3519             </row>
3520             <row>
3521               <entry
3522                 valign="top"><varname>jde-ant-args</varname></entry>
3523               <entry valign="top">Ant</entry>
3524               <entry><para>-emacs</para></entry>
3525               <entry>
3526                 <para> Specifies arguments to be passed to the Ant
3527                   program. </para>
3528               </entry>
3529             </row>
3530             <row>
3531               <entry
3532                 valign="top"><varname>jde-ant-buildfile</varname></entry>
3533               <entry valign="top">Ant</entry>
3534               <entry><para>build.xml</para></entry>
3535               <entry>
3536                 <para> Specifies the default buildfile to use. </para>
3537               </entry>
3538             </row>
3539             <row>
3540               <entry
3541                 valign="top"><varname>jde-ant-read-buildfile</varname></entry>
3542               <entry valign="top">Ant</entry>
3543               <entry><para>off</para></entry>
3544               <entry>
3545                 <para> Specify whether to prompt for a buildfile. If
3546                   non-nil, the jde-ant-build command prompts you for
3547                   an ant buildfile.  Note that
3548                   <varname>jde-ant-read-buildfile</varname> and
3549                   <varname>jde-ant-enable-find</varname> are
3550                   incompatible and that
3551                   <varname>jde-ant-read-buildfile</varname> will
3552                   override the former. </para>
3553               </entry>
3554             </row>
3555             <row>
3556               <entry
3557                 valign="top"><varname>jde-ant-read-target</varname></entry>
3558               <entry valign="top">Ant</entry>
3559               <entry><para>off</para></entry>
3560               <entry>
3561                 <para> Specify whether to prompt for a build target.
3562                   If non-nil, the jde-ant-build command prompts you
3563                   for an ant target. </para>
3564               </entry>
3565             </row>
3566             <row>
3567               <entry
3568                 valign="top"><varname>jde-ant-interactive-buildfile</varname></entry>
3569               <entry valign="top">Ant</entry>
3570               <entry><para>off</para></entry>
3571               <entry>
3572                 <para> Default buildfile to use when prompting
3573                   interactively. </para>
3574               </entry>
3575             </row>
3576             <row>
3577               <entry
3578                 valign="top"><varname>jde-ant-read-args</varname></entry>
3579               <entry valign="top">Ant</entry>
3580               <entry><para>off</para></entry>
3581               <entry>
3582                 <para> Specify whether to prompt for additional
3583                   arguments to pass to Ant. If non-nil, the
3584                   <command>jde-ant-build</command> command prompts you
3585                   for the additional arguments. </para>
3586               </entry>
3587             </row>
3588             <row>
3589               <entry
3590                 valign="top"><varname>jde-ant-enable-find</varname></entry>
3591               <entry valign="top">Ant</entry>
3592               <entry><para>off</para></entry>
3593               <entry>
3594                 <para> Specify whether jde-ant find the
3595                   <filename>build.xml</filename> file based on your
3596                   current directory. If non-nil, we will search up the
3597                   directory hierarchy from the current directory for
3598                   the build definition file. Also note that, if
3599                   non-nil, this will relax the requirement for an
3600                   explicit jde project file.  In order for this to
3601                   work <varname>jde-ant-read-buildfile</varname> must
3602                   be nil.</para>
3603               </entry>
3604             </row>
3605             <row>
3606               <entry
3607                 valign="top"><varname>jde-ant-complete-target</varname></entry>
3608               <entry valign="top">Ant</entry>
3609               <entry><para>off</para></entry>
3610               <entry>
3611                 <para> Specify whether to enable completion of build
3612                   target names in the minibuffer. If non-nil, the
3613                   <command>jde-ant-build</command> command allows you
3614                   to use tab completion in the minibuffer to specify
3615                   the build target name.  This list of valid build
3616                   targets is determined by parsing the Ant build file.
3617                   This option has no effect if
3618                   <varname>jde-ant-read-target</varname> is
3619                   nil.</para>
3620               </entry>
3621             </row>
3622             <row>
3623               <entry
3624                 valign="top"><varname>jde-ant-use-global-classpath</varname></entry>
3625               <entry valign="top">Ant</entry>
3626               <entry><para>off</para></entry>
3627               <entry>
3628                 <para>Specify whether to enable use of
3629                   <varname>jde-global-classpath</varname> when running
3630                   <filename>jde-ant</filename>.</para>
3631               </entry>
3632             </row>
3633             <row>
3634               <entry
3635                 valign="top"><varname>jde-ant-target-regexp</varname></entry>
3636               <entry valign="top">Ant</entry>
3637               <entry>
3638                 <para>
3639                   &lt;\s-*target\s-[^...]*?name\s-*=\s-*\"\s-*\([^\"]+\)
3640                 </para>
3641               </entry>
3642               <entry>
3643                 <para>Regular expression used to match target names in
3644                   Ant build files.</para>
3645               </entry>
3646             </row>
3647             <row>
3648               <entry
3649                 valign="top"><varname>jde-ant-build-hook</varname></entry>
3650               <entry valign="top">Ant</entry>
3651               <entry><para>nil</para></entry>
3652               <entry>
3653                 <para>List of hook functions run by
3654                   <command>jde-ant-build</command> (see
3655                   <varname>run-hooks</varname> in the Emacs
3656                   documentation for more information).</para>
3657               </entry>
3658             </row>
3659           </tbody>
3660         </tgroup>
3661       </table>
3662
3663     </sect3>
3664
3665   </chapter>
3666
3667   <chapter>
3668
3669
3670     <title><anchor id="RunningJavaApps"/>Running Java
3671       Applications</title>
3672
3673
3674     <para>The JDE allows you to run a Java application as an Emacs
3675       subprocess. You can run multiple applications concurrently, but
3676       only one instance of each application at a time. The JDE
3677       displays each application's standard and error output in an
3678       Emacs command interface (<varname>comint</varname>) buffer. You
3679       can interact with applications that accept command line input
3680       via the <varname>comint</varname> buffer. When interacting with
3681       an application, you can use any of
3682       <varname>comint-mode</varname>'s extensive set of command-line
3683       history commands to speed interaction. To run an application,
3684       enter </para>
3685
3686     <programlisting>
3687       M-x jde-run
3688     </programlisting>
3689
3690     <para>or select <menuchoice><guimenu>Java</guimenu>
3691         <guimenuitem>Run App</guimenuitem></menuchoice> from the Emacs
3692       menubar or type <keycombo>
3693         <keycap>C</keycap><keycap>c</keycap></keycombo>&nbsp;<keycombo>
3694         <keycap>C</keycap><keycap>v</keycap></keycombo>&nbsp;<keycombo>
3695         <keycap>C</keycap><keycap>r</keycap></keycombo>. </para>
3696
3697     <sect3>
3698       <title><anchor id="SpecifyingMainClass"/>Specifying the
3699         Application's Main Class</title>
3700
3701       <para>The term <emphasis>main class</emphasis> refers to the
3702         class that contains the application's main method. The JDE's
3703         Run App command assumes by default that the class in the
3704         current buffer is the application's main class. This can be
3705         inconvenient if you have an application that has multiple
3706         classes. You may want to be able to run the application from
3707         any buffer containing one of the application's classes. To do
3708         this, set the variable
3709         <varname>jde-run-application-class</varname> to the
3710         <emphasis>fully qualified name</emphasis> of the application's
3711         main class.</para>
3712
3713       <para>You can temporarily override the setting of
3714         <varname>jde-run-application-class</varname> by typing
3715         <varname>C-u -</varname> before executing the <command
3716           moreinfo="none">jde-run</command> command, for example, by
3717         typing <varname>C-u - C-c C-r</varname>. This causes the JDE to
3718         prompt you to enter the <emphasis>fully qualified
3719           name</emphasis> of the application's main class (as well
3720         application arguments if any).</para>
3721
3722     </sect3>
3723
3724     <sect3>
3725
3726
3727
3728       <title><anchor id="SpecifyingStartupDirectory"/>Specifying a
3729         Startup Directory</title>
3730
3731       <para>The JDE can start an application from any directory that
3732         you specify. By default, the JDE starts an application from
3733         the default directory of the current source buffer. The
3734         default directory of the current source buffer is the
3735         directory containing the source file displayed in the buffer.
3736         You can specify another directory as the startup directory by
3737         setting the JDE customization variable
3738         <varname>jde-run-working-directory</varname>.</para>
3739
3740       <para>To set this variable, </para>
3741
3742       <procedure>
3743
3744         <step>
3745           <para>Display its customization panel.</para>
3746           <para>You can do this by  typing </para>
3747           <para><keycombo>
3748               <keycap>M</keycap><keycap>x</keycap></keycombo>&nbsp;<varname>customize-variable</varname>&nbsp;<varname>jde-run-working-directory</varname></para>
3749           <para>or selecting <menuchoice><guimenu>JDE</guimenu>
3750               <guisubmenu>Options</guisubmenu><guimenuitem>Project</guimenuitem>
3751
3752
3753
3754             </menuchoice> to display the project customization  panel
3755             and searching this panel for
3756             <varname>jde-run-working-directory</varname>.
3757           </para>
3758           <para>
3759             <screenshot>
3760               <mediaobject>
3761                 <imageobject>
3762                   <imagedata fileref="images/WorkingDirectory.gif"/>
3763                 </imageobject>
3764                 <textobject>
3765                   <phrase>Screenshow showing customization buffer for
3766                     <varname>jde-run-working-directory</varname>.</phrase>
3767                 </textobject>
3768               </mediaobject>
3769             </screenshot>
3770           </para>
3771         </step>
3772
3773         <step>
3774           <para>Enter the working directory in the variable's edit
3775             field. </para></step>
3776
3777         <step>
3778           <para>Save the new setting.</para>
3779           <para>To save the edited bindings,  right click the
3780             <guibutton>[State]</guibutton>  button and choose
3781             <menuchoice>
3782               <guimenuitem>Set for current
3783                 session</guimenuitem></menuchoice> if you want the
3784             settings to apply only  to the current project or
3785             <menuchoice>
3786               <guimenuitem>Save for  future
3787                 sessions</guimenuitem></menuchoice> if you want the
3788             settings to  apply to all projects. In either case, you
3789             should save  the new settings in you project file if your
3790             project has  a project file. To save the new settings in
3791             your project  file, switch to a source buffer and choose
3792             <menuchoice><guimenu>JDE</guimenu>
3793               <guisubmenu>Options</guisubmenu><guimenuitem>Save
3794                 Project</guimenuitem></menuchoice>.</para>
3795         </step>
3796
3797       </procedure>
3798
3799     </sect3>
3800
3801     <sect3>
3802
3803
3804       <title><anchor id="RunVMArgs"/> Setting VM Command-Line
3805         Arguments</title>
3806
3807       <para>If you set the customization variable
3808         <varname>jde-run-read-vm-args</varname>  to a
3809         non-<varname>nil</varname> value, the JDE compile command
3810         prompts you to enter virtual machine options in the
3811         minibuffer. It appends  the options that you enter to the
3812         options specified via  customization variables. The JDE saves
3813         the arguments that you  enter in a minibuffer history list.
3814         You can recall previously  entered options by pressing the up
3815         or down arrows on your  keyboard. </para>
3816
3817     </sect3>
3818
3819     <sect3>
3820
3821
3822       <title><anchor id="RunAppArgs"/> Setting Command-Line
3823         Application Arguments</title>
3824
3825       <para>Specifying a prefix argument before the
3826         <command>jde-run</command>, e.g., <varname>C-u C-c C-v
3827           C-r</varname> causes the command to prompt you to enter
3828         arguments to be passed to the application's main
3829         method. The command appends the options that you enter to the
3830         arguments specified via  the customization variable
3831         <varname>jde-run-option-application-args</varname>.  The JDE
3832         saves the arguments that you enter in a minibuffer  history
3833         list. You can recall previously entered options by  pressing
3834         the up or down arrows on your keyboard. </para>
3835
3836       <para>If you set the customization variable
3837         <varname>jde-run-read-app-args</varname>  to a
3838         non-<varname>nil</varname> value, the JDE run command
3839         prompts you to enter command-line application arguments
3840         by default, i.e., you do not have to specify a prefix
3841         argument each time you execute the command.</para>
3842     </sect3>
3843
3844     <sect3>
3845       <title><anchor id="NavigatingExceptionTraces"/>Navigating
3846         Exception Traces</title>
3847
3848       <para>If an exception occurs while your program is running, the
3849         Java vm outputs an exception trace. This trace appears in the
3850         run buffer for the application.</para>
3851
3852       <para>
3853         <screenshot>
3854           <mediaobject>
3855             <imageobject>
3856               <imagedata fileref="images/excepttrace.gif"/>
3857             </imageobject>
3858             <textobject>
3859               <phrase>Screenshot showing an exception trace in the
3860               JDE's run buffer.</phrase>
3861             </textobject>
3862           </mediaobject>
3863         </screenshot>
3864       </para>
3865     </sect3>
3866
3867     <para>To view the source line corresponding to a point in the
3868       exception stack trace, right-click the corresponding stack trace
3869       line in the run buffer. You can move up and down the stack trace
3870       by typing the key combinations <varname>C-c C-v C-[</varname> or
3871       <varname>C-c C-v C-]</varname>.</para>
3872
3873
3874
3875     <sect3>
3876
3877       <title><anchor id="RunOptions"/>Run Customization Variables
3878       </title>
3879
3880       <para>The JDE allows you to specify run-time options by setting
3881         run variables.You can use the Emacs customization feature to
3882         set run-time variables interactively. To use the customization
3883         feature, select
3884         <menuchoice>
3885           <guimenu>JDE</guimenu><guisubmenu>Project</guisubmenu><guisubmenu>Options</guisubmenu><guimenuitem>Run</guimenuitem></menuchoice>.
3886         (See <ulink url="#ConfiguringJDE">Configuring  the JDE</ulink>
3887         for more information on using the customization  feature). To
3888         save the compilation settings in the project file (see <ulink
3889           url="#UsingProjectFiles">Using Project Files</ulink>) for
3890         the  current source buffer, select <menuchoice>
3891           <guimenu>JDE</guimenu>
3892           <guisubmenu> Project</guisubmenu><guisubmenu>Project
3893             File</guisubmenu><guimenuitem>Save
3894             Project</guimenuitem></menuchoice>.
3895       </para>
3896
3897       <para>The following table lists the JDE run variables and the
3898         functions used to set them. &nbsp; </para>
3899
3900       <table>
3901         <title></title>
3902         <tgroup cols="3">
3903           <colspec colnum="1"/>
3904           <colspec colnum="2"/>
3905           <colspec colnum="3"/>
3906           <thead>
3907             <row>
3908               <entry>Variable</entry>
3909               <entry>Group</entry>
3910               <entry>Usage</entry>
3911             </row>
3912           </thead>
3913           <tbody>
3914             <row>
3915               <entry
3916                 valign="top"><varname>jde-run-mode-hook</varname></entry>
3917               <entry valign="top">Project</entry>
3918               <entry valign="top">List of hook functions run by
3919                 <varname>jde-run-mode</varname></entry>
3920             </row>
3921             <row>
3922               <entry
3923                 valign="top"><varname>jde-run-working-directory</varname></entry>
3924               <entry valign="top">Project</entry>
3925               <entry>Startup directory for running or debugging Java
3926                 applications.</entry>
3927             </row>
3928             <row>
3929               <entry
3930                 valign="top"><varname>jde-run-application-class</varname></entry>
3931               <entry valign="top">Project&nbsp;</entry>
3932               <entry valign="top">Name of the Java class to run. The
3933                 command <varname>jde-run-set-app</varname> sets the
3934                 buffer-local value of this variable.&nbsp;</entry>
3935             </row>
3936             <row>
3937               <entry
3938                 valign="top"><varname>jde-run-java-vm</varname></entry>
3939               <entry valign="top">Project&nbsp;</entry>
3940               <entry valign="top">Specify Java interpreter for
3941                 non-Windows platforms. The command
3942                 <varname>jde-run-set-vm</varname> sets the
3943                 buffer-local value of this variable.&nbsp;</entry>
3944             </row>
3945             <row>
3946               <entry
3947                 valign="top"><varname>jde-run-java-vm-w</varname></entry>
3948               <entry valign="top">Project&nbsp;</entry>
3949               <entry valign="top">Specify Java interpreter for Windows
3950                 platforms. The command
3951                 <varname>jde-run-set-vm-w</varname> sets the
3952                 buffer-local value of this variable.&nbsp;</entry>
3953             </row>
3954             <row>
3955               <entry
3956                 valign="top"><varname>jde-global-classpath</varname></entry>
3957               <entry valign="top">Project&nbsp;</entry>
3958               <entry valign="top">Specify class paths for compile,
3959                 run, and debug commands. The command<varname>
3960                   jde-set-global-classpath</varname> sets the
3961                 buffer-local value of this variable.&nbsp;</entry>
3962             </row>
3963             <row>
3964               <entry
3965                 valign="top"><varname>jde-run-classic-mode-vm</varname></entry>
3966               <entry valign="top">Project</entry>
3967               <entry>Specifies that the JDE should run the JDK's
3968                 classic version of the Java virtual machine (as
3969                 opposed to the HotSpot version). This option applies
3970                 only to versions of the JDK that include both a
3971                 classic and a HotSpot vm.</entry>
3972             </row>
3973             <row>
3974               <entry
3975                 valign="top"><varname>jde-run-read-vm-args</varname></entry>
3976               <entry valign="top">Project</entry>
3977               <entry>Specifies whether to read vm arguments from
3978                 the&nbsp; minibuffer.</entry>
3979             </row>
3980             <row>
3981               <entry
3982                 valign="top"><varname>jde-run-option-classpath</varname></entry>
3983               <entry valign="top">Run&nbsp;</entry>
3984               <entry valign="top">Specifies the classpath for&nbsp;
3985                 the Java interpreter. This option overrides the
3986                 jde-global-classpath option.&nbsp;</entry>
3987             </row>
3988             <row>
3989               <entry
3990                 valign="top"><varname>jde-run-option-verbose</varname></entry>
3991               <entry valign="top">Run&nbsp;</entry>
3992               <entry valign="top">Print messages about the running
3993                 process.&nbsp;</entry>
3994             </row>
3995             <row>
3996               <entry
3997                 valign="top"><varname>jde-run-option-properties</varname></entry>
3998               <entry valign="top">Run&nbsp;</entry>
3999               <entry valign="top">Specify property values.</entry>
4000             </row>
4001             <row>
4002               <entry
4003                 valign="top"><varname>jde-run-option-heap-size</varname></entry>
4004               <entry valign="top">Run&nbsp;</entry>
4005               <entry valign="top">Specify the initial and maximum size
4006                 of the interpreter heap.&nbsp;</entry>
4007             </row>
4008             <row>
4009               <entry
4010                 valign="top"><varname>jde-run-option-stack-size</varname></entry>
4011               <entry valign="top">Run&nbsp;</entry>
4012               <entry valign="top">Specify size of the C and Java
4013                 stacks.</entry>
4014             </row>
4015             <row>
4016               <entry
4017                 valign="top"><varname>jde-run-option-garbage-</varname>&nbsp;
4018                 <varname>collection</varname>&nbsp;</entry>
4019               <entry valign="top">Run</entry>
4020               <entry valign="top">Specify garbage collection
4021                 options.&nbsp;</entry>
4022             </row>
4023             <row>
4024               <entry
4025                 valign="top"><varname>jde-run-option-java-profile</varname></entry>
4026               <entry valign="top">Run&nbsp;</entry>
4027               <entry valign="top">Enable Java profiling.</entry>
4028             </row>
4029             <row>
4030               <entry
4031                 valign="top"><varname>jde-run-option-heap-profile</varname></entry>
4032               <entry valign="top">Run&nbsp;</entry>
4033               <entry valign="top">Output heap profiling data.</entry>
4034             </row>
4035             <row>
4036               <entry
4037                 valign="top"><varname>jde-run-option-verify</varname></entry>
4038               <entry valign="top">Run&nbsp;</entry>
4039               <entry valign="top">Verify classes.</entry>
4040             </row>
4041             <row>
4042               <entry
4043                 valign="top"><varname>jde-run-option-vm-args</varname></entry>
4044               <entry valign="top">Run&nbsp;</entry>
4045               <entry valign="top">Specify command-line arguments to be
4046                 passed to the Java vm. The command jde-run-set-args
4047                 sets the buffer-local value of this
4048                 variable.&nbsp;</entry>
4049             </row>
4050             <row>
4051               <entry
4052                 valign="top"><varname>jde-run-option-application-args</varname></entry>
4053               <entry valign="top">Run&nbsp;</entry>
4054               <entry valign="top">Specify command-line arguments to
4055                 pass to the application. The command
4056                 <varname>jde-run-set-app-args </varname>sets the
4057                 buffer-local value of this variable.&nbsp;</entry>
4058             </row>
4059           </tbody>
4060         </tgroup>
4061       </table>
4062
4063     </sect3>
4064
4065   </chapter>
4066
4067   <chapter>
4068
4069
4070       <title><anchor id="WorkingWithApplets"/> Working with Applets</title>
4071
4072     <para>The JDE provides specialized commands for running and
4073       debugging applets.</para>
4074
4075     <sect3>
4076
4077
4078       <title><anchor id="RunningApplets"/>Running Applets</title>
4079
4080       <para>To run an applet:</para>
4081
4082       <procedure>
4083
4084         <step>
4085           <para>Open the applet's source file in a buffer. </para>
4086         </step>
4087
4088         <step>
4089           <para>Choose <menuchoice>
4090               <guimenu>JDE</guimenu><guimenuitem>Run
4091                 Applet</guimenuitem>
4092             </menuchoice>. </para>
4093           <para>The JDE searches for an html file in the directory
4094             containing the applet source file and displays the first
4095             file it finds, using your system's default browser. If
4096             the JDE cannot find an html page in the applet's source
4097             file directory, it signals an error by default.
4098           </para>
4099         </step>
4100
4101       </procedure>
4102
4103       <para>The  <menuchoice><guimenu>JDE</guimenu>
4104           <guimenuitem>Run Applet</guimenuitem></menuchoice> command
4105         assumes by default that the directory containing the  applet's
4106         source also contains an html page for testing that  applet. If
4107         this is not true in your case, you have two options.  You can
4108         either specify the path of the applet file via the JDE
4109         customization variable <varname>jde-run-applet-doc</varname>
4110         or you can use  the <varname>jde-run-applet</varname> command
4111         to run your applet. If the
4112         <varname>jde-run-applet-doc</varname>  variable is not a null
4113         string, <menuchoice><guimenu>JDE</guimenu>
4114           <guimenuitem>Run Applet</guimenuitem></menuchoice> displays
4115         the
4116         document that the variable  specifies instead of searching the source
4117         file directory for a  document to display. The
4118         <varname>jde-run-applet</varname> command prompts  you to enter in the
4119         minibuffer the path of an html file to  display. If you enter nothing,
4120         the command defaults to the  behavior of  <menuchoice><guimenu>JDE</guimenu>
4121           <guimenuitem>Run Applet</guimenuitem></menuchoice>.</para>
4122
4123       <para>The run commands chooses the viewer as follows. If
4124         <varname>jde-run-applet-viewer</varname> is a null string (the
4125         default) or browse-url, the JDE uses browse-url to launch the
4126         applet doc in your system's default browser. Otherwise, the
4127         menu command uses comint to launch the viewer (e.g.,
4128         appletviewer) specified by
4129         <varname>jde-run-applet-viewer</varname>.</para>
4130     </sect3>
4131
4132     <sect3>
4133
4134
4135       <title><anchor id="DebuggingApplets"/>Debugging Applets</title>
4136
4137       <para>To debug an applet:</para>
4138
4139       <procedure>
4140
4141         <step>
4142           <para>Open the applet's source file in a buffer.</para>
4143         </step>
4144
4145         <step>
4146           <para>Choose  <menuchoice><guimenu>JDE</guimenu>
4147               <guimenuitem>Debug
4148                 Applet</guimenuitem></menuchoice>.</para>
4149           <para>The JDE searches for an html file in the directory
4150             containing the applet source file. If the JDE cannot find
4151             an html page in the applet's source file directory, it
4152             signals an error by default. Otherwise, it runs
4153             appletviewer in debug mode on the first file that it
4154             finds.</para>
4155           <para>The Emacs window splits into two panes.</para>
4156         </step>
4157       </procedure>
4158
4159       <para>The top pane shows the applet's source file with the debug
4160         cursor pointing to the first line of the applet's init file.
4161         The bottom pane displays the debugger's command line
4162         interface. You can now set breakpoints, single-step, or
4163         continue running the applet. See <ulink
4164           url="#DebuggingApps">Debugging Applications</ulink> for more
4165         information.</para>
4166
4167       <para>If you want to specify the document to be used to test the
4168         applet, customize the variable jde-run-applet-doc or execute
4169         <varname>M-x jde-db-applet</varname>. This command prompts you
4170         to enter the test document's name.</para>
4171     </sect3>
4172
4173     <sect3>
4174
4175
4176       <title><anchor id="AppletOptions"/>Applet Customization
4177         Variables</title>
4178
4179       <para>The JDE allows you to specify run-time options for applets
4180         by setting JDE configuration variables.You must use the Emacs
4181         customization feature to set applet run-time variables . To
4182         use the customization feature, select <menuchoice>
4183           <guimenu>JDE</guimenu><guisubmenu>Options</guisubmenu><guimenuitem>Run</guimenuitem></menuchoice>.
4184         (See <ulink url="#ConfiguringJDE">Configuring the JDE</ulink>
4185         for more information on using the customization feature). In
4186         some cases, the JDE also provides functions for setting the
4187         buffer-local values of the compilation variables. To save the
4188         compilation settings in the project file (see <ulink
4189           url="#UsingProjectFiles">Using Project Files</ulink>) for
4190         the current source buffer, select
4191         <menuchoice><guimenu>JDE</guimenu><guisubmenu>Options</guisubmenu><guimenuitem>Update
4192             Project</guimenuitem></menuchoice>. </para>
4193
4194       <para>The following table lists the JDE applet run-time
4195         variables and the functions used to set them.  </para>
4196
4197       <table>
4198         <title></title>
4199         <tgroup cols="3">
4200           <thead>
4201             <row>
4202               <entry>Variable</entry>
4203               <entry>Group</entry>
4204               <entry>Usage</entry>
4205             </row >
4206           </thead>
4207           <tbody>
4208             <row>
4209               <entry
4210                 valign="top"><varname>jde-run-applet-viewer</varname></entry>
4211               <entry valign="top">Project&nbsp;</entry>
4212               <entry valign="top">Specify name of viewer to use to
4213                 display page containing the applet. The command
4214                 <varname>jde-run-set-applet-viewer</varname> sets the
4215                 buffer-local value of this variable.&nbsp;</entry>
4216             </row >
4217             <row>
4218               <entry
4219                 valign="top"><varname>jde-run-applet-doc</varname></entry>
4220               <entry valign="top">Project&nbsp;</entry>
4221               <entry valign="top">Specify name of document containing
4222                 applet to be viewed. The command
4223                 <varname>jde-run-set-applet-doc</varname> sets the
4224                 buffer-local value of this variable.&nbsp;</entry>
4225             </row >
4226           </tbody>
4227         </tgroup>
4228       </table>
4229     </sect3>
4230
4231   </chapter>
4232
4233   <chapter>
4234
4235
4236       <title><anchor id="DebuggingApps"/>Debugging Applications</title>
4237
4238     <para>The JDE provides two options for debugging Java applications.</para>
4239
4240     <itemizedlist>
4241       <listitem>
4242         <para>An Emacs interface to <command>jdb</command>, the command-line
4243           debugger that comes with the JDK. See <ulink url="../jdb-ug/jdb-ug-frame.html"
4244                                                        type="jdb-ug">Debugging with jdb</ulink> for more
4245           information. </para>
4246       </listitem>
4247
4248       <listitem>
4249         <para>
4250           JDEbug, a Java debugger developed specifically for use  with the JDE.
4251           See <ulink url="../jdebug-ug/jdebug-ug.html"  type="jdebug-ug">JDEbug
4252             User's Guide</ulink> for more information</para>.
4253       </listitem>
4254     </itemizedlist>
4255
4256     <para>JDEbug provides more debugging features but requires a JDK 1.2
4257       or higher vm. You must use <command>jdb</command> to debug applications
4258       running on earlier vms.</para>
4259
4260   </chapter>
4261
4262
4263   <chapter>
4264
4265     <title><anchor id="SpecifyingClasspaths"/>Specifying
4266       Classpaths</title>
4267
4268     <para>The JDE provides customization variables that permit you to
4269       specify a classpath for the JDE's compile, run, debug,
4270       Beanshell, and other commands. The following table lists these
4271       variables.</para>
4272
4273     <table>
4274       <title>Classpath Variables</title>
4275       <tgroup cols="2">
4276         <thead>
4277           <row>
4278             <entry>Variable</entry>
4279             <entry>Applies To ...</entry>
4280           </row>
4281         </thead>
4282         <tbody>
4283           <row>
4284             <entry><para><varname>jde-global-classpath</varname></para></entry>
4285             <entry><para>All JDE commands that use a
4286                 classpath.</para></entry>
4287           </row>
4288           <row>
4289             <entry><para><varname>jde-compile-option-classpath</varname></para></entry>
4290             <entry><para>Compile command</para></entry>
4291           </row>
4292           <row>
4293             <entry><para><varname>jde-run-option-classpath</varname></para></entry>
4294             <entry><para>Run App command</para></entry>
4295           </row>
4296           <row>
4297             <entry><para><varname>jde-db-option-classpath</varname></para></entry>
4298             <entry><para>Debug App command</para></entry>
4299           </row>
4300         </tbody>
4301       </tgroup>
4302     </table>
4303
4304     <para>The <varname>jde-global-classpath</varname> variable is so
4305       named because it specifies a classpath that is used by all JDE
4306       commands unless overridden by a classpath variable specific to a
4307       particular command. For example, the JDE's
4308       <command>Compile</command> command uses
4309       <varname>jde-global-classpath</varname> unless the value of
4310       <varname>jde-compile-option-classpath</varname> is set.
4311       Typically you want to use the same classpath to compile, run,
4312       and debug an application. So typically
4313       <varname>jde-global-classpath</varname> is the only variable you
4314       need to set.</para>
4315
4316
4317
4318     <sect3>
4319       <title><anchor id="SettingClasspathVar"/>Setting a Classpath
4320         Variable</title>
4321       <para>As with other JDE customization variables, you must use
4322         Emacs' <command moreinfo="none">customize-variable</command>
4323         command to set the JDE's classpath variables. You can use
4324         relative paths, cygwin paths, and paths with tilde notation
4325         and environment variables as values of JDE classpath
4326         variables. See <ulink url="#SpecifyingPaths">Specifying
4327           Paths</ulink> for more information.
4328       </para>
4329
4330       <para>
4331         When setting a classpath variable, you must enter each path as
4332         a separate entry in the customization buffer. Do not enter the
4333         paths as semicolon or colon-separated lists of paths. The
4334         following examples show the right and wrong way to specify a
4335         classpath.</para>
4336
4337       <example>
4338         <title>Wrong Way to Specify a Classpath</title>
4339         <programlisting format="linespecific">
4340           jde-global-classpath: [Hide]
4341           [INS] [DEL] Path: c:/jde-dev/jmath/classes;c:/jde-dev/jmath/src
4342           [INS]
4343             [State]: this option has been set and saved.
4344         </programlisting>
4345       </example>
4346
4347       <example>
4348         <title>Right Way to Specify a Classpath</title>
4349         <programlisting format="linespecific">
4350           jde-global-classpath: [Hide]
4351           [INS] [DEL] Path: c:/jde-dev/jmath/classes
4352           [INS] [DEL] Path: c:/jde-dev/jmath/src
4353           [INS]
4354             [State]: this option has been set and saved.
4355         </programlisting>
4356       </example>
4357     </sect3>
4358
4359     <sect3>
4360       <title><anchor id="ClassLibraries"/>Including Class
4361         Libraries</title>
4362       <para>
4363         If you store your class libraries as jar or zip files in
4364         separate directory, you need specify only the path of the
4365         directory in a JDE classpath variable. Whenever the JDE
4366         encounters a library directory in a classpath variable, it
4367         expands the classpath to include all the jar and zip files in
4368         the library directory.
4369       </para>
4370
4371       <para>
4372         For example, suppose you organize your project directory as
4373         follows:
4374       </para>
4375
4376       <para> <programlisting format="linespecific"> myproj classes lib
4377           src </programlisting>
4378       </para>
4379
4380       <para>
4381         where the <filename>src</filename> directory contains all of
4382         your source files, the <filename>lib</filename> directory all
4383         of your jar and zip files,  and the
4384         <filename>classes</filename> directory all of the classes
4385         compiled from the <filename>src</filename> directory. Further,
4386         suppose you store your project file (see <ulink
4387           url="#UsingProjectFiles">Using Project Files</ulink>) at the
4388         root of your project directory. Then, you can specify
4389         <varname>jde-global-classpath</varname> simply as follows.
4390       </para>
4391
4392       <para>
4393         <programlisting format="linespecific"> jde-global-classpath:
4394           [Hide] [INS] [DEL] Path: ./classes [INS] [DEL] Path: ./src
4395           [INS] [DEL] Path: ./lib [INS] [State]: this option has been
4396           set and saved. </programlisting>
4397       </para>
4398
4399       <para>
4400         If you do not want the JDE to expand library directories, set
4401         the variable <varname>jde-expand-classpath-p</varname> off.
4402         The JDE expands directories whose names match the regular
4403         expressions specified by
4404         <varname>jde-lib-directory-names</varname>. The default values
4405         of this variable are <filename>^lib</filename> and
4406         <filename>^jar</filename>. So by default, the JDE expands
4407         names that begin with the string <filename>lib</filename> or
4408         <filename>lib</filename>, e.g., <filename>lib</filename>,
4409         <filename>libraries</filename>, etc. However, you can
4410         customize <varname>jde-lib-directory-names</varname> to
4411         reflect any library naming scheme you prefer.
4412       </para>
4413
4414     </sect3>
4415
4416
4417   </chapter>
4418
4419   <chapter>
4420
4421
4422       <title><anchor id="UsingProjectFiles"/>Using Project Files</title>
4423
4424     <para>A project file is a Lisp file that the JDEE loads and
4425       evaluates whenever you open a Java source file belonging to a
4426       specific project. The JDEE has commands that save the current
4427       settings of JDEE project variables in the project file for the
4428       current project. Project files thus allow you to save and
4429       restore project-specific settings of JDEE customization
4430       variables. For example, you can use a project file to set the
4431       value of the <varname>jde-global-classpath</varname> variable to
4432       a project-specific classpath automatically whenever you load a
4433       file belonging to that project. </para>
4434
4435     <sect3>
4436
4437
4438       <title><anchor id="FindingProjectFiles"/>How the JDE Finds Project Files</title>
4439
4440       <para>To simplify the task of finding project files, the JDE makes
4441         two assumptions. First, it assumes that all Java source files
4442         relating to a particular project live in a single directory tree.
4443         Second, it assumes that all project files have the same file name.
4444         The name assumed by default is <filename>prj.el</filename>. You can use the JDE
4445         configuration variable <varname>jde-project-file-name</varname> to specify
4446         another name.</para>
4447
4448       <para>
4449         When you open a Java source file, the JDE looks for
4450         project files in the directory tree containing the source file.
4451         If the JDE finds one or more project files, it loads the
4452         project files in the following manner.
4453       </para>
4454
4455       <para>
4456         The JDE  first sets all the JDE variables to their
4457         Emacs startup values (i.e., the default value or the value
4458         saved in your <filename>.emacs</filename> file). It then loads
4459         all the project files in the directory tree containing the
4460         current source buffer, starting with the topmost file.
4461       </para>
4462
4463       <para>
4464         What this means is that you can use project files to extend
4465         and/or override the settings in your
4466         <filename>.emacs</filename> file and in other project files.
4467         For example, your <filename>.emacs</filename> file can specify
4468         settings that are common to all your projects. You can put
4469         settings common to a group of projects at the top of the
4470         directory tree containing the projects, settings common to
4471         each project at the top of the directory containing each
4472         projects, and so on.
4473       </para>
4474
4475     </sect3>
4476
4477     <sect3>
4478
4479
4480       <title><anchor id="ProjectFileContents"/> Project File
4481         Contents</title>
4482
4483
4484       <para>A project file can contain any Lisp code that can be
4485         evaluated correctly as the last step in creating a Java source
4486         buffer. For example, a project file can contain code that sets
4487         the value of JDE configuration variables. In general, a
4488         project file can  contain any code that could be implemented
4489         as a <varname>jde-mode</varname> hook function. In fact, you
4490         can think of a project file as a project-specific
4491         <varname>jde-mode</varname> hook function. </para>
4492     </sect3>
4493
4494     <sect3>
4495
4496
4497       <title><anchor id="CreatingProjectFiles"/>Creating a Project
4498         File</title>
4499
4500       <para>The easiest way to create a project file is to use the
4501         <varname>jde-create-new-project </varname> command (<menuchoice>
4502           <guimenu>JDE</guimenu>
4503           <guisubmenu>Project</guisubmenu><guisubmenu>Project
4504             File</guisubmenu><guimenuitem>Create
4505             New</guimenuitem></menuchoice>). This command creates a
4506         new project file and saves the
4507         current values of all customized JDE configuration variables
4508         in the project file for the selected Java buffer. (To be
4509         precise,  the command inserts Lisp code in the project file
4510         that restores  the current settings of the configuration
4511         variables; if such code  already exists in the file, it
4512         replaces it with updated code.) Thus, to create
4513         a project file that sets JDE configuration  variables to
4514         project-specific values:
4515       </para>
4516
4517       <procedure>
4518         <step>
4519           <para>Open any source file belonging to the project.</para>
4520         </step>
4521         <step>
4522           <para>Set the values of the JDE configuration variables to
4523             the appropriate values for the project to which the source
4524             file belongs.</para>
4525         </step>
4526         <step>
4527           <para>See <ulink url="#ConfiguringJDE">Configuring the
4528               JDE</ulink>  for information on how to set the values of
4529             the JDE  configuration variables.</para>
4530         </step>
4531         <step>
4532           <para>Select <menuchoice>
4533               <guimenu>JDE</guimenu>
4534               <guisubmenu>Project</guisubmenu><guisubmenu>Project
4535                 File</guisubmenu><guimenuitem>Save
4536                 Project</guimenuitem></menuchoice>.
4537           </para>
4538         </step>
4539         <step performance="required">
4540           <para> The JDE prompts you to enter the path to a directory
4541             in which to store the project file.
4542           </para>
4543         </step>
4544         <step performance="required">
4545           <para>
4546             Enter the directory where you want to store the project
4547             file or press <keycap>Enter</keycap> to store the project
4548             file in the current directory.
4549           </para>
4550         </step>
4551       </procedure>
4552
4553       <para>Once you have created the project file, you can insert
4554         additional configuration code into the file if desired. Note
4555         that the <varname>jde-save-project</varname> command edits
4556         rather than replaces existing project files. Thus, you can use
4557         the command to update configuration variable settings without
4558         disturbing any other configuration code that you have inserted
4559         manually into the project file.
4560       </para>
4561     </sect3>
4562
4563     <sect3>
4564       <title><anchor id="CreatingPortableProjects"/>Creating Portable Projects</title>
4565       <para>
4566         You can use relative paths and environment variables to
4567         construct portable project files. For example, suppose your
4568         project directory has the following structure:
4569       </para>
4570       <para>
4571         <programlisting>
4572     myprj
4573       classes
4574         pkg1
4575         pkg2
4576       src
4577         pkg1
4578         pkg2
4579       prj.el
4580         </programlisting>
4581       </para>
4582       <para>
4583         Further suppose that your project uses beans  from a
4584         shared library specified by the environment variable
4585         <varname>BEANS</varname>. With this setup,
4586         you can specify <varname>jde-global-classpath</varname> as
4587       </para>
4588       <para>
4589         <programlisting>
4590       ./src
4591       ./classes
4592       $BEANS/lib/dials.jar
4593         </programlisting>
4594       </para>
4595       <para>
4596         and <varname>jde-compile-option-directory</varname> as
4597       </para>
4598       <para>
4599         <programlisting>
4600       ./classes
4601         </programlisting>
4602       </para>
4603       <para>
4604         This causes the JDE to store classes compiled from your src
4605         directory in the classes directory.  Note that you have not
4606         used any absolute paths in creating your project file. This
4607         means you can move your project anywhere without having to update
4608         the project file.
4609       </para>
4610
4611     </sect3>
4612
4613     <sect3>
4614       <title><anchor id="DisablingContextSwitching"/>Disabling Context Switching</title>
4615       <para>When you select a buffer that belongs to another
4616         project, the JDE loads the project file for that project
4617         and may update the class list for the project. This
4618         causes a slight delay before you can begin using the
4619         new buffer. The delay can be irritating if you need
4620         to switch frequently among open projects, for example,
4621         when copying or diffing code from different projects.
4622         Accordingly, the JDE provides ways for you to disable
4623         context-switching either permanently or  temporarily.
4624      </para>
4625
4626       <para>To disable context-switching permanently, toggle
4627         the customizat variable
4628         <varname>jde-project-context-switching-enabled-p</varname>
4629         off. Be sure to use customize to do this and save the
4630         customization in your <filename moreinfo="none">
4631           .emacs</filename> or <filename moreinfo="none">prj.el</filename>
4632         file. Note that you can use the JDE's project file loading
4633         command, <command>JDE->Project->Project File->Load</command>,
4634         to switch contexts manually.
4635       </para>
4636
4637       <para>
4638         To disable context-switching temporarily during a session,
4639         select <command>
4640         JDE->Project->Auto Switch</command> or enter
4641         <varname>M-x jde-toggle-project-context-switching</varname>. To reenable
4642         context-switching, execute the same command again.
4643       </para>
4644     </sect3>
4645
4646     <sect3>
4647       <title><anchor id="ProjectHooks"/>Project Hook Functions</title>
4648       <para>The variable <varname>jde-project-hooks</varname> lists
4649         functions that execute after the JDEE loads a project file. By
4650         writing hook functions and adding them to this list, you can
4651         specify actions to be taken every time the JDEE switches from
4652         one project to another.</para>
4653     </sect3>
4654
4655   </chapter>
4656
4657   <chapter>
4658
4659
4660       <title><anchor id="DisplayingDoc"/> Displaying Java Documentation</title>
4661
4662
4663     <para>
4664       The JDE provides commands for displaying the JDK API documentation
4665       and context-sensitive help for classes.
4666     </para>
4667
4668     <sect3>
4669
4670
4671       <title><anchor id="BrowsingJDKDoc"/> Browsing JDK
4672         Documentation</title>
4673
4674
4675       <para>The <varname>jde-browse-jdk-doc</varname> command
4676         (<menuchoice>
4677           <guimenu>JDE</guimenu><guimenuitem>Help</guimenuitem>
4678           <guimenuitem>JDK</guimenuitem></menuchoice>, <keycombo>
4679           <keycap>C</keycap><keycap>c</keycap></keycombo>&nbsp;
4680         <keycombo>
4681           <keycap>C</keycap><keycap>v</keycap></keycombo>&nbsp;<keycombo>
4682           <keycap>C</keycap><keycap>n</keycap></keycombo>) opens the
4683         JDK documentation in a browser. By default, this command
4684         displays the JDK documentation page at JavaSoft's web site. To
4685         display a different copy, set the variable
4686         <varname>jde-jdk-doc-url</varname> to the url of the index
4687         page of the copy you want to be displayed. </para>
4688     </sect3>
4689
4690     <sect3>
4691
4692
4693       <title><anchor id="ClassHelp"/> Context-Sensitive Class
4694         Help</title>
4695
4696
4697       <para>The JDK provides context-sensitive help for Java classes.
4698         To use this facility, you must first customize the variable
4699         <varname>jde-help-docsets</varname> to specify the location of
4700         class documentation on your system. The JDE class help
4701         facility supports javadoc documentation by default but it
4702         works with other types of documentation as well.</para>
4703
4704       <para>Once you have specified the location of class
4705         documentation on your system, you can get help for the class
4706         at point in the current buffer by selecting <menuchoice>
4707           <guimenu>JDE</guimenu><guisubmenu>Help</guisubmenu><guimenuitem>Symbol
4708             at Point</guimenuitem></menuchoice> . </para>
4709     </sect3>
4710
4711     <sect3>
4712       <title><anchor id="Specifying a Browser"/>Specifying a Browser</title>
4713       <para>The JDEE uses the browsers or browsers specified by the customization
4714         variable <varname>browse-url-browser-function</varname>. See the documentation
4715       for this variable for more information.</para>
4716
4717       <sect4>
4718         <title><anchor id="UsingEmacs-w3m"/>Using emacs-w3m to Browse Java Doc</title>
4719         <para>The <filename>emacs-w3m</filename> package uses the
4720           <filename>w3m</filename> text-mode HTML browser to enable
4721           Emacs to render text HTML pages. This allows you to use
4722           Emacs not only to develop Java code but also to browse Java
4723           API and tools documentation. For information on downloading
4724           and installing emacs-w3m and w3m, see the <ulink
4725             url="http://emacs-w3m.namazu.org/">emacs-w3m</ulink> web
4726           site. </para>
4727
4728         <para>While you're at it, you should also install the <ulink
4729             url="http://www.emacswiki.org/cgi-bin/wiki/WThreeM">
4730             WThreeM</ulink> package. This package provides
4731         incremental searching on URLs in w3m HTML buffers, a nice feature
4732         for browsing Javadoc class documentation, with its wealth of
4733         links.</para>
4734
4735         <para>One you have installed <filename>emacs-w3m/w3m</filename>, you can
4736         configure Emacs (and hence the JDEE) to use it to display Javadoc pages
4737           by customizing <varname>jde-help-browser-function</varname> to specify
4738           <filename>w3m-browse-url</filename>. </para>
4739
4740
4741         <para>The <filename>w3m-browse-url</filename> function displays its output
4742         by default in the current window, replacing the Java file in the buffer.
4743         To cause the function to display its output in a popup window, customize
4744           <varname>w3m-pop-up-frames</varname>.</para>
4745
4746       </sect4>
4747     </sect3>
4748
4749   </chapter>
4750
4751   <chapter>
4752
4753       <title><anchor id="BrowsingSourceCode"/>Browsing Source Code</title>
4754
4755     <para>The JDE provides the following facilities for browsing Java source code:</para>
4756
4757     <itemizedlist>
4758       <listitem>
4759         <para><ulink url="#ClassesMenu">Classes index menu</ulink></para>
4760       </listitem>
4761       <listitem>
4762         <para><ulink url="#Speedbar">Speedbar</ulink></para></listitem>
4763       <listitem>
4764         <para><ulink url="#Tags">Etags</ulink></para></listitem>
4765     </itemizedlist>
4766
4767
4768     <sect3>
4769
4770
4771       <title><anchor id="ClassesMenu"/> Classes Index Menu</title>
4772
4773
4774       <para>The <menuchoice><guimenu>Classes</guimenu></menuchoice>
4775         index menu appears by default in the Emacs menubar whenever a
4776         Java source buffer is active. The menu consists of a cascading
4777         list of all classes, methods, fields, and imports defined in
4778         the current buffer plus the package to which the current
4779         buffer belongs. Selecting any item scrolls the buffer to the
4780         statement that defines the item.</para>
4781
4782       <para><screenshot>
4783           <mediaobject>
4784             <imageobject>
4785               <imagedata fileref="images/classes_menu1.gif"/>
4786             </imageobject>
4787             <textobject>
4788               <phrase>Screenshot showing Classes menu.</phrase>
4789             </textobject>
4790           </mediaobject>
4791         </screenshot>
4792       </para>
4793       <para>The top-level menu contains an entry for each each class
4794         defined by the active buffer followed by entries for the
4795         imports and package of the current buffer. Selecting the entry
4796         for a class displays a submenu listing the inner classes,
4797         methods, and fields defined by the class. Selecting the entry
4798         for an inner class displays another submenu for that class,
4799         and so on. Selecting the
4800         <menuchoice><guimenu>imports</guimenu></menuchoice> entry on
4801         the top-level menu displays a submenu listing all the classes
4802         and packages imported by the active buffer.</para>
4803
4804       <sect4>
4805
4806
4807         <title><anchor id="SpecialIndexEntries"/> Special Index
4808           Entries</title>
4809
4810         <para>The index menu includes the following special index
4811           entries:</para>
4812
4813         <itemizedlist>
4814
4815           <listitem>
4816             <para><menuchoice><guimenu>*Rescan*</guimenu></menuchoice></para>
4817             <para>Selecting this item causes the JDE to rebuild the
4818               index menu.  You should rebuild the menu whenever you
4819               edit the buffer.
4820             </para>
4821           </listitem>
4822
4823           <listitem>
4824             <para><menuchoice><guimenu>*class
4825                   def*</guimenu></menuchoice></para>
4826             <para>Selecting this item takes you to the start of the
4827               definition of  the class on whose submenu it appears.
4828               Turn the variable
4829               <varname>jde-imenu-include-classdef</varname> off to
4830               suppress inclusion  of these items in the menu. </para>
4831           </listitem>
4832
4833         </itemizedlist>
4834       </sect4>
4835
4836       <sect4>
4837
4838
4839         <title><anchor id="AlphabetClassesMenu"/>Alphabetizing the
4840           Classes Menu</title>
4841
4842         <para>By default the
4843           <menuchoice><guimenu>Classes</guimenu></menuchoice> menu
4844           lists methods and fields in the order in which the active
4845           buffer defines them. Use the variable
4846           <varname>jde-imenu-sort</varname> to customize the menu to
4847           list methods and fields alphabetically in either ascending
4848           or descending order.</para>
4849       </sect4>
4850
4851       <sect4>
4852
4853
4854         <title><anchor id="SuppressingSignatures"/>Suppressing Method
4855           Signatures and Field Types</title>
4856
4857         <para>By default the
4858           <menuchoice><guimenu>Classes</guimenu></menuchoice> menu
4859           displays the signatures of methods and the types of fields
4860           displayed in the active buffer. The method signatures enable
4861           you to distinguish overloaded method names. The menu can
4862           also display the names of methods and fields without
4863           signatures and types. Use the variable
4864           <varname>jde-imenu-include-signature</varname> to turn
4865           signature and type display off or on. </para>
4866       </sect4>
4867
4868       <sect4>
4869
4870         <title><anchor id="DisablingClassesMenu"/>Disabling the
4871           Classes Menu</title>
4872
4873
4874         <para>Set the variable <varname>jde-imenu-enable</varname> off
4875           to disable the
4876           <menuchoice><guimenu>Classes</guimenu></menuchoice> menu.
4877           When disabled, the menu does not appear in the Emacs
4878           menubar.</para>
4879       </sect4>
4880
4881       <sect4>
4882         <title>Using the Keyboard to Navigate the Classes Menu</title>
4883         <para>
4884           Execute <command>M-x imenu</command> to use the keyboard
4885           to navigate the Classes menu. Emacs displays the
4886           top-level items on the Classes menu in a buffer and
4887           prompts you to enter the name of an an item in the
4888           minibuffer. Enter the name of the item to select it.
4889           Note that you can use completion to avoid having to
4890           type the whole name. If you select a submenu, Emacs
4891           displays the contents of the submenu and prompts
4892           you to enter a selection in the keyboard. If you
4893           select an index entry, Emacs scrolls the buffer
4894           to the indexed point in the buffer.
4895         </para>
4896       </sect4>
4897
4898     </sect3>
4899
4900     <sect3>
4901
4902
4903         <title><anchor id="Speedbar"/>Using the Speedbar</title>
4904
4905       <para>To display the speedbar, select <menuchoice>
4906           <guimenu>JDE</guimenu>
4907           <guimenuitem>Browse</guimenuitem>
4908           <guimenuitem>Source Files</guimenuitem></menuchoice>. The
4909         speedbar opens in a separate frame.</para>
4910
4911       <para><screenshot>
4912           <mediaobject>
4913             <imageobject>
4914               <imagedata fileref="images/speedbar1.gif"/>
4915             </imageobject>
4916             <textobject>
4917               <phrase>Screenshot showing the speedbar.</phrase>
4918             </textobject>
4919           </mediaobject>
4920         </screenshot>
4921       </para>
4922
4923       <para>The speedbar displays a list of the files and
4924         subdirectories in the directory containing the file displayed
4925         in the current buffer. The speedbar highlights the file
4926         displayed in the current buffer.</para>
4927
4928       <para>Click on the expand (+) button in front of any file. The
4929         node for the  file expands</para>
4930
4931        <para>
4932         <screenshot>
4933           <mediaobject>
4934             <imageobject>
4935               <imagedata fileref="images/speedbar2.gif"/>
4936             </imageobject>
4937             <textobject>
4938               <phrase>Screenshot showing a speedbar entry.</phrase>
4939             </textobject>
4940           </mediaobject>
4941         </screenshot>
4942       </para>
4943
4944       <para>to show up to three entries, depending on the contents of
4945         the source file. </para>
4946
4947       <sect4>
4948
4949         <title><anchor id="Package"/>Package</title>
4950
4951         <para>
4952           This item expands to show the package to which the file
4953           belongs.
4954         </para>
4955
4956         <para><screenshot>
4957             <mediaobject>
4958               <imageobject>
4959                 <imagedata fileref="images/speedbar3.gif"/>
4960               </imageobject>
4961               <textobject>
4962                 <phrase>Screenshot showing a speedbar entry.</phrase>
4963               </textobject>
4964             </mediaobject>
4965           </screenshot>
4966         </para>
4967
4968         <para>
4969           Clicking on the package scrolls the buffer to the
4970           corresponding package declaration.
4971         </para>
4972       </sect4>
4973
4974       <sect4>
4975
4976
4977         <title><anchor id="Types"/>Types</title>
4978
4979         <para>
4980           This item expands to show the classes in the selected file.
4981         </para>
4982
4983         <para><screenshot>
4984             <mediaobject>
4985               <imageobject>
4986                 <imagedata fileref="images/speedbar4.gif"/>
4987               </imageobject>
4988               <textobject>
4989                 <phrase>Screenshot showing a speedbar entry.</phrase>
4990               </textobject>
4991             </mediaobject>
4992           </screenshot>
4993         </para>
4994
4995         <para>
4996           Each class expands to show the constructors, methods,
4997           fields, and inner classes defined by the class and the
4998           class's parent, if any. Inner classes also expand and their
4999           inner classes, and so on. The constructors and methods
5000           expand to show arguments and argument types and return
5001           types. Fields expand to show their type.
5002         </para>
5003
5004         <para>
5005           Clicking on any class, inner class, method, constructor, or
5006           field scrolls the buffer to show that item.
5007         </para>
5008       </sect4>
5009
5010       <sect4>
5011
5012
5013         <title><anchor id="Dependencies"/>Dependencies</title>
5014
5015         This item expands to show the classes and packages imported by the current source file.
5016
5017         <para><screenshot>
5018             <mediaobject>
5019               <imageobject>
5020                 <imagedata fileref="images/speedbar5.gif"/>
5021               </imageobject>
5022               <textobject>
5023                 <phrase>Screenshot showing a speedbar entry.</phrase>
5024               </textobject>
5025             </mediaobject>
5026           </screenshot>
5027         </para>
5028
5029         <para>Click on class or package to scroll the buffer to the
5030           corresponding import statement.</para>
5031       </sect4>
5032
5033       <sect4>
5034
5035
5036         <title><anchor id="UpdatingSpeedbar"/>Updating the
5037           Speedbar</title>
5038
5039         <para>If you make changes to a source buffer, you must update
5040           the speedbar view to reflect the changes. To update the
5041           speedbar view of a buffer:</para>
5042
5043         <procedure>
5044           <step>
5045             <para>
5046               Collapse the speedbar view of the buffer.
5047             </para>
5048             <para>
5049               This is necessary only if the speedbar view is expanded.
5050               To collapse the speedbar view, click the collapse button
5051               (-) next to the buffer's file name in the speedbar view.
5052             </para>
5053           </step>
5054           <step>
5055             <para>Hold the shift key down while clicking the expand
5056               button (+) next to the buffer's name  in the speedbar
5057               view.  </para>
5058           </step>
5059         </procedure>
5060       </sect4>
5061     </sect3>
5062
5063   </chapter>
5064
5065   <chapter>
5066     <title><anchor id="SearchSource"/>Searching Source Code</title>
5067
5068     <para>The JDEE provides commands that enable you to find</para>
5069
5070     <itemizedlist>
5071       <listitem>
5072         <para>
5073           All occurences of strings matching a regular expression anywhere
5074           in your project's source path (see <ulink url="#FindExpressions">Finding
5075           Expressions</ulink>)
5076         </para>
5077       </listitem>
5078       <listitem>
5079         <para>
5080           Source code that defines the method, field,
5081           or other symbol at point (see <ulink url="#FindSymbolDef">Finding
5082           Symbol Definitions</ulink>)
5083         </para>
5084       </listitem>
5085       <listitem>
5086         <para>Source code for the class at point (see <ulink url="#FindClasses">Finding
5087           Classes</ulink>)</para>
5088       </listitem>
5089       <listitem>
5090         <para>Source for the parent of the class at point</para>
5091       </listitem>
5092       <listitem>
5093         <para>Source for an interface implemented by the class at point</para>
5094       </listitem>
5095       <listitem>
5096         <para>All methods that invoke a specifed method (see <ulink url="#Xref">Cross-Referencing
5097             Classes</ulink>)</para>
5098       </listitem>
5099     </itemizedlist>
5100
5101     <sect3>
5102       <title><anchor id="FindExpressions"/>Finding Expressions</title>
5103       <para>The JDEE provides two commands for finding occurrences of strings
5104       in Java source and other types of text files:</para>
5105
5106       <itemizedlist>
5107         <listitem>
5108           <para><command>JDE->Find->Expression</command>
5109             (<function>jde-find</function>)</para>
5110           <para>
5111             This command uses the minibuffer to prompt you for the
5112             search expression and the paths to be searched. You can
5113             use customization variables to specify values for the
5114             search paths and other search options. The default values
5115             for the customization variables search the Java source
5116             files on the classpaths and sourcepaths for your project.
5117             See <ulink url="#FindExpressionMinibuf">Using the Minibuffer-Based
5118             Find Command</ulink> for more information.
5119           </para>
5120         </listitem>
5121         <listitem>
5122           <para><command>JDE->Find->Expression...</command>
5123             (<function>jde-find-dlg</function>)</para>
5124           <para>This command uses a text dialog buffer to
5125             prompt you for search arguments. The dialog buffer
5126             allows you to specify all search options
5127             interactively. It is thus useful for performing
5128             searches that have special requirements.
5129             See <ulink url="#FindExpressionDlg">Using the Dialog-Based
5130             Find Command</ulink> for more information. </para>
5131         </listitem>
5132       </itemizedlist>
5133
5134       <para>
5135         Both commands use the Unix <command>grep</command> and
5136         <command>find</command> utilities to perform the searches that
5137         you specify. Before executing a search, both commands search
5138         your system for copies of <command>grep</command> and
5139         <command>find</command> and signal an error if the utilities
5140         are missing. All Unix systems include copies of
5141         <command>grep</command> and <command>find</command>. Versions
5142         of these utilities are available for Microsoft Windows, e.g.,
5143         as part of the Cygwin Unix emulation package for Microsoft
5144         Windows. If you want to use the JDEE's <command>find</command>
5145         commands on Windows, you must install copies of
5146         <command>grep</command> and <command>find</command> on your
5147         system and either include them in your system's command path
5148         or use the variables <varname>grep-command</varname> and
5149         <varname>find-program</varname> to specify their respective
5150         locations on your system.
5151       </para>
5152
5153       <note>
5154         <para>
5155           Microsoft Windows/NT and Windows 2000 provide a
5156           <command>find</command> utility that is incompatible with
5157           the Unix <command>find</command> utility. To ensure that the
5158           JDEE finds the right version, you should either put the
5159           Unix-style <command>find</command> command ahead of the
5160           Windows <command>find</command> command in your system
5161           command path or use the <varname>find-program</varname>
5162           variable to specify the Unix-style command's location.
5163         </para>
5164       </note>
5165
5166       <sect4>
5167         <title><anchor id="FindExpressionMinibuf"/>Using the
5168           Minibuffer-Based Find (jde-find) Command</title>
5169
5170         <para>To find an expression with the minibuffer-based find
5171           command:</para>
5172
5173         <orderedlist>
5174           <listitem>
5175             <para>
5176               Select
5177               <menuchoice>
5178                 <shortcut>
5179                   <keycombo>
5180                     <keysym>C-c</keysym>
5181                     <keysym>C-v</keysym>
5182                     <keysym>C-f</keysym>
5183                   </keycombo>
5184                 </shortcut>
5185                 <guimenu>Find</guimenu>
5186                 <guimenuitem>Expression</guimenuitem>
5187               </menuchoice>
5188               from the <guimenu>JDE</guimenu> menu
5189               or execute the <command>jde-find</command> command.
5190             </para>
5191             <para>The JDEE prompts you to enter a regular expression.</para>
5192             <screenshot>
5193               <mediaobject>
5194                 <imageobject>
5195                   <imagedata fileref="images/find_minibuf_prompt_regex.gif"/>
5196                 </imageobject>
5197                 <textobject>
5198                   <phrase>Screenshot showing the regular expression prompt.</phrase>
5199                 </textobject>
5200               </mediaobject>
5201             </screenshot>
5202           </listitem>
5203           <listitem>
5204             <para>Enter a regular expression that matches the
5205               expressions you want to find and press <keycap>Enter</keycap>.</para>
5206             <para>The JDEE prompts you to enter a list of directories to search.</para>
5207             <screenshot>
5208               <mediaobject>
5209                 <imageobject>
5210                   <imagedata fileref="images/find_minibuf_prompt_dirs.gif"/>
5211                 </imageobject>
5212                 <textobject>
5213                   <phrase>Screenshot showing the directories prompt.</phrase>
5214                 </textobject>
5215               </mediaobject>
5216             </screenshot>
5217             <para>The prompt may list a default search path. The JDEE determines the
5218               default path by testing each of the following variables in the order
5219               listed.</para>
5220             <itemizedlist>
5221               <listitem>
5222                 <para><varname>jde-sourcepath</varname></para>
5223               </listitem>
5224               <listitem>
5225                 <para><varname>jde-compile-option-sourcepath</varname></para>
5226               </listitem>
5227               <listitem>
5228                 <para><varname>jde-compile-option-classpath</varname></para>
5229               </listitem>
5230               <listitem>
5231                 <para><varname>jde-global-classpath</varname></para>
5232               </listitem>
5233             </itemizedlist>
5234             <para>The JDEE uses the directories
5235               specified by the first path variable that has a nonnil
5236               value as the default search path.</para>
5237           </listitem>
5238           <listitem>
5239             <para>Edit the default search path, if desired, in the minibuffer
5240               and press <keycap>Enter</keycap>.</para>
5241             <para>The JDEE executes the find command that you have specified
5242             and displays the command's output in a popup grep-mode buffer.</para>
5243             <screenshot>
5244               <mediaobject>
5245                 <imageobject>
5246                   <imagedata fileref="images/find_minibuf_result.gif"/>
5247                 </imageobject>
5248                 <textobject>
5249                   <phrase>Screenshot showing the search results.</phrase>
5250                 </textobject>
5251               </mediaobject>
5252             </screenshot>
5253           </listitem>
5254         </orderedlist>
5255
5256         <para>The search results buffer lists each instance of a string
5257         that matches the specified regular expression in the specified
5258         search path. For each match, the listing shows the file
5259         and line number of the match, highlighted in red, and a snippet
5260         of the text in which the match occurred.
5261         </para>
5262         <para>To visit the file containing the match, click the
5263         match message in the grep buffer with the middle mouse button
5264         or move point to the message and press <keycap>Enter</keycap></para>
5265       </sect4>
5266
5267       <sect4>
5268         <title><anchor id="FindExpressionCustomize"/>Customizing the
5269           Minibuffer-Based Find Command</title>
5270         <para>
5271           The following variables allow you to customize the
5272           minibuffer-based search command:
5273         </para>
5274
5275         <table>
5276           <tgroup cols="3">
5277             <thead>
5278               <row>
5279                 <entry>Variable</entry>
5280                 <entry>Default Value</entry>
5281                 <entry>Description</entry>
5282               </row>
5283             </thead>
5284             <tbody>
5285               <row>
5286                 <entry><varname>jde-find-case-sensitive</varname></entry>
5287                 <entry><literal>nil</literal></entry>
5288                 <entry>Specifies whether the <command>jde-find</command> command
5289                   performs a case-sensitive search. If non-nil, the
5290                   search is case-sensitive; otherwise the search
5291                   ignores case.</entry>
5292               </row>
5293               <row>
5294                 <entry><varname>jde-find-granularity</varname></entry>
5295                 <entry><literal>Character</literal></entry>
5296                 <entry>Specifies the granularity of the expression
5297                   search conducted by <command>jde-find</command>: <literal>Character</literal>
5298                   (expression starting on any character), <literal>Word</literal> (match
5299                   words only), <literal>Line</literal> (match lines only).</entry>
5300               </row>
5301               <row>
5302                 <entry><varname>jde-find-file-regexp</varname></entry>
5303                 <entry><literal>*.java</literal></entry>
5304                 <entry>Specifies the regular expression that the
5305                   <command>jde-find</command> command uses to select
5306                   files to be searched. You can use any regular
5307                   expression supported by the <literal>-name</literal>
5308                   option of the GNU <command>find</command>
5309                   command.</entry>
5310               </row>
5311             </tbody>
5312           </tgroup>
5313         </table>
5314       </sect4>
5315
5316       <sect4>
5317         <title><anchor id="FindExpressionDlg"/>Using the Dialog-Based Find (jde-find-dlg) Command</title>
5318
5319         <para>To find an expression with the dialog-based find command:</para>
5320
5321         <orderedlist>
5322           <listitem>
5323             <para>
5324               Select
5325               <menuchoice>
5326                 <guimenu>Find</guimenu>
5327                 <guimenuitem>Expression...</guimenuitem>
5328               </menuchoice>
5329               from the <guimenu>JDE</guimenu> menu
5330               or execute the <command>jde-find</command> command.
5331             </para>
5332
5333             <para>The <guilabel>Find Expression Options</guilabel> buffer appears.</para>
5334
5335             <screenshot>
5336               <mediaobject>
5337                 <imageobject>
5338                   <imagedata fileref="images/find_options_buffer.gif"/>
5339                 </imageobject>
5340                 <textobject>
5341                   <phrase>Screenshot showing the Find Expression Options buffer.</phrase>
5342                 </textobject>
5343               </mediaobject>
5344             </screenshot>
5345
5346           </listitem>
5347           <listitem>
5348             <para>Edit the buffer to reflect the search options that you desire.</para>
5349             <note>
5350               <para>The options you select will appear the
5351                 next time you execute the <command>jde-find-dlg</command> command.</para>
5352             </note>
5353           </listitem>
5354           <listitem>
5355             <para>Select the <guibutton>Ok</guibutton> button.</para>
5356           </listitem>
5357         </orderedlist>
5358
5359         <para>The <command>jde-find-dlg</command> invokes the
5360           <command>find</command> and <command>grep</command> commands
5361           with the options you specified and displays the results in a
5362           buffer.
5363         </para>
5364       </sect4>
5365
5366     </sect3>
5367
5368     <sect3>
5369       <title><anchor id="FindSymbolDef"/>Finding Symbol Definitions</title>
5370       <para>To find the source code that defines the class, interface,
5371         method, or field at point, select
5372         <menuchoice>
5373           <shortcut>
5374             <keycombo><keysym>C</keysym><keysym>c</keysym></keycombo>&nbsp;
5375             <keycombo><keysym>C</keysym>
5376               <keysym>v</keysym></keycombo>&nbsp;
5377             <keycombo><keysym>C</keysym><keysym>y</keysym></keycombo>
5378           </shortcut>
5379           <guimenu>Find</guimenu>
5380           <guimenuitem>Symbol Definition</guimenuitem>
5381               </menuchoice> from the <guimenu>JDE</guimenu> menu or
5382         execute <keycombo>
5383           <keysym>M</keysym><keysym>x</keysym></keycombo>
5384         <function>jde-open-class-at-point</function>. The JDEE
5385         displays a buffer containing the source code that defines the
5386         symbol at point in the original buffer.</para>
5387
5388       <note>
5389         <para>This command requires that the symbol definition be
5390           located on <varname>jde-sourcepath</varname> and that the
5391           class referenced at point be located on
5392           <varname>jde-global-classpath</varname>. The command uses
5393           the beanshell to determine the fully qualified name of the
5394           class referenced at point. If the beanshell is not running,
5395           it launches the beanshell.</para>
5396       </note>
5397     </sect3>
5398
5399
5400     <sect3>
5401
5402
5403       <title><anchor id="FindClasses"/>Finding Classes</title>
5404
5405       <para>The <function>jde-open-class-source</function> command
5406         finds and opens the Java source file for the class whose
5407         qualified or unqualified name appears at point.</para>
5408
5409       <note>
5410         <para>The JDE uses Java reflection to determine the fully
5411           qualified name of the class at point. Therefore, the class
5412           must be on <varname>jde-global-classpath</varname>.</para>
5413       </note>
5414
5415       <para>If more than one class with the same name exists on
5416         <varname>jde-global-classpath</varname>, this command prompts
5417         you to select one of the classes. The following conditions
5418         must be true for this command to work. First, a class file for
5419         this class must exist on the classpath specified by
5420         <varname>jde-global-classpath</varname>. Secondly, the source
5421         for the class must exist on one of the paths specified by
5422         <varname>jde-sourcepath</varname>. This command uses the
5423         Beanshell to determine the fully qualified name of the class
5424         to be found. It starts the Beanshell if necessary. Thus, the
5425         command may respond somewhat slowly the first time you it in a
5426         session. </para>
5427
5428     </sect3>
5429
5430
5431     <sect3>
5432       <title><anchor id="Xref"/>Cross-Referencing Classes</title>
5433
5434
5435       <para>JDE includes a facility for creating and utilizing a
5436         cross-referencing database to enable you to quickly locate all
5437         the callers of any particular function.  This functionality is
5438         very useful for quickly figuring how unfamiliar code works,
5439         and useful for doing certain tasks such as renaming functions.
5440         Be advised that this only finds direct callers, and cannot
5441         detect calls via Java's reflection mechanism.  The
5442         cross-reference database must be kept in sync with the project
5443         code, however the database generation is generally quick. The
5444         remainder of this section explains how to configure and use
5445         the cross-referencer.</para>
5446
5447       <note>The JDEE's cross-referencing facility was developed by Andrew Hyatt.</note>
5448
5449
5450       <sect4>
5451         <title><anchor id="ConfigXRef"/>Configuring the Cross-Referencer</title>
5452
5453         <para>JDE's cross-referencing database is built by examining
5454           class files for a particular project.  To this end, JDE
5455           needs to know where the built class files for a project
5456           live.  This is usually a subset of the classpath.
5457         </para>
5458
5459         <para>Then select JDE->Options->Project->General, and go to
5460           the "Jde Built Class Path" option.  Insert one path for each
5461           place where built classes wind up.  You can add both
5462           directories and zip files (jar/bar/etc).  Any file entered
5463           will be assumed to be a zip file.</para>
5464
5465         <para>Now that you have the built class path defined, you can
5466           configure the cross-referencer that uses it.  Type M-x
5467           jde-xref-customize. The following are a list the variables
5468           that can be set, and what they do:
5469         </para>
5470
5471         <itemizedlist>
5472           <listitem>
5473             <para><varname>jde-xref-db-base-directory</varname></para>
5474
5475             <para>The cross-referencer creates a database to
5476               store the cross-reference information. This variable
5477               defines a directory where that information resides. It
5478               might, for example, be at the base of your project tree,
5479               in a directory called xrefdb
5480             </para>
5481           </listitem>
5482
5483           <listitem>
5484             <para><varname>jde-xref-store-prefixes</varname></para>
5485
5486             <para>To reduce database size,
5487               it's useful to ignore all information that doesn't refer
5488               to code you care about. For example, most people don't
5489               need to know who calls java.lang.System.out.println.  To
5490               not store this information, insert a package prefix for
5491               each package you are interested in. Typically, this may
5492               be just one string, for example "com.mycompany", to
5493               store only code that references com.mycompany
5494               classes.</para>
5495           </listitem>
5496
5497           <listitem>
5498             <para><varname>jde-xref-cache-size</varname></para>
5499             <para>The caller database can be quite large. However, it
5500               is useful for efficiency reasons to keep part of it in
5501               memory. This variable deterines how many packages to
5502               keep in memory simulatenously. The higher this is, the
5503               faster things will be, but also the more memory will be
5504               taken up by the cross-reference information.
5505             </para>
5506           </listitem>
5507
5508         </itemizedlist>
5509       </sect4>
5510
5511       <sect4>
5512
5513         <title><anchor id="BuildingXRefDB"/>Building the Cross-Reference Database</title>
5514
5515
5516         <para>The next step into getting the cross-reference
5517           functionality working is to build the cross-reference
5518           database.  The project must be fully built for this to work,
5519           since it takes cross-reference information directly from the
5520           built classes.
5521         </para>
5522
5523         <para>To build the database, type <command>M-x jde-xref-make-xref-db</command></para>
5524
5525         <para>If all the settings are properly configured, JDE will go
5526           off and create the cross-reference database.  This can take
5527           from a few seconds to several minutes depending on the size
5528           of your project. Large class files may take long to parse,
5529           so if it seems to be "stuck", please give it time.
5530         </para>
5531
5532         <para>When it is done, it will save the database in the base
5533           directory specified in the jde-xref customization group.
5534         </para>
5535
5536       </sect4>
5537
5538       <sect4>
5539
5540         <title><anchor id="UsingXRefDB"/>Using the Cross-Reference Database</title>
5541
5542
5543         <para>There are several basic operations that use the
5544           cross-reference database:
5545         </para>
5546
5547
5548         <itemizedlist>
5549
5550           <listitem>
5551
5552             <para><command>M-x jde-xref-first-caller (C-c C-v a)</command>
5553             </para>
5554
5555             <para> If your cursor is in the body of a function, then
5556               this will go to the first in a sequence of callers to
5557               this function.  If there are no callers, there will be a
5558               message saying so.
5559             </para>
5560
5561           </listitem>
5562
5563
5564           <listitem>
5565             <para><command>M-x jde-xref-next-caller (C-c C-v n)</command></para>
5566
5567             <para> After calling <command>jde-xref-first-caller</command>, you can go to
5568               each of the callers in sequence with this function.  The
5569               first caller function creates a list of callers and goes
5570               to the first one.  This navigates to the next caller on
5571               the list.  You can keep calling this until there are no
5572               more callers, in which case there will be a message
5573               saying so.
5574             </para>
5575           </listitem>
5576
5577           <listitem>
5578             <para><command>M-x jde-xref-display-call-tree</command>
5579             </para>
5580
5581             <para>This displays an interactive tree view of the
5582               function you are in, and it's callers.  Each level down
5583               will show you who calls the parent function.  In this
5584               way you can quickly get an overview of the context in
5585               which the current function is used in.  Each item in the
5586               tree will take you to it's definition if it is clicked
5587               on.
5588             </para></listitem>
5589
5590           <listitem>
5591
5592             <para><command>M-x jde-xref-list-uncalled-functions</command></para>
5593
5594             <para> Called from a java file, this lists all the
5595               functions in the file that have no apparent callers.
5596               It's important to remember that because of Java
5597               reflection, there is no guarantee that the functions are
5598               truly uncalled.  It only means they are not called
5599               directly.
5600             </para>
5601           </listitem>
5602
5603         </itemizedlist>
5604
5605         <para>All of these functions have two modes, a strict and
5606           non-strict mode. In non-strict mode, the default, more
5607           potential callers are treated as callers, including those
5608           that call an interface that the function implements, or who
5609           call a superclass's function you are overriding. For
5610           example, if you are in Foo.doSomething(), and foo implements
5611           IFoo, and a caller calls IFoo.doSomething(), then this is
5612           treated as a caller in non-strict mode.  Also, if you are in
5613           Foo.doSomething, and Foo's superclass is Bar, and there is a
5614           Bar.doSomething(), then Bar.doSomething() is treated as a
5615           caller in non-strict mode.  In strict mode, however, the
5616           caller must specify the function directly for it to be
5617           considered a hit.   To run these functions with strict mode,
5618           type C-u M-x and then the function-name.  So C-u M-x
5619           jde-xref-list-uncalled-functions will list only functions
5620           that are uncalled directly.
5621         </para>
5622
5623       </sect4>
5624
5625
5626       <sect4>
5627
5628         <title><anchor id="UpdatingXRefDB"/>Updating the Cross-Reference Database</title>
5629
5630
5631         <para>As the code changes, the cross-referencer must be kept
5632           up to date, or else the jde-xref functions will start taking
5633           you to incorrect places in files, and the callers list
5634           itself will become incorrect.  As you change the code, you
5635           can call M-x jde-xref-update after a recompile, and it will
5636           go through and recompute just the part of the database you
5637           have changed.
5638         </para>
5639
5640         <para>Another, easier way to update, for those of us who leave
5641           their emacs running all the time, is to add a line such as
5642           this in their .emacs
5643         </para>
5644
5645         <programlisting>
5646           (run-at-time "11:00pm" 86400 'jde-xref-make-xref-db)
5647         </programlisting>
5648
5649       </sect4>
5650
5651
5652     </sect3>
5653
5654
5655     <sect3>
5656
5657
5658       <title><anchor id="Tags"/>Tags</title>
5659
5660       <para>To use the <varname>etags</varname> facility, you must
5661         first construct a  TAGS file that indexes every symbol in your
5662         source code. The JDE  package contains two shell scripts that
5663         you can use to tag your  source code, one for
5664         <command>csh</command> shells and the other for
5665         <command>bash</command>.  The <command>bash</command> version
5666         is called <command>jtags</command>; the <command>csh</command>
5667         version, <command>jtags.csh</command>. </para>
5668
5669       <sect4>
5670
5671
5672           <title><anchor id="TaggingCode"/> Tagging Java Source Code</title>
5673
5674
5675
5676         <para>To tag your source code, first copy the appropriate shell
5677           script to a directory in your Emacs path. Then start a shell (<keycombo>
5678             <keycap>M</keycap><keycap>x</keycap> </keycombo>&nbsp;
5679           shell). Change to the top-level directory containing your
5680           source code and then enter <command>jtags</command>. The <command>jtags</command>
5681           script tags every <filename>.java</filename> file in the current directory
5682           and in all descendants of the current directory, storing the
5683           result in a file called <filename>TAGS</filename> in the top-level directory.
5684         </para>
5685       </sect4>
5686
5687       <sect4>
5688
5689
5690           <title><anchor id="FindingSymbols"/>Finding the Definition of a Symbol</title>
5691
5692
5693         <para>To find the definition of a symbol, put your cursor anywhere
5694           in the symbol and enter
5695           <keycombo><keycap>M</keycap><keycap>.</keycap></keycombo>. Emacs
5696           responds by locating
5697           and opening (if necessary) the file containing the definition and
5698           positioning the point at the definition. (The first time you type
5699           <keycombo><keycap>M</keycap><keycap>.</keycap></keycombo>, Emacs
5700           prompts you to load the <filename>TAGS</filename> file.) </para>
5701       </sect4>
5702
5703     </sect3>
5704
5705   </chapter>
5706
5707   <chapter>
5708
5709
5710       <title><anchor id="CustomizingJDE"/>Customizing the JDE</title>
5711
5712
5713     <para>
5714       This section describes various ways you can customize the JDE.
5715     </para>
5716
5717     <sect3>
5718
5719
5720         <title><anchor id="CustomizationVariables"/>Customization Variables</title>
5721
5722       <para>
5723         JDE customization variables allow you to specify compile, run, debug,
5724         and other JDE options. </para>
5725
5726       <note>
5727         <para> The traditional way of customizing Emacs is to use
5728           <varname>setq</varname> forms to set the values of customization
5729           variables in the Emacs initialization (<filename>.emacs</filename>)
5730           file. This method does <emphasis>not</emphasis> work for JDE
5731           customization variables. To set a JDE customization variable, you
5732           <emphasis>must</emphasis> use  the customization buffer for a variable
5733           (see the Emacs online manual for information on the  customization
5734           feature). This is because the JDE context switching code resets all
5735           JDE customization variables to their default or customized (via a
5736           custom buffer) values whenever you open a Java source file or switch
5737           projects.
5738         </para>
5739       </note>
5740
5741       <para>  The following section explains  how to use the Emacs
5742         customization  feature to set the value of a JDE customization
5743         variable.</para>
5744
5745       <sect4>
5746
5747
5748         <title><anchor id="SettingVariable"/> Setting a Customization Variable</title>
5749
5750
5751         <para>
5752           To set a JDE customization variable:
5753         </para>
5754
5755         <procedure>
5756           <step>
5757             <para>Determine the name of the variable you want to customize.</para>
5758             <para>  Refer to the section of this guide that documents the feature
5759               you want to customize for the name of the corresponding variable.  Or
5760             type <keycombo><keycap>C</keycap><keycap>h</keycap></keycombo>&nbsp;
5761             <keysym>v</keysym> followed by the JDE group prefix
5762             (<varname>jde-</varname>) or subgroup prefix (e.g.,
5763             <varname>jde-compile-option-</varname>,
5764             see <ulink url="#JDECustomizationGroups">JDE Customization Groups</ulink>).
5765             Emacs displays all  variables belonging to the JDE group or subgroup. You
5766             can then browse this list, using Emacs search, completion,  and
5767             documentation display command, to find the applicable  variable.
5768             </para>
5769           </step>
5770
5771           <step>
5772           <para>Display a customization buffer for the variable. </para>
5773           <para>  If you know the name of the variable, the easiest way to
5774             display a customization buffer for the variable is to select
5775             <menuchoice><guimenu>Help</guimenu><guisubmenu>Customize</guisubmenu>
5776               <guimenuitem>Specific Option...</guimenuitem></menuchoice> from the
5777             Emacs  menubar or type <keycombo><keycap>M</keycap><keycap>x</keycap>
5778               </keycombo>&nbsp;<command>jde-customize-variable</command>.</para>
5779
5780             <note>
5781               <para><command>jde-customize-variable</command> is a
5782                 special version of the standard Emacs
5783                 <command>customize-variable</command> command that
5784                 provides a customization buffer menu item for saving a
5785                 customization in a JDEE project file (see below). You
5786                 should use this version of the command if you intend
5787                 to save customizations in project files. You can also
5788                 use it to do any other type of customization that the
5789                 standard command supports. This allows you to use the
5790                 JDEE version of the command for all your
5791                 customizations regardless of whether you intend to
5792                 save them in project files. </para>
5793             </note>
5794
5795             <para>
5796             If you know the  group to which the variable belongs (.e.g., compile
5797             options), you  can display the customization buffer for the group. This
5798             is useful when  you want to customize several related variables. See
5799             <ulink url="#JDECustomizationGroups">JDE Customization Groups</ulink> for
5800             more information.
5801           </para>
5802         </step>
5803
5804         <step>
5805           <para>Edit the value for the variable displayed in the customization
5806             buffer. </para>
5807         </step>
5808
5809           <step>
5810             <para>Save the value for the variable in your <filename>.emacs</filename>
5811             or <filename>.prj</filename> file.
5812             </para>
5813             <para>If you want the setting to apply to all projects that do not
5814             have a project file  (see <ulink url="#UsingProjectFiles">Using Project
5815               Files</ulink>), you should save the variable in your
5816             <filename>.emacs</filename> file. To save the variable in your
5817             <filename>.emacs</filename> file, select  <menuchoice><guimenuitem>Save
5818                 for Future Sessions</guimenuitem></menuchoice> from the
5819             <menuchoice><guimenu>State</guimenu></menuchoice> menu for the
5820             variable in the customization buffer.
5821             </para>
5822             <para>  If you want the setting to apply only to the current project,
5823               select
5824             <menuchoice><guimenuitem>Save in JDEE Project File</guimenuitem>
5825             </menuchoice> from the <menuchoice><guimenu>State</guimenu>
5826             </menuchoice> menu for the variable.
5827             </para>
5828
5829             <note>
5830               <para>
5831                 The <menuchoice><guimenuitem>Save in JDEE Project File</guimenuitem>
5832                 </menuchoice> menu item appears only if you used the
5833                 <command>jde-customize-variable</command> command to create
5834                 the customization buffer.
5835               </para>
5836             </note>
5837
5838             <para>
5839               If a project file does not exist for the project, the
5840               JDEE prompts you to enter a name for the project.
5841               It then creates a project file for the project with
5842               the name that you enter.
5843             </para>
5844
5845           </step>
5846         </procedure>
5847
5848       </sect4>
5849
5850       <sect4>
5851         <title><anchor id="SpecifyingPaths"/>Specifying Paths</title>
5852         <para>You can use paths containing environment variables and
5853           or a tilde (~), cygwin paths, and  relative paths as a value
5854           of any JDE customization variable that requires a
5855           path.</para>
5856
5857         <sect5>
5858           <title><anchor id="EnvVarsInPaths"/>Environment Variables</title>
5859           <para>The JDE accepts paths that contain envirnoment variables, for
5860             example, </para>
5861
5862           <para>
5863             <programlisting format="linespecific">
5864               $JDK_HOME/src
5865             </programlisting>
5866           </para>
5867
5868           <para>
5869             The JDE replaces the environment variables with their
5870             actual values before passing the paths to commands (e.g.,
5871             javac) that require them. You must use Unix notation
5872             (i.e., <varname>$VARNAME</varname> or
5873             <varname>${VARNAME}</varname>) to  specify an environment
5874             variable in a path even on Windows.
5875         </para>
5876
5877         </sect5>
5878
5879         <sect5>
5880           <title><anchor id="TildeNotation"/>Tilde (~) Notation</title>
5881           <para>The JDE accepts paths that begin with a tilde, for example,
5882             <filename>~/myproj/classes</filename>. The JDE replaces the tilde
5883             with the path to your home directory.</para>
5884         </sect5>
5885
5886         <sect5>
5887           <title><anchor id="RelativePaths"/>Relative Paths</title>
5888           <para>A relative path is a path that begins with a period, for
5889           example, <filename>./src</filename>. If
5890           <varname>jde-resolve-relative-paths</varname> is
5891           set to a non-nil value (the default), the JDE converts a relative
5892           path to an absolute path by appending the relative path to the
5893           path of the project file that set the path variable, or if no such
5894           file exists, to the path of the current Java source buffer.</para>
5895
5896           <para>
5897             You can use your <filename>.emacs</filename> file to
5898             specify default relative paths for projects. For example,
5899             setting <varname>jde-global-classpath</varname> to
5900             <filename>./classes</filename> in your
5901             <filename>.emacs</filename> file specifies that the
5902             default location of class files is in a subdirectory of
5903             the project file directory named <filename>classes</filename>.
5904           </para>
5905         </sect5>
5906
5907         <sect5>
5908           <title><anchor id="CygwinPaths"/>Cygwin Paths</title>
5909           <para>You can use cygwin style paths in JDE classpath variables
5910           on Windows. The JDE converts such paths to DOS paths before
5911           using them, using a conversion function that you can specify.</para>
5912
5913           <para>The jde-cgywin-path-converter variable allows you
5914           to choose the path conversion function used by the JDE.</para>
5915
5916           <itemizedlist>
5917             <listitem>
5918               <para><function moreinfo="none">
5919                 jde-cygwin-path-converter-internal</function></para>
5920               <para>This is the default path conversion function used by
5921               the JDE. It converts any paths of the form <varname>//[a-z]/</varname>
5922               or <varname>//cygdrive/[a-z]/</varname> to the corresponding DOS form. For
5923               example it converts  <varname>/c/jde/java/classes</varname> to
5924               <varname>c:/jde/java/classes</varname>.
5925               </para>
5926             </listitem>
5927             <listitem>
5928               <para><function moreinfo="none">jde-cygwin-path-converter-cygpath</function></para>
5929               <para>This function invokes the cygwin
5930                 <function>cygpath</function> utility to perform the
5931                 path conversion. The advantage is that the cygwin path
5932                 utility can recognize and convert Unix style paths
5933                 that represent mount points in the cygwin mount table.
5934                 For example, suppose that you have mounted
5935                 <varname>d:/javadev</varname> as
5936                 <varname>/javadev</varname> in the cygwin mount table.
5937                 Then choosing <function
5938                   moreinfo="none">jde-cygwin-path-converter-cygpath</function>
5939                 allows you to use paths beginning with
5940                 <varname>/javadev</varname> in JDE classpaths. The
5941                 drawback is that the conversion is slow as it requires
5942                 running the cygwin utility for each Unix-style path to
5943                 be converted.</para>
5944             </listitem>
5945             <listitem>
5946               <para>A custom conversion function that you supply.</para>
5947             </listitem>
5948           </itemizedlist>
5949
5950         </sect5>
5951
5952       </sect4>
5953
5954       <sect4>
5955
5956
5957         <title><anchor id="JDECustomizationGroups"/> JDE Customization Groups</title>
5958
5959
5960         <para>The JDE defines a top-level customization group, the JDE
5961           Group, for JDE customization variables. The JDE Group itself
5962           contains the following subgroups:</para>
5963
5964
5965         <sect5>
5966
5967
5968           <title><anchor id="CompileOptionGroup"/> Compile Option
5969             Group</title>
5970
5971
5972           <para>Specifies compile options corresponding to the
5973           command-line arguments (e.g., -d) accepted by the JDK
5974           compiler, javac. When  you execute the JDE compile command,
5975           the JDE uses the settings of  this group to construct a list
5976           of command-line arguments that it  passes to the Java
5977           compiler that the JDE uses to compile Java  source programs.
5978           The compiler is itself an option that you can  specify (see
5979           the Project Option Group). You can specify command-line
5980           arguments directly by setting the value of the
5981           <varname>jde-compile-option-command-line-args</varname>
5982           variable. You can display the customization buffer for the
5983           Compile Option Group by selecting
5984           <menuchoice><guimenu>JDE</guimenu><guisubmenu>
5985               Project</guisubmenu>-<guisubmenu>Options</guisubmenu>
5986           <guimenuitem>Compile</guimenuitem></menuchoice> from  the
5987           <productname>Emacs</productname> menubar. </para>
5988          </sect5>
5989
5990         <sect5>
5991
5992
5993           <title><anchor id="CompileOptionGroup"/>Run Option Group</title>
5994
5995
5996           <para>Specifies run-time options corresponding to the
5997             command-line arguments (for example, -classpath) accepted
5998             by the JDK virtual machine, java. When you execute the JDE
5999             Run command,&nbsp; the JDE uses the settings of this group
6000             to construct a list of command-line arguments that it
6001             passes to the Java interpreter used by the JDE to run
6002             applications. This group also contains options for
6003             specifying non-java command-line arguments (in case you
6004             want to use a VM that accepts a different set of arguments
6005             than java does) and for specifying arguments to be passed
6006             to the application (as opposed to the virtual machine
6007             interpreting the application.) You can display the
6008             customization buffer for the Run Option Group by selecting
6009             <menuchoice><guimenu>JDE</guimenu>
6010               <guisubmenu>Project</guisubmenu>-<guisubmenu>Options</guisubmenu>
6011             <guimenuitem>Run</guimenuitem></menuchoice> from  the
6012             <productname>Emacs</productname> menubar. </para>
6013         </sect5>
6014
6015         <sect5>
6016
6017           <title><anchor id="DebugOptionGroup"/>Debug Option Group</title>
6018
6019           <para>Specifies run-time options corresponding to the command-line
6020           arguments (for example, -classpath) accepted by the JDK debugger,
6021           jdb. jdb accepts the same command-line arguments as java. However,
6022           the JDE maintains two parallel sets of configuration variables
6023           for these programs in case you want to use a different set of
6024           options for running a program in debug mode then you use for
6025           running it normally. When you execute the JDE Debug command,
6026           the JDE uses the settings of this group to construct a list of
6027           command-line arguments that it passes to the Java debugger used
6028           by the JDE to run applications in debug mode. You can display the
6029           customization buffer for the Debug Option Group by selecting
6030           <menuchoice><guimenu>JDE</guimenu>
6031             <guisubmenu>Project</guisubmenu>-<guisubmenu>Options</guisubmenu>
6032           <guimenuitem>Debug</guimenuitem></menuchoice>
6033           from  the <productname>Emacs</productname> menubar. </para>
6034         </sect5>
6035
6036         <sect5>
6037
6038
6039           <title> <anchor id="AutocodeGroup"/>Autocode Group</title>
6040
6041
6042           <para>Specifies templates used to generate code automatically. </para>
6043         </sect5>
6044
6045         <sect5>
6046
6047
6048           <title><anchor id="GeneralGroup"/> General Options Group</title>
6049
6050
6051         <para>Specify all other JDE options. You can display the
6052           customization buffer for the General Option Group by selecting
6053           <menuchoice><guimenu>JDE</guimenu>
6054             <guisubmenu>Project</guisubmenu>-<guisubmenu>Options</guisubmenu>
6055           <guimenuitem>General</guimenuitem></menuchoice>
6056           from  the <productname>Emacs</productname> menubar. </para>
6057         </sect5>
6058
6059       </sect4>
6060
6061     </sect3>
6062
6063     <sect3>
6064
6065       <title><anchor id="Customizingjde_mode"/> Customizing jde-mode</title>
6066
6067
6068       <para>The JDE defines a major mode, named jde-mode, for editing
6069         Java source files. This mode derives from the standard Emacs
6070         Java source editing mode java-mode. In particular, it inherits
6071         all the functions and customization variables defined by
6072         java-mode and adds its own customization variables. When you
6073         load a Java source file, Emacs runs a JDE mode initialization
6074         function called jde-mode. The jde-mode function in turn calls
6075         the Java mode intialization function, java-mode. The last
6076         thing that jde-mode does before returning is to call a JDE
6077         mode function, if it exists. You can customize the JDE by
6078         defining a JDE mode hook function in your .emacs file. The
6079         following is an example of how to do this: </para>
6080
6081
6082     <programlisting>
6083       (defun my-jde-mode-hook ()
6084       (message &quot;my-jde-mode-hook function executed&quot;))
6085        (add-hook 'jde-mode-hook 'my-jde-mode-hook)
6086        </programlisting>
6087
6088     <para>The preceding example defines a JDE mode hook function named
6089       my-jde-mode-hook and adds it to the list of JDE mode hook
6090       functions, using the Emacs Lisp function add-hook. Now, whenever
6091       you open a Java source file, jde-mode invokes the function my-jde-mode-hook.
6092       Of course, the hook function defined in this example is trivial.
6093       A real-world example might do something more useful, such as
6094       setting a custom indentation style. </para>
6095
6096
6097     <sect4>
6098
6099
6100         <title><anchor id="Keybindings"/> Customizing Key Bindings</title>
6101
6102
6103       <para>A key binding establishes an equivalence between a keystroke
6104         or a sequence of keystrokes and an interactive Lisp function. The
6105         keystroke or keystroke combination causes Emacs to execute the
6106         function to which the keystroke (combination) is bound. For
6107         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>
6108         to the function <varname>jde-compile</varname>. You can use the JDE
6109         customization facility to change the standard JDE bindings or
6110         create bindings for functions that do not have default bindings. </para>
6111
6112       <para>To customize key bindings: </para>
6113
6114       <procedure>
6115         <step>
6116           <para>Open a buffer on the JDE customization variable <varname>jde-key-bindings</varname>.</para>
6117           <para>You can do this by typing
6118             <keycombo><keycap>M</keycap><keycap>x</keycap>
6119             </keycombo>&nbsp;<varname>customize-variable</varname>&nbsp;
6120             <varname>jde-key-bindings</varname> or by selecting <menuchoice>
6121               <guimenu>JDE</guimenu><guisubmenu>Options</guisubmenu><guimenuitem>Project</guimenuitem></menuchoice>  and searching the
6122             resulting JDE project customization  buffer for
6123             <varname>jde-key-bindings</varname>. </para>
6124           <para>The key bindings panel looks like this: </para>
6125
6126           <para><screenshot>
6127               <mediaobject>
6128                 <imageobject>
6129                   <imagedata fileref="images/keybindings.gif"/>
6130                 </imageobject>
6131                 <textobject>
6132                   <phrase>Screenshot showing key bindings buffer.</phrase>
6133                 </textobject>
6134               </mediaobject>
6135             </screenshot>
6136           </para>
6137
6138         </step>
6139         <step>
6140           <para>Edit the buffer to specify altered or new bindings. </para>
6141           <para>For example, to add a binding, right click the
6142             <guibutton>[INS]</guibutton> button, then enter the key  stroke in the
6143             <guilabel>Key</guilabel> field and  the interactive function (command)
6144             to which it is bound  in the <guilabel>Command</guilabel> field.</para>
6145         </step>
6146
6147         <step>
6148           <para>Save the edited bindings. </para>
6149           <para>To save the edited bindings, right click the
6150             <guibutton>[State]</guibutton> button and choose <menuchoice>
6151               <guimenuitem>Set for current session</guimenuitem></menuchoice> if you
6152             want the settings to apply only to the current project or
6153             <menuchoice><guimenuitem>Save for future
6154                 sessions</guimenuitem></menuchoice>if  you want the settings to apply
6155             to all projects. In either  case, you should save the new settings in
6156             you project  file if your project has a project file. To save the new
6157             settings in your project file, switch to a source buffer  and choose
6158             <menuchoice><guimenu>JDE</guimenu><guisubmenu> Options</guisubmenu><guimenuitem>Save Project</guimenuitem></menuchoice>  from the Emacs menubar.
6159           </para>
6160           </step>
6161         </procedure>
6162       </sect4>
6163     </sect3>
6164
6165   </chapter>
6166
6167   <chapter>
6168     <title><anchor id="Plugins"/>Creating and Installing Plugins</title>
6169
6170     <para>Plugins are independently developed applications intended
6171         for use with the JDEE and distributed in the form of a (g)zip or
6172         jar file. The following sections explain how to create and install
6173         plugins.
6174     </para>
6175
6176     <sect3>
6177
6178       <title><anchor id="InstallingPlugins"/>Installing a Plugin</title>
6179
6180       <para>To install a plugin:</para>
6181
6182       <orderedlist>
6183         <listitem>
6184           <para>Copy the zip or jar file containing the plugin in to
6185             the JDEE's plugins directory.</para>
6186
6187           <note>
6188             <para>By default the JDEE plugin directory is a
6189               subdirectory of the JDEE directory named
6190               <filename>plugins</filename>. If you want to keep your
6191               plugins in another directory, set
6192               <varname>jde-plugins-directory</varname> to the path of
6193               that directory.</para>
6194             </note>
6195
6196         </listitem>
6197
6198         <listitem>
6199
6200           <para>Execute <command>M-h jde-pi-install-plugins</command>.</para>
6201             <para>This command installs any plugins at the top level of the plugins
6202             directory in the plugins directory.</para>
6203
6204         </listitem>
6205
6206       </orderedlist>
6207
6208       <para>If the plugin adds any menu items to the JDEE's plugins menu
6209         (named <guimenu>JDEpi</guimenu>), you should now be able to see the
6210           items on the plugins menu.</para>
6211
6212     </sect3>
6213
6214     <sect3>
6215
6216       <title><anchor id="CreatingPlugins"/>Creating a Plugin</title>
6217
6218       <para>The following sections explain how to create a JDEE plugin.</para>
6219
6220       <sect4>
6221
6222         <title><anchor id="PluginRequirements"/>Plugin Requirements</title>
6223
6224         <para>A JDEE plugin must meet the following requirements:</para>
6225
6226         <sect5>
6227
6228           <title>Packaging</title>
6229
6230             <para>The plugin must be distributed as a compressed file that can be
6231             decompressed by Java's jar program. Compressed file formats that meet this
6232             requirement include zip, gzip, and jar.
6233             </para>
6234
6235         </sect5>
6236
6237         <sect5>
6238
6239           <title>Directory Structure</title>
6240
6241           <para>Decompressing the plugin should create a subdirectory in the
6242             current directory whose name is the plugin's name and that contains
6243             at least one directory named <filename>lisp</filename>. The
6244             plugin directory can contain any number of other directories.
6245             The other directories can have any names. However, it would be
6246             nice if plugins standardized on the following directory structure
6247             and names.
6248           </para>
6249
6250           <programlisting>
6251
6252    plugin
6253      bsh
6254       doc
6255       scripts
6256      help
6257        info
6258        html
6259        src      (e.g., xml files used to generate info and html)
6260      java
6261        class
6262        doc
6263        lib      (e.g, jar files)
6264        src
6265      lisp
6266           </programlisting>
6267
6268
6269         </sect5>
6270
6271         <sect5>
6272
6273           <title>Bootstrap File</title>
6274
6275           <para>The plugin's lisp directory must contain a Lisp file
6276             named <filename>jde-PLUGIN.el </filename>where PLUGIN is
6277             the same as the plugin's toplevel directory name. This
6278             file is called a bootstrap file because it is the only
6279             file directly loaded by the JDEE. It is responsible for
6280             registering the plugin with the JDEE and loading any other
6281             Lisp files required by the plugin.</para>
6282
6283         </sect5>
6284
6285       </sect4>
6286
6287       <sect4>
6288
6289         <title><anchor id="RegisteringPlugin"/>Registering a Plugin</title>
6290
6291         <para>A plugin's bootstrap file must register the plugin with
6292           the JDEE when it is loaded. The bootstrap file should do
6293           this by invoking the JDEE's
6294           <function>jde-pi-register</function> function. This function
6295           takes a single argument: an instance of
6296           <varname>jde-plugin</varname> class that optionally
6297           specifies the plugin's menu and its contribution to the
6298           classpath of the instance of the BeanShell run by the
6299           JDEE. </para>
6300
6301       </sect4>
6302
6303       <sect4>
6304         <title>Running Java Code from a Plugin</title>
6305
6306         <para>A plugin can use the JDEE's instance of the BeanShell to
6307         invoke Java methods and display their output in an Emacs
6308         buffer. The JDEE provides the following functions for this
6309         purpose:</para>
6310
6311         <itemizedlist>
6312
6313           <listitem>
6314             <para><function>jde-jeval</function></para>
6315             <para>Evaluate a Java statement in the JDEE's BeanShell
6316               instance and return the resulting BeanShell
6317               output.</para>
6318           </listitem>
6319
6320           <listitem>
6321             <para><function>jde-jeval-r</function></para>
6322             <para>Evaluate a Java statement in the JDEE's BeanShell
6323               instance, use the Emacs Lisp interpreter to evaluate the
6324               resulting BeanShell output, and return the result. This
6325               function assumes that the Java statement emits Emacs
6326               Lisp code, i.e., that the Java code was developed
6327               specifically to cause Emacs to do something.
6328             </para>
6329           </listitem>
6330
6331           <listitem>
6332             <para><function>jde-jeval-cm</function></para>
6333             <para>Evaluate a Java statement in the JDEE's BeanShell
6334               instance and display the resulting BeanShell output in
6335               an Emacs compilation buffer. This function is intended
6336               to run Java applications, such as style checkers, that
6337               output error messages keyed to specific lines in a
6338               source file.
6339             </para>
6340           </listitem>
6341
6342         </itemizedlist>
6343
6344         <para>See the doc strings for these functions for more information.</para>
6345
6346
6347       </sect4>
6348
6349
6350      <sect4>
6351
6352         <title><anchor id="BootstrapExample"/>Bootstrap File Example</title>
6353
6354         <para>
6355           The following is an example of the bootstrap file
6356         for a plugin named pi1.</para>
6357
6358         <programlisting>
6359
6360   ;; jde-pi1.el
6361   (defun jde-pi1-cmd ()
6362     (interactive)
6363     (message "plugin 1"))
6364
6365   (jde-pi-register
6366    (jde-plugin
6367     "pi1"
6368     :bsh-cp (list
6369            (expand-file-name "lib/lib1.jar" (jde-pi-get-plugin-dir "pi1"))
6370            (expand-file-name "lib/lib2.jar" (jde-pi-get-plugin-dir "pi1")))
6371     :menu-spec (list (list "Pi1" ["cmd" jde-pi1-cmd :active t]))))
6372
6373
6374   (provide 'jde-pi1)
6375
6376         </programlisting>
6377
6378       </sect4>
6379
6380     </sect3>
6381
6382   </chapter>
6383
6384 </book>
6385
6386
6387
6388 <!--
6389 Local Variables:
6390 mode: xae
6391 sgml-indent-step: 2
6392 sgml-indent-data: t
6393 sgml-set-face: t
6394 sgml-insert-missing-element-comment: nil
6395 End:
6396  -->