1 <html><link rel="StyleSheet" href="../css/jde_style.css" TYPE="text/css"><head>
2 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
3 <title>JDEE User's Guide</title><meta name="generator" content="DocBook XSL Stylesheets V1.67.0"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="d51e3"></a>JDEE User's Guide</h1></div><div><p class="releaseinfo">
4 <em><span class="remark">
5 Revised for JDEE <span class="productnumber">2.3.6</span>
7 </p></div><div><p class="copyright">Copyright © 1997-2005 Paul Kinnucan</p></div></div><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e36"></a><a name="Intro"></a>Introduction</h2></div></div></div><p>Welcome to the <span class="emphasis"><em>JDEE User's Guide</em></span>. This
8 guide explains how to use the JDEE to develop Java applications and
9 applets. The guide assumes that you are familiar with Emacs, the
10 Java programming language, and Java development tools provided
11 by Sun Microsystems, Inc.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
12 This guide and the JDEE user interface use the term "JDK" to
13 refer to Sun's Java 2 Software Development Kit (SDK) and its
15 </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e48"></a><a name="AboutJDE"></a>About the JDEE</h4></div></div></div><p>The Java Development Environment for Emacs (JDEE) is an
16 Emacs Lisp package that interfaces Emacs to third-party Java
17 application development tools, such as those provided by Sun
18 Microsystems as part of its JDK. The result is an integrated
19 development environment (IDE) comparable in power to many
20 commercial Java IDEs. Features include: </p><div class="itemizedlist"><ul type="disc"><li><p>source code editing with syntax highlighting and auto
21 indentation</p></li><li><p>automatic completion of class fields and methods
22 </p></li><li><p>compilation with automatic jump from error messages
23 to responsible line in the source code.</p></li><li><p>
24 generates class and method skeletons automatically
25 </p></li><li><p>run Java application in an interactive (comint)
28 integrated debugging with interactive debug command
29 buffer and automatic display of current source file/line
30 when stepping through code
32 browse JDK doc, using the browser of your choice
34 browse your source code, using the Emacs etags facility
35 or a tree-structured speedbar.
37 supports latest version of JavaSoft's Java Development
39 runs on any platform supported by Emacs and Sun's Java SDK (e.g.,
42 easily and infinitely customizable
44 works with FSF Emacs and XEmacs
45 </p></li></ul></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e91"></a><a name="JDERequirements"></a>JDE Requirements</h4></div></div></div><p>The JDE requires the following software: </p><div class="itemizedlist"><ul type="disc"><li><p><a href="http://www.gnu.org/">FSF Emacs</a> or
46 <a href="http://www.xemacs.org/">XEmacs</a> on Unix
47 platforms; the 20.6.1 version (or later) of
48 <a href="ftp://ftp.gnu.org/gnu/windows/emacs/latest">NT/Emacs</a> on
49 Windows platforms, for general source file editing and tool integration functions.
51 <a href="http://java.sun.com/j2se">Java
52 Development Kit (JDK)</a> or compatible set of Java
53 development tools (compiler, virtual machine, debugger,
54 class libraries, etc.)
56 Web browser (e.g., Netscape or Internet Explorer) for
57 viewing documentation.
59 latest versions of Eric Ludlam's <span class="symbol">speedbar</span>,
60 <span class="symbol">semantic</span>, and
61 <span class="symbol">eieio</span> packages available for download from
62 <a href="http://cedet.sourceforge.net">the CDET home page</a>
64 The elib package available from the
65 <a href="http://jdee.sunsite.dk">JDE web site</a>
67 <code class="command">bash</code> or another Unix-style shell highly
68 recommended for Windows95/NT environments. The <a href="http://sources.redhat.com/cygwin">cygwin</a>
69 Unix emulation package for Windows from Red Hat includes
70 <code class="command">bash</code>.
71 </p></li></ul></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e151"></a><a name="JDEComponents"></a>JDEE Components</h4></div></div></div><p>
72 The JDEE distribution includes the following files:
73 </p><div class="itemizedlist"><ul type="disc"><li><p>
76 <a href="../../../lisp/jde.el"><code class="filename">jde.el</code></a>.
77 Defines jde-mode, a major Emacs mode for developing Java code.
79 <a href="../../../lisp/jde-run.el"><code class="filename">jde-run.el</code></a>.
80 Runs Java applications and applets
82 <a href="../../../lisp/jde-db.el"><code class="filename">jde-db.el</code></a>.
83 Interfaces Emacs to <code class="command">jdb</code>, the command-line debugger that
86 <a href="../../../lisp/jde-gen.el"><code class="filename">jde-gen.el</code></a>.
87 Contains code generation templates.
89 <code class="filename">bsh.jar</code>. Compiled files for the
90 <a href="http://www.beanshell.org/">BeanShell</a>,
91 a Java source code interpreter developed by Pat Neimeyer.
93 <a href="../../../lisp/beanshell.el"><code class="filename">beanshell.el</code></a>.
94 Provides an Emacs interface to the BeanShell interpreter.
96 <a href="../../../lisp/jde-wiz.el"><code class="filename">jde-wiz.el</code></a>.
97 Provides "wizards" that generate skeleton
98 implementations of interfaces and skeleton overrides of
99 methods declared by superclasses.
101 <a href="../../../lisp/jde-complete.el"><code class="filename">jde-complete.el</code></a>.
102 Automatic field and method completion package.
104 <a href="../../../lisp/jde-parse.el"><code class="filename">jde-parse.el</code></a>.
105 Java parser package.</p></li><li><p>
106 <a href="../../../lisp/java.bnf"><code class="filename">java.bnf</code></a>.
107 Java grammar used to generate the JDE's lisp-based Java parser.
109 <a href="../../../lisp/jde-bug.el"><code class="filename">jde-bug.el
111 JDEbug user interface package.
113 <a href="../../../lisp/jde-dbs.el"><code class="filename">jde-dbs.el</code></a>.
114 JDEbug low-level command interface package.
116 <a href="../../../lisp/jde-dbo.el"><code class="filename">jde-dbo.el</code></a>.
117 JDEbug output processing functions.
119 source code, jar files, and documentation for the <a href="../../java/">Java components</a> of the
120 JDE.</p></li><li><p><a href="../../../lisp/jtags"><code class="filename">jtags</code></a>
121 is a bash shell script that tags Java source hierarchies.
123 <a href="../../../lisp/jtags.csh"><code class="filename">jtags.csh</code></a>
124 is a c shell script that tags Java source heierarchies.
125 </p></li></ul></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e273"></a><a name="LatestVersion"></a>Latest Version</h4></div></div></div><p>See <a href="http://jdee.sunsite.dk/rootpage.html#Downloading">
126 Downloading the JDE</a> on the JDE website for instructions on
127 downloading the most recent version of the JDE.
128 </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e282"></a><a name="InstallingJDE"></a>Installing the JDE</h4></div></div></div><p>See the <a href="http://jdee.sunsite.dk/install.html">
129 JDE Installation Guide</a> on the JDE website for information
130 on installing the JDE on your system.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e291"></a><a name="ContactingAuthor"></a>Contacting the Author</h4></div></div></div><p>Please send bug reports and enhancement suggestions to
131 <a href="mailto:pkinnucan@comcast.net">Paul Kinnucan</a>.
132 </p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e300"></a><a name="RegisterSelectJDK"></a>Registering and Selecting a JDK</h2></div></div></div><p>The JDEE relies on command-line Java development tools, such
133 as those supplied by Sun Microsystems as part of its Java 2
134 Software Development Kit (SDK) also known as a Java Development
135 Kit (JDK). Before you can use the JDEE to compile, debug, or run
136 an application, you must tell it where the Java compiler,
137 debugger, and virtual machine are located on your system. The
138 JDEE assumes that the compiler, debugger, and vm are named
139 <code class="filename">javac</code>, <code class="filename">jdb</code>, and
140 <code class="filename">java</code>, respectively, and that they are
141 located on your system's command path. If these tools are not
142 located on the system command path or have different names, you
143 must tell the JDEE where they are located. The JDEE provides
144 customization variables for specifying the locations of
147 However, if you are using one or more versions of Sun's JDK or a
148 clone of the Sun JDK, the easiest way to specify the location of
149 the external development tools is to register the version of the
150 JDK that you intend to use. It is especially advantageous to
151 register a JDK, if you intend to use multiple versions of the
152 JDK. The reason? Registering each version of the JDK allows you
153 to change JDKs by changing a single customization variable. The
154 following sections explain how to register and select
156 </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e317"></a><a name="RegisterJDK"></a>Registering a JDK</h4></div></div></div><p>To register a version of the JDK with the JDEE:</p><div class="orderedlist"><ol type="1"><li><p>Start Emacs.</p></li><li><p>Type <code class="command">M-x customize-variable</code> and
157 press <code class="command">Enter</code></p><p>Emacs prompts you to enter the name of a variable
158 to customize.</p></li><li><p>Enter <code class="varname">jde-jdk-registry</code> and
159 press <code class="command">Enter</code>.</p><p>The <code class="varname">jde-jdk-registry</code> customization
160 buffer appears.</p><div class="screenshot"><div class="mediaobject"><img src="images/regjdk1.gif"></div></div></li><li><p>Click the <code class="command">INS</code> button.</p><p>The entry for the JDK appears.</p><div class="screenshot"><div class="mediaobject"><img src="images/regjdk2.gif"></div></div></li><li><p>Enter the version number of the JDK and the path of the directory
161 in which the JDK is installed.</p></li><li><p>Repeat the preceding steps until you have entered the versions and
162 paths of all versions of the JDK that you wish to use with the JDEE.</p><div class="screenshot"><div class="mediaobject"><img src="images/regjdk3.gif"></div></div></li><li><p>Click the <code class="command">State</code> button.</p><p>The <code class="command">State</code> menu appears.</p></li><li><p>Select <code class="command">Save for Future Sessions</code> from
163 the <code class="command">State</code> menu.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This saves the setting of <code class="varname">jde-jdk-registry</code>
164 in your <code class="filename">.emacs</code> file.</p></div></li><li><p>Click the <code class="command">Finish</code> button to dismiss
165 the customization buffer.</p></li></ol></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e412"></a><a name="SelectingJDK"></a>Selecting a JDK</h4></div></div></div><p>To select a JDK:</p><div class="orderedlist"><ol type="1"><li><p>Type <code class="command">M-x customize-variable</code> and
166 press <code class="command">Enter</code></p><p>Emacs prompts you to enter the name of a variable
167 to customize.</p></li><li><p>Enter <code class="varname">jde-jdk</code> and
168 press <code class="command">Enter</code>.</p><p>The <code class="varname">jde-jdk</code> customization
169 buffer appears.</p><div class="screenshot"><div class="mediaobject"><img src="images/seljdk1.gif"></div></div><p>The buffer lists the JDKs that you have previously registered
170 (see <a href="#RegisterJDK">Registering a JDK</a>).</p></li><li><p>Click the radio button next to the version of the JDK you
171 want to use.</p></li><li><p>Click the <code class="command">State</code> button.</p><p>The <code class="command">State</code> menu appears.</p></li><li><p>Select <code class="command">Save for Future Sessions</code> from
172 the <code class="command">State</code> menu.</p></li><li><p>Click the <code class="command">Finish</code> button to dismiss
173 the customization buffer.</p></li></ol></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This procedure saves your JDK selection in your
174 <code class="filename">.emacs</code> file so that it applies to all
175 projects. You can configure the JDEE to use different JDKs
176 for different projects by saving your customization in a
177 project file. See <a href="#UsingProjectFiles">Using
178 Project Files</a> or more information.</p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e490"></a><a name="EditingJavaSourceFiles"></a>Editing Java Source Files</h2></div></div></div><p>
179 To edit an existing Java source file, load it into an Emacs
180 buffer by executing <code class="command">C-x C-f</code>. Loading a Java source file
181 into a buffer causes the buffer to enter into <code class="function">jde-mode</code>,
182 a variant of <code class="function">java-mode</code>, which is in turn a variant of
183 the standard Emacs <code class="function">cc-mode</code> for editing source files
184 written in C and related languages. <code class="function">jde-mode</code> offers all the
185 specialized source file editing commands of <code class="function">cc-mode</code> plus
186 functions for creating, compiling, building, running, and debugging Java source files.
187 You can invoke the commands by selecting them from the <span><strong class="guimenu">JDE</strong></span>
188 menu that <code class="function">jde-mode</code> displays on the Emacs menu bar or by
189 typing the commands in the Emacs minibuffer.
191 </p><div class="screenshot"><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="544"><tr style="height: 350px"><td><img src="images/jdemenu.gif" height="350" alt="Screenshot showing the JDE menu."></td></tr></table></div></div><p>
192 </p></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e530"></a><a name="DocumentingCode"></a>Documenting Code</h2></div></div></div><p>
193 The JDE provides complete support for generating HTML
194 documentation for Java classes from comments inserted into the
195 source code for those classes.
196 </p><p>See also</p><p><a href="#DisplayingDoc">Displaying Java
197 Documentation</a></p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e541"></a><a name="InsertingComments"></a>Inserting Javadoc
198 Comments</h4></div></div></div><p>
199 To insert a skeleton javadoc comment for a class or method,
200 position point in the first line of the method or class and
201 select <span><strong class="guimenuitem">JDE->Document</strong></span> from the
202 Emacs menubar or type <code class="command">C-c C-v j</code>.
204 To customize the javadoc skeletons, select
205 <span><strong class="guimenuitem">JDE->Options->Project->Javadoc</strong></span>
206 from the Emacs menubar.
207 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Thanks...</h3><p>
208 to <a href="mailto:david@dponce.com">David Ponce</a>
209 for developing the JDE's javadoc comment generation
211 </p></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e566"></a><a name="GeneratingJavadoc"></a>Generating the
212 Documentation</h4></div></div></div><p>
213 To generate documentation for the current project, open any
214 source file in the project and select <span><strong class="guimenuitem">Make
215 Doc</strong></span> from the <span><strong class="guimenu">JDE</strong></span> menu or
216 enter <code class="command">M-x jde-javadoc-make</code>.
218 The <code class="command">jde-javadoc-make</code> command runs the JDK's
219 javadoc program to generate the documentation. The
220 <code class="command">javadoc</code> command must be on your system's
223 The <code class="command">jde-javadoc-make</code> command uses
224 <code class="varname">jde-global-classpath</code> as the
225 <code class="varname">-classpath</code> and <code class="varname">jde-sourcepath
226 </code> as the <code class="varname">-sourcepath</code> option for
227 generating the doc. You can specify all other javadoc options
228 via JDE customization variables. To specify the options,
229 select <span><strong class="guimenu">Project</strong></span>-><span><strong class="guisubmenu">Options</strong></span>-><span><strong class="guimenuitem">Javadoc</strong></span>
233 <span><strong class="guimenu">JDE</strong></span> menu. Use
234 <code class="varname">jde-javadoc-gen-packages</code> to specify the
235 packages, classes, or source files for which you want to
236 generate javadoc. If this variable is
237 <code class="varname">nil</code>, the
238 <code class="command">jde-javadoc-make</code> generates javadoc for
239 the Java source file in the current buffer.
240 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
241 Thanks to <a href="mailto:sakliban@cs.wustl.edu">Sergey A
242 Klibanov </a> for developing the JDE's javadoc
244 </p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e633"></a><a name="Abbrevs"></a>Abbreviations</h2></div></div></div><p>
245 The JDEE allows you to use abbreviations for Java keywords and
246 control flow constructs. The following sections explain how to
247 use these abbreviations.
248 </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e639"></a><a name="KeywordAbbrevs"></a>Keyword
249 Abbreviations</h4></div></div></div><p>The JDEE defines a set of abbreviations for Java keywords.
250 When you type one of these abbreviations followed by a space
251 in a Java source buffer, the JDE optionally expands the
252 abbreviation into the keyword. For example, when the
253 abbreviation mode is enabled, you need only type
254 <code class="varname">fa</code> followed by a space to enter the Java
255 keyword <code class="varname">false</code>. To enable or disable
256 abbreviation mode by default for a project, select
257 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Project</strong></span>-><span><strong class="guisubmenu">Options
258 </strong></span>-><span><strong class="guimenuitem">General</strong></span>
259 and toggle the boolean variable
260 <code class="varname">jde-enable-abbrev-mode</code>. To toggle
261 abbreviation mode on or off during a session, select
262 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Code Generation</strong></span>-><span><strong class="guisubmenu">Modes</strong></span>-><span><strong class="guimenuitem">Abbrev</strong></span>. To change, remove, or add an abbreviation, edit
263 the variable <code class="varname">jde-mode-abbreviations</code> in the
264 project customization buffer.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The JDE's Java keyword expansion facility is based
265 on the Emacs <code class="varname">abbrev-mode</code> facility. For
266 more information, see the Emacs user manual.</p></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e683"></a><a name="ControlFlowAbbrevs"></a>Control Flow
267 Abbreviations</h4></div></div></div><p>The JDEE defines abbreviations for Java control flow
268 structures, such as if-then-else. When you enter the
269 abbreviation followed by a space, the JDE expands the
270 abbreviation into a corresponding control structure
271 template.</p><div class="example"><a name="d51e689"></a><p class="title"><b>Example 1. Expanding a Control Flow Abbreviation</b></p><p>The if-then-else abbreviation</p><pre class="programlisting">
273 </pre><p>expands to the control flow structure</p><pre class="programlisting">
274 if ( ) { } // end of if () else } // end of if ()else
275 </pre></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e700"></a>Control Flow Abbreviations</h5></div></div></div><p>The JDE defines the following abbreviations for control
276 structures.</p><div class="table"><a name="d51e705"></a><p class="title"><b>Table 1. Control Flow Abbreviations</b></p><table summary="Control Flow Abbreviations" border="1"><colgroup><col><col></colgroup><thead><tr><th>Statement</th><th>Abbreviation</th></tr></thead><tbody><tr><td><code class="varname">if-then</code></td><td><code class="varname">if</code></td></tr><tr><td><code class="varname">else</code></td><td><code class="varname">else</code></td></tr><tr><td><code class="varname">if-then-else</code></td><td><code class="varname">ife</code></td></tr><tr><td><code class="varname">else-if</code></td><td><code class="varname">eif</code></td></tr><tr><td><code class="varname">while</code></td><td><code class="varname">while</code></td></tr><tr><td><code class="varname">for</code></td><td><code class="varname">for</code></td></tr><tr><td><code class="varname">for (int
277 I=0;I<UL;I++)</code></td><td><code class="varname">fori</code></td></tr><tr><td><code class="varname">for (Iterator i = c.iterator();
278 i.hasNext();)</code></td><td><code class="varname">foriter</code></td></tr><tr><td><code class="varname">main method</code></td><td><code class="varname">main</code></td></tr><tr><td><code class="varname">switch</code></td><td><code class="varname">switch</code></td></tr><tr><td><code class="varname">case</code></td><td><code class="varname">case</code></td></tr><tr><td><code class="varname">try</code></td><td><code class="varname">try</code></td></tr><tr><td><code class="varname">catch</code></td><td><code class="varname">catch</code></td></tr><tr><td><code class="varname">try finally</code></td><td><code class="varname">tryf</code></td></tr><tr><td><code class="varname">finally</code></td><td><code class="varname">finally</code></td></tr></tbody></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
279 You must enable the JDE's Java keyword abbreviation mode
280 to use the control flow abbreviations. See <a href="#JavaKeywordCompletion">Java Keyword
281 Completion</a> for more information.
282 </p></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e829"></a>Left Brace Placement</h5></div></div></div><p>
283 The JDE's Java control flow templates support two options
284 for opening brace placement: placement on the first line of
285 the template (Kerningham & Ritchie Style, the default)
286 and placement on a separate line. Type <code class="command">M-x
287 customize-variable jde-gen-k&r</code> to specify
288 the style you prefer.
289 </p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e837"></a>Customizing the Control Flow Templates</h5></div></div></div><p>You can customize the templates to suit any indentation
290 style. To customize the templates, select
291 <span><strong class="guimenu">Project</strong></span>-><span><strong class="guisubmenu">Options</strong></span>-><span><strong class="guimenuitem">Autocode</strong></span> from the JDE menu.</p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e850"></a>Adding Your Own Control Flow Templates</h5></div></div></div><p>
292 Use the <code class="function">jde-gen-define-abbrev-template</code>
293 function to define your own control flow abbreviation in
294 your <code class="filename">.emacs</code> file. For example, the
295 following code defines an abbreviation for an else clause.
296 </p><pre class="programlisting">
297 (jde-gen-define-abbrev-template "melse" '('> "else {" '> 'n
299 </pre><p>The <code class="function">jde-gen-define-abbrev-template</code>
300 function takes two arguments. The first argument is a string
301 that specifies the abbreviation. The section argument is a
302 list defining the text that replaces the abbreviation. The
303 list can contain any of the following elements.</p><div class="table"><a name="d51e868"></a><p class="title"><b>Table 2. Template Elements</b></p><table summary="Template Elements" border="1"><colgroup><col><col></colgroup><thead><tr><th>Element</th><th>Usage</th></tr></thead><tbody><tr><td>A string.</td><td>The string is inserted into the buffer at
304 point.</td></tr><tr><td>The symbol <code class="varname">'p</code>.</td><td>This position is saved in
305 <code class="varname">tempo-marks</code>.</td></tr><tr><td>The symbol <code class="varname">'r</code>.</td><td>If <code class="varname">tempo-insert</code> is called
306 with <code class="varname">ON-REGION</code> non-nil the
307 current region is placed here. Otherwise it works
308 like 'p.</td></tr><tr><td><code class="varname">(p PROMPT <NAME>
309 <NOINSERT>)</code></td><td>If <code class="varname">tempo-interactive</code> is
310 non-nil, the user is prompted in the minbuffer with
311 <code class="varname">PROMPT</code> for a string to be
312 inserted. If the optional parameter
313 <code class="varname">NAME</code> is non-nil, the text is
314 saved for later insertion with the
315 <code class="varname">s</code> tag. If there already is
316 something saved under <code class="varname">NAME</code> that
317 value is used instead and no prompting is made. If
318 <code class="varname">NOINSERT</code> is provided and non-nil,
319 nothing is inserted, but text is still saved when a
320 <code class="varname">NAME</code> is provided. For clarity,
321 the symbol <code class="varname">'noinsert</code> should be
322 used as argument.</td></tr><tr><td><code class="varname">(P PROMPT <NAME>
323 <NOINSERT>)</code></td><td>Works just like the previous element, but
324 forces <code class="varname">tempo-interactive</code> to be
325 true.</td></tr><tr><td><code class="varname">(r PROMPT <NAME>
326 <NOINSERT>)</code></td><td>Like the previous, but if
327 <code class="varname">tempo-interactive</code> is
328 <code class="varname">nil</code> and
329 <code class="varname">tempo-insert</code> is called with
330 <code class="varname">ON-REGION</code> non-nil, the current
331 region is placed here. This usually happens when you
332 call the template function with a prefix
333 argument.</td></tr><tr><td><code class="varname">(s NAME)</code></td><td>Inserts text previously read with the
334 <code class="varname">(p ..)</code> construct. Finds the
335 insertion saved under <code class="varname">NAME</code> and
336 inserts it. Acts like <code class="varname">'p</code> if
337 <code class="varname">tempo-interactive</code> is
338 <code class="varname">nil</code>.</td></tr><tr><td><code class="varname">'&</code></td><td>If there is only whitespace between the line
339 start and point, nothing happens. Otherwise a
340 newline is inserted.</td></tr><tr><td><code class="varname">'%</code></td><td>If there is only whitespace between point and
341 end-of-line nothing happens. Otherwise a newline is
342 inserted.</td></tr><tr><td><code class="varname">'n</code></td><td>Inserts a newline.</td></tr><tr><td><code class="varname">'></code></td><td>The line is indented using
343 <code class="varname">indent-according-to-mode</code>. Note
344 that you often should place this item after the text
345 you want on the line.</td></tr><tr><td><code class="varname">'n></code></td><td>Inserts a newline and indents line.</td></tr><tr><td><code class="varname">'r></code></td><td>Like <code class="varname">r</code>, but it also indents
346 the region.</td></tr><tr><td><code class="varname">'o</code></td><td>Like <code class="varname">'%</code> but leaves the point
347 before the new line.</td></tr><tr><td>Anything else.</td><td>It is evaluated and the result is treated as an
348 element to be inserted. One additional tag is useful
349 for these cases. If an expression returns a list
350 <code class="varname">'(l foo bar)</code>, the elements after
351 <code class="varname">'l</code> will be inserted according to
352 the usual rules. This makes it possible to return
353 several elements from one expression.</td></tr></tbody></table></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e1049"></a>Enabling Variable Content</h5></div></div></div><p>Some templates optionally prompt you for items to insert
354 into the template. To enable prompting, set the variable
355 <code class="varname">tempo-interactive</code> to a
356 non-<code class="varname">nil</code> value in your
357 <code class="filename">.emacs</code> file.</p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e1063"></a>Disabling the Control Flow Abbreviations</h5></div></div></div><p>To disable the control flow abbreviations, set the
358 variable <code class="varname">jde-gen-cflow-enable</code> off.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Thanks to...</h3><p>Thanks to Eric D. Friedman >friedman@lmi.net<
359 for contributing the control flow templates.</p></div></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e1076"></a><a name="CodeCompletion"></a>Completing Expressions</h2></div></div></div><p>
360 Both Emacs and the JDEE provide commands for completing incomplete
361 expressions. Emacs provides commands that work for any expression
362 but only if the completions exist in an open buffer. The JDEE
363 provides completion commands that work for any Java method or field
364 name that exists on <code class="varname">jde-global-classpath</code>.
365 The following sections explain how to use completion facilities
366 supplied by the JDEE and by Emacs itself.
368 </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e1085"></a><a name="FieldAndMethodCompletion"></a>Completing Method
369 and Field Names</h4></div></div></div><p>
370 The JDEE provides comamnds that can complete an incomplete
371 field or method name. All the methods determine the set of
372 possible completions for an incomplete field or method name at
373 point. They differ in how they present the completions to you
374 for selection. The commands include:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="command">jde-complete-in-line</code></p><p>This command uses the first completion that it finds
375 to complete the method or field name at point. If multiple
376 completions exist, it allows you to cycle through the
377 completions, each completion replacing the previous in the
378 source buffer. See <a href="#InLineCompletion">Using
379 In-Line Completion</a> for more information.
380 </p></li><li><p><code class="command">jde-complete-menu</code></p><p>
381 This command displays a menu of possible completions for
382 the incomplete method or field name at point. It enters
383 the completion that you select in the source buffer. See
384 <a href="#MenuCompletion">Using Menu-Based
385 Completion</a> for more information.
386 </p></li><li><p><code class="command">jde-complete-minibuf</code></p><p>
387 This command uses the minibuffer to display possible
388 completions for the incomplete method or field name at
389 point. The comamnd enters the completion that you select
390 in the source buffer. See <a href="#MinibufferCompletion">Using Minibuffer-Based
391 Completion</a> for more information.</p></li><li><p><code class="command">jde-complete</code></p><p>This is the JDEE's user-definable "standard"
392 completion command. It delegates completion to one of the
393 JDEE's other completion commands
394 (<code class="command">jde-complete-menu</code> by default) or to a
395 custom completion function that you specify (see <a href="SelectCompletionMethod">Selecting a Completion
396 Method</a> for more information.) The
397 <code class="command">jde-complete</code> command is bound by
398 default to the key combination <code class="command">C-c C-v
399 C-.</code>. If you prefer another binding, use the
400 customization variable <code class="varname">jde-key-bindings</code>
401 to change the binding.
402 </p></li></ul></div><p>
403 The JDEE's field and method completion commands use the
404 Beanshell to run Java code that in turn uses Java's reflection
405 (class introspection) capability to determine the fields and
406 methods defined for the class of object at point. The commands
407 start the Beanshell if it is not running. This can cause a
408 noticeable delay in completion the first time it is used in a
409 session. The response can also be slow for classes containing
410 many methods and fields.
411 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>See <a href="#SpeedingUpCompletion">Speeding Up Completion</a>
412 for some tips on how you can dramatically speed up field and
413 method completion.</p></div><p>
414 Completion works only for compiled classes that reside in the
415 classpath defined by <code class="varname">jde-global-classpath</code>,
416 if set, otherwise by the <code class="varname">CLASSPATH</code>
417 environment variable when the Beanshell starts. Thus, if the
418 JDEE is unable to complete a method or field, make sure that
419 the class that defines the field or method is compiled and
420 exists on the classpath defined by
421 <code class="varname">jde-global-classpath</code>, if set, otherwise by
422 the <code class="varname">CLASSPATH</code> environment variable.
424 The JDEE completion commands work for all of the following
426 </p><div class="itemizedlist"><ul type="disc"><li><p>objects referenced by variables declared in the
427 current buffer</p></li><li><p>static fields and methods</p></li><li><p>
428 fields and methods of objects defined by the current class
431 Names of fields and methods of the current class must
432 start with <code class="varname">this</code> or <code class="varname">.</code>
433 (period). Names of fields and methods declared by the
434 parent of the current class must start with
435 <code class="varname">super</code>.
436 </p><p>For example, this command completes</p><pre class="programlisting">
439 objects referenced by the fields of objects referenced by
440 variables declared in the current class or its parent or
442 </p><p>For example, this command completes</p><pre class="programlisting">
445 objects returned by methods of objects referenced by
446 variables defined in the current
448 For example, this command completes
449 </p><pre class="programlisting">
450 Toolkit.getDefaultToolkit().get ^
452 objects referenced by method parameters</p><p>
453 For example, this command completes
454 </p><pre class="programlisting">
455 void setColor(String color) { color.get ^ }
456 </pre></li></ul></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e1210"></a><a name="SelectStdCompletionMethod"></a> Selecting a
457 Completion Method</h5></div></div></div><p>The JDEE's generic completion command,
458 <code class="command">jde-complete</code> delegates completion to one
459 of several specific completion commands supplied by the JDEE
460 or to a custom completion method that you supply. This
461 allows you to customize <code class="command">jde-complete</code> to
462 use the completion method that you prefer.</p><p>To specify your preferred completion method:</p><div class="orderedlist"><ol type="1"><li><p>Open a customization buffer for
463 <code class="varname">jde-complete-function</code>.</p><div class="screenshot"><div class="mediaobject"><img src="images/completion_sel_method.gif"></div></div></li><li><p>Select the completion command that implements the
464 completion method you prefer.</p></li><li><p>If you selected <code class="varname">Custom</code> as your
465 preferred completion function, enter the name of the
466 custom completion function in the adjacent edit field,
467 replacing the existing contents
468 (<code class="varname">ignore</code> by default.).
469 </p></li><li><p>Save your selection in your
470 <code class="filename">.emacs</code> or project file.
471 </p></li></ol></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e1253"></a><a name="MenuCompletion"></a>Using Menu-Based
472 Completion</h5></div></div></div><p>The <code class="command">jde-complete-menu</code> displays a
473 popup menu of completions for the method or field name at
474 point. Selecting a completion from the menu causes the
475 command to use it to complete the method or field at point.
476 This section assumes that you have selected
477 <code class="command">jde-complete-menu</code> as your standard
479 </p><p>To select completions from a menu:</p><div class="orderedlist"><ol type="1"><li><p>Position point immediately following the partially
480 complete field or method name.</p><div class="screenshot"><div class="mediaobject"><img src="./images/completion_menu1.gif"></div></div></li><li><p>Type the <code class="command">C-c C-v C-.</code> key combination.</p><p>A menu of completions pops up.</p><div class="screenshot"><div class="mediaobject"><img src="./images/completion_menu2.gif"></div></div></li><li><p>Select the desired completion from the menu.</p><p>The JDEE inserts the completion at point in the
481 buffer.</p><div class="screenshot"><div class="mediaobject"><img src="./images/completion_menu3.gif"></div></div></li></ol></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e1296"></a><a name="InLineCompletion"></a>Using In-Line
482 Completion</h5></div></div></div><p>
483 The <code class="command">jde-complete-in-line</code> command allows
484 you to select completions at the point of insertion in the
485 source buffer. The command finds all the fields and methods
486 that complete the name at point. It then inserts the first
487 potential completion in the buffer at point. Repeatedly
488 executing the command causes the JDEE to cycle through the
489 other potential completions. If the completion is a method
490 name, the command completes the method name and displays the
491 method signature in the minibuffer.
493 The <code class="command">jde-complete-in-line</code> command is bound
494 to <code class="command">C-c C-v .</code>. You can use this
495 combination to invoke the command or <code class="command">C-c C-v
496 C-.</code>, if you have selected this command as your
497 preferred completion method. The following examples use the
498 <code class="command">C-c C-v .</code> combination.
499 </p><div class="example"><a name="d51e1319"></a><p class="title"><b>Example 1. Completing a String Method Name</b></p><p>
501 <span class="keysym">C-c</span>-<span class="keysym">C-v</span>-<span class="keysym">.</span>
502 </p><pre class="programlisting">
505 completes the method name at point as follows</p><pre class="programlisting">
506 String s; s.getClass( ^
507 </pre><p>and displays</p><pre class="programlisting">
508 java.lang.Class getClass()
509 </pre><p>in the minibuffer. Repeatedly typing
510 <span class="keysym">C-c</span>-<span class="keysym">C-v</span>-<span class="keysym">.</span>
511 cycles through all the other get methods for the Java
512 <code class="varname">String</code> class.</p></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e1355"></a><a name="SpeedingUpCompletion"></a>Speeding Up Completion</h5></div></div></div><p>Here are two ways you can significantly speed up field
513 and method completion:
514 </p><div class="itemizedlist"><ul type="disc"><li><p>Byte-compile the eieio and JDEE packages.</p><p>The beanshell package, the Emacs interface to the
515 BeanShell, is based on the eieio object-oriented Lisp
516 package for Emacs. Completion uses the BeanShell heavily
517 to determine the class of the field or method at point.
518 Thus compiling eieio and beanshell.el improves
519 completion's performance, dramatically in my tests.
520 </p></li><li><p>Import by class, not by package, in your Java files.
521 </p><p>Every package import, e.g.,
522 <code class="filename">java.util.*</code>, requires invoking the
523 BeanShell to determine the fully qualified name of the
525 <code class="function">jde-parse-get-qualified-name</code>).
526 A Beanshell invocation is by far the most time-consuming
527 operation required for completion. Thus eliminating the
528 use of package-level imports can significantly
530 </p></li></ul></div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e1378"></a><a name="DynamicKeywordCompletion"></a>Dynamic Keyword Completion</h4></div></div></div><p>Emacs provides dynamic completion commands that attempt
531 to find completions for the word at point in the current
532 buffer or other buffers.
533 </p><div class="example"><a name="d51e1384"></a><p class="title"><b>Example 2. Using Dynamic Completion</b></p><p>
534 Suppose that the current source buffer contains the class
535 names <code class="varname">Component</code> and
536 <code class="varname">Container</code>. Now suppose you enter
537 <code class="varname">Co</code> somewhere in the buffer and type
538 <span><strong class="keycap">M</strong></span>-<span><strong class="keycap">/</strong></span>.
540 The text <code class="varname">Component</code> replaces
541 <code class="varname">Co</code> in the buffer.
543 <span><strong class="keycap">M</strong></span>-<span><strong class="keycap">/</strong></span>
544 again changes <code class="varname">Component</code> to
545 <code class="varname">Container</code>. In this way, you can cycle
546 through all the possible completions for
547 <code class="varname">Co</code> in the current buffer.
548 </p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e1427"></a>Dynamic Completion Commands</h5></div></div></div><p>Emacs provides two dynamic completion commands.</p><p>
549 The <code class="command">dabbrev-expand</code> command is bound to
551 <span><strong class="keycap">M</strong></span>-<span><strong class="keycap">/</strong></span>
552 by default. It searches the current buffer for completions
553 of the word at point and, if none are found, other buffers
554 of the same type. For example, if the current buffer is a
555 Java source buffer, it searches other Java source buffers
556 for completions if none are found in the active buffer.
558 The <code class="command">hippie-expand</code> command provides more
559 extensive search capabilities. See the docstrings for these
560 functions for more information.
561 </p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e1448"></a>Electric Return</h5></div></div></div><p>In electric return mode, pressing the
562 <span><strong class="keycap">Enter</strong></span> key causes the JDEE to close open
563 braces at the end of a line. To enable or disable this
564 mode by default, customize <code class="varname">jde-electric-return-p</code>.
565 To turn the mode on or off during a session, select <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Code Generation</strong></span>-><span><strong class="guisubmenu">Modes</strong></span>-><span><strong class="guimenuitem">Electric Return</strong></span>.</p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e1469"></a><a name="GeneratingCode"></a>Generating Code</h2></div></div></div><p>The JDE provides the following code generation capabilities.</p><div class="itemizedlist"><ul type="disc"><li><p>Code wizards</p></li><li><p>Code templates</p></li></ul></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e1482"></a><a name="GeneratingImportStatements"></a>Generating Import Statements</h4></div></div></div><p>The JDEE provides a set of commands that generate and
566 organize import statements in the current buffer. The commands
567 automate the following tasks:</p><div class="itemizedlist"><ul type="disc"><li><p>Generate an import statement for the class at point (see
568 <a href="#ImportingClasses">Importing Classes</a>).</p></li><li><p>Generate import statements for all classes in the current
569 buffer that need import statements (see
570 <a href="#ImportingAllClasses">Importing All Classes</a>).</p></li><li><p>Expand a package import statement into specific class imports (see
571 <a href="#ExpandingPackageImports">Expanding Package Imports</a>).</p></li><li><p>Collapse class imports into a package import statement (see
572 <a href="#CollapsingClassImports">Collapsing Class Imports</a>).</p></li><li><p>Group import statements (see
573 <a href="#GroupingImports">Grouping Imports</a>).</p></li><li><p>Sort import statements alphabetically (see
574 <a href="#SortingImports">Sorting Imports</a>).</p></li><li><p>Delete superfluous import statements (see
575 <a href="#DeletingImports">Deleting Imports</a>).</p></li></ul></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e1531"></a><a name="ImportingClasses"></a>Importing Classes</h5></div></div></div><p>
576 The <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Import</strong></span>-><span><strong class="guimenuitem">Class</strong></span>
577 (<code class="command">jde-import-find-and-import</code>,
578 <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">c</strong></span>
579 <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">v</strong></span>
580 <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">z</strong></span>) command
581 generates an import statement for the
582 class at point in the current buffer. It inserts the import
583 statement at the head of the buffer.
584 </p><p>This command uses the BeanShell to search the classpath
585 of the current project for classes that match the name of
586 the class at point. The class name may be unqualified.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
587 The classpath that the import wizard searches for import
588 candidates is the classpath specified by the value of
589 <code class="varname">jde-global-classpath</code> for the current
591 </p></div><p>If the command finds more than one class of the same
592 unqualified name on the current classpath, it prompts you to
593 select one of the classes to import.</p><p>
594 The customization variable
595 <code class="varname">jde-import-excluded-classes</code> allows
596 you to specify rules for excluding classes from
597 consideration for import into the current source file. If
598 the import command finds any classes on the classpath that
599 belong to the list of prohibited classes, it removes them
600 from the list of classes considered for import into the
602 </p><p>You can use either regular expressions or Lisp functions to
603 specify class exclusion rules. For each rule, you can also
604 specify that all classes whose unqualified names match the
605 rule be excluded from consideration for import. This is
606 useful for preventing the JDEE from importing alternate
607 implementations of standard Java classes that do not need to
608 be imported.</p><p>For example, the default setting for
609 <code class="varname">jde-import-excluded-classes</code> includes a
610 rule to exclude all classes belonging to the
611 <code class="varname">java.lang</code> package because every Java
612 class implicitly imports this package. The default setting
613 for <code class="varname">jde-import-excluded-classes</code> also
614 excludes all unqualified synonyms of classes belonging to
615 the <code class="varname">java.lang</code> package. This prevents
616 importation of alternate implementations of these classes,
617 e.g., alternate implementations of
618 <code class="varname">java.lang.String</code>, included in some
619 commonly used class libraries and intended for internal use.
620 See the docstring for
621 <code class="varname">jde-import-excluded-classes</code> for more
622 information.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Thanks to ...</h3><p><a href="mailto:len@reeltwo.com">Len
623 Trigg</a> for contributing the initial
624 implementation of the import wizard and to
625 Martin Schwarmberger for significantly
626 enhancing the import wizard.
627 </p></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e1610"></a><a name="ImportingAllClasses"></a>Importing All Classes</h5></div></div></div><p>The <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Code Generation</strong></span>-><span><strong class="guisubmenu">Import</strong></span>-><span><strong class="guimenuitem">All</strong></span> (<code class="command">jde-import-all</code>,
628 <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">c </strong></span>
630 <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">v </strong></span>
631 <span><strong class="keycap">z</strong></span>
632 ) imports all the classes that need to be
633 imported into the current buffer.
635 The command imports all classes that meet the following
636 conditions:</p><div class="itemizedlist"><ul type="disc"><li><p>The class's base name begins with an uppercase letter.</p></li><li><p>The class's base name contains at least one noninitial
637 lowercase letter.</p></li><li><p>The class is not already imported into the buffer.</p></li><li><p>The class is not in
638 <code class="varname">jde-import-excluded-classes</code>.</p></li><li><p>The class exists on the current classpath.</p></li></ul></div><p>If more than one import candidate with the same base
639 name exists on the classpath, the JDEE displays a dialog
640 that allows you to select one of the candidates.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>You can use the <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Code Generation</strong></span>-><span><strong class="guisubmenu">Import</strong></span>-><span><strong class="guimenuitem">Import All Unique</strong></span> (<code class="command">jde-import-all-unique</code>
641 ) command to avoid the dialog box. This command imports all classes
642 whose unqualified names appear only once on the classpath.</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Thanks to ...</h3><p><a href="mailto:p.lord@russet.org.uk">Phillip
643 Lord</a> for contributing the initial implementation
644 of the Import All Wizard.</p></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e1690"></a><a name="ExpandingPackageImports"></a>Expanding Package Imports</h5></div></div></div><p>To expand a package import statement, select <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Code Generation</strong></span>-><span><strong class="guisubmenu">Import</strong></span>-><span><strong class="guisubmenu">Expand Package Imports</strong></span>
645 (<code class="command">jde-import-expand-imports</code>). This command replaces
646 a package import statement, e.g.,
647 </p><pre class="programlisting">
649 </pre><p>with import statements for the members of that package referenced
650 by the current buffer, e.g.,</p><pre class="programlisting">
651 import java.io.BufferedReader;
652 import java.io.InputStreamReader;
653 import java.io.IOException;
654 </pre></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e1717"></a><a name="CollapsingClassImports"></a>Collapsing Class Imports</h5></div></div></div><p>To collapse class import statements in the current buffer into
655 package imports, select <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Code Generation</strong></span>-><span><strong class="guisubmenu">Import</strong></span>-><span><strong class="guisubmenu">Collapse Class Imports</strong></span> (<code class="command">jde-import-collapse-imports</code>). This command
656 collapses imports for any package that contains as many as or more than the
657 number of imports specified by <code class="varname">jde-import-collapse-imports-threshhold</code>.
658 The default value of this variable is 2. This causes this command to collapse
659 imports for any package from which the current buffer imports two or more classes.
660 For example, this command, by default, collapses
661 </p><pre class="programlisting">
662 import java.io.BufferedReader;
663 import java.io.InputStreamReader;
664 import java.io.IOException;
665 </pre><p>to</p><pre class="programlisting">
667 </pre></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e1745"></a><a name="GroupingImports"></a>Grouping Imports</h5></div></div></div><p>To organize import statements into groups of related imports, select
668 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Code Generation</strong></span>-><span><strong class="guisubmenu">Import</strong></span>-><span><strong class="guisubmenu">Organize Imports</strong></span> (<code class="command">jde-import-organize</code>). By default this command
669 groups import statements into two groups separated by a blank line. The first
670 group contains all imports from the java and javax packages. The other group
671 contains imports from all other packages. The imports are sorted alphabetically
672 in ascending order in each group, e.g.,
673 </p><pre class="programlisting">
674 import java.io.InputStreamReader;
675 import java.util.Hashtable;
676 import javax.swing.JFrame;
677 import javax.swing.JPanel;
679 import jmath.LinearSystem;
681 </pre><p>The following variables allow you to customize the organization of imports
682 into groups:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="varname">jde-import-group-function</code></p><p>This variable allows you to specify a function that assigns imports
683 to groups. The default group function is <code class="function">jde-import-group-of</code>,
684 which uses rules specified by the following variable to assign imports to
685 groups.</p></li><li><p><code class="varname">jde-import-group-rules</code></p><p>This variable specifies a list of rules for assigning import statements to
686 group, e.g., <code class="filename">'(("^javax\\." . "Swing"))</code>,
687 Each rule consists of two parts: a regular expression and an optional
688 group name specifier. The <code class="function">jde-import-group-of</code> function assigns
689 an import statement to the group if it matches the regular expression. The group name
690 specifier is either a string that specifies the name or an index to a component of the regular
691 expression to be used as the group name.</p></li><li><p><code class="varname">jde-import-insert-group-names</code></p><p>Specifies whether to insert an import group's name in the buffer.</p></li><li><p><code class="varname">jde-import-default-group-name</code></p><p>Specifies the default name for an import group.</p></li><li><p><code class="varname">jde-import-blank-line-between-groups</code></p><p>Specifies whether to insert a blank line between import groups.</p></li><li><p><code class="varname">jde-import-sorted-groups</code></p><p>Specifies whether and how to sort groups of packages. Options include
692 no sorting, in the order specified by grouping rules, or in ascending or
693 descending alphabetical order.</p></li></ul></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e1814"></a><a name="DeletingUnneededImports"></a>Deleting Unneeded Imports</h5></div></div></div><p>
694 To delete superfluous import statements from the current buffer, select
695 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Code Generation</strong></span>-><span><strong class="guisubmenu">Import</strong></span>-><span><strong class="guisubmenu">Delete Unneeded</strong></span>
696 (<code class="command">jde-import-kill-extra-imports</code>). This command deletes all
697 import statements for classes that are not actually referenced by the class
698 in the current buffer.
699 </p></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e1833"></a><a name="CodeWizards"></a>Code Wizards</h4></div></div></div><p>
700 The JDE provides a set of procedural code generators called
701 code wizards. They include:
702 </p><div class="table"><a name="d51e1839"></a><p class="title"><b>Table 1. Code Wizards</b></p><table summary="Code Wizards" border="1"><colgroup><col><col></colgroup><thead><tr><th><p>Wizard</p></th><th><p>Generates...</p></th></tr></thead><tbody><tr><td>
703 <p><a href="#MethodOverrideWizard">Method
704 Override Wizard</a></p>
706 <p> A method that overrides a method inherited by
707 the class containing point. </p>
709 <p><a href="#InterfaceWizard">Interface
712 <p>Implementation of an interface in the class
713 containing point. </p>
715 <p><a href="#DelegateWizard">Delegate
718 <p> Methods that delegate tasks to a specified
721 <p><a href="#AbstractClassWizard">Abstract Class
724 <p>Implementations of the abstract methods
725 inherited by the class containing point. </p>
727 <p><a href="#GetSetWizard">Get/Set
730 <p>Get and set methods for the private fields of
731 the class containing point. </p>
732 </td></tr></tbody></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
733 Some of the wizards use the BeanShell to run Java code. A
734 wizard starts the Beanshell interpreter if it is not already
735 running. Thus, you may experience a slight delay when
736 invoking a wizard for the first time in a session.
737 </p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e1915"></a><a name="MethodOverrideWizard"></a>Method Override
738 Wizard</h5></div></div></div><p>
739 The method override wizard generates a skeleton method that
740 overrides a similarly named method defined by a superclass.
741 </p><p>To override a method of a superclass: </p><div class="orderedlist"><ol type="1"><li><p>
742 Position the Emacs point at the location in the buffer
743 where you want the generated method to appear.
745 The point must be within the class that is overriding
748 </p><div class="screenshot"><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="472"><tr style="height: 328px"><td><img src="images/OverrideMeth1.gif" width="472" alt="Screen capture showing point inside a
 class."></td></tr></table></div></div><p>
751 <span><strong class="guisubmenu">Wizards</strong></span>-><span><strong class="guimenuitem">Override
752 Method</strong></span> from the
753 <span><strong class="guimenu">JDE</strong></span> menu or enter
754 <span><strong class="keycap">M</strong></span>-<span><strong class="keycap">x</strong></span> <code class="varname">jde-wiz-overrided-method</code>.
756 </p><div class="screenshot"><div class="mediaobject"><img src="images/OverrideMeth2.gif" alt="Screen shot showing
 Wizards menu."></div></div><p>
758 The JDE prompts you to enter the name of the method to
759 be overridden in the minibuffer.
761 </p><div class="screenshot"><div class="mediaobject"><img src="images/OverrideMeth3.gif" alt="Screen shot showing prompt for
 method name. "></div></div><p>
763 The name must be the name of a method defined by an
764 ancestor of the class in which the Emacs point is
765 located. The compiled class of the ancestor must be on
766 the classpath specified by
767 <code class="varname">jde-global-classpath</code>.
769 Enter the name of the method to be overridden.
771 If the ancestors of the class in which you are
772 overriding the method define more than one method of the
773 same name, the wizard displays a dialog buffer that
774 lists the methods. For example, Java's awt class
775 hierarchy defines several variants of the method
776 <code class="varname">repaint</code>. If you specify
777 <code class="varname">repaint</code> as the method to override,
778 the JDE displays the following dialog buffer:
780 </p><div class="screenshot"><div class="mediaobject"><img src="images/OverrideMeth4.gif" alt="Screen shot showing dialog
 buffer for selecting method. "></div></div><p>
782 The dialog buffer lists the signature of each variant of
783 the method you specified. Next to each signature is a
784 radio button. The radio button of the currently selected
785 signature contains an asterisk. To select another
786 signature, right-click the radio button next to the
787 variant. To confirm your selection and dismiss the
788 dialog, right-click the <span class="guibutton">[Ok]</span>
791 Select the method variant you want to override and click
792 the <span class="guibutton">[Ok]</span> button.
793 </p><p>The wizard inserts a skeleton implementation of
794 the selected method at the current point in the Java
795 source buffer.</p><p>
796 </p><div class="screenshot"><div class="mediaobject"><img src="images/OverrideMeth5.gif" alt="Screen shot showing the inserted
 method. "></div></div><p>
798 The wizard also inserts import statements for any
799 classes referenced by the method that are not already
800 imported by the containing class either explicitly or
801 implicitly. The wizard inserts the import statements at
802 the head of the source buffer after any existing import
803 statements, or any package statement, or the first blank
805 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
806 The method override wizard uses the BeanShell to
807 create the interface implementation. If the BeanShell
808 is not currently running, the wizard starts the
809 BeanShell. Thus, if the BeanShell is not already
810 running, you may experience a short pause the first
811 time you override a method.
812 </p></div></li></ol></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e2041"></a><a name="InterfaceWizard"></a>Interface Wizard</h5></div></div></div><p>
813 This wizard creates a skeleton implementation of any
814 interface defined on the classpath specified by
815 <code class="varname">jde-global-classpath</code>.
816 </p><p>To create an implementation of an interface: </p><div class="orderedlist"><ol type="1"><li><p>
817 If the interface is to be implemented by a new class,
818 create the class in a buffer.
820 Position the Emacs point at the point in the class where
821 you want the implementation of the interface's methods
825 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Wizards</strong></span>-><span><strong class="guimenuitem">Implement Interface</strong></span> or enter
826 <span><strong class="keycap">M</strong></span>-<span><strong class="keycap">x
827 </strong></span><code class="varname">jde-wiz-implement-interface</code>.
833 The JDE prompts you to enter the name of the interface
835 </p></li><li><p>Enter the fully qualified name of the interface, for
837 <code class="classname">java.awt.Event.MouseListener</code>.</p><p>
838 The wizard inserts skeleton implementations of the
839 methods declared by the interface at the current point
840 in the current buffer. It inserts import statements for
841 any classes required by the interface at the head of the
842 current buffer (only if import statements do not already
843 exist for the required classes). It also updates or
844 creates an implements clause for the class.
845 </p></li></ol></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
846 The interface wizard uses the BeanShell to create the
847 interface implementation. If the BeanShell is not
848 currently running, it starts the BeanShell. Thus, if the
849 BeanShell is not already running, you may experience a
850 short pause the first time you use the wizard. </p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Thanks to ...</h3><p><a href="mailto:friedman@lmi.net">Eric
851 Friedman</a> for creating the framework for the
852 interface, method override, and abstract class wizards and
853 for contributing the initial implementation of the
854 interface wizard.</p></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e2098"></a><a name="DelegateWizard"></a>Delegate Wizard</h5></div></div></div><p>
855 This wizard generates methods that delegate calls to a class
856 in the current buffer to an attribute of the class, i.e., to
857 an object that is a field of the current class. For example,
858 if the current buffer contains class
859 <code class="classname">A</code> and <code class="classname">A</code> has
860 an attribute, <code class="varname">A.b</code>, that is an instance
861 of class <code class="classname">B</code>, this wizard generates
862 all the public methods of class <code class="classname">B</code> in
863 <code class="classname">A</code> and delegates handling of those
864 methods to <code class="varname">b</code>.
865 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Thanks to...</h3><p>
866 <a href="mailto:cfhart@Z-TEL.com">Charles Hart</a>
867 for contributing this wizard.
868 </p></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e2133"></a><a name="GetSetWizard"></a>Get/Set Wizard</h5></div></div></div><p>
869 This wizard generates get and set methods for the private
870 fields of the class at point, but only if the fields do not
871 already have get or set methods. To generate the methods,
872 move point to the point in the class where you want the get
873 and set methods to appear. Then select
874 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Code
875 Generation</strong></span>-><span><strong class="guisubmenu">Wizards</strong></span>-><span><strong class="guimenuitem">Generate Get/Set Methods...</strong></span> or enter
876 <span><strong class="keycap">M</strong></span>-<span><strong class="keycap">x </strong></span>
877 <code class="varname">jde-wiz-get-set-methods</code>
878 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Thanks to...</h3><p>
879 <a href="mailto:jslopez@forumsys.com">Javier
880 Lopez</a> and <a href="mailto:sandip.chitale@brokat.com">Sandip
881 Chitale</a> for contributing this wizard.
882 </p></div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e2169"></a><a name="CodeTemplates"></a>Code Templates</h4></div></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e2173"></a><a name="BufferTemplates"></a>Buffer Templates</h5></div></div></div><p>These commands create buffers containing a skeleton Java class.
883 Each command prompts you to enter the path to a new Java source
884 file. They then create a buffer for the new file and insert a
885 template for a class of the same name as the newly created file.
886 In particular, the command </p><div class="itemizedlist"><ul type="disc"><li><p>
887 <span><strong class="guimenu">Files</strong></span>-><span><strong class="guisubmenu">JDE New</strong></span>-><span><strong class="guimenuitem">Class</strong></span> creates a buffer containing a generic Java public class.
889 <span><strong class="guimenu">Files</strong></span>-><span><strong class="guisubmenu">JDE New</strong></span>-><span><strong class="guimenuitem">Console</strong></span> creates a buffer containing the main class of a
890 Java console application.
892 <span><strong class="guimenu">Files</strong></span>-><span><strong class="guisubmenu">JDE New</strong></span>-><span><strong class="guimenuitem">Other</strong></span> prompts you to create any of the above buffers or a
893 custom (user-defined) buffer.
894 </p></li></ul></div><p>
895 You can create an empty Java class buffer by selecting
896 <span><strong class="guimenu">Files</strong></span>-><span><strong class="guisubmenu">Open</strong></span>
897 (<span><strong class="keycap">C</strong></span>-<span><strong class="keycap">x</strong></span> <span class="keysym">f</span>) and
898 entering the path for a new file whose root name is the same as
899 the class you want to create and whose extension is <code class="filename">.java.</code>
900 </p><div class="sect5" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d51e2233"></a>Specifying Boilerplate Text</h6></div></div></div><p>
901 You can specify boilerplate text (for example, a copyright
902 notice) to be inserted at the head of class source files
903 created by the JDE. The JDE provides two ways to specify
904 the boilerplate text. The simplest way is to enter the
905 lines of boilerplate text as the value of the
906 customization variable
907 <code class="varname">jde-gen-buffer-boilerplate</code>. Another way
908 to specify the text is to set the value of the
909 customization variable
910 <code class="varname">jde-gen-boilerplate-function</code>to a
911 function that generates the boilerplate text. (The default
912 value of this variable is
913 <code class="varname">jde-gen-create-buffer-boilerplate</code>,
914 which returns the value of the boilerplate variable,
915 <code class="varname">jde-gen-buffer-boilerplate</code>). The
916 functional approach allows you to generate boilerplate
917 text dynamically by evaluating the appropriate Lisp code.
918 By saving the values of boilerplate variables in project
919 files, you can specify different boilerplate text for each
921 </p></div><div class="sect5" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d51e2250"></a>Customization Variables</h6></div></div></div><p>The following JDE customization variables control creation of
922 autocoded Java source buffers:
923 </p><div class="table"><a name="d51e2255"></a><p class="title"><b>Table 2. </b></p><table summary="" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Variable</th><th>Group</th><th>Usage</th></tr></thead><tbody><tr><td><code class="varname">jde-gen-class-buffer-template</code></td><td>Autocode</td><td>Template for a generic public class buffer.</td></tr><tr><td><code class="varname">jde-gen-console-buffer-template</code></td><td>Autocode</td><td>Template for a console application buffer.</td></tr><tr><td><code class="varname">jde-gen-jfc-app-buffer-template</code></td><td>Autocode</td><td>Template for a JFC (Swing) application.</td></tr><tr><td><code class="varname">jde-gen-junit-test-class-buffer-template</code></td><td>Autocode</td><td>Template for a JUnit test case class. This template requires
924 the <a href="http://www.junit.org">JUnit</a> test framework.</td></tr><tr><td><code class="varname">jde-gen-buffer-templates</code></td><td>Autocode</td><td>Specifies templates available to create
925 Java buffers.</td></tr><tr><td><code class="varname">jde-gen-buffer-boilerplate</code></td><td>Autocode</td><td>Specifies lines of text to be inserted
926 at the head of class files.</td></tr><tr><td><code class="varname">jde-gen-boilerplate-function</code></td><td>Autocode</td><td>Specifies a function that returns a string
927 of boilerplate text. The default value is
928 <code class="varname">jde-gen-create-buffer-boilerplate</code>, which returns
929 the value of <code class="varname">jde-gen-buffer-boilerplate</code>.</td></tr></tbody></table></div><p>
930 See <a href="#CustomizingTemplates">Customizing
931 Templates</a> for information on how to customize
932 the class creation templates. </p></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e2340"></a><a name="PointTemplates"></a>Point Templates</h5></div></div></div><p>The following commands insert templates at the current
933 point in the buffer: </p><div class="itemizedlist"><ul type="disc"><li><p>
934 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Generate</strong></span>-><span><strong class="guimenuitem">Get/Set Pair </strong></span>
935 generates an instance variable and a get and set method .
938 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Generate</strong></span>-><span><strong class="guimenuitem">Println </strong></span>
940 </p><pre class="programlisting">System.out.println(...);</pre><p>
943 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Generate</strong></span>-><span><strong class="guimenuitem">Action </strong></span>
944 generates and registers an action listener for a
947 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Generate</strong></span>-><span><strong class="guisubmenu">Listener</strong></span>-><span><strong class="guimenuitem">Window
949 generates and registers a window listener for a specified
952 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Generate</strong></span>-><span><strong class="guisubmenu">Listener</strong></span>-><span><strong class="guimenuitem">Mouse
954 generates and registers a mouse listener for a specified
957 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Generate</strong></span>-><span><strong class="guimenuitem">Other </strong></span>
958 allows you to select any of the above templates or a
959 custom (user-defined) template.
960 </p></li></ul></div><p>The following variables control generation of code at
962 </p><div class="table"><a name="d51e2422"></a><p class="title"><b>Table 3. </b></p><table summary="" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Variable</th><th>Group</th><th>Usage</th></tr></thead><tbody><tr><td><code class="varname">jde-gen-get-set-var-template</code></td><td>Autocode</td><td>Defines a get/set method pair template.</td></tr><tr><td><code class="varname">jde-gen-listener-action-template</code></td><td>Autocode</td><td>Defines an action listener template.</td></tr><tr><td><code class="varname">jde-gen-listener-window-template</code></td><td>Autocode</td><td>Defines a window listener template.</td></tr><tr><td><code class="varname">jde-gen-listener-mouse-template</code></td><td>Autocode</td><td>Defines a mouse listener template.</td></tr><tr><td><code class="varname">jde-gen-inner-class-template</code></td><td>Autocode</td><td>Defines a template for creating a class inside
963 another class or inside an existing source
964 buffer.</td></tr><tr><td><code class="varname">jde-gen-code-templates</code></td><td>Autocode</td><td>Specifies available code templates.</td></tr></tbody></table></div><p>See</p><div class="itemizedlist"><ul type="disc"><li><p>
965 <a href="#CustomizingTemplates">Customizing
966 Templates</a> for information on how to customize
967 templates provided by the JDE.
969 <a href="#CreatingTemplates">Creating
970 Templates</a> for information on how to create
971 templates from scratch.
972 </p></li></ul></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e2500"></a><a name="CustomizingTemplates"></a>Customizing
973 Templates</h5></div></div></div><p>You can customize the JDE's standard code templates,
974 using the Emacs customization feature. </p><p>To customize an autocode template: </p><div class="orderedlist"><ol type="1"><li><p>Select <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Options</strong></span>-><span><strong class="guimenuitem">Autocode</strong></span></p><p>The JDE displays a customization buffer containing
975 the autocode templates. </p></li><li><p>Edit the template to suit your needs.</p><p>The JDE uses the template format defined by
976 <code class="filename">tempo.el</code> to represent class
977 templates. Each template consists of a list of strings,
978 symbols, and functions, each of which represents content
979 to be inserted successively into the buffer at the
980 current point. The strings represent fixed content. The
981 symbols and functions represent variable content. See
982 the docstring for the function
983 <code class="varname">tempo-define-template</code> for more
984 information, including the meaning of special symbols
985 such as <code class="varname">'n</code>. </p></li><li><p>Select the state button associated with the
986 template.</p><p>A menu pops up with a list of options for saving
987 your changes. </p></li><li><p>Save your changes.</p><p>Select
988 <span><strong class="guimenuitem">Save for Future
989 Sessions</strong></span> if you want
990 your changes to apply to all projects. If you want your changes to apply
991 only to the current projects, select <span><strong class="guimenuitem">Set for Current
992 Session</strong></span>. Then select
993 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Options</strong></span>-><span><strong class="guimenuitem">Save Project</strong></span>
994 to save your changes in the current project's project
995 file.</p></li></ol></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e2561"></a><a name="CreatingTemplates"></a>Creating Templates</h5></div></div></div><p>The JDE considers any command (interactive function) that
996 inserts code into a buffer at point to be a template. The JDE
997 uses the Emacs tempo library to create built-in templates.
998 You can use tempo to create your own, add-on templates (see below
999 and the doc for the <code class="varname">tempo-define-template </code>for
1000 more information) or create templates from scratch.
1001 In either case, once you have created a template, you can add it
1002 to the JDE's lists of available code and/or buffer templates,
1003 using the JDE's <code class="varname">jde-gen-code-templates</code> and/or
1004 <code class="varname">jde-gen-buffer-templates</code>
1005 variables, respectively. Adding a template to these lists enables
1006 you to invoke the templates from the JDE menus. When adding a
1007 template, you need to specify a unique title for the template.
1008 These titles enable you to specify the templates when invoking
1009 them, using the JDE's custom code template commands
1010 (<span><strong class="guimenu">Files</strong></span>-><span><strong class="guisubmenu">JDE New</strong></span>-><span><strong class="guimenuitem">Custom</strong></span> and
1011 <span><strong class="guimenuitem">JDE</strong></span>-><span><strong class="guisubmenu">Generate</strong></span>-><span><strong class="guimenuitem">Custom</strong></span>). You can use
1012 auto completion to enter a template title when invoking a custom
1013 code generation command. Note that you can specify different sets
1014 of templates for different projects, by setting and saving the
1015 template list variables in project files. See the following
1016 sections for more information: </p><div class="itemizedlist"><ul type="disc"><li><p><a href="#DefiningTemplate">Defining a Template and
1017 Template Insertion Function</a></p></li><li><p><a href="#RegisterTemplate">Registering Custom
1018 Templates</a></p></li><li><p><a href="#AssignKeyToTemplate">Assigning Keys To
1019 emplates</a></p></li></ul></div><div class="sect5" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d51e2605"></a><a name="DefiningTemplate"></a>Defining a Template
1020 and Template Insertion Function</h6></div></div></div><p>The <code class="varname">tempo-define-template</code> macro
1021 enables you to define a template and a function that
1022 inserts that template at the current point in the current
1023 buffer. You specify the template as a list oftemplate
1024 elements where each element is text, a special symbol, or
1025 a Lisp expression. The function inserts each text element
1026 exactly as specified in the buffer; it replaces special
1027 symbols with some text (e.g., user input), and it replaces
1028 Lisp expressions with the text that results from
1029 evaluating them. </p><p>For example, the following Lisp code </p><pre class="programlisting">
1030 (tempo-define-template "foo"
1032 '("System.out.println(\"foo\");")
1033 ;;template definition "f"
1034 ;; abbreviation "Inserts a print foo message")
1035 ;; template documentation
1036 </pre><p>defines a template for Java code that always prints
1037 "foo" to standard out: </p><pre class="programlisting">
1038 System.out.println("foo");
1039 </pre><p>Notice that the template definition uses the Lisp
1040 string escape character to specify the string
1041 "foo". This is necessary when you want to
1042 include quoted strings in a template definition.)
1043 </p><p>The sample Lisp form also defines an interactive
1044 template function <code class="varname">tempo-template-foo</code>.
1045 Now suppose you insert the sample code in your
1046 <code class="filename">.emacs</code> file. After Emacs starts up,
1047 whenever you enter the command <span><strong class="keycap">M</strong></span>-<span><strong class="keycap">x</strong></span>
1048 <code class="varname">tempo-template-foo,</code> Emacs inserts
1049 </p><pre class="programlisting">
1050 System.out.println("foo");
1051 </pre><p>at the current point in your Java source buffer (or
1052 any buffer, tempo doesn't care). </p><p>The preceding example is admittedly not vary useful
1053 because it always prints the same text. You can create
1054 more useful templates, using special tempo template
1055 symbols and lisp forms. This approach, for example, allows
1056 you to create a template that can print any user-defined
1057 text to standard out: </p><pre class="programlisting">
1058 (tempo-define-template "debug"
1059 ;; template name '("if (debug)" n>
1060 ;; insert new line plus indent
1061 "System.out.println(" (p "Enter debug
1062 message:") ;; Prompts for debug message
1064 ;; abbreviation "Inserts a print debug message")
1065 ;; template documentation
1066 </pre><p>The template function produced by this example prompts
1067 you to enter the text to be printed when inserting the
1068 function into a buffer. In particular, it inserts </p><pre class="programlisting">
1069 if (debug) System.out.println(DEBUG-MESSAGE);
1070 </pre><p>where <code class="varname">DEBUG-MESSAGE</code> is any text
1071 that you enter. For example, suppose you enter </p><pre class="programlisting">
1072 "Selected color = " + color
1073 </pre><p>at the prompt. The template function inserts </p><pre class="programlisting">
1074 if (debug) System.out.println("Selected color =
1076 </pre><p>at the current point in the buffer. </p><p>See the documentation for
1077 <code class="varname">tempo-define-template</code> (type
1078 <span><strong class="keycap">c</strong></span>-<span><strong class="keycap">h</strong></span> <span class="keysym">f</span>
1079 <code class="varname">tempo-define-template</code>) for more
1080 information on creating templates. </p></div><div class="sect5" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d51e2683"></a><a name="RegisterTemplate"></a>Registering Custom
1081 Templates</h6></div></div></div><p>You can register templates that you create with the
1082 JDE. When you register a template with the JDE, it appears
1083 among the list of templates that you can select when you
1084 select <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Generate</strong></span>-><span><strong class="guimenuitem">Other....</strong></span>. You
1085 register a template by customizing the JDE variable
1086 <code class="varname">jde-gen-code-templates</code>. The value of
1087 this variable is a list of the template functions that the
1088 JDE command <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Generate</strong></span>-><span><strong class="guimenuitem">Other....</strong></span> can
1089 invoke. To register a custom template, add its name to the
1090 list. For example, the following screen shows the
1091 customization buffer for
1092 <code class="varname">jde-gen-code-templates</code> after it has
1093 been customized to include the template defined in the
1094 previous example. </p><p>
1095 </p><div class="screenshot"><div class="mediaobject"><img src="images/RegisterTemplate.gif" alt="Screenshot showing customization buffer for
 registering templates."></div></div><p>
1096 </p><p>To insert a template that you have registered </p><div class="procedure"><ol type="1"><li><p>Select <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Generate</strong></span>-><span><strong class="guimenuitem">Other....</strong></span></p><p>The JDE displays the prompt</p><pre class="programlisting">
1098 </pre><p>in the minibuffer. </p></li><li><p>Enter the template's name and press
1099 <span><strong class="keycap">Enter</strong></span></p><p>or,</p><p>press the <span><strong class="keycap">Tab</strong></span> key to display a
1100 list of templates in a completion buffer: </p><p>
1101 </p><div class="screenshot"><div class="mediaobject"><img src="images/TemplateList.gif" alt="Screenshot showing template completion
buffer."></div></div><p>
1102 </p><p>Select the template you want by double-clicking
1103 its name.</p></li></ol></div></div><div class="sect5" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d51e2764"></a><a name="AssignKeyToTemplate"></a>Assigning Keys to
1104 Templates</h6></div></div></div><p>You can assign templates to keyboard keys to speed use
1105 of frequently used templates. For example, insert this
1106 form </p><pre class="programlisting">
1107 (global-set-key [f9] 'jde-gen-to-string-method)
1108 </pre><p>in your <code class="filename">.emacs</code> file to assign the
1109 <span><strong class="keycap">F9</strong></span> function key to the JDE template that
1110 generates a skeleton <code class="varname">toString</code> method.
1111 </p></div></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e2783"></a><a name="CheckStyle"></a>Checking Coding Style</h2></div></div></div><p>The <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guimenuitem">Check Style</strong></span> command (<span class="keysym">M</span>-<span class="keysym">x</span> <code class="command">jde-checkstyle</code>) command checks
1112 the current buffer for conformity to a Java coding standard. The
1113 default standard is that specified by Sun Microsystems. Execute
1114 <code class="command">jde-checkstyle-customize</code> to customize the
1115 command to support your own coding standard.
1116 </p><p>The command displays a list of stylistic faults in a popup
1117 buffer. Click the error message to display the line that violates
1118 the standard.</p></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e2809"></a><a name="CompilingJavaPrograms"></a>Compiling Java Programs</h2></div></div></div><p>To compile the source file in the current buffer, select
1119 <span><strong class="guimenuitem">JDE</strong></span>-><span><strong class="guimenuitem">Compile</strong></span>, type
1120 <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">c</strong></span>-<span><strong class="keycap">C</strong></span>-<span><strong class="keycap">v</strong></span>-<span><strong class="keycap">C</strong></span>-<span><strong class="keycap">c</strong></span>,
1121 or execute <code class="command">M-x jde-compile</code>. The compiler uses
1122 the version of <code class="filename">javac</code> included in the
1123 currently selected JDK or on your system command path by
1124 default. However, you can configure the JDEE to use another
1125 compiler for the current project or all projects (see <a href="#SpecifyingCompiler">Specifying a Compiler</a>). The
1126 JDEE also allows you to configure the JDEE to invoke the
1127 compiler with various <a href="#CompilationOptions">compilation options</a>.
1128 </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e2850"></a><a name="CompileBuffer"></a>Compilation Buffer</h4></div></div></div><p>
1129 The compile command displays the output of the compiler in a
1130 separate compilation buffer.
1131 </p><div class="screenshot"><div class="mediaobject"><img src="images/compile_buffer.gif" alt="Image showing compilation buffer with
 errors."></div></div><p>
1132 If a compilation buffer exists from a previous compilation, the compile command
1133 reuses the existing buffer; otherwise, it creates a compilation buffer. By default,
1134 if no errors occur in the compilation, the JDEE deletes the compilation buffer
1135 two seconds after the compilation finishes. You can disable this feature by
1136 setting the variable <code class="varname">jde-compile-enable-kill-buffer</code> off (i.e., to
1137 <code class="code">nil</code>).
1138 </p><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e2871"></a>Compilation Mode</h5></div></div></div><p>The compilation buffer operates in
1139 <code class="varname">compilation-mode</code>, a standard Emacs buffer
1140 mode. This mode greatly simplify locating compilation errors
1141 in the Java source code. For example, to find the line that
1142 cause a compilation error, simply click the error message in
1143 the compilation buffer.</p></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e2879"></a><a name="SpecifyingCompiler"></a>Specifying a Compiler</h4></div></div></div><p>The JDEE supports the following Java compilers.</p><div class="itemizedlist"><ul type="disc"><li><p><code class="filename">javac</code></p><p>
1144 This is the compiler that comes with Sun's JDK and the
1145 JDK's clones. Note that <code class="filename">javac</code>
1146 compiler is itself implemented in Java. The
1147 <code class="filename">javac</code> executable that comes with the
1148 JDK simply starts a vm to run <code class="filename">javac</code>.
1149 The executable passes its command-line arguments to
1150 <code class="filename">javac</code>'s main method.
1151 </p></li><li><p>javac compile server</p><p>This is a JDEE feature that uses the BeanShell to
1152 invoke the javac compiler on a source file, thus avoiding
1153 the need to start a vm everytime you want to compile
1154 a file. This option greatly reduces the time required
1155 to compile individual files by eliminating the vm startup
1156 time, which is usually much longer than the time required
1157 to compile a file.</p></li><li><p><code class="filename">jikes</code></p><p>
1158 Developed by IBM, this compiler is implemented in
1159 C++ and hence avoids the vm startup time that slows
1161 </p></li></ul></div><p>
1162 To specify one of these compilers for the current project or
1164 </p><div class="orderedlist"><ol type="1"><li><p>Type <code class="command">M-x customize-variable</code> and
1165 press <code class="command">Enter</code></p><p>Emacs prompts you to enter the name of a variable
1166 to customize.</p></li><li><p>Enter <code class="varname">jde-compiler</code> and
1167 press <code class="command">Enter</code>.</p><p>The <code class="varname">jde-compiler</code> customization
1168 buffer appears.</p><div class="screenshot"><div class="mediaobject"><img src="images/spec_compiler.gif"></div></div></li><li><p>Select the compiler that you want to use for the
1169 current project or all projects.</p><p>
1170 You can skip the next step if you selected the compile server
1171 or if you selected javac and you want to use the version of
1172 javac that comes with the currently selected JDK, or you have
1173 selected the javac executable or jikes and the executable for
1174 the selected compiler is in your system's command path.
1175 </p></li><li><p>Enter the path to the executable for the selected
1177 </p></li><li><p>If you want your selection to apply only to the current
1178 project, select <code class="command">Save for Current Session</code>
1179 from the <code class="command">State</code> menu. Otherwise select
1180 <code class="command">Save for Future Sessions</code>.</p></li><li><p>Select <code class="command">Finish</code> to dismiss the
1181 customization buffer.</p></li><li><p>If you want the selection to apply to the current
1182 project, select <code class="command">Project->Project
1183 File->Save</code> from the <code class="command">JDE</code>
1184 menu.</p></li></ol></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e2981"></a><a name="CompilationOptions"></a>Compilation Options</h4></div></div></div><p>The JDEE allows you to specify compilation options by
1185 setting compilation variables. You must use the Emacs
1186 customization feature. To use the customization feature,
1187 select <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Options</strong></span>-><span><strong class="guimenuitem">Compile</strong></span>. (See
1188 <a href="#ConfiguringJDE">Configuring the JDEE</a> for
1189 more information on using the customization feature). To save
1190 the compilation settings in the project file
1191 (see <a href="#UsingProjectFiles">Using Project Files</a>)
1192 for the current source buffer, select <span><strong class="guimenuitem">JDE</strong></span>-><span><strong class="guisubmenu">Options</strong></span>-><span><strong class="guimenuitem">Update Project</strong></span>.
1193 </p><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e3009"></a><a name="SetCompileOptionsInteractively"></a> Setting
1194 Compile Options Interactively</h5></div></div></div><p>If you set the customization variable
1195 <code class="varname">jde-read-compile-args</code> to a
1196 non-<code class="varname">nil</code> value, the JDEE compile command
1197 prompts you to enter compilation options in the minibuffer.
1198 It appends the options that you enter to the options
1199 specified via customization variables. The JDEE saves the
1200 arguments that you enter in a minibuffer history list. You
1201 can recall previously entered options by pressing the up or
1202 down arrows on your keyboard. </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The JDEE uses the values of the JDEE customization
1203 variables to set the compiler's command-line option
1204 switches. The JDEE assumes that the compiler you are using
1205 (specified by the customization variable
1206 <code class="varname">jde-compiler</code>) has the same set of
1207 command-line switches as the version of
1208 <code class="varname">javac</code> or jikes that you have selected.
1209 If the command-line switch for a particular option
1210 supported by the compiler your are using is not the same
1211 as that specified by <code class="varname">javac</code> or jikes,
1212 you must use the variable
1213 <code class="varname">jde-compile-option-command-line-args</code> to
1214 select the option.</p></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e3036"></a><a name="CompilerCustomizationVariables"></a>
1215 Compiler Customization Variables</h5></div></div></div><p>The following table lists the JDEE compilation variables and
1216 the functions used to set them.</p><div class="table"><a name="d51e3042"></a><p class="title"><b>Table 1. </b></p><table summary="" border="1"><colgroup><col align="left"><col align="left"><col align="left"></colgroup><thead><tr><th align="left"><p>Name</p></th><th align="left"><p>Group</p></th><th align="left"><p>Usage</p></th></tr></thead><tbody valign="top"><tr><td align="left"><p><code class="varname">jde-compiler</code></p></td><td align="left">Project</td><td align="left">
1217 <p>Specifies the compiler (javac server, by default)
1218 to use to compile the code in the current source buffer.
1220 </td></tr><tr><td align="left">
1222 <code class="varname">jde-compile-option-command-line-args</code>
1224 </td><td align="left">Compile</td><td align="left">Specifies a string of
1225 command-line arguments to be passed to the compiler.</td></tr><tr><td align="left"><code class="varname">jde-global-classpath</code></td><td align="left">Project</td><td align="left">Specify class paths
1226 for compile, run, and debug commands.</td></tr><tr><td align="left"><code class="varname">jde-read-compile-args</code></td><td align="left">Project</td><td align="left">Specify whether to read compile
1227 options from the minibuffer.</td></tr><tr><td align="left"><code class="varname">jde-compile-option-classpath</code></td><td align="left">Compile </td><td align="left">Specifies the
1228 classpath for compile command. If set, this variable
1229 overrides <code class="varname">jde-global-classpath</code>. </td></tr><tr><td align="left"><code class="varname">jde-compile-option-sourcepath</code></td><td align="left">Compile</td><td align="left">Specifies the path of source files
1230 for classes required to compile the current class.</td></tr><tr><td align="left"><code class="varname">jde-quote-classpath</code></td><td align="left">Project </td><td align="left">Quote the classpath
1231 argument.</td></tr><tr><td align="left"><code class="varname">jde-compile-option-directory</code></td><td align="left">Compile </td><td align="left">Specifies the
1232 directory into which to place the compiled class. </td></tr><tr><td align="left"><code class="varname">jde-compile-option-deprecation</code></td><td align="left">Compile </td><td align="left">Warn of use or
1233 override of a deprecated member or class </td></tr><tr><td align="left"><code class="varname">jde-compile-option-debug</code></td><td align="left">Compile </td><td align="left">Generate information
1234 about local variables for debug tools. </td></tr><tr><td align="left"><code class="varname">jde-compile-option-optimize</code></td><td align="left">Compile </td><td align="left">Directs the compiler
1235 to try to generate faster varname. </td></tr><tr><td align="left"><code class="varname">jde-compile-option-depend</code></td><td align="left">Compile</td><td align="left">Analyze dependencies.</td></tr><tr><td align="left"><code class="varname">jde-compile-option-depend-switch</code></td><td align="left">Compile</td><td align="left">Command line switch that causes the
1236 compiler to analyze dependencies.</td></tr><tr><td align="left"><code class="varname">jde-compile-option-vm-args</code></td><td align="left">Compile </td><td align="left">Specify command-line
1237 arguments for Java interpreter used to run the compiler. </td></tr><tr><td align="left"><code class="varname">jde-compile-option-verbose-path</code></td><td align="left">Compile </td><td align="left">Print verbose messages.</td></tr><tr><td align="left"><code class="varname">jde-compile-option-verbose</code></td><td align="left">Compile</td><td align="left">List directories searched to
1238 compile current class.</td></tr><tr><td align="left"><code class="varname">jde-compile-option-nowarn</code></td><td align="left">Compile </td><td align="left">Turn off warnings.</td></tr><tr><td align="left"><code class="varname">jde-compile-option-encoding</code></td><td align="left">Compile </td><td align="left">Specify the source
1239 file encoding name, such as EUCJIS\SJIS. </td></tr><tr><td align="left"><code class="varname">jde-compile-option-target</code></td><td align="left">Compile</td><td align="left">Generate code compatible with a
1240 specified vm version.</td></tr><tr><td align="left"><code class="varname">jde-compile-option-bootclasspath</code></td><td align="left">Compile</td><td align="left">Specify classpath of standard
1241 libraries for target vm.</td></tr><tr><td align="left"><code class="varname">jde-compile-option-bootclasspath</code></td><td align="left">Compile</td><td align="left">Specify path of directories
1242 containing extensions for target vm.</td></tr></tbody></table></div></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e3240"></a><a name="BuildingJavaApplications"></a>Building Java Applications</h2></div></div></div><p>The <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guimenuitem">Build</strong></span>
1243 command builds an application. By default this command invokes the
1244 Unix-style make utility to build the application. You can configure
1245 the build command to invoke the Ant build system or a custom build
1247 </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e3252"></a><a name="SelectBuildMethod"></a>Selecting a Build Method</h4></div></div></div><p>To select a build method:</p><div class="orderedlist"><ol type="1"><li><p>Type <code class="command">M-x customize-variable</code> and
1248 press <code class="command">Enter</code></p><p>Emacs prompts you to enter the name of a variable
1249 to customize.</p></li><li><p>Enter <code class="varname">jde-build-function</code> and
1250 press <code class="command">Enter</code>.</p><p>The <code class="varname">jde-build-function</code> customization
1251 buffer appears.</p><div class="screenshot"><div class="mediaobject"><img src="images/build_fcn_cust_buff.gif"></div></div></li><li><p>Select the build function that you want to use.</p></li><li><p>If you want your selection to apply only to the current
1252 project, select <code class="command">Save for Current Session</code>
1253 from the <code class="command">State</code> menu. Otherwise select
1254 <code class="command">Save for Future Sessions</code>.</p></li><li><p>Select <code class="command">Finish</code> to dismiss the
1255 customization buffer.</p></li><li><p>If you want the selection to apply to the current
1256 project, select <code class="command">Project->Project
1257 File->Save</code> from the <code class="command">JDE</code>
1258 menu.</p></li></ol></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e3317"></a><a name="BuildWithMake"></a>Building with Make</h4></div></div></div><p>
1259 The <code class="command">jde-make</code> command uses a make utility,
1260 such as GNU make, to rebuild a project. You must supply the
1261 makefiles used to build your projects. See <a href="#SampleMakefile">Sample Makefile</a> for an example
1262 of a makefile for building a Java project. David Ponce's
1263 <a href="http://perso.wanadoo.fr/david.ponce/">JMaker</a>
1264 package generates makefiles automatically for JDEE projects.
1265 It uses JDEE variables to determine classpaths, compiler
1266 options, and other information needed to create projects.
1267 JMaker recursively creates makefiles for all the Java packages
1268 in a project plus a toplevel makefile that invokes the other
1269 makefiles to build the entire project.
1270 </p><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e3332"></a><a name="MakeOptions"></a>Make Options</h5></div></div></div><p>
1271 The following customization variables allow you to specify
1272 various <code class="command">jde-make</code> options:
1273 </p><div class="table"><a name="d51e3341"></a><p class="title"><b>Table 1. </b></p><table summary="" border="1"><colgroup><col align="left"><col align="left"><col align="left"><col align="left"></colgroup><thead><tr><th align="left">Name</th><th align="left">Group</th><th align="left">Default</th><th align="left">Usage</th></tr></thead><tbody><tr><td align="left" valign="top"><code class="varname">jde-make-program</code></td><td align="left" valign="top">Project</td><td align="left">make</td><td align="left">
1274 <p>Specifies the pathname on your system of the
1275 make utility that the <code class="command">jde-make</code>
1276 uses to build your project. </p>
1277 </td></tr><tr><td align="left" valign="top"><code class="varname">jde-make-args</code></td><td align="left" valign="top">Project</td><td align="left"> </td><td align="left">
1278 <p> Specifies a string of command-line arguments
1279 (for example, "<code class="varname">-f mymakefile
1280 all</code>") to be passed to the make
1282 </td></tr><tr><td align="left" valign="top"><code class="varname">jde-read-make-args</code></td><td align="left" valign="top">Project</td><td align="left"><code class="varname">nil</code></td><td align="left">
1283 <p> If nonnil, this variable causes the
1284 <code class="command">jde-make</code> command to prompt you
1285 to enter command-line arguments in the minibuffer.
1286 <code class="command">jde-make</code> passes these arguments
1287 along with the arguments specified by
1288 <code class="varname">jde-make-args</code> to the make
1290 </td></tr><tr><td align="left" valign="top"><code class="varname">jde-make-working-directory</code></td><td align="left" valign="top">Project</td><td align="left"> </td><td align="left">
1291 <p> Specifies the directory from which
1292 <code class="command">jde-make</code> runs the make utility.
1294 </td></tr></tbody></table></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e3428"></a><a name="SampleMakefile"></a>Sample Makefile</h5></div></div></div><p>The following is a sample makefile that you can use as a
1295 model for creating makefiles to build Java projects. </p><pre class="programlisting">
1296 JDK = d:/jdk1.2/lib/classes.zip
1297 JMATH = d:/jmath/src
1298 CLASSPATH = $(JMATH);$(JDK)
1299 COMPILER = javac VM = java
1300 COPTIONS = -g -deprecation
1302 CLASSES = Test.class \
1304 JMathException.class \
1307 .SUFFIXES: .java .class
1309 # Rebuild (if necessary) and run the JMath test suite. run: $(CLASSES)
1310 $(VM) -classpath "$(CLASSPATH)" jmath.Test
1312 # Remove all class files from the project directory.
1315 # Implicit rule for making Java class files from Java
1317 .java.class: $(COMPILER) $(COPTIONS) -classpath "$(CLASSPATH)" $?
1318 </pre></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e3436"></a><a name="BuildWithAnt"></a>Building with Ant</h4></div></div></div><p>
1319 The <code class="command">jde-ant-build</code> command uses the <a href="http://jakarta.apache.org/ant/">Apache Ant</a>
1320 build tool to build a Java project.
1321 </p><p>The following variables allow you to control the build
1322 process.</p><div class="table"><a name="d51e3450"></a><p class="title"><b>Table 2. Ant Options</b></p><table summary="Ant Options" border="1"><colgroup><col align="left"><col align="left"><col align="left"><col align="left"></colgroup><thead><tr><th align="left">Name</th><th align="left">Group</th><th align="left">Default</th><th align="left">Usage</th></tr></thead><tbody><tr><td align="left" valign="top"><code class="varname">jde-ant-invocation-method</code></td><td align="left" valign="top">Ant</td><td align="left">script</td><td align="left">
1323 <p> Specifies how to invoke ant. Ant can be invoked
1324 in one of three ways. The first is via the ant
1325 script/program that comes with ant. The second is
1326 via java and the third is via the Ant Server.
1328 </td></tr><tr><td align="left" valign="top"><code class="varname">jde-ant-home</code></td><td align="left" valign="top">Ant</td><td align="left"> </td><td align="left">
1329 <p> Directory where ant is installed. </p>
1330 </td></tr><tr><td align="left" valign="top"><code class="varname">jde-ant-user-jar-files</code></td><td align="left" valign="top">Ant</td><td align="left"><code class="varname">nil</code></td><td align="left">
1331 <p> Specifies jar files that hold user-defined
1333 </td></tr><tr><td align="left" valign="top"><code class="varname">jde-ant-program</code></td><td align="left" valign="top">Ant</td><td align="left"><p>ant</p></td><td align="left">
1334 <p> Specifies name of ant program/script. </p>
1335 </td></tr><tr><td align="left" valign="top"><code class="varname">jde-ant-args</code></td><td align="left" valign="top">Ant</td><td align="left"><p>-emacs</p></td><td align="left">
1336 <p> Specifies arguments to be passed to the Ant
1338 </td></tr><tr><td align="left" valign="top"><code class="varname">jde-ant-buildfile</code></td><td align="left" valign="top">Ant</td><td align="left"><p>build.xml</p></td><td align="left">
1339 <p> Specifies the default buildfile to use. </p>
1340 </td></tr><tr><td align="left" valign="top"><code class="varname">jde-ant-read-buildfile</code></td><td align="left" valign="top">Ant</td><td align="left"><p>off</p></td><td align="left">
1341 <p> Specify whether to prompt for a buildfile. If
1342 non-nil, the jde-ant-build command prompts you for
1343 an ant buildfile. Note that
1344 <code class="varname">jde-ant-read-buildfile</code> and
1345 <code class="varname">jde-ant-enable-find</code> are
1346 incompatible and that
1347 <code class="varname">jde-ant-read-buildfile</code> will
1348 override the former. </p>
1349 </td></tr><tr><td align="left" valign="top"><code class="varname">jde-ant-read-target</code></td><td align="left" valign="top">Ant</td><td align="left"><p>off</p></td><td align="left">
1350 <p> Specify whether to prompt for a build target.
1351 If non-nil, the jde-ant-build command prompts you
1352 for an ant target. </p>
1353 </td></tr><tr><td align="left" valign="top"><code class="varname">jde-ant-interactive-buildfile</code></td><td align="left" valign="top">Ant</td><td align="left"><p>off</p></td><td align="left">
1354 <p> Default buildfile to use when prompting
1356 </td></tr><tr><td align="left" valign="top"><code class="varname">jde-ant-read-args</code></td><td align="left" valign="top">Ant</td><td align="left"><p>off</p></td><td align="left">
1357 <p> Specify whether to prompt for additional
1358 arguments to pass to Ant. If non-nil, the
1359 <code class="command">jde-ant-build</code> command prompts you
1360 for the additional arguments. </p>
1361 </td></tr><tr><td align="left" valign="top"><code class="varname">jde-ant-enable-find</code></td><td align="left" valign="top">Ant</td><td align="left"><p>off</p></td><td align="left">
1362 <p> Specify whether jde-ant find the
1363 <code class="filename">build.xml</code> file based on your
1364 current directory. If non-nil, we will search up the
1365 directory hierarchy from the current directory for
1366 the build definition file. Also note that, if
1367 non-nil, this will relax the requirement for an
1368 explicit jde project file. In order for this to
1369 work <code class="varname">jde-ant-read-buildfile</code> must
1371 </td></tr><tr><td align="left" valign="top"><code class="varname">jde-ant-complete-target</code></td><td align="left" valign="top">Ant</td><td align="left"><p>off</p></td><td align="left">
1372 <p> Specify whether to enable completion of build
1373 target names in the minibuffer. If non-nil, the
1374 <code class="command">jde-ant-build</code> command allows you
1375 to use tab completion in the minibuffer to specify
1376 the build target name. This list of valid build
1377 targets is determined by parsing the Ant build file.
1378 This option has no effect if
1379 <code class="varname">jde-ant-read-target</code> is
1381 </td></tr><tr><td align="left" valign="top"><code class="varname">jde-ant-use-global-classpath</code></td><td align="left" valign="top">Ant</td><td align="left"><p>off</p></td><td align="left">
1382 <p>Specify whether to enable use of
1383 <code class="varname">jde-global-classpath</code> when running
1384 <code class="filename">jde-ant</code>.</p>
1385 </td></tr><tr><td align="left" valign="top"><code class="varname">jde-ant-target-regexp</code></td><td align="left" valign="top">Ant</td><td align="left">
1387 <\s-*target\s-[^...]*?name\s-*=\s-*\"\s-*\([^\"]+\)
1389 </td><td align="left">
1390 <p>Regular expression used to match target names in
1391 Ant build files.</p>
1392 </td></tr><tr><td align="left" valign="top"><code class="varname">jde-ant-build-hook</code></td><td align="left" valign="top">Ant</td><td align="left"><p>nil</p></td><td align="left">
1393 <p>List of hook functions run by
1394 <code class="command">jde-ant-build</code> (see
1395 <code class="varname">run-hooks</code> in the Emacs
1396 documentation for more information).</p>
1397 </td></tr></tbody></table></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e3714"></a><a name="RunningJavaApps"></a>Running Java
1398 Applications</h2></div></div></div><p>The JDE allows you to run a Java application as an Emacs
1399 subprocess. You can run multiple applications concurrently, but
1400 only one instance of each application at a time. The JDE
1401 displays each application's standard and error output in an
1402 Emacs command interface (<code class="varname">comint</code>) buffer. You
1403 can interact with applications that accept command line input
1404 via the <code class="varname">comint</code> buffer. When interacting with
1405 an application, you can use any of
1406 <code class="varname">comint-mode</code>'s extensive set of command-line
1407 history commands to speed interaction. To run an application,
1408 enter </p><pre class="programlisting">
1410 </pre><p>or select <span><strong class="guimenu">Java</strong></span>-><span><strong class="guimenuitem">Run App</strong></span> from the Emacs
1411 menubar or type <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">c</strong></span> <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">v</strong></span> <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">r</strong></span>. </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e3757"></a><a name="SpecifyingMainClass"></a>Specifying the
1412 Application's Main Class</h4></div></div></div><p>The term <span class="emphasis"><em>main class</em></span> refers to the
1413 class that contains the application's main method. The JDE's
1414 Run App command assumes by default that the class in the
1415 current buffer is the application's main class. This can be
1416 inconvenient if you have an application that has multiple
1417 classes. You may want to be able to run the application from
1418 any buffer containing one of the application's classes. To do
1419 this, set the variable
1420 <code class="varname">jde-run-application-class</code> to the
1421 <span class="emphasis"><em>fully qualified name</em></span> of the application's
1422 main class.</p><p>You can temporarily override the setting of
1423 <code class="varname">jde-run-application-class</code> by typing
1424 <code class="varname">C-u -</code> before executing the <code class="command">jde-run</code> command, for example, by
1425 typing <code class="varname">C-u - C-c C-r</code>. This causes the JDE to
1426 prompt you to enter the <span class="emphasis"><em>fully qualified
1427 name</em></span> of the application's main class (as well
1428 application arguments if any).</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e3789"></a><a name="SpecifyingStartupDirectory"></a>Specifying a
1429 Startup Directory</h4></div></div></div><p>The JDE can start an application from any directory that
1430 you specify. By default, the JDE starts an application from
1431 the default directory of the current source buffer. The
1432 default directory of the current source buffer is the
1433 directory containing the source file displayed in the buffer.
1434 You can specify another directory as the startup directory by
1435 setting the JDE customization variable
1436 <code class="varname">jde-run-working-directory</code>.</p><p>To set this variable, </p><div class="procedure"><ol type="1"><li><p>Display its customization panel.</p><p>You can do this by typing </p><p><span><strong class="keycap">M</strong></span>-<span><strong class="keycap">x</strong></span> <code class="varname">customize-variable</code> <code class="varname">jde-run-working-directory</code></p><p>or selecting <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Options</strong></span>-><span><strong class="guimenuitem">Project</strong></span> to display the project customization panel
1437 and searching this panel for
1438 <code class="varname">jde-run-working-directory</code>.
1440 </p><div class="screenshot"><div class="mediaobject"><img src="images/WorkingDirectory.gif" alt="Screenshow showing customization buffer for
 jde-run-working-directory."></div></div><p>
1441 </p></li><li><p>Enter the working directory in the variable's edit
1442 field. </p></li><li><p>Save the new setting.</p><p>To save the edited bindings, right click the
1443 <span class="guibutton">[State]</span> button and choose
1444 <span><strong class="guimenuitem">Set for current
1445 session</strong></span> if you want the
1446 settings to apply only to the current project or
1447 <span><strong class="guimenuitem">Save for future
1448 sessions</strong></span> if you want the
1449 settings to apply to all projects. In either case, you
1450 should save the new settings in you project file if your
1451 project has a project file. To save the new settings in
1452 your project file, switch to a source buffer and choose
1453 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Options</strong></span>-><span><strong class="guimenuitem">Save
1454 Project</strong></span>.</p></li></ol></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e3871"></a><a name="RunVMArgs"></a> Setting VM Command-Line
1455 Arguments</h4></div></div></div><p>If you set the customization variable
1456 <code class="varname">jde-run-read-vm-args</code> to a
1457 non-<code class="varname">nil</code> value, the JDE compile command
1458 prompts you to enter virtual machine options in the
1459 minibuffer. It appends the options that you enter to the
1460 options specified via customization variables. The JDE saves
1461 the arguments that you enter in a minibuffer history list.
1462 You can recall previously entered options by pressing the up
1463 or down arrows on your keyboard. </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e3883"></a><a name="RunAppArgs"></a> Setting Command-Line
1464 Application Arguments</h4></div></div></div><p>Specifying a prefix argument before the
1465 <code class="command">jde-run</code>, e.g., <code class="varname">C-u C-c C-v
1466 C-r</code> causes the command to prompt you to enter
1467 arguments to be passed to the application's main
1468 method. The command appends the options that you enter to the
1469 arguments specified via the customization variable
1470 <code class="varname">jde-run-option-application-args</code>. The JDE
1471 saves the arguments that you enter in a minibuffer history
1472 list. You can recall previously entered options by pressing
1473 the up or down arrows on your keyboard. </p><p>If you set the customization variable
1474 <code class="varname">jde-run-read-app-args</code> to a
1475 non-<code class="varname">nil</code> value, the JDE run command
1476 prompts you to enter command-line application arguments
1477 by default, i.e., you do not have to specify a prefix
1478 argument each time you execute the command.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e3906"></a><a name="NavigatingExceptionTraces"></a>Navigating
1479 Exception Traces</h4></div></div></div><p>If an exception occurs while your program is running, the
1480 Java vm outputs an exception trace. This trace appears in the
1481 run buffer for the application.</p><p>
1482 </p><div class="screenshot"><div class="mediaobject"><img src="images/excepttrace.gif" alt="Screenshot showing an exception trace in the
 JDE's run buffer."></div></div><p>
1483 </p></div><p>To view the source line corresponding to a point in the
1484 exception stack trace, right-click the corresponding stack trace
1485 line in the run buffer. You can move up and down the stack trace
1486 by typing the key combinations <code class="varname">C-c C-v C-[</code> or
1487 <code class="varname">C-c C-v C-]</code>.</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e3930"></a><a name="RunOptions"></a>Run Customization Variables
1488 </h4></div></div></div><p>The JDE allows you to specify run-time options by setting
1489 run variables.You can use the Emacs customization feature to
1490 set run-time variables interactively. To use the customization
1492 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Project</strong></span>-><span><strong class="guisubmenu">Options</strong></span>-><span><strong class="guimenuitem">Run</strong></span>.
1493 (See <a href="#ConfiguringJDE">Configuring the JDE</a>
1494 for more information on using the customization feature). To
1495 save the compilation settings in the project file (see <a href="#UsingProjectFiles">Using Project Files</a>) for
1496 the current source buffer, select <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu"> Project</strong></span>-><span><strong class="guisubmenu">Project
1497 File</strong></span>-><span><strong class="guimenuitem">Save
1498 Project</strong></span>.
1499 </p><p>The following table lists the JDE run variables and the
1500 functions used to set them. </p><div class="table"><a name="d51e3964"></a><p class="title"><b>Table 1. </b></p><table summary="" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Variable</th><th>Group</th><th>Usage</th></tr></thead><tbody><tr><td valign="top"><code class="varname">jde-run-mode-hook</code></td><td valign="top">Project</td><td valign="top">List of hook functions run by
1501 <code class="varname">jde-run-mode</code></td></tr><tr><td valign="top"><code class="varname">jde-run-working-directory</code></td><td valign="top">Project</td><td>Startup directory for running or debugging Java
1502 applications.</td></tr><tr><td valign="top"><code class="varname">jde-run-application-class</code></td><td valign="top">Project </td><td valign="top">Name of the Java class to run. The
1503 command <code class="varname">jde-run-set-app</code> sets the
1504 buffer-local value of this variable. </td></tr><tr><td valign="top"><code class="varname">jde-run-java-vm</code></td><td valign="top">Project </td><td valign="top">Specify Java interpreter for
1505 non-Windows platforms. The command
1506 <code class="varname">jde-run-set-vm</code> sets the
1507 buffer-local value of this variable. </td></tr><tr><td valign="top"><code class="varname">jde-run-java-vm-w</code></td><td valign="top">Project </td><td valign="top">Specify Java interpreter for Windows
1508 platforms. The command
1509 <code class="varname">jde-run-set-vm-w</code> sets the
1510 buffer-local value of this variable. </td></tr><tr><td valign="top"><code class="varname">jde-global-classpath</code></td><td valign="top">Project </td><td valign="top">Specify class paths for compile,
1511 run, and debug commands. The command<code class="varname">
1512 jde-set-global-classpath</code> sets the
1513 buffer-local value of this variable. </td></tr><tr><td valign="top"><code class="varname">jde-run-classic-mode-vm</code></td><td valign="top">Project</td><td>Specifies that the JDE should run the JDK's
1514 classic version of the Java virtual machine (as
1515 opposed to the HotSpot version). This option applies
1516 only to versions of the JDK that include both a
1517 classic and a HotSpot vm.</td></tr><tr><td valign="top"><code class="varname">jde-run-read-vm-args</code></td><td valign="top">Project</td><td>Specifies whether to read vm arguments from
1518 the minibuffer.</td></tr><tr><td valign="top"><code class="varname">jde-run-option-classpath</code></td><td valign="top">Run </td><td valign="top">Specifies the classpath for
1519 the Java interpreter. This option overrides the
1520 jde-global-classpath option. </td></tr><tr><td valign="top"><code class="varname">jde-run-option-verbose</code></td><td valign="top">Run </td><td valign="top">Print messages about the running
1521 process. </td></tr><tr><td valign="top"><code class="varname">jde-run-option-properties</code></td><td valign="top">Run </td><td valign="top">Specify property values.</td></tr><tr><td valign="top"><code class="varname">jde-run-option-heap-size</code></td><td valign="top">Run </td><td valign="top">Specify the initial and maximum size
1522 of the interpreter heap. </td></tr><tr><td valign="top"><code class="varname">jde-run-option-stack-size</code></td><td valign="top">Run </td><td valign="top">Specify size of the C and Java
1523 stacks.</td></tr><tr><td valign="top"><code class="varname">jde-run-option-garbage-</code>
1524 <code class="varname">collection</code> </td><td valign="top">Run</td><td valign="top">Specify garbage collection
1525 options. </td></tr><tr><td valign="top"><code class="varname">jde-run-option-java-profile</code></td><td valign="top">Run </td><td valign="top">Enable Java profiling.</td></tr><tr><td valign="top"><code class="varname">jde-run-option-heap-profile</code></td><td valign="top">Run </td><td valign="top">Output heap profiling data.</td></tr><tr><td valign="top"><code class="varname">jde-run-option-verify</code></td><td valign="top">Run </td><td valign="top">Verify classes.</td></tr><tr><td valign="top"><code class="varname">jde-run-option-vm-args</code></td><td valign="top">Run </td><td valign="top">Specify command-line arguments to be
1526 passed to the Java vm. The command jde-run-set-args
1527 sets the buffer-local value of this
1528 variable. </td></tr><tr><td valign="top"><code class="varname">jde-run-option-application-args</code></td><td valign="top">Run </td><td valign="top">Specify command-line arguments to
1529 pass to the application. The command
1530 <code class="varname">jde-run-set-app-args </code>sets the
1531 buffer-local value of this variable. </td></tr></tbody></table></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e4152"></a><a name="WorkingWithApplets"></a> Working with Applets</h2></div></div></div><p>The JDE provides specialized commands for running and
1532 debugging applets.</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e4158"></a><a name="RunningApplets"></a>Running Applets</h4></div></div></div><p>To run an applet:</p><div class="procedure"><ol type="1"><li><p>Open the applet's source file in a buffer. </p></li><li><p>Choose <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guimenuitem">Run
1533 Applet</strong></span>. </p><p>The JDE searches for an html file in the directory
1534 containing the applet source file and displays the first
1535 file it finds, using your system's default browser. If
1536 the JDE cannot find an html page in the applet's source
1537 file directory, it signals an error by default.
1538 </p></li></ol></div><p>The <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guimenuitem">Run Applet</strong></span> command
1539 assumes by default that the directory containing the applet's
1540 source also contains an html page for testing that applet. If
1541 this is not true in your case, you have two options. You can
1542 either specify the path of the applet file via the JDE
1543 customization variable <code class="varname">jde-run-applet-doc</code>
1544 or you can use the <code class="varname">jde-run-applet</code> command
1545 to run your applet. If the
1546 <code class="varname">jde-run-applet-doc</code> variable is not a null
1547 string, <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guimenuitem">Run Applet</strong></span> displays
1549 document that the variable specifies instead of searching the source
1550 file directory for a document to display. The
1551 <code class="varname">jde-run-applet</code> command prompts you to enter in the
1552 minibuffer the path of an html file to display. If you enter nothing,
1553 the command defaults to the behavior of <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guimenuitem">Run Applet</strong></span>.</p><p>The run commands chooses the viewer as follows. If
1554 <code class="varname">jde-run-applet-viewer</code> is a null string (the
1555 default) or browse-url, the JDE uses browse-url to launch the
1556 applet doc in your system's default browser. Otherwise, the
1557 menu command uses comint to launch the viewer (e.g.,
1558 appletviewer) specified by
1559 <code class="varname">jde-run-applet-viewer</code>.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e4219"></a><a name="DebuggingApplets"></a>Debugging Applets</h4></div></div></div><p>To debug an applet:</p><div class="procedure"><ol type="1"><li><p>Open the applet's source file in a buffer.</p></li><li><p>Choose <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guimenuitem">Debug
1560 Applet</strong></span>.</p><p>The JDE searches for an html file in the directory
1561 containing the applet source file. If the JDE cannot find
1562 an html page in the applet's source file directory, it
1563 signals an error by default. Otherwise, it runs
1564 appletviewer in debug mode on the first file that it
1565 finds.</p><p>The Emacs window splits into two panes.</p></li></ol></div><p>The top pane shows the applet's source file with the debug
1566 cursor pointing to the first line of the applet's init file.
1567 The bottom pane displays the debugger's command line
1568 interface. You can now set breakpoints, single-step, or
1569 continue running the applet. See <a href="#DebuggingApps">Debugging Applications</a> for more
1570 information.</p><p>If you want to specify the document to be used to test the
1571 applet, customize the variable jde-run-applet-doc or execute
1572 <code class="varname">M-x jde-db-applet</code>. This command prompts you
1573 to enter the test document's name.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e4252"></a><a name="AppletOptions"></a>Applet Customization
1574 Variables</h4></div></div></div><p>The JDE allows you to specify run-time options for applets
1575 by setting JDE configuration variables.You must use the Emacs
1576 customization feature to set applet run-time variables . To
1577 use the customization feature, select <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Options</strong></span>-><span><strong class="guimenuitem">Run</strong></span>.
1578 (See <a href="#ConfiguringJDE">Configuring the JDE</a>
1579 for more information on using the customization feature). In
1580 some cases, the JDE also provides functions for setting the
1581 buffer-local values of the compilation variables. To save the
1582 compilation settings in the project file (see <a href="#UsingProjectFiles">Using Project Files</a>) for
1583 the current source buffer, select
1584 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Options</strong></span>-><span><strong class="guimenuitem">Update
1585 Project</strong></span>. </p><p>The following table lists the JDE applet run-time
1586 variables and the functions used to set them. </p><div class="table"><a name="d51e4282"></a><p class="title"><b>Table 1. </b></p><table summary="" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Variable</th><th>Group</th><th>Usage</th></tr></thead><tbody><tr><td valign="top"><code class="varname">jde-run-applet-viewer</code></td><td valign="top">Project </td><td valign="top">Specify name of viewer to use to
1587 display page containing the applet. The command
1588 <code class="varname">jde-run-set-applet-viewer</code> sets the
1589 buffer-local value of this variable. </td></tr><tr><td valign="top"><code class="varname">jde-run-applet-doc</code></td><td valign="top">Project </td><td valign="top">Specify name of document containing
1590 applet to be viewed. The command
1591 <code class="varname">jde-run-set-applet-doc</code> sets the
1592 buffer-local value of this variable. </td></tr></tbody></table></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e4316"></a><a name="DebuggingApps"></a>Debugging Applications</h2></div></div></div><p>The JDE provides two options for debugging Java applications.</p><div class="itemizedlist"><ul type="disc"><li><p>An Emacs interface to <code class="command">jdb</code>, the command-line
1593 debugger that comes with the JDK. See <a href="../jdb-ug/jdb-ug-frame.html" target="jdb-ug">Debugging with jdb</a> for more
1594 information. </p></li><li><p>
1595 JDEbug, a Java debugger developed specifically for use with the JDE.
1596 See <a href="../jdebug-ug/jdebug-ug.html" target="jdebug-ug">JDEbug
1597 User's Guide</a> for more information</p>.
1598 </li></ul></div><p>JDEbug provides more debugging features but requires a JDK 1.2
1599 or higher vm. You must use <code class="command">jdb</code> to debug applications
1600 running on earlier vms.</p></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e4344"></a><a name="SpecifyingClasspaths"></a>Specifying
1601 Classpaths</h2></div></div></div><p>The JDE provides customization variables that permit you to
1602 specify a classpath for the JDE's compile, run, debug,
1603 Beanshell, and other commands. The following table lists these
1604 variables.</p><div class="table"><a name="d51e4350"></a><p class="title"><b>Table 1. Classpath Variables</b></p><table summary="Classpath Variables" border="1"><colgroup><col><col></colgroup><thead><tr><th>Variable</th><th>Applies To ...</th></tr></thead><tbody><tr><td><p><code class="varname">jde-global-classpath</code></p></td><td><p>All JDE commands that use a
1605 classpath.</p></td></tr><tr><td><p><code class="varname">jde-compile-option-classpath</code></p></td><td><p>Compile command</p></td></tr><tr><td><p><code class="varname">jde-run-option-classpath</code></p></td><td><p>Run App command</p></td></tr><tr><td><p><code class="varname">jde-db-option-classpath</code></p></td><td><p>Debug App command</p></td></tr></tbody></table></div><p>The <code class="varname">jde-global-classpath</code> variable is so
1606 named because it specifies a classpath that is used by all JDE
1607 commands unless overridden by a classpath variable specific to a
1608 particular command. For example, the JDE's
1609 <code class="command">Compile</code> command uses
1610 <code class="varname">jde-global-classpath</code> unless the value of
1611 <code class="varname">jde-compile-option-classpath</code> is set.
1612 Typically you want to use the same classpath to compile, run,
1613 and debug an application. So typically
1614 <code class="varname">jde-global-classpath</code> is the only variable you
1615 need to set.</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e4410"></a><a name="SettingClasspathVar"></a>Setting a Classpath
1616 Variable</h4></div></div></div><p>As with other JDE customization variables, you must use
1617 Emacs' <code class="command">customize-variable</code>
1618 command to set the JDE's classpath variables. You can use
1619 relative paths, cygwin paths, and paths with tilde notation
1620 and environment variables as values of JDE classpath
1621 variables. See <a href="#SpecifyingPaths">Specifying
1622 Paths</a> for more information.
1624 When setting a classpath variable, you must enter each path as
1625 a separate entry in the customization buffer. Do not enter the
1626 paths as semicolon or colon-separated lists of paths. The
1627 following examples show the right and wrong way to specify a
1628 classpath.</p><div class="example"><a name="d51e4424"></a><p class="title"><b>Example 1. Wrong Way to Specify a Classpath</b></p><pre class="programlisting">
1629 jde-global-classpath: [Hide]
1630 [INS] [DEL] Path: c:/jde-dev/jmath/classes;c:/jde-dev/jmath/src
1632 [State]: this option has been set and saved.
1633 </pre></div><div class="example"><a name="d51e4429"></a><p class="title"><b>Example 2. Right Way to Specify a Classpath</b></p><pre class="programlisting">
1634 jde-global-classpath: [Hide]
1635 [INS] [DEL] Path: c:/jde-dev/jmath/classes
1636 [INS] [DEL] Path: c:/jde-dev/jmath/src
1638 [State]: this option has been set and saved.
1639 </pre></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e4434"></a><a name="ClassLibraries"></a>Including Class
1640 Libraries</h4></div></div></div><p>
1641 If you store your class libraries as jar or zip files in
1642 separate directory, you need specify only the path of the
1643 directory in a JDE classpath variable. Whenever the JDE
1644 encounters a library directory in a classpath variable, it
1645 expands the classpath to include all the jar and zip files in
1646 the library directory.
1648 For example, suppose you organize your project directory as
1650 </p><p> </p><pre class="programlisting"> myproj classes lib
1653 where the <code class="filename">src</code> directory contains all of
1654 your source files, the <code class="filename">lib</code> directory all
1655 of your jar and zip files, and the
1656 <code class="filename">classes</code> directory all of the classes
1657 compiled from the <code class="filename">src</code> directory. Further,
1658 suppose you store your project file (see <a href="#UsingProjectFiles">Using Project Files</a>) at the
1659 root of your project directory. Then, you can specify
1660 <code class="varname">jde-global-classpath</code> simply as follows.
1662 </p><pre class="programlisting"> jde-global-classpath:
1663 [Hide] [INS] [DEL] Path: ./classes [INS] [DEL] Path: ./src
1664 [INS] [DEL] Path: ./lib [INS] [State]: this option has been
1665 set and saved. </pre><p>
1667 If you do not want the JDE to expand library directories, set
1668 the variable <code class="varname">jde-expand-classpath-p</code> off.
1669 The JDE expands directories whose names match the regular
1670 expressions specified by
1671 <code class="varname">jde-lib-directory-names</code>. The default values
1672 of this variable are <code class="filename">^lib</code> and
1673 <code class="filename">^jar</code>. So by default, the JDE expands
1674 names that begin with the string <code class="filename">lib</code> or
1675 <code class="filename">lib</code>, e.g., <code class="filename">lib</code>,
1676 <code class="filename">libraries</code>, etc. However, you can
1677 customize <code class="varname">jde-lib-directory-names</code> to
1678 reflect any library naming scheme you prefer.
1679 </p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e4501"></a><a name="UsingProjectFiles"></a>Using Project Files</h2></div></div></div><p>A project file is a Lisp file that the JDEE loads and
1680 evaluates whenever you open a Java source file belonging to a
1681 specific project. The JDEE has commands that save the current
1682 settings of JDEE project variables in the project file for the
1683 current project. Project files thus allow you to save and
1684 restore project-specific settings of JDEE customization
1685 variables. For example, you can use a project file to set the
1686 value of the <code class="varname">jde-global-classpath</code> variable to
1687 a project-specific classpath automatically whenever you load a
1688 file belonging to that project. </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e4510"></a><a name="FindingProjectFiles"></a>How the JDE Finds Project Files</h4></div></div></div><p>To simplify the task of finding project files, the JDE makes
1689 two assumptions. First, it assumes that all Java source files
1690 relating to a particular project live in a single directory tree.
1691 Second, it assumes that all project files have the same file name.
1692 The name assumed by default is <code class="filename">prj.el</code>. You can use the JDE
1693 configuration variable <code class="varname">jde-project-file-name</code> to specify
1694 another name.</p><p>
1695 When you open a Java source file, the JDE looks for
1696 project files in the directory tree containing the source file.
1697 If the JDE finds one or more project files, it loads the
1698 project files in the following manner.
1700 The JDE first sets all the JDE variables to their
1701 Emacs startup values (i.e., the default value or the value
1702 saved in your <code class="filename">.emacs</code> file). It then loads
1703 all the project files in the directory tree containing the
1704 current source buffer, starting with the topmost file.
1706 What this means is that you can use project files to extend
1707 and/or override the settings in your
1708 <code class="filename">.emacs</code> file and in other project files.
1709 For example, your <code class="filename">.emacs</code> file can specify
1710 settings that are common to all your projects. You can put
1711 settings common to a group of projects at the top of the
1712 directory tree containing the projects, settings common to
1713 each project at the top of the directory containing each
1714 projects, and so on.
1715 </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e4537"></a><a name="ProjectFileContents"></a> Project File
1716 Contents</h4></div></div></div><p>A project file can contain any Lisp code that can be
1717 evaluated correctly as the last step in creating a Java source
1718 buffer. For example, a project file can contain code that sets
1719 the value of JDE configuration variables. In general, a
1720 project file can contain any code that could be implemented
1721 as a <code class="varname">jde-mode</code> hook function. In fact, you
1722 can think of a project file as a project-specific
1723 <code class="varname">jde-mode</code> hook function. </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e4549"></a><a name="CreatingProjectFiles"></a>Creating a Project
1724 File</h4></div></div></div><p>The easiest way to create a project file is to use the
1725 <code class="varname">jde-create-new-project </code> command (<span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Project</strong></span>-><span><strong class="guisubmenu">Project
1726 File</strong></span>-><span><strong class="guimenuitem">Create
1727 New</strong></span>). This command creates a
1728 new project file and saves the
1729 current values of all customized JDE configuration variables
1730 in the project file for the selected Java buffer. (To be
1731 precise, the command inserts Lisp code in the project file
1732 that restores the current settings of the configuration
1733 variables; if such code already exists in the file, it
1734 replaces it with updated code.) Thus, to create
1735 a project file that sets JDE configuration variables to
1736 project-specific values:
1737 </p><div class="procedure"><ol type="1"><li><p>Open any source file belonging to the project.</p></li><li><p>Set the values of the JDE configuration variables to
1738 the appropriate values for the project to which the source
1739 file belongs.</p></li><li><p>See <a href="#ConfiguringJDE">Configuring the
1740 JDE</a> for information on how to set the values of
1741 the JDE configuration variables.</p></li><li><p>Select <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Project</strong></span>-><span><strong class="guisubmenu">Project
1742 File</strong></span>-><span><strong class="guimenuitem">Save
1743 Project</strong></span>.
1744 </p></li><li><p> The JDE prompts you to enter the path to a directory
1745 in which to store the project file.
1747 Enter the directory where you want to store the project
1748 file or press <span><strong class="keycap">Enter</strong></span> to store the project
1749 file in the current directory.
1750 </p></li></ol></div><p>Once you have created the project file, you can insert
1751 additional configuration code into the file if desired. Note
1752 that the <code class="varname">jde-save-project</code> command edits
1753 rather than replaces existing project files. Thus, you can use
1754 the command to update configuration variable settings without
1755 disturbing any other configuration code that you have inserted
1756 manually into the project file.
1757 </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e4608"></a><a name="CreatingPortableProjects"></a>Creating Portable Projects</h4></div></div></div><p>
1758 You can use relative paths and environment variables to
1759 construct portable project files. For example, suppose your
1760 project directory has the following structure:
1762 </p><pre class="programlisting">
1773 Further suppose that your project uses beans from a
1774 shared library specified by the environment variable
1775 <code class="varname">BEANS</code>. With this setup,
1776 you can specify <code class="varname">jde-global-classpath</code> as
1778 </p><pre class="programlisting">
1781 $BEANS/lib/dials.jar
1784 and <code class="varname">jde-compile-option-directory</code> as
1786 </p><pre class="programlisting">
1790 This causes the JDE to store classes compiled from your src
1791 directory in the classes directory. Note that you have not
1792 used any absolute paths in creating your project file. This
1793 means you can move your project anywhere without having to update
1795 </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e4644"></a><a name="DisablingContextSwitching"></a>Disabling Context Switching</h4></div></div></div><p>When you select a buffer that belongs to another
1796 project, the JDE loads the project file for that project
1797 and may update the class list for the project. This
1798 causes a slight delay before you can begin using the
1799 new buffer. The delay can be irritating if you need
1800 to switch frequently among open projects, for example,
1801 when copying or diffing code from different projects.
1802 Accordingly, the JDE provides ways for you to disable
1803 context-switching either permanently or temporarily.
1804 </p><p>To disable context-switching permanently, toggle
1805 the customizat variable
1806 <code class="varname">jde-project-context-switching-enabled-p</code>
1807 off. Be sure to use customize to do this and save the
1808 customization in your <code class="filename">
1809 .emacs</code> or <code class="filename">prj.el</code>
1810 file. Note that you can use the JDE's project file loading
1811 command, <code class="command">JDE->Project->Project File->Load</code>,
1812 to switch contexts manually.
1814 To disable context-switching temporarily during a session,
1815 select <code class="command">
1816 JDE->Project->Auto Switch</code> or enter
1817 <code class="varname">M-x jde-toggle-project-context-switching</code>. To reenable
1818 context-switching, execute the same command again.
1819 </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e4672"></a><a name="ProjectHooks"></a>Project Hook Functions</h4></div></div></div><p>The variable <code class="varname">jde-project-hooks</code> lists
1820 functions that execute after the JDEE loads a project file. By
1821 writing hook functions and adding them to this list, you can
1822 specify actions to be taken every time the JDEE switches from
1823 one project to another.</p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e4681"></a><a name="DisplayingDoc"></a> Displaying Java Documentation</h2></div></div></div><p>
1824 The JDE provides commands for displaying the JDK API documentation
1825 and context-sensitive help for classes.
1826 </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e4687"></a><a name="BrowsingJDKDoc"></a> Browsing JDK
1827 Documentation</h4></div></div></div><p>The <code class="varname">jde-browse-jdk-doc</code> command
1828 (<span><strong class="guimenu">JDE</strong></span>-><span><strong class="guimenuitem">Help</strong></span>-><span><strong class="guimenuitem">JDK</strong></span>, <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">c</strong></span>
1829 <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">v</strong></span> <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">n</strong></span>) opens the
1830 JDK documentation in a browser. By default, this command
1831 displays the JDK documentation page at JavaSoft's web site. To
1832 display a different copy, set the variable
1833 <code class="varname">jde-jdk-doc-url</code> to the url of the index
1834 page of the copy you want to be displayed. </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e4725"></a><a name="ClassHelp"></a> Context-Sensitive Class
1835 Help</h4></div></div></div><p>The JDK provides context-sensitive help for Java classes.
1836 To use this facility, you must first customize the variable
1837 <code class="varname">jde-help-docsets</code> to specify the location of
1838 class documentation on your system. The JDE class help
1839 facility supports javadoc documentation by default but it
1840 works with other types of documentation as well.</p><p>Once you have specified the location of class
1841 documentation on your system, you can get help for the class
1842 at point in the current buffer by selecting <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Help</strong></span>-><span><strong class="guimenuitem">Symbol
1843 at Point</strong></span> . </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e4744"></a><a name="Specifying a Browser"></a>Specifying a Browser</h4></div></div></div><p>The JDEE uses the browsers or browsers specified by the customization
1844 variable <code class="varname">browse-url-browser-function</code>. See the documentation
1845 for this variable for more information.</p><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e4753"></a><a name="UsingEmacs-w3m"></a>Using emacs-w3m to Browse Java Doc</h5></div></div></div><p>The <code class="filename">emacs-w3m</code> package uses the
1846 <code class="filename">w3m</code> text-mode HTML browser to enable
1847 Emacs to render text HTML pages. This allows you to use
1848 Emacs not only to develop Java code but also to browse Java
1849 API and tools documentation. For information on downloading
1850 and installing emacs-w3m and w3m, see the <a href="http://emacs-w3m.namazu.org/">emacs-w3m</a> web
1851 site. </p><p>While you're at it, you should also install the <a href="http://www.emacswiki.org/cgi-bin/wiki/WThreeM">
1852 WThreeM</a> package. This package provides
1853 incremental searching on URLs in w3m HTML buffers, a nice feature
1854 for browsing Javadoc class documentation, with its wealth of
1855 links.</p><p>One you have installed <code class="filename">emacs-w3m/w3m</code>, you can
1856 configure Emacs (and hence the JDEE) to use it to display Javadoc pages
1857 by customizing <code class="varname">jde-help-browser-function</code> to specify
1858 <code class="filename">w3m-browse-url</code>. </p><p>The <code class="filename">w3m-browse-url</code> function displays its output
1859 by default in the current window, replacing the Java file in the buffer.
1860 To cause the function to display its output in a popup window, customize
1861 <code class="varname">w3m-pop-up-frames</code>.</p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e4792"></a><a name="BrowsingSourceCode"></a>Browsing Source Code</h2></div></div></div><p>The JDE provides the following facilities for browsing Java source code:</p><div class="itemizedlist"><ul type="disc"><li><p><a href="#ClassesMenu">Classes index menu</a></p></li><li><p><a href="#Speedbar">Speedbar</a></p></li><li><p><a href="#Tags">Etags</a></p></li></ul></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e4811"></a><a name="ClassesMenu"></a> Classes Index Menu</h4></div></div></div><p>The <span><strong class="guimenu">Classes</strong></span>
1862 index menu appears by default in the Emacs menubar whenever a
1863 Java source buffer is active. The menu consists of a cascading
1864 list of all classes, methods, fields, and imports defined in
1865 the current buffer plus the package to which the current
1866 buffer belongs. Selecting any item scrolls the buffer to the
1867 statement that defines the item.</p><div class="screenshot"><div class="mediaobject"><img src="images/classes_menu1.gif" alt="Screenshot showing Classes menu."></div></div><p>
1868 </p><p>The top-level menu contains an entry for each each class
1869 defined by the active buffer followed by entries for the
1870 imports and package of the current buffer. Selecting the entry
1871 for a class displays a submenu listing the inner classes,
1872 methods, and fields defined by the class. Selecting the entry
1873 for an inner class displays another submenu for that class,
1874 and so on. Selecting the
1875 <span><strong class="guimenu">imports</strong></span> entry on
1876 the top-level menu displays a submenu listing all the classes
1877 and packages imported by the active buffer.</p><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e4836"></a><a name="SpecialIndexEntries"></a> Special Index
1878 Entries</h5></div></div></div><p>The index menu includes the following special index
1879 entries:</p><div class="itemizedlist"><ul type="disc"><li><p><span><strong class="guimenu">*Rescan*</strong></span></p><p>Selecting this item causes the JDE to rebuild the
1880 index menu. You should rebuild the menu whenever you
1882 </p></li><li><p><span><strong class="guimenu">*class
1883 def*</strong></span></p><p>Selecting this item takes you to the start of the
1884 definition of the class on whose submenu it appears.
1886 <code class="varname">jde-imenu-include-classdef</code> off to
1887 suppress inclusion of these items in the menu. </p></li></ul></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e4860"></a><a name="AlphabetClassesMenu"></a>Alphabetizing the
1888 Classes Menu</h5></div></div></div><p>By default the
1889 <span><strong class="guimenu">Classes</strong></span> menu
1890 lists methods and fields in the order in which the active
1891 buffer defines them. Use the variable
1892 <code class="varname">jde-imenu-sort</code> to customize the menu to
1893 list methods and fields alphabetically in either ascending
1894 or descending order.</p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e4873"></a><a name="SuppressingSignatures"></a>Suppressing Method
1895 Signatures and Field Types</h5></div></div></div><p>By default the
1896 <span><strong class="guimenu">Classes</strong></span> menu
1897 displays the signatures of methods and the types of fields
1898 displayed in the active buffer. The method signatures enable
1899 you to distinguish overloaded method names. The menu can
1900 also display the names of methods and fields without
1901 signatures and types. Use the variable
1902 <code class="varname">jde-imenu-include-signature</code> to turn
1903 signature and type display off or on. </p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e4886"></a><a name="DisablingClassesMenu"></a>Disabling the
1904 Classes Menu</h5></div></div></div><p>Set the variable <code class="varname">jde-imenu-enable</code> off
1906 <span><strong class="guimenu">Classes</strong></span> menu.
1907 When disabled, the menu does not appear in the Emacs
1908 menubar.</p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e4899"></a>Using the Keyboard to Navigate the Classes Menu</h5></div></div></div><p>
1909 Execute <code class="command">M-x imenu</code> to use the keyboard
1910 to navigate the Classes menu. Emacs displays the
1911 top-level items on the Classes menu in a buffer and
1912 prompts you to enter the name of an an item in the
1913 minibuffer. Enter the name of the item to select it.
1914 Note that you can use completion to avoid having to
1915 type the whole name. If you select a submenu, Emacs
1916 displays the contents of the submenu and prompts
1917 you to enter a selection in the keyboard. If you
1918 select an index entry, Emacs scrolls the buffer
1919 to the indexed point in the buffer.
1920 </p></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e4907"></a><a name="Speedbar"></a>Using the Speedbar</h4></div></div></div><p>To display the speedbar, select <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guimenuitem">Browse</strong></span>-><span><strong class="guimenuitem">Source Files</strong></span>. The
1921 speedbar opens in a separate frame.</p><div class="screenshot"><div class="mediaobject"><img src="images/speedbar1.gif" alt="Screenshot showing the speedbar."></div></div><p>
1922 </p><p>The speedbar displays a list of the files and
1923 subdirectories in the directory containing the file displayed
1924 in the current buffer. The speedbar highlights the file
1925 displayed in the current buffer.</p><p>Click on the expand (+) button in front of any file. The
1926 node for the file expands</p><p>
1927 </p><div class="screenshot"><div class="mediaobject"><img src="images/speedbar2.gif" alt="Screenshot showing a speedbar entry."></div></div><p>
1928 </p><p>to show up to three entries, depending on the contents of
1929 the source file. </p><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e4946"></a><a name="Package"></a>Package</h5></div></div></div><p>
1930 This item expands to show the package to which the file
1932 </p><div class="screenshot"><div class="mediaobject"><img src="images/speedbar3.gif" alt="Screenshot showing a speedbar entry."></div></div><p>
1934 Clicking on the package scrolls the buffer to the
1935 corresponding package declaration.
1936 </p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e4963"></a><a name="Types"></a>Types</h5></div></div></div><p>
1937 This item expands to show the classes in the selected file.
1938 </p><div class="screenshot"><div class="mediaobject"><img src="images/speedbar4.gif" alt="Screenshot showing a speedbar entry."></div></div><p>
1940 Each class expands to show the constructors, methods,
1941 fields, and inner classes defined by the class and the
1942 class's parent, if any. Inner classes also expand and their
1943 inner classes, and so on. The constructors and methods
1944 expand to show arguments and argument types and return
1945 types. Fields expand to show their type.
1947 Clicking on any class, inner class, method, constructor, or
1948 field scrolls the buffer to show that item.
1949 </p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e4982"></a><a name="Dependencies"></a>Dependencies</h5></div></div></div>
1951 This item expands to show the classes and packages imported by the current source file.
1953 <div class="screenshot"><div class="mediaobject"><img src="images/speedbar5.gif" alt="Screenshot showing a speedbar entry."></div></div><p>
1954 </p><p>Click on class or package to scroll the buffer to the
1955 corresponding import statement.</p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e4998"></a><a name="UpdatingSpeedbar"></a>Updating the
1956 Speedbar</h5></div></div></div><p>If you make changes to a source buffer, you must update
1957 the speedbar view to reflect the changes. To update the
1958 speedbar view of a buffer:</p><div class="procedure"><ol type="1"><li><p>
1959 Collapse the speedbar view of the buffer.
1961 This is necessary only if the speedbar view is expanded.
1962 To collapse the speedbar view, click the collapse button
1963 (-) next to the buffer's file name in the speedbar view.
1964 </p></li><li><p>Hold the shift key down while clicking the expand
1965 button (+) next to the buffer's name in the speedbar
1966 view. </p></li></ol></div></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e5013"></a><a name="SearchSource"></a>Searching Source Code</h2></div></div></div><p>The JDEE provides commands that enable you to find</p><div class="itemizedlist"><ul type="disc"><li><p>
1967 All occurences of strings matching a regular expression anywhere
1968 in your project's source path (see <a href="#FindExpressions">Finding
1971 Source code that defines the method, field,
1972 or other symbol at point (see <a href="#FindSymbolDef">Finding
1973 Symbol Definitions</a>)
1974 </p></li><li><p>Source code for the class at point (see <a href="#FindClasses">Finding
1975 Classes</a>)</p></li><li><p>Source for the parent of the class at point</p></li><li><p>Source for an interface implemented by the class at point</p></li><li><p>All methods that invoke a specifed method (see <a href="#Xref">Cross-Referencing
1976 Classes</a>)</p></li></ul></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e5050"></a><a name="FindExpressions"></a>Finding Expressions</h4></div></div></div><p>The JDEE provides two commands for finding occurrences of strings
1977 in Java source and other types of text files:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="command">JDE->Find->Expression</code>
1978 (<code class="function">jde-find</code>)</p><p>
1979 This command uses the minibuffer to prompt you for the
1980 search expression and the paths to be searched. You can
1981 use customization variables to specify values for the
1982 search paths and other search options. The default values
1983 for the customization variables search the Java source
1984 files on the classpaths and sourcepaths for your project.
1985 See <a href="#FindExpressionMinibuf">Using the Minibuffer-Based
1986 Find Command</a> for more information.
1987 </p></li><li><p><code class="command">JDE->Find->Expression...</code>
1988 (<code class="function">jde-find-dlg</code>)</p><p>This command uses a text dialog buffer to
1989 prompt you for search arguments. The dialog buffer
1990 allows you to specify all search options
1991 interactively. It is thus useful for performing
1992 searches that have special requirements.
1993 See <a href="#FindExpressionDlg">Using the Dialog-Based
1994 Find Command</a> for more information. </p></li></ul></div><p>
1995 Both commands use the Unix <code class="command">grep</code> and
1996 <code class="command">find</code> utilities to perform the searches that
1997 you specify. Before executing a search, both commands search
1998 your system for copies of <code class="command">grep</code> and
1999 <code class="command">find</code> and signal an error if the utilities
2000 are missing. All Unix systems include copies of
2001 <code class="command">grep</code> and <code class="command">find</code>. Versions
2002 of these utilities are available for Microsoft Windows, e.g.,
2003 as part of the Cygwin Unix emulation package for Microsoft
2004 Windows. If you want to use the JDEE's <code class="command">find</code>
2005 commands on Windows, you must install copies of
2006 <code class="command">grep</code> and <code class="command">find</code> on your
2007 system and either include them in your system's command path
2008 or use the variables <code class="varname">grep-command</code> and
2009 <code class="varname">find-program</code> to specify their respective
2010 locations on your system.
2011 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
2012 Microsoft Windows/NT and Windows 2000 provide a
2013 <code class="command">find</code> utility that is incompatible with
2014 the Unix <code class="command">find</code> utility. To ensure that the
2015 JDEE finds the right version, you should either put the
2016 Unix-style <code class="command">find</code> command ahead of the
2017 Windows <code class="command">find</code> command in your system
2018 command path or use the <code class="varname">find-program</code>
2019 variable to specify the Unix-style command's location.
2020 </p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e5136"></a><a name="FindExpressionMinibuf"></a>Using the
2021 Minibuffer-Based Find (jde-find) Command</h5></div></div></div><p>To find an expression with the minibuffer-based find
2022 command:</p><div class="orderedlist"><ol type="1"><li><p>
2024 <span><strong class="guimenu">Find</strong></span>-><span><strong class="guimenuitem">Expression</strong></span> (<span><strong class="shortcut"><span class="keysym">C-c</span>-<span class="keysym">C-v</span>-<span class="keysym">C-f</span></strong></span>)
2025 from the <span><strong class="guimenu">JDE</strong></span> menu
2026 or execute the <code class="command">jde-find</code> command.
2027 </p><p>The JDEE prompts you to enter a regular expression.</p><div class="screenshot"><div class="mediaobject"><img src="images/find_minibuf_prompt_regex.gif" alt="Screenshot showing the regular expression prompt."></div></div></li><li><p>Enter a regular expression that matches the
2028 expressions you want to find and press <span><strong class="keycap">Enter</strong></span>.</p><p>The JDEE prompts you to enter a list of directories to search.</p><div class="screenshot"><div class="mediaobject"><img src="images/find_minibuf_prompt_dirs.gif" alt="Screenshot showing the directories prompt."></div></div><p>The prompt may list a default search path. The JDEE determines the
2029 default path by testing each of the following variables in the order
2030 listed.</p><div class="itemizedlist"><ul type="disc"><li><p><code class="varname">jde-sourcepath</code></p></li><li><p><code class="varname">jde-compile-option-sourcepath</code></p></li><li><p><code class="varname">jde-compile-option-classpath</code></p></li><li><p><code class="varname">jde-global-classpath</code></p></li></ul></div><p>The JDEE uses the directories
2031 specified by the first path variable that has a nonnil
2032 value as the default search path.</p></li><li><p>Edit the default search path, if desired, in the minibuffer
2033 and press <span><strong class="keycap">Enter</strong></span>.</p><p>The JDEE executes the find command that you have specified
2034 and displays the command's output in a popup grep-mode buffer.</p><div class="screenshot"><div class="mediaobject"><img src="images/find_minibuf_result.gif" alt="Screenshot showing the search results."></div></div></li></ol></div><p>The search results buffer lists each instance of a string
2035 that matches the specified regular expression in the specified
2036 search path. For each match, the listing shows the file
2037 and line number of the match, highlighted in red, and a snippet
2038 of the text in which the match occurred.
2039 </p><p>To visit the file containing the match, click the
2040 match message in the grep buffer with the middle mouse button
2041 or move point to the message and press <span><strong class="keycap">Enter</strong></span></p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e5232"></a><a name="FindExpressionCustomize"></a>Customizing the
2042 Minibuffer-Based Find Command</h5></div></div></div><p>
2043 The following variables allow you to customize the
2044 minibuffer-based search command:
2045 </p><div class="table"><a name="d51e5238"></a><p class="title"><b>Table 1. </b></p><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Variable</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><code class="varname">jde-find-case-sensitive</code></td><td><code class="literal">nil</code></td><td>Specifies whether the <code class="command">jde-find</code> command
2046 performs a case-sensitive search. If non-nil, the
2047 search is case-sensitive; otherwise the search
2048 ignores case.</td></tr><tr><td><code class="varname">jde-find-granularity</code></td><td><code class="literal">Character</code></td><td>Specifies the granularity of the expression
2049 search conducted by <code class="command">jde-find</code>: <code class="literal">Character</code>
2050 (expression starting on any character), <code class="literal">Word</code> (match
2051 words only), <code class="literal">Line</code> (match lines only).</td></tr><tr><td><code class="varname">jde-find-file-regexp</code></td><td><code class="literal">*.java</code></td><td>Specifies the regular expression that the
2052 <code class="command">jde-find</code> command uses to select
2053 files to be searched. You can use any regular
2054 expression supported by the <code class="literal">-name</code>
2055 option of the GNU <code class="command">find</code>
2056 command.</td></tr></tbody></table></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e5300"></a><a name="FindExpressionDlg"></a>Using the Dialog-Based Find (jde-find-dlg) Command</h5></div></div></div><p>To find an expression with the dialog-based find command:</p><div class="orderedlist"><ol type="1"><li><p>
2058 <span><strong class="guimenu">Find</strong></span>-><span><strong class="guimenuitem">Expression...</strong></span>
2059 from the <span><strong class="guimenu">JDE</strong></span> menu
2060 or execute the <code class="command">jde-find</code> command.
2061 </p><p>The <span class="guilabel">Find Expression Options</span> buffer appears.</p><div class="screenshot"><div class="mediaobject"><img src="images/find_options_buffer.gif" alt="Screenshot showing the Find Expression Options buffer."></div></div></li><li><p>Edit the buffer to reflect the search options that you desire.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The options you select will appear the
2062 next time you execute the <code class="command">jde-find-dlg</code> command.</p></div></li><li><p>Select the <span class="guibutton">Ok</span> button.</p></li></ol></div><p>The <code class="command">jde-find-dlg</code> invokes the
2063 <code class="command">find</code> and <code class="command">grep</code> commands
2064 with the options you specified and displays the results in a
2066 </p></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e5360"></a><a name="FindSymbolDef"></a>Finding Symbol Definitions</h4></div></div></div><p>To find the source code that defines the class, interface,
2067 method, or field at point, select
2068 <span><strong class="guimenu">Find</strong></span>-><span><strong class="guimenuitem">Symbol Definition</strong></span> (<span><strong class="shortcut"><span class="keysym">C</span>-<span class="keysym">c</span>
2069 <span class="keysym">C</span>-<span class="keysym">v</span>
2070 <span class="keysym">C</span>-<span class="keysym">y</span></strong></span>) from the <span><strong class="guimenu">JDE</strong></span> menu or
2071 execute <span class="keysym">M</span>-<span class="keysym">x</span>
2072 <code class="function">jde-open-class-at-point</code>. The JDEE
2073 displays a buffer containing the source code that defines the
2074 symbol at point in the original buffer.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This command requires that the symbol definition be
2075 located on <code class="varname">jde-sourcepath</code> and that the
2076 class referenced at point be located on
2077 <code class="varname">jde-global-classpath</code>. The command uses
2078 the beanshell to determine the fully qualified name of the
2079 class referenced at point. If the beanshell is not running,
2080 it launches the beanshell.</p></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e5411"></a><a name="FindClasses"></a>Finding Classes</h4></div></div></div><p>The <code class="function">jde-open-class-source</code> command
2081 finds and opens the Java source file for the class whose
2082 qualified or unqualified name appears at point.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The JDE uses Java reflection to determine the fully
2083 qualified name of the class at point. Therefore, the class
2084 must be on <code class="varname">jde-global-classpath</code>.</p></div><p>If more than one class with the same name exists on
2085 <code class="varname">jde-global-classpath</code>, this command prompts
2086 you to select one of the classes. The following conditions
2087 must be true for this command to work. First, a class file for
2088 this class must exist on the classpath specified by
2089 <code class="varname">jde-global-classpath</code>. Secondly, the source
2090 for the class must exist on one of the paths specified by
2091 <code class="varname">jde-sourcepath</code>. This command uses the
2092 Beanshell to determine the fully qualified name of the class
2093 to be found. It starts the Beanshell if necessary. Thus, the
2094 command may respond somewhat slowly the first time you it in a
2095 session. </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e5437"></a><a name="Xref"></a>Cross-Referencing Classes</h4></div></div></div><p>JDE includes a facility for creating and utilizing a
2096 cross-referencing database to enable you to quickly locate all
2097 the callers of any particular function. This functionality is
2098 very useful for quickly figuring how unfamiliar code works,
2099 and useful for doing certain tasks such as renaming functions.
2100 Be advised that this only finds direct callers, and cannot
2101 detect calls via Java's reflection mechanism. The
2102 cross-reference database must be kept in sync with the project
2103 code, however the database generation is generally quick. The
2104 remainder of this section explains how to configure and use
2105 the cross-referencer.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>The JDEE's cross-referencing facility was developed by Andrew Hyatt.</div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e5445"></a><a name="ConfigXRef"></a>Configuring the Cross-Referencer</h5></div></div></div><p>JDE's cross-referencing database is built by examining
2106 class files for a particular project. To this end, JDE
2107 needs to know where the built class files for a project
2108 live. This is usually a subset of the classpath.
2109 </p><p>Then select JDE->Options->Project->General, and go to
2110 the "Jde Built Class Path" option. Insert one path for each
2111 place where built classes wind up. You can add both
2112 directories and zip files (jar/bar/etc). Any file entered
2113 will be assumed to be a zip file.</p><p>Now that you have the built class path defined, you can
2114 configure the cross-referencer that uses it. Type M-x
2115 jde-xref-customize. The following are a list the variables
2116 that can be set, and what they do:
2117 </p><div class="itemizedlist"><ul type="disc"><li><p><code class="varname">jde-xref-db-base-directory</code></p><p>The cross-referencer creates a database to
2118 store the cross-reference information. This variable
2119 defines a directory where that information resides. It
2120 might, for example, be at the base of your project tree,
2121 in a directory called xrefdb
2122 </p></li><li><p><code class="varname">jde-xref-store-prefixes</code></p><p>To reduce database size,
2123 it's useful to ignore all information that doesn't refer
2124 to code you care about. For example, most people don't
2125 need to know who calls java.lang.System.out.println. To
2126 not store this information, insert a package prefix for
2127 each package you are interested in. Typically, this may
2128 be just one string, for example "com.mycompany", to
2129 store only code that references com.mycompany
2130 classes.</p></li><li><p><code class="varname">jde-xref-cache-size</code></p><p>The caller database can be quite large. However, it
2131 is useful for efficiency reasons to keep part of it in
2132 memory. This variable deterines how many packages to
2133 keep in memory simulatenously. The higher this is, the
2134 faster things will be, but also the more memory will be
2135 taken up by the cross-reference information.
2136 </p></li></ul></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e5474"></a><a name="BuildingXRefDB"></a>Building the Cross-Reference Database</h5></div></div></div><p>The next step into getting the cross-reference
2137 functionality working is to build the cross-reference
2138 database. The project must be fully built for this to work,
2139 since it takes cross-reference information directly from the
2141 </p><p>To build the database, type <code class="command">M-x jde-xref-make-xref-db</code></p><p>If all the settings are properly configured, JDE will go
2142 off and create the cross-reference database. This can take
2143 from a few seconds to several minutes depending on the size
2144 of your project. Large class files may take long to parse,
2145 so if it seems to be "stuck", please give it time.
2146 </p><p>When it is done, it will save the database in the base
2147 directory specified in the jde-xref customization group.
2148 </p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e5488"></a><a name="UsingXRefDB"></a>Using the Cross-Reference Database</h5></div></div></div><p>There are several basic operations that use the
2149 cross-reference database:
2150 </p><div class="itemizedlist"><ul type="disc"><li><p><code class="command">M-x jde-xref-first-caller (C-c C-v a)</code>
2151 </p><p> If your cursor is in the body of a function, then
2152 this will go to the first in a sequence of callers to
2153 this function. If there are no callers, there will be a
2155 </p></li><li><p><code class="command">M-x jde-xref-next-caller (C-c C-v n)</code></p><p> After calling <code class="command">jde-xref-first-caller</code>, you can go to
2156 each of the callers in sequence with this function. The
2157 first caller function creates a list of callers and goes
2158 to the first one. This navigates to the next caller on
2159 the list. You can keep calling this until there are no
2160 more callers, in which case there will be a message
2162 </p></li><li><p><code class="command">M-x jde-xref-display-call-tree</code>
2163 </p><p>This displays an interactive tree view of the
2164 function you are in, and it's callers. Each level down
2165 will show you who calls the parent function. In this
2166 way you can quickly get an overview of the context in
2167 which the current function is used in. Each item in the
2168 tree will take you to it's definition if it is clicked
2170 </p></li><li><p><code class="command">M-x jde-xref-list-uncalled-functions</code></p><p> Called from a java file, this lists all the
2171 functions in the file that have no apparent callers.
2172 It's important to remember that because of Java
2173 reflection, there is no guarantee that the functions are
2174 truly uncalled. It only means they are not called
2176 </p></li></ul></div><p>All of these functions have two modes, a strict and
2177 non-strict mode. In non-strict mode, the default, more
2178 potential callers are treated as callers, including those
2179 that call an interface that the function implements, or who
2180 call a superclass's function you are overriding. For
2181 example, if you are in Foo.doSomething(), and foo implements
2182 IFoo, and a caller calls IFoo.doSomething(), then this is
2183 treated as a caller in non-strict mode. Also, if you are in
2184 Foo.doSomething, and Foo's superclass is Bar, and there is a
2185 Bar.doSomething(), then Bar.doSomething() is treated as a
2186 caller in non-strict mode. In strict mode, however, the
2187 caller must specify the function directly for it to be
2188 considered a hit. To run these functions with strict mode,
2189 type C-u M-x and then the function-name. So C-u M-x
2190 jde-xref-list-uncalled-functions will list only functions
2191 that are uncalled directly.
2192 </p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e5526"></a><a name="UpdatingXRefDB"></a>Updating the Cross-Reference Database</h5></div></div></div><p>As the code changes, the cross-referencer must be kept
2193 up to date, or else the jde-xref functions will start taking
2194 you to incorrect places in files, and the callers list
2195 itself will become incorrect. As you change the code, you
2196 can call M-x jde-xref-update after a recompile, and it will
2197 go through and recompute just the part of the database you
2199 </p><p>Another, easier way to update, for those of us who leave
2200 their emacs running all the time, is to add a line such as
2201 this in their .emacs
2202 </p><pre class="programlisting">
2203 (run-at-time "11:00pm" 86400 'jde-xref-make-xref-db)
2204 </pre></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e5536"></a><a name="Tags"></a>Tags</h4></div></div></div><p>To use the <code class="varname">etags</code> facility, you must
2205 first construct a TAGS file that indexes every symbol in your
2206 source code. The JDE package contains two shell scripts that
2207 you can use to tag your source code, one for
2208 <code class="command">csh</code> shells and the other for
2209 <code class="command">bash</code>. The <code class="command">bash</code> version
2210 is called <code class="command">jtags</code>; the <code class="command">csh</code>
2211 version, <code class="command">jtags.csh</code>. </p><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e5563"></a><a name="TaggingCode"></a> Tagging Java Source Code</h5></div></div></div><p>To tag your source code, first copy the appropriate shell
2212 script to a directory in your Emacs path. Then start a shell (<span><strong class="keycap">M</strong></span>-<span><strong class="keycap">x</strong></span>
2213 shell). Change to the top-level directory containing your
2214 source code and then enter <code class="command">jtags</code>. The <code class="command">jtags</code>
2215 script tags every <code class="filename">.java</code> file in the current directory
2216 and in all descendants of the current directory, storing the
2217 result in a file called <code class="filename">TAGS</code> in the top-level directory.
2218 </p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e5587"></a><a name="FindingSymbols"></a>Finding the Definition of a Symbol</h5></div></div></div><p>To find the definition of a symbol, put your cursor anywhere
2219 in the symbol and enter
2220 <span><strong class="keycap">M</strong></span>-<span><strong class="keycap">.</strong></span>. Emacs
2221 responds by locating
2222 and opening (if necessary) the file containing the definition and
2223 positioning the point at the definition. (The first time you type
2224 <span><strong class="keycap">M</strong></span>-<span><strong class="keycap">.</strong></span>, Emacs
2225 prompts you to load the <code class="filename">TAGS</code> file.) </p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e5608"></a><a name="CustomizingJDE"></a>Customizing the JDE</h2></div></div></div><p>
2226 This section describes various ways you can customize the JDE.
2227 </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e5614"></a><a name="CustomizationVariables"></a>Customization Variables</h4></div></div></div><p>
2228 JDE customization variables allow you to specify compile, run, debug,
2229 and other JDE options. </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> The traditional way of customizing Emacs is to use
2230 <code class="varname">setq</code> forms to set the values of customization
2231 variables in the Emacs initialization (<code class="filename">.emacs</code>)
2232 file. This method does <span class="emphasis"><em>not</em></span> work for JDE
2233 customization variables. To set a JDE customization variable, you
2234 <span class="emphasis"><em>must</em></span> use the customization buffer for a variable
2235 (see the Emacs online manual for information on the customization
2236 feature). This is because the JDE context switching code resets all
2237 JDE customization variables to their default or customized (via a
2238 custom buffer) values whenever you open a Java source file or switch
2240 </p></div><p> The following section explains how to use the Emacs
2241 customization feature to set the value of a JDE customization
2242 variable.</p><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e5637"></a><a name="SettingVariable"></a> Setting a Customization Variable</h5></div></div></div><p>
2243 To set a JDE customization variable:
2244 </p><div class="procedure"><ol type="1"><li><p>Determine the name of the variable you want to customize.</p><p> Refer to the section of this guide that documents the feature
2245 you want to customize for the name of the corresponding variable. Or
2246 type <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">h</strong></span>
2247 <span class="keysym">v</span> followed by the JDE group prefix
2248 (<code class="varname">jde-</code>) or subgroup prefix (e.g.,
2249 <code class="varname">jde-compile-option-</code>,
2250 see <a href="#JDECustomizationGroups">JDE Customization Groups</a>).
2251 Emacs displays all variables belonging to the JDE group or subgroup. You
2252 can then browse this list, using Emacs search, completion, and
2253 documentation display command, to find the applicable variable.
2254 </p></li><li><p>Display a customization buffer for the variable. </p><p> If you know the name of the variable, the easiest way to
2255 display a customization buffer for the variable is to select
2256 <span><strong class="guimenu">Help</strong></span>-><span><strong class="guisubmenu">Customize</strong></span>-><span><strong class="guimenuitem">Specific Option...</strong></span> from the
2257 Emacs menubar or type <span><strong class="keycap">M</strong></span>-<span><strong class="keycap">x</strong></span> <code class="command">jde-customize-variable</code>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p><code class="command">jde-customize-variable</code> is a
2258 special version of the standard Emacs
2259 <code class="command">customize-variable</code> command that
2260 provides a customization buffer menu item for saving a
2261 customization in a JDEE project file (see below). You
2262 should use this version of the command if you intend
2263 to save customizations in project files. You can also
2264 use it to do any other type of customization that the
2265 standard command supports. This allows you to use the
2266 JDEE version of the command for all your
2267 customizations regardless of whether you intend to
2268 save them in project files. </p></div><p>
2269 If you know the group to which the variable belongs (.e.g., compile
2270 options), you can display the customization buffer for the group. This
2271 is useful when you want to customize several related variables. See
2272 <a href="#JDECustomizationGroups">JDE Customization Groups</a> for
2274 </p></li><li><p>Edit the value for the variable displayed in the customization
2275 buffer. </p></li><li><p>Save the value for the variable in your <code class="filename">.emacs</code>
2276 or <code class="filename">.prj</code> file.
2277 </p><p>If you want the setting to apply to all projects that do not
2278 have a project file (see <a href="#UsingProjectFiles">Using Project
2279 Files</a>), you should save the variable in your
2280 <code class="filename">.emacs</code> file. To save the variable in your
2281 <code class="filename">.emacs</code> file, select <span><strong class="guimenuitem">Save
2282 for Future Sessions</strong></span> from the
2283 <span><strong class="guimenu">State</strong></span> menu for the
2284 variable in the customization buffer.
2285 </p><p> If you want the setting to apply only to the current project,
2287 <span><strong class="guimenuitem">Save in JDEE Project File</strong></span> from the <span><strong class="guimenu">State</strong></span> menu for the variable.
2288 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
2289 The <span><strong class="guimenuitem">Save in JDEE Project File</strong></span> menu item appears only if you used the
2290 <code class="command">jde-customize-variable</code> command to create
2291 the customization buffer.
2293 If a project file does not exist for the project, the
2294 JDEE prompts you to enter a name for the project.
2295 It then creates a project file for the project with
2296 the name that you enter.
2297 </p></li></ol></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e5755"></a><a name="SpecifyingPaths"></a>Specifying Paths</h5></div></div></div><p>You can use paths containing environment variables and
2298 or a tilde (~), cygwin paths, and relative paths as a value
2299 of any JDE customization variable that requires a
2300 path.</p><div class="sect5" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d51e5761"></a><a name="EnvVarsInPaths"></a>Environment Variables</h6></div></div></div><p>The JDE accepts paths that contain envirnoment variables, for
2302 </p><pre class="programlisting">
2306 The JDE replaces the environment variables with their
2307 actual values before passing the paths to commands (e.g.,
2308 javac) that require them. You must use Unix notation
2309 (i.e., <code class="varname">$VARNAME</code> or
2310 <code class="varname">${VARNAME}</code>) to specify an environment
2311 variable in a path even on Windows.
2312 </p></div><div class="sect5" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d51e5780"></a><a name="TildeNotation"></a>Tilde (~) Notation</h6></div></div></div><p>The JDE accepts paths that begin with a tilde, for example,
2313 <code class="filename">~/myproj/classes</code>. The JDE replaces the tilde
2314 with the path to your home directory.</p></div><div class="sect5" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d51e5789"></a><a name="RelativePaths"></a>Relative Paths</h6></div></div></div><p>A relative path is a path that begins with a period, for
2315 example, <code class="filename">./src</code>. If
2316 <code class="varname">jde-resolve-relative-paths</code> is
2317 set to a non-nil value (the default), the JDE converts a relative
2318 path to an absolute path by appending the relative path to the
2319 path of the project file that set the path variable, or if no such
2320 file exists, to the path of the current Java source buffer.</p><p>
2321 You can use your <code class="filename">.emacs</code> file to
2322 specify default relative paths for projects. For example,
2323 setting <code class="varname">jde-global-classpath</code> to
2324 <code class="filename">./classes</code> in your
2325 <code class="filename">.emacs</code> file specifies that the
2326 default location of class files is in a subdirectory of
2327 the project file directory named <code class="filename">classes</code>.
2328 </p></div><div class="sect5" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d51e5818"></a><a name="CygwinPaths"></a>Cygwin Paths</h6></div></div></div><p>You can use cygwin style paths in JDE classpath variables
2329 on Windows. The JDE converts such paths to DOS paths before
2330 using them, using a conversion function that you can specify.</p><p>The jde-cgywin-path-converter variable allows you
2331 to choose the path conversion function used by the JDE.</p><div class="itemizedlist"><ul type="disc"><li><p><code class="function">
2332 jde-cygwin-path-converter-internal</code></p><p>This is the default path conversion function used by
2333 the JDE. It converts any paths of the form <code class="varname">//[a-z]/</code>
2334 or <code class="varname">//cygdrive/[a-z]/</code> to the corresponding DOS form. For
2335 example it converts <code class="varname">/c/jde/java/classes</code> to
2336 <code class="varname">c:/jde/java/classes</code>.
2337 </p></li><li><p><code class="function">jde-cygwin-path-converter-cygpath</code></p><p>This function invokes the cygwin
2338 <code class="function">cygpath</code> utility to perform the
2339 path conversion. The advantage is that the cygwin path
2340 utility can recognize and convert Unix style paths
2341 that represent mount points in the cygwin mount table.
2342 For example, suppose that you have mounted
2343 <code class="varname">d:/javadev</code> as
2344 <code class="varname">/javadev</code> in the cygwin mount table.
2345 Then choosing <code class="function">jde-cygwin-path-converter-cygpath</code>
2346 allows you to use paths beginning with
2347 <code class="varname">/javadev</code> in JDE classpaths. The
2348 drawback is that the conversion is slow as it requires
2349 running the cygwin utility for each Unix-style path to
2350 be converted.</p></li><li><p>A custom conversion function that you supply.</p></li></ul></div></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e5869"></a><a name="JDECustomizationGroups"></a> JDE Customization Groups</h5></div></div></div><p>The JDE defines a top-level customization group, the JDE
2351 Group, for JDE customization variables. The JDE Group itself
2352 contains the following subgroups:</p><div class="sect5" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d51e5875"></a><a name="CompileOptionGroup"></a> Compile Option
2353 Group</h6></div></div></div><p>Specifies compile options corresponding to the
2354 command-line arguments (e.g., -d) accepted by the JDK
2355 compiler, javac. When you execute the JDE compile command,
2356 the JDE uses the settings of this group to construct a list
2357 of command-line arguments that it passes to the Java
2358 compiler that the JDE uses to compile Java source programs.
2359 The compiler is itself an option that you can specify (see
2360 the Project Option Group). You can specify command-line
2361 arguments directly by setting the value of the
2362 <code class="varname">jde-compile-option-command-line-args</code>
2363 variable. You can display the customization buffer for the
2364 Compile Option Group by selecting
2365 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">
2366 Project</strong></span>-><span><strong class="guisubmenu">Options</strong></span>-><span><strong class="guimenuitem">Compile</strong></span> from the
2367 <span class="productname">Emacs</span>™ menubar. </p></div><div class="sect5" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d51e5898"></a><a name="CompileOptionGroup"></a>Run Option Group</h6></div></div></div><p>Specifies run-time options corresponding to the
2368 command-line arguments (for example, -classpath) accepted
2369 by the JDK virtual machine, java. When you execute the JDE
2370 Run command, the JDE uses the settings of this group
2371 to construct a list of command-line arguments that it
2372 passes to the Java interpreter used by the JDE to run
2373 applications. This group also contains options for
2374 specifying non-java command-line arguments (in case you
2375 want to use a VM that accepts a different set of arguments
2376 than java does) and for specifying arguments to be passed
2377 to the application (as opposed to the virtual machine
2378 interpreting the application.) You can display the
2379 customization buffer for the Run Option Group by selecting
2380 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Project</strong></span>-><span><strong class="guisubmenu">Options</strong></span>-><span><strong class="guimenuitem">Run</strong></span> from the
2381 <span class="productname">Emacs</span>™ menubar. </p></div><div class="sect5" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d51e5918"></a><a name="DebugOptionGroup"></a>Debug Option Group</h6></div></div></div><p>Specifies run-time options corresponding to the command-line
2382 arguments (for example, -classpath) accepted by the JDK debugger,
2383 jdb. jdb accepts the same command-line arguments as java. However,
2384 the JDE maintains two parallel sets of configuration variables
2385 for these programs in case you want to use a different set of
2386 options for running a program in debug mode then you use for
2387 running it normally. When you execute the JDE Debug command,
2388 the JDE uses the settings of this group to construct a list of
2389 command-line arguments that it passes to the Java debugger used
2390 by the JDE to run applications in debug mode. You can display the
2391 customization buffer for the Debug Option Group by selecting
2392 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Project</strong></span>-><span><strong class="guisubmenu">Options</strong></span>-><span><strong class="guimenuitem">Debug</strong></span>
2393 from the <span class="productname">Emacs</span>™ menubar. </p></div><div class="sect5" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d51e5938"></a> <a name="AutocodeGroup"></a>Autocode Group</h6></div></div></div><p>Specifies templates used to generate code automatically. </p></div><div class="sect5" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d51e5945"></a><a name="GeneralGroup"></a> General Options Group</h6></div></div></div><p>Specify all other JDE options. You can display the
2394 customization buffer for the General Option Group by selecting
2395 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Project</strong></span>-><span><strong class="guisubmenu">Options</strong></span>-><span><strong class="guimenuitem">General</strong></span>
2396 from the <span class="productname">Emacs</span>™ menubar. </p></div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e5965"></a><a name="Customizingjde_mode"></a> Customizing jde-mode</h4></div></div></div><p>The JDE defines a major mode, named jde-mode, for editing
2397 Java source files. This mode derives from the standard Emacs
2398 Java source editing mode java-mode. In particular, it inherits
2399 all the functions and customization variables defined by
2400 java-mode and adds its own customization variables. When you
2401 load a Java source file, Emacs runs a JDE mode initialization
2402 function called jde-mode. The jde-mode function in turn calls
2403 the Java mode intialization function, java-mode. The last
2404 thing that jde-mode does before returning is to call a JDE
2405 mode function, if it exists. You can customize the JDE by
2406 defining a JDE mode hook function in your .emacs file. The
2407 following is an example of how to do this: </p><pre class="programlisting">
2408 (defun my-jde-mode-hook ()
2409 (message "my-jde-mode-hook function executed"))
2410 (add-hook 'jde-mode-hook 'my-jde-mode-hook)
2411 </pre><p>The preceding example defines a JDE mode hook function named
2412 my-jde-mode-hook and adds it to the list of JDE mode hook
2413 functions, using the Emacs Lisp function add-hook. Now, whenever
2414 you open a Java source file, jde-mode invokes the function my-jde-mode-hook.
2415 Of course, the hook function defined in this example is trivial.
2416 A real-world example might do something more useful, such as
2417 setting a custom indentation style. </p><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e5975"></a><a name="Keybindings"></a> Customizing Key Bindings</h5></div></div></div><p>A key binding establishes an equivalence between a keystroke
2418 or a sequence of keystrokes and an interactive Lisp function. The
2419 keystroke or keystroke combination causes Emacs to execute the
2420 function to which the keystroke (combination) is bound. For
2421 example, the JDE by default binds the keystroke <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">c</strong></span> <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">v</strong></span> <span><strong class="keycap">C</strong></span>-<span><strong class="keycap">c</strong></span>
2422 to the function <code class="varname">jde-compile</code>. You can use the JDE
2423 customization facility to change the standard JDE bindings or
2424 create bindings for functions that do not have default bindings. </p><p>To customize key bindings: </p><div class="procedure"><ol type="1"><li><p>Open a buffer on the JDE customization variable <code class="varname">jde-key-bindings</code>.</p><p>You can do this by typing
2425 <span><strong class="keycap">M</strong></span>-<span><strong class="keycap">x</strong></span> <code class="varname">customize-variable</code>
2426 <code class="varname">jde-key-bindings</code> or by selecting <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu">Options</strong></span>-><span><strong class="guimenuitem">Project</strong></span> and searching the
2427 resulting JDE project customization buffer for
2428 <code class="varname">jde-key-bindings</code>. </p><p>The key bindings panel looks like this: </p><div class="screenshot"><div class="mediaobject"><img src="images/keybindings.gif" alt="Screenshot showing key bindings buffer."></div></div><p>
2429 </p></li><li><p>Edit the buffer to specify altered or new bindings. </p><p>For example, to add a binding, right click the
2430 <span class="guibutton">[INS]</span> button, then enter the key stroke in the
2431 <span class="guilabel">Key</span> field and the interactive function (command)
2432 to which it is bound in the <span class="guilabel">Command</span> field.</p></li><li><p>Save the edited bindings. </p><p>To save the edited bindings, right click the
2433 <span class="guibutton">[State]</span> button and choose <span><strong class="guimenuitem">Set for current session</strong></span> if you
2434 want the settings to apply only to the current project or
2435 <span><strong class="guimenuitem">Save for future
2436 sessions</strong></span>if you want the settings to apply
2437 to all projects. In either case, you should save the new settings in
2438 you project file if your project has a project file. To save the new
2439 settings in your project file, switch to a source buffer and choose
2440 <span><strong class="guimenu">JDE</strong></span>-><span><strong class="guisubmenu"> Options</strong></span>-><span><strong class="guimenuitem">Save Project</strong></span> from the Emacs menubar.
2441 </p></li></ol></div></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d51e6085"></a><a name="Plugins"></a>Creating and Installing Plugins</h2></div></div></div><p>Plugins are independently developed applications intended
2442 for use with the JDEE and distributed in the form of a (g)zip or
2443 jar file. The following sections explain how to create and install
2445 </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e6091"></a><a name="InstallingPlugins"></a>Installing a Plugin</h4></div></div></div><p>To install a plugin:</p><div class="orderedlist"><ol type="1"><li><p>Copy the zip or jar file containing the plugin in to
2446 the JDEE's plugins directory.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>By default the JDEE plugin directory is a
2447 subdirectory of the JDEE directory named
2448 <code class="filename">plugins</code>. If you want to keep your
2449 plugins in another directory, set
2450 <code class="varname">jde-plugins-directory</code> to the path of
2451 that directory.</p></div></li><li><p>Execute <code class="command">M-h jde-pi-install-plugins</code>.</p><p>This command installs any plugins at the top level of the plugins
2452 directory in the plugins directory.</p></li></ol></div><p>If the plugin adds any menu items to the JDEE's plugins menu
2453 (named <span><strong class="guimenu">JDEpi</strong></span>), you should now be able to see the
2454 items on the plugins menu.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d51e6123"></a><a name="CreatingPlugins"></a>Creating a Plugin</h4></div></div></div><p>The following sections explain how to create a JDEE plugin.</p><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e6129"></a><a name="PluginRequirements"></a>Plugin Requirements</h5></div></div></div><p>A JDEE plugin must meet the following requirements:</p><div class="sect5" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d51e6135"></a>Packaging</h6></div></div></div><p>The plugin must be distributed as a compressed file that can be
2455 decompressed by Java's jar program. Compressed file formats that meet this
2456 requirement include zip, gzip, and jar.
2457 </p></div><div class="sect5" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d51e6140"></a>Directory Structure</h6></div></div></div><p>Decompressing the plugin should create a subdirectory in the
2458 current directory whose name is the plugin's name and that contains
2459 at least one directory named <code class="filename">lisp</code>. The
2460 plugin directory can contain any number of other directories.
2461 The other directories can have any names. However, it would be
2462 nice if plugins standardized on the following directory structure
2464 </p><pre class="programlisting">
2473 src (e.g., xml files used to generate info and html)
2477 lib (e.g, jar files)
2480 </pre></div><div class="sect5" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d51e6150"></a>Bootstrap File</h6></div></div></div><p>The plugin's lisp directory must contain a Lisp file
2481 named <code class="filename">jde-PLUGIN.el </code>where PLUGIN is
2482 the same as the plugin's toplevel directory name. This
2483 file is called a bootstrap file because it is the only
2484 file directly loaded by the JDEE. It is responsible for
2485 registering the plugin with the JDEE and loading any other
2486 Lisp files required by the plugin.</p></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e6158"></a><a name="RegisteringPlugin"></a>Registering a Plugin</h5></div></div></div><p>A plugin's bootstrap file must register the plugin with
2487 the JDEE when it is loaded. The bootstrap file should do
2488 this by invoking the JDEE's
2489 <code class="function">jde-pi-register</code> function. This function
2490 takes a single argument: an instance of
2491 <code class="varname">jde-plugin</code> class that optionally
2492 specifies the plugin's menu and its contribution to the
2493 classpath of the instance of the BeanShell run by the
2494 JDEE. </p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e6170"></a>Running Java Code from a Plugin</h5></div></div></div><p>A plugin can use the JDEE's instance of the BeanShell to
2495 invoke Java methods and display their output in an Emacs
2496 buffer. The JDEE provides the following functions for this
2497 purpose:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="function">jde-jeval</code></p><p>Evaluate a Java statement in the JDEE's BeanShell
2498 instance and return the resulting BeanShell
2499 output.</p></li><li><p><code class="function">jde-jeval-r</code></p><p>Evaluate a Java statement in the JDEE's BeanShell
2500 instance, use the Emacs Lisp interpreter to evaluate the
2501 resulting BeanShell output, and return the result. This
2502 function assumes that the Java statement emits Emacs
2503 Lisp code, i.e., that the Java code was developed
2504 specifically to cause Emacs to do something.
2505 </p></li><li><p><code class="function">jde-jeval-cm</code></p><p>Evaluate a Java statement in the JDEE's BeanShell
2506 instance and display the resulting BeanShell output in
2507 an Emacs compilation buffer. This function is intended
2508 to run Java applications, such as style checkers, that
2509 output error messages keyed to specific lines in a
2511 </p></li></ul></div><p>See the doc strings for these functions for more information.</p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d51e6196"></a><a name="BootstrapExample"></a>Bootstrap File Example</h5></div></div></div><p>
2512 The following is an example of the bootstrap file
2513 for a plugin named pi1.</p><pre class="programlisting">
2516 (defun jde-pi1-cmd ()
2518 (message "plugin 1"))
2524 (expand-file-name "lib/lib1.jar" (jde-pi-get-plugin-dir "pi1"))
2525 (expand-file-name "lib/lib2.jar" (jde-pi-get-plugin-dir "pi1")))
2526 :menu-spec (list (list "Pi1" ["cmd" jde-pi1-cmd :active t]))))
2531 </pre></div></div></div></div></body></html>
projects / packages / blob