JDEE User's Guide
Revised for JDEE 2.3.3
1997
1998
1999
2000
2001
2002
2003
Paul Kinnucan
Introduction
Welcome to the JDEE User's Guide. This
guide explains how to use the JDEE to develop Java applications and
applets. The guide assumes that you are familiar with Emacs, the
Java programming language, and the Java development tools provided
with the Java Development Kit (JDK) from Sun Microsystems,
Inc. and compatible tools provided by other vendors.
About the JDEE
The Java Development Environment for Emacs (JDEE) is an
Emacs Lisp package that interfaces Emacs to third-party Java
application development tools, such as those provided by Sun
Microsystems as part of its JDK. The result is an integrated
development environment (IDE) comparable in power to many
commercial Java IDEs. Features include:
source code editing with syntax highlighting and auto
indentation
automatic completion of class fields and methods
compilation with automatic jump from error messages
to responsible line in the source code.
generates class and method skeletons automatically
run Java application in an interactive (comint)
Emacs buffer
integrated debugging with interactive debug command
buffer and automatic display of current source file/line
when stepping through code
browse JDK doc, using the browser of your choice
browse your source code, using the Emacs etags facility
or a tree-structured speedbar.
supports latest version of JavaSoft's Java Development
runs on any platform supported by Emacs and Sun's Java SDK (e.g.,
Win95/NT and Solaris)
easily and infinitely customizable
works with FSF Emacs and XEmacs
JDE Requirements
The JDE requires the following software:
FSF Emacs or
XEmacs on Unix
platforms; the 20.6.1 version (or later) of
NT/Emacs on
Windows platforms, for general source file editing and tool integration functions.
Java
Development Kit (JDK) or compatible set of Java
development tools (compiler, virtual machine, debugger,
class libraries, etc.)
Web browser (e.g., Netscape or Internet Explorer) for
viewing documentation.
latest versions of Eric Ludlam's speedbar,
semantic, and
eieio packages available for download from
the CDET home page
The elib package available from the
JDE web site
bash or another Unix-style shell highly
recommended for Windows95/NT environments. The cygwin
Unix emulation package for Windows from Red Hat includes
bash.
JDEE Components
The JDEE distribution includes the following files:
jde.el.
Defines jde-mode, a major Emacs mode for developing Java code.
jde-run.el.
Runs Java applications and applets
jde-db.el.
Interfaces Emacs to jdb, the command-line debugger that
comes with the JDK.
jde-gen.el.
Contains code generation templates.
bsh.jar. Compiled files for the
BeanShell,
a Java source code interpreter developed by Pat Neimeyer.
beanshell.el.
Provides an Emacs interface to the BeanShell interpreter.
jde-wiz.el.
Provides "wizards" that generate skeleton
implementations of interfaces and skeleton overrides of
methods declared by superclasses.
jde-complete.el.
Automatic field and method completion package.
jde-parse.el.
Java parser package.
java.bnf.
Java grammar used to generate the JDE's lisp-based Java parser.
jde-bug.el
.
JDEbug user interface package.
jde-dbs.el.
JDEbug low-level command interface package.
jde-dbo.el.
JDEbug output processing functions.
source code, jar files, and documentation for the Java components of the
JDE.
jtags
is a bash shell script that tags Java source hierarchies.
jtags.csh
is a c shell script that tags Java source heierarchies.
Latest Version
See
Downloading the JDE on the JDE website for instructions on
downloading the most recent version of the JDE.
Installing the JDE
See the
JDE Installation Guide on the JDE website for information
on installing the JDE on your system.
Contacting the Author
Please send bug reports and enhancement suggestions to
Paul Kinnucan.
Registering and Selecting a JDK
The JDEE relies on command-line Java development tools, such
as those supplied by Sun Microsystems as part of its Java
Software Development Kit (SDK) also known as a Java Development
Kit (JDK). Before you can use the JDEE to compile, debug, or run
an application, you must tell it where the Java compiler,
debugger, and virtual machine are located on your system. The
JDEE assumes that the compiler, debugger, and vm are named
javac, jdb, and
java, respectively, and that they are
located on your system's command path. If these tools are not
located on the system command path or have different names, you
must tell the JDEE where they are located. The JDEE provides
customization variables for specifying the locations of
individual tools.
However, if you are using one or more versions of Sun's JDK or a
clone of the Sun JDK, the easiest way to specify the location of
the external development tools is to register the version of the
JDK that you intend to use. It is especially advantageous to
register a JDK, if you intend to use multiple versions of the
JDK. The reason? Registering each version of the JDK allows you
to change JDKs by changing a single customization variable. The
following sections explain how to register and select
JDKs.
Registering a JDK
To register a version of the JDK with the JDEE:
Start Emacs.
Type M-x customize-variable and
press Enter
Emacs prompts you to enter the name of a variable
to customize.
Enter jde-jdk-registry and
press Enter.
The jde-jdk-registry customization
buffer appears.
Click the INS button.
The entry for the JDK appears.
Enter the version number of the JDK and the path of the directory
in which the JDK is installed.
Repeat the preceding steps until you have entered the versions and
paths of all versions of the JDK that you wish to use with the JDEE.
Click the State button.
The State menu appears.
Select Save for Future Sessions from
the State menu.
Click the Finish button to dismiss
the customization buffer.
Selecting a JDK
To select a JDK:
Type M-x customize-variable and
press Enter
Emacs prompts you to enter the name of a variable
to customize.
Enter jde-jdk and
press Enter.
The jde-jdk customization
buffer appears.
The buffer lists the JDKs that you have previously registered
(see Registering a JDK).
Click the radio button next to the version of the JDK you
want to use.
Click the State button.
The State menu appears.
Select Save for Future Sessions from
the State menu.
Click the Finish button to dismiss
the customization buffer.
This procedure saves your JDK selection in your
.emacs file so that it applies to all
projects. You can configure the JDEE to use different JDKs
for different projects by saving your customization in a
project file. See Using
Project Files or more information.
Editing Java Source Files
To edit an existing Java source file, load it into an Emacs
buffer by executing C-x C-f. Loading a Java source file
into a buffer causes the buffer to enter into jde-mode,
a variant of java-mode, which is in turn a variant of
the standard Emacs cc-mode for editing source files
written in C and related languages. jde-mode offers all the
specialized source file editing commands of cc-mode plus
functions for creating, compiling, building, running, and debugging Java source files.
You can invoke the commands by selecting them from the JDE
menu that jde-mode displays on the Emacs menu bar or by
typing the commands in the Emacs minibuffer.
Screenshot showing the JDE menu.
Documenting Code
The JDE provides complete support for generating HTML
documentation for Java classes from comments inserted into the
source code for those classes.
See also
Displaying Java
Documentation
Inserting Javadoc
Comments
To insert a skeleton javadoc comment for a class or method,
position point in the first line of the method or class and
select JDE->Document from the
Emacs menubar or type C-c C-v j.
To customize the javadoc skeletons, select
JDE->Options->Project->Javadoc
from the Emacs menubar.
Thanks...
to David Ponce
for developing the JDE's javadoc comment generation
facility.
Generating the
Documentation
To generate documentation for the current project, open any
source file in the project and select Make
Doc from the JDE menu or
enter M-x jde-javadoc-make.
The jde-javadoc-make command runs the JDK's
javadoc program to generate the documentation. The
javadoc command must be on your system's
command path.
The jde-javadoc-make command uses
jde-global-classpath as the
-classpath and jde-sourcepath
as the -sourcepath option for
generating the doc. You can specify all other javadoc options
via JDE customization variables. To specify the options,
select Project
OptionsJavadoc
from the
JDE menu. Use
jde-javadoc-gen-packages to specify the
packages, classes, or source files for which you want to
generate javadoc. If this variable is
nil, the
jde-javadoc-make generates javadoc for
the Java source file in the current buffer.
Thanks to Sergey A
Klibanov for developing the JDE's javadoc
generation facility.
Abbreviations
The JDEE allows you to use abbreviations for Java keywords and
control flow constructs. The following sections explain how to
use these abbreviations.
Keyword
Abbreviations
The JDEE defines a set of abbreviations for Java keywords.
When you type one of these abbreviations followed by a space
in a Java source buffer, the JDE optionally expands the
abbreviation into the keyword. For example, when the
abbreviation mode is enabled, you need only type
fa followed by a space to enter the Java
keyword false. To enable or disable
abbreviation mode, select JDE
ProjectOptions
General
and toggle the boolean variable
jde-enable-abbrev-mode. To change, remove,
or add an abbreviation, edit the variable
jde-mode-abbreviations in the project
customization buffer.
The JDE's Java keyword expansion facility is based
on the Emacs abbrev-mode facility. For
more information, see the Emacs user manual.
Control Flow
Abbreviations
The JDEE defines abbreviations for Java control flow
structures, such as if-then-else. When you enter the
abbreviation followed by a space, the JDE expands the
abbreviation into a corresponding control structure
template.
Expanding a Control Flow Abbreviation
The if-then-else abbreviation
ife
expands to the control flow structure
if ( ) { } // end of if () else } // end of if ()else
Control Flow Abbreviations
The JDE defines the following abbreviations for control
structures.
Control Flow Abbreviations
StatementAbbreviation
if-then
if
else
else
if-then-else
ife
else-if
eif
while
while
for
for
for (int
I=0;I<UL;I++)
fori
for (Iterator i = c.iterator();
i.hasNext();)
foriter
main method
main
switch
switch
case
case
try
try
catch
catch
try finally
tryf
finally
finally
You must enable the JDE's Java keyword abbreviation mode
to use the control flow abbreviations. See Java Keyword
Completion for more information.
Left Brace Placement
The JDE's Java control flow templates support two options
for opening brace placement: placement on the first line of
the template (Kerningham & Ritchie Style, the default)
and placement on a separate line. Type M-x
customize-variable jde-gen-k&r to specify
the style you prefer.
Customizing the Control Flow Templates
You can customize the templates to suit any indentation
style. To customize the templates, select
Project
Options
Autocode
from the JDE menu.
Adding Your Own Control Flow Templates
Use the jde-gen-define-abbrev-template
function to define your own control flow abbreviation in
your .emacs file. For example, the
following code defines an abbreviation for an else clause.
(jde-gen-define-abbrev-template "melse" '('> "else {" '> 'n
'> 'r 'n "}"))
The jde-gen-define-abbrev-template
function takes two arguments. The first argument is a string
that specifies the abbreviation. The section argument is a
list defining the text that replaces the abbreviation. The
list can contain any of the following elements.
Template Elements
Element
Usage
A string.
The string is inserted into the buffer at
point.
The symbol 'p.
This position is saved in
tempo-marks.
The symbol 'r.
If tempo-insert is called
with ON-REGION non-nil the
current region is placed here. Otherwise it works
like 'p.
(p PROMPT <NAME>
<NOINSERT>)
If tempo-interactive is
non-nil, the user is prompted in the minbuffer with
PROMPT for a string to be
inserted. If the optional parameter
NAME is non-nil, the text is
saved for later insertion with the
s tag. If there already is
something saved under NAME that
value is used instead and no prompting is made. If
NOINSERT is provided and non-nil,
nothing is inserted, but text is still saved when a
NAME is provided. For clarity,
the symbol 'noinsert should be
used as argument.
(P PROMPT <NAME>
<NOINSERT>)
Works just like the previous element, but
forces tempo-interactive to be
true.
(r PROMPT <NAME>
<NOINSERT>)
Like the previous, but if
tempo-interactive is
nil and
tempo-insert is called with
ON-REGION non-nil, the current
region is placed here. This usually happens when you
call the template function with a prefix
argument.
(s NAME)
Inserts text previously read with the
(p ..) construct. Finds the
insertion saved under NAME and
inserts it. Acts like 'p if
tempo-interactive is
nil.
'&
If there is only whitespace between the line
start and point, nothing happens. Otherwise a
newline is inserted.
'%
If there is only whitespace between point and
end-of-line nothing happens. Otherwise a newline is
inserted.
'n
Inserts a newline.
'>
The line is indented using
indent-according-to-mode. Note
that you often should place this item after the text
you want on the line.
'n>
Inserts a newline and indents line.
'r>
Like r, but it also indents
the region.
'o
Like '% but leaves the point
before the new line.
Anything else.
It is evaluated and the result is treated as an
element to be inserted. One additional tag is useful
for these cases. If an expression returns a list
'(l foo bar), the elements after
'l will be inserted according to
the usual rules. This makes it possible to return
several elements from one expression.
Enabling Variable Content
Some templates optionally prompt you for items to insert
into the template. To enable prompting, set the variable
tempo-interactive to a
non-nil value in your
.emacs file.
Disabling the Control Flow Abbreviations
To disable the control flow abbreviations, set the
variable jde-gen-cflow-enable off.
Thanks to...
Thanks to Eric D. Friedman >friedman@lmi.net<
for contributing the control flow templates.
Completing Expressions
Both Emacs and the JDEE provide commands for completing incomplete
expressions. Emacs provides commands that work for any expression
but only if the completions exist in an open buffer. The JDEE
provides completion commands that work for any Java method or field
name that exists on jde-global-classpath.
The following sections explain how to use completion facilities
supplied by the JDEE and by Emacs itself.
Completing Method
and Field Names
The JDEE provides comamnds that can complete an incomplete
field or method name. All the methods determine the set of
possible completions for an incomplete field or method name at
point. They differ in how they present the completions to you
for selection. The commands include:
jde-complete-in-line
This command uses the first completion that it finds
to complete the method or field name at point. If multiple
completions exist, it allows you to cycle through the
completions, each completion replacing the previous in the
source buffer. See Using
In-Line Completion for more information.
jde-complete-menu
This command displays a menu of possible completions for
the incomplete method or field name at point. It enters
the completion that you select in the source buffer. See
Using Menu-Based
Completion for more information.
jde-complete-minibuf
This command uses the minibuffer to display possible
completions for the incomplete method or field name at
point. The comamnd enters the completion that you select
in the source buffer. See Using Minibuffer-Based
Completion for more information.
jde-complete
This is the JDEE's user-definable "standard"
completion command. It delegates completion to one of the
JDEE's other completion commands
(jde-complete-menu by default) or to a
custom completion function that you specify (see Selecting a Completion
Method for more information.) The
jde-complete command is bound by
default to the key combination C-c C-v
C-.. If you prefer another binding, use the
customization variable jde-key-bindings
to change the binding.
The JDEE's field and method completion commands use the
Beanshell to run Java code that in turn uses Java's reflection
(class introspection) capability to determine the fields and
methods defined for the class of object at point. The commands
start the Beanshell if it is not running. This can cause a
noticeable delay in completion the first time it is used in a
session. The response can also be slow for classes containing
many methods and fields.
See Speeding Up Completion
for some tips on how you can dramatically speed up field and
method completion.
Completion works only for compiled classes that reside in the
classpath defined by jde-global-classpath,
if set, otherwise by the CLASSPATH
environment variable when the Beanshell starts. Thus, if the
JDEE is unable to complete a method or field, make sure that
the class that defines the field or method is compiled and
exists on the classpath defined by
jde-global-classpath, if set, otherwise by
the CLASSPATH environment variable.
The JDEE completion commands work for all of the following
cases.
objects referenced by variables declared in the
current buffer
static fields and methods
fields and methods of objects defined by the current class
and its parent
Names of fields and methods of the current class must
start with this or .
(period). Names of fields and methods declared by the
parent of the current class must start with
super.
For example, this command completes
. ^ this. ^ super. ^
objects referenced by the fields of objects referenced by
variables declared in the current class or its parent or
by static fields
For example, this command completes
System.out.prin ^
objects returned by methods of objects referenced by
variables defined in the current
For example, this command completes
Toolkit.getDefaultToolkit().get ^
objects referenced by method parameters
For example, this command completes
void setColor(String color) { color.get ^ }
Selecting a
Completion Method
The JDEE's generic completion command,
jde-complete delegates completion to one
of several specific completion commands supplied by the JDEE
or to a custom completion method that you supply. This
allows you to customize jde-complete to
use the completion method that you prefer.
To specify your preferred completion method:
Open a customization buffer for
jde-complete-function.
Select the completion command that implements the
completion method you prefer.
If you selected Custom as your
preferred completion function, enter the name of the
custom completion function in the adjacent edit field,
replacing the existing contents
(ignore by default.).
Save your selection in your
.emacs or project file.
Using Menu-Based
Completion
The jde-complete-menu displays a
popup menu of completions for the method or field name at
point. Selecting a completion from the menu causes the
command to use it to complete the method or field at point.
This section assumes that you have selected
jde-complete-menu as your standard
completion command.
To select completions from a menu:
Position point immediately following the partially
complete field or method name.
Type the C-c C-v C-. key combination.
A menu of completions pops up.
Select the desired completion from the menu.
The JDEE inserts the completion at point in the
buffer.
Using In-Line
Completion
The jde-complete-in-line command allows
you to select completions at the point of insertion in the
source buffer. The command finds all the fields and methods
that complete the name at point. It then inserts the first
potential completion in the buffer at point. Repeatedly
executing the command causes the JDEE to cycle through the
other potential completions. If the completion is a method
name, the command completes the method name and displays the
method signature in the minibuffer.
The jde-complete-in-line command is bound
to C-c C-v .. You can use this
combination to invoke the command or C-c C-v
C-., if you have selected this command as your
preferred completion method. The following examples use the
C-c C-v . combination.
Completing a String Method Name
Typing
C-cC-v.
String s; s.get ^
completes the method name at point as follows
String s; s.getClass( ^
and displays
java.lang.Class getClass()
in the minibuffer. Repeatedly typing
C-cC-v.
cycles through all the other get methods for the Java
String class.
Speeding Up Completion
Here are two ways you can significantly speed up field
and method completion:
Byte-compile the eieio and JDEE packages.
The beanshell package, the Emacs interface to the
BeanShell, is based on the eieio object-oriented Lisp
package for Emacs. Completion uses the BeanShell heavily
to determine the class of the field or method at point.
Thus compiling eieio and beanshell.el improves
completion's performance, dramatically in my tests.
Import by class, not by package, in your Java files.
Every package import, e.g.,
java.util.*, requires invoking the
BeanShell to determine the fully qualified name of the
class at point (see
jde-parse-get-qualified-name).
A Beanshell invocation is by far the most time-consuming
operation required for completion. Thus eliminating the
use of package-level imports can significantly
speed up completion.
Dynamic Keyword Completion
Emacs provides dynamic completion commands that attempt
to find completions for the word at point in the current
buffer or other buffers.
Using Dynamic Completion
Suppose that the current source buffer contains the class
names Component and
Container. Now suppose you enter
Co somewhere in the buffer and type
M/.
The text Component replaces
Co in the buffer.
Typing
M/
again changes Component to
Container. In this way, you can cycle
through all the possible completions for
Co in the current buffer.
Dynamic Completion Commands
Emacs provides two dynamic completion commands.
The dabbrev-expand command is bound to
the key combination
M/
by default. It searches the current buffer for completions
of the word at point and, if none are found, other buffers
of the same type. For example, if the current buffer is a
Java source buffer, it searches other Java source buffers
for completions if none are found in the active buffer.
The hippie-expand command provides more
extensive search capabilities. See the docstrings for these
functions for more information.
Generating Code
The JDE provides the following code generation capabilities.
Code wizards
Code templates
Code Wizards
The JDE provides a set of procedural code generators called
code wizards. They include:
Code Wizards
Wizard
Generates...
Import
Wizard
An import statement for the class at point.
Method
Override Wizard
A method that overrides a method inherited by
the class containing point.
Interface
Wizard
Implementation of an interface in the class
containing point.
Delegate
Wizard
Methods that delegate tasks to a specified
class.
Abstract Class
Wizard
Implementations of the abstract methods
inherited by the class containing point.
Get/Set
Wizard
Get and set methods for the private fields of
the class containing point.
Some of the wizards use the BeanShell to run Java code. A
wizard starts the Beanshell interpreter if it is not already
running. Thus, you may experience a slight delay when
invoking a wizard for the first time in a session.
Import Wizard
The import wizard generates an import statement for the
class name at point if an import statement does not already
exist for that class. The wizard generates the import
statement at the head of the source buffer.
To import the class at point, select
JDE
WizardsImport
Class from the Emacs menubar
or type
C-cC-vC-z.
The import wizard searches the current
classpath for classes that match the class name at point,
which may be unqualified. If the import wizard finds more
than one class of the same unqualified name on the current
classpath, it prompts you to select one of the classes to
import.
The classpath that the import wizard searches for import
candidates is the classpath specified by
jde-global-classpath when the BeanShell
was last started.
The customization variable
jde-wiz-import-excluded-packages allows
you to specify a list of packages to exclude from
consideration for import into the current source file. If
the import wizard finds any classes on the classpath that
belong to the list of prohibited packages, it removes them
from the list of classes considered for import.
Thanks to ...
Len
Trigg for contributing the initial
implementation of the import wizard.
Method Override
Wizard
The method override wizard generates a skeleton method that
overrides a similarly named method defined by a superclass.
To override a method of a superclass:
Position the Emacs point at the location in the buffer
where you want the generated method to appear.
The point must be within the class that is overriding
the method.
Screen capture showing point inside a
class.
Select
WizardsOverride
Method
from the
JDE
menu or enter
Mx
jde-wiz-overrided-method.
Screen shot showing
Wizards
menu.
The JDE prompts you to enter the name of the method to
be overridden in the minibuffer.
Screen shot showing prompt for
method name.
The name must be the name of a method defined by an
ancestor of the class in which the Emacs point is
located. The compiled class of the ancestor must be on
the classpath specified by
jde-global-classpath.
Enter the name of the method to be overridden.
If the ancestors of the class in which you are
overriding the method define more than one method of the
same name, the wizard displays a dialog buffer that
lists the methods. For example, Java's awt class
hierarchy defines several variants of the method
repaint. If you specify
repaint as the method to override,
the JDE displays the following dialog buffer:
Screen shot showing dialog
buffer for selecting method.
The dialog buffer lists the signature of each variant of
the method you specified. Next to each signature is a
radio button. The radio button of the currently selected
signature contains an asterisk. To select another
signature, right-click the radio button next to the
variant. To confirm your selection and dismiss the
dialog, right-click the [Ok]
button.
Select the method variant you want to override and click
the [Ok] button.
The wizard inserts a skeleton implementation of
the selected method at the current point in the Java
source buffer.
Screen shot showing the inserted
method.
The wizard also inserts import statements for any
classes referenced by the method that are not already
imported by the containing class either explicitly or
implicitly. The wizard inserts the import statements at
the head of the source buffer after any existing import
statements, or any package statement, or the first blank
line in the buffer.
The method override wizard uses the BeanShell to
create the interface implementation. If the BeanShell
is not currently running, the wizard starts the
BeanShell. Thus, if the BeanShell is not already
running, you may experience a short pause the first
time you override a method.
Interface Wizard
This wizard creates a skeleton implementation of any
interface defined on the classpath specified by
jde-global-classpath.
To create an implementation of an interface:
If the interface is to be implemented by a new class,
create the class in a buffer.
Position the Emacs point at the point in the class where
you want the implementation of the interface's methods
to appear.
Select
JDEWizards
Implement Interface
or enter
Mx
jde-wiz-implement-interface.
The JDE prompts you to enter the name of the interface
to be implemented.
Enter the fully qualified name of the interface, for
example,
java.awt.Event.MouseListener.
The wizard inserts skeleton implementations of the
methods declared by the interface at the current point
in the current buffer. It inserts import statements for
any classes required by the interface at the head of the
current buffer (only if import statements do not already
exist for the required classes). It also updates or
creates an implements clause for the class.
The interface wizard uses the BeanShell to create the
interface implementation. If the BeanShell is not
currently running, it starts the BeanShell. Thus, if the
BeanShell is not already running, you may experience a
short pause the first time you use the wizard.
Thanks to ...
Eric
Friedman for creating the framework for the
interface, method override, and abstract class wizards and
for contributing the initial implementation of the
interface wizard.
Delegate Wizard
This wizard generates methods that delegate calls to a class
in the current buffer to an attribute of the class, i.e., to
an object that is a field of the current class. For example,
if the current buffer contains class
A and A has
an attribute, A.b, that is an instance
of class B, this wizard generates
all the public methods of class B in
A and delegates handling of those
methods to b.
Thanks to...
Charles Hart
for contributing this wizard.
Get/Set Wizard
This wizard generates get and set methods for the private
fields of the class at point, but only if the fields do not
already have get or set methods. To generate the methods,
move point to the point in the class where you want the get
and set methods to appear. Then select
JDECode
Generation
Wizards
Generate Get/Set Methods...
or enter
Mx
jde-wiz-get-set-methods
Thanks to...
Javier
Lopez and Sandip
Chitale for contributing this wizard.
Code Templates
Buffer Templates
These commands create buffers containing a skeleton Java class.
Each command prompts you to enter the path to a new Java source
file. They then create a buffer for the new file and insert a
template for a class of the same name as the newly created file.
In particular, the command
FilesJDE NewClass creates a buffer containing a generic Java public class.
FilesJDE NewConsole creates a buffer containing the main class of a
Java console application.
FilesJDE NewOther prompts you to create any of the above buffers or a
custom (user-defined) buffer.
You can create an empty Java class buffer by selecting
FilesOpen
(Cx f) and
entering the path for a new file whose root name is the same as
the class you want to create and whose extension is .java.
Specifying Boilerplate Text
You can specify boilerplate text (for example, a copyright
notice) to be inserted at the head of class source files
created by the JDE. The JDE provides two ways to specify
the boilerplate text. The simplest way is to enter the
lines of boilerplate text as the value of the
customization variable
jde-gen-buffer-boilerplate. Another way
to specify the text is to set the value of the
customization variable
jde-gen-boilerplate-functionto a
function that generates the boilerplate text. (The default
value of this variable is
jde-gen-create-buffer-boilerplate,
which returns the value of the boilerplate variable,
jde-gen-buffer-boilerplate). The
functional approach allows you to generate boilerplate
text dynamically by evaluating the appropriate Lisp code.
By saving the values of boilerplate variables in project
files, you can specify different boilerplate text for each
project.
Customization Variables
The following JDE customization variables control creation of
autocoded Java source buffers:
Variable
Group
Usage
jde-gen-class-buffer-template
Autocode
Template for a generic public class buffer.
jde-gen-console-buffer-template
Autocode
Template for a console application buffer.
jde-gen-jfc-app-buffer-template
Autocode
Template for a JFC (Swing) application.
jde-gen-junit-test-class-buffer-template
Autocode
Template for a JUnit test case class. This template requires
the JUnit test framework.
jde-gen-buffer-templates
Autocode
Specifies templates available to create
Java buffers.
jde-gen-buffer-boilerplate
Autocode
Specifies lines of text to be inserted
at the head of class files.
jde-gen-boilerplate-function
Autocode
Specifies a function that returns a string
of boilerplate text. The default value is
jde-gen-create-buffer-boilerplate, which returns
the value of jde-gen-buffer-boilerplate.
See Customizing
Templates for information on how to customize
the class creation templates.
Point Templates
The following commands insert templates at the current
point in the buffer:
JDEGenerate
Get/Set Pair
generates an instance variable and a get and set method .
for that variable
JDEGenerate
Println
generates a
System.out.println(...);
statement.
JDEGenerate
Action
generates and registers an action listener for a
specified component.
JDEGenerate
ListenerWindow
generates and registers a window listener for a specified
window.
JDEGenerate
ListenerMouse
generates and registers a mouse listener for a specified
component.
JDEGenerate
Other
allows you to select any of the above templates or a
custom (user-defined) template.
The following variables control generation of code at
point:
Variable
Group
Usage
jde-gen-get-set-var-template
Autocode
Defines a get/set method pair template.
jde-gen-listener-action-template
Autocode
Defines an action listener template.
jde-gen-listener-window-template
Autocode
Defines a window listener template.
jde-gen-listener-mouse-template
Autocode
Defines a mouse listener template.
jde-gen-inner-class-template
Autocode
Defines a template for creating a class inside
another class or inside an existing source
buffer.
jde-gen-code-templates
Autocode
Specifies available code templates.
See
Customizing
Templates for information on how to customize
templates provided by the JDE.
Creating
Templates for information on how to create
templates from scratch.
Customizing
Templates
You can customize the JDE's standard code templates,
using the Emacs customization feature.
To customize an autocode template:
Select
JDE
Options
Autocode
The JDE displays a customization buffer containing
the autocode templates.
Edit the template to suit your needs.
The JDE uses the template format defined by
tempo.el to represent class
templates. Each template consists of a list of strings,
symbols, and functions, each of which represents content
to be inserted successively into the buffer at the
current point. The strings represent fixed content. The
symbols and functions represent variable content. See
the docstring for the function
tempo-define-template for more
information, including the meaning of special symbols
such as 'n.
Select the state button associated with the
template.
A menu pops up with a list of options for saving
your changes.
Save your changes.
Select
Save for Future
Sessions if you want
your changes to apply to all projects. If you want your changes to apply
only to the current projects, select
Set for Current
Session. Then select
JDE
Options
Save Project
to save your changes in the current project's project
file.
Creating Templates
The JDE considers any command (interactive function) that
inserts code into a buffer at point to be a template. The JDE
uses the Emacs tempo library to create built-in templates.
You can use tempo to create your own, add-on templates (see below
and the doc for the tempo-define-template for
more information) or create templates from scratch.
In either case, once you have created a template, you can add it
to the JDE's lists of available code and/or buffer templates,
using the JDE's jde-gen-code-templates and/or
jde-gen-buffer-templates
variables, respectively. Adding a template to these lists enables
you to invoke the templates from the JDE menus. When adding a
template, you need to specify a unique title for the template.
These titles enable you to specify the templates when invoking
them, using the JDE's custom code template commands
(Files
JDE New
Custom and
JDE
Generate
Custom). You can use
auto completion to enter a template title when invoking a custom
code generation command. Note that you can specify different sets
of templates for different projects, by setting and saving the
template list variables in project files. See the following
sections for more information:
Defining a Template and
Template Insertion Function
Registering Custom
Templates
Assigning Keys To
emplates
Defining a Template
and Template Insertion Function
The tempo-define-template macro
enables you to define a template and a function that
inserts that template at the current point in the current
buffer. You specify the template as a list oftemplate
elements where each element is text, a special symbol, or
a Lisp expression. The function inserts each text element
exactly as specified in the buffer; it replaces special
symbols with some text (e.g., user input), and it replaces
Lisp expressions with the text that results from
evaluating them.
For example, the following Lisp code
(tempo-define-template "foo"
;; template name
'("System.out.println(\"foo\");")
;;template definition "f"
;; abbreviation "Inserts a print foo message")
;; template documentation
defines a template for Java code that always prints
"foo" to standard out:
System.out.println("foo");
Notice that the template definition uses the Lisp
string escape character to specify the string
"foo". This is necessary when you want to
include quoted strings in a template definition.)
The sample Lisp form also defines an interactive
template function tempo-template-foo.
Now suppose you insert the sample code in your
.emacs file. After Emacs starts up,
whenever you enter the command
Mx
tempo-template-foo, Emacs inserts
System.out.println("foo");
at the current point in your Java source buffer (or
any buffer, tempo doesn't care).
The preceding example is admittedly not vary useful
because it always prints the same text. You can create
more useful templates, using special tempo template
symbols and lisp forms. This approach, for example, allows
you to create a template that can print any user-defined
text to standard out:
(tempo-define-template "debug"
;; template name '("if (debug)" n>
;; insert new line plus indent
"System.out.println(" (p "Enter debug
message:") ;; Prompts for debug message
");") "d"
;; abbreviation "Inserts a print debug message")
;; template documentation
The template function produced by this example prompts
you to enter the text to be printed when inserting the
function into a buffer. In particular, it inserts
if (debug) System.out.println(DEBUG-MESSAGE);
where DEBUG-MESSAGE is any text
that you enter. For example, suppose you enter
"Selected color = " + color
at the prompt. The template function inserts
if (debug) System.out.println("Selected color =
" + color);
at the current point in the buffer.
See the documentation for
tempo-define-template (type
ch f
tempo-define-template) for more
information on creating templates.
Registering Custom
Templates
You can register templates that you create with the
JDE. When you register a template with the JDE, it appears
among the list of templates that you can select when you
select
JDEGenerate
Other..... You
register a template by customizing the JDE variable
jde-gen-code-templates. The value of
this variable is a list of the template functions that the
JDE command
JDEGenerate
Other.... can
invoke. To register a custom template, add its name to the
list. For example, the following screen shows the
customization buffer for
jde-gen-code-templates after it has
been customized to include the template defined in the
previous example.
Screenshot showing customization buffer for
registering templates.
To insert a template that you have registered
Select
JDEGenerate
Other....
The JDE displays the prompt
Enter template:
in the minibuffer.
Enter the template's name and press
Enter
or,
press the Tab key to display a
list of templates in a completion buffer:
Screenshot showing template completion
buffer.
Select the template you want by double-clicking
its name.
Assigning Keys to
Templates
You can assign templates to keyboard keys to speed use
of frequently used templates. For example, insert this
form
(global-set-key [f9] 'jde-gen-to-string-method)
in your .emacs file to assign the
F9 function key to the JDE template that
generates a skeleton toString method.
Checking Coding Style
The
JDE
Check Style
command (
M
x
jde-checkstyle) command checks
the current buffer for conformity to a Java coding standard. The
default standard is that specified by Sun Microsystems. Execute
jde-checkstyle-customize to customize the
command to support your own coding standard.
The command displays a list of stylistic faults in a popup
buffer. Click the error message to display the line that violates
the standard.
Compiling Java Programs
To compile the source file in the current buffer, select
JDE
Compile, type
C
c
Cv
Cc,
or execute M-x jde-compile. The compiler uses
the version of javac included in the
currently selected JDK or on your system command path by
default. However, you can configure the JDEE to use another
compiler for the current project or all projects (see Specifying a Compiler). The
JDEE also allows you to configure the JDEE to invoke the
compiler with various compilation options.
Compilation Buffer
The compile command displays the output of the compiler in a
separate compilation buffer.
Image showing compilation buffer with
errors.
If a compilation buffer does not exist, the compile command
creates the buffer; otherwise, it reuses the existing compile
output buffer. The compilation buffer operates in
compilation-mode, a standard Emacs buffer
mode. This mode greatly simplify locating compilation errors
in the Java source code. For example, to find the line that
cause a compilation error, simply click the error message in
the compilation buffer.
Specifying a Compiler
The JDEE supports the following Java compilers.
javac
This is the compiler that comes with Sun's JDK and the
JDK's clones. Note that javac
compiler is itself implemented in Java. The
javac executable that comes with the
JDK simply starts a vm to run javac.
The executable passes its command-line arguments to
javac's main method.
javac compile server
This is a JDEE feature that uses the BeanShell to
invoke the javac compiler on a source file, thus avoiding
the need to start a vm everytime you want to compile
a file. This option greatly reduces the time required
to compile individual files by eliminating the vm startup
time, which is usually much longer than the time required
to compile a file.
jikes
Developed by IBM, this compiler is implemented in
C++ and hence avoids the vm startup time that slows
down javac.
To specify one of these compilers for the current project or
all projects:
Type M-x customize-variable and
press Enter
Emacs prompts you to enter the name of a variable
to customize.
Enter jde-compiler and
press Enter.
The jde-compiler customization
buffer appears.
Select the compiler that you want to use for the
current project or all projects.
You can skip the next step if you selected the compile server
or if you selected javac and you want to use the version of
javac that comes with the currently selected JDK, or you have
selected the javac executable or jikes and the executable for
the selected compiler is in your system's command path.
Enter the path to the executable for the selected
compiler.
If you want your selection to apply only to the current
project, select Save for Current Session
from the State menu. Otherwise select
Save for Future Sessions.
Select Finish to dismiss the
customization buffer.
If you want the selection to apply to the current
project, select Project->Project
File->Save from the JDE
menu.
Compilation Options
The JDEE allows you to specify compilation options by
setting compilation variables. You must use the Emacs
customization feature. To use the customization feature,
select
JDE
Options
Compile. (See
Configuring the JDEE for
more information on using the customization feature). To save
the compilation settings in the project file
(see Using Project Files)
for the current source buffer, select
JDE
Options
Update Project.
Setting
Compile Options Interactively
If you set the customization variable
jde-read-compile-args to a
non-nil value, the JDEE compile command
prompts you to enter compilation options in the minibuffer.
It appends the options that you enter to the options
specified via customization variables. The JDEE saves the
arguments that you enter in a minibuffer history list. You
can recall previously entered options by pressing the up or
down arrows on your keyboard.
The JDEE uses the values of the JDEE customization
variables to set the compiler's command-line option
switches. The JDEE assumes that the compiler you are using
(specified by the customization variable
jde-compiler) has the same set of
command-line switches as the version of
javac or jikes that you have selected.
If the command-line switch for a particular option
supported by the compiler your are using is not the same
as that specified by javac or jikes,
you must use the variable
jde-compile-option-command-line-args to
select the option.
Compiler Customization Variables
The following table lists the JDEE compilation variables and
the functions used to set them.
Name
Group
Usage
jde-compiler
Project
Specifies the compiler (javac server, by default)
to use to compile the code in the current source buffer.
jde-compile-option-command-line-args
Compile
Specifies a string of
command-line arguments to be passed to the compiler.
jde-global-classpath
Project
Specify class paths
for compile, run, and debug commands.
jde-read-compile-args
Project
Specify whether to read compile
options from the minibuffer.
jde-compile-option-classpath
Compile
Specifies the
classpath for compile command. If set, this variable
overrides jde-global-classpath.
jde-compile-option-sourcepath
Compile
Specifies the path of source files
for classes required to compile the current class.
jde-quote-classpath
Project
Quote the classpath
argument.
jde-compile-option-directory
Compile
Specifies the
directory into which to place the compiled class.
jde-compile-option-deprecation
Compile
Warn of use or
override of a deprecated member or class
jde-compile-option-debug
Compile
Generate information
about local variables for debug tools.
jde-compile-option-optimize
Compile
Directs the compiler
to try to generate faster varname.
jde-compile-option-depend
Compile
Analyze dependencies.
jde-compile-option-depend-switch
Compile
Command line switch that causes the
compiler to analyze dependencies.
jde-compile-option-vm-args
Compile
Specify command-line
arguments for Java interpreter used to run the compiler.
jde-compile-option-verbose-path
Compile
Print verbose messages.
jde-compile-option-verbose
Compile
List directories searched to
compile current class.
jde-compile-option-nowarn
Compile
Turn off warnings.
jde-compile-option-encoding
Compile
Specify the source
file encoding name, such as EUCJIS\SJIS.
jde-compile-option-target
Compile
Generate code compatible with a
specified vm version.
jde-compile-option-bootclasspath
Compile
Specify classpath of standard
libraries for target vm.
jde-compile-option-bootclasspath
Compile
Specify path of directories
containing extensions for target vm.
Building Java Applications
The
JDEBuild
command builds an application. By default this command invokes the
Unix-style make utility to build the application. You can configure
the build command to invoke the Ant build system or a custom build
function.
Selecting a Build Method
To select a build method:
Type M-x customize-variable and
press Enter
Emacs prompts you to enter the name of a variable
to customize.
Enter jde-build-function and
press Enter.
The jde-build-function customization
buffer appears.
Select the build function that you want to use.
If you want your selection to apply only to the current
project, select Save for Current Session
from the State menu. Otherwise select
Save for Future Sessions.
Select Finish to dismiss the
customization buffer.
If you want the selection to apply to the current
project, select Project->Project
File->Save from the JDE
menu.
Building with Make
The jde-make command uses a make utility,
such as GNU make, to rebuild a project. You must supply the
makefiles used to build your projects. See Sample Makefile for an example
of a makefile for building a Java project. David Ponce's
JMaker
package generates makefiles automatically for JDEE projects.
It uses JDEE variables to determine classpaths, compiler
options, and other information needed to create projects.
JMaker recursively creates makefiles for all the Java packages
in a project plus a toplevel makefile that invokes the other
makefiles to build the entire project.
Make Options
The following customization variables allow you to specify
various jde-make options:
Name
Group
Default
Usage
jde-make-program
Project
make
Specifies the pathname on your system of the
make utility that the jde-make
uses to build your project.
jde-make-args
Project
Specifies a string of command-line arguments
(for example, "-f mymakefile
all") to be passed to the make
utility.
jde-read-make-args
Project
nil
If nonnil, this variable causes the
jde-make command to prompt you
to enter command-line arguments in the minibuffer.
jde-make passes these arguments
along with the arguments specified by
jde-make-args to the make
utility.
jde-make-working-directory
Project
Specifies the directory from which
jde-make runs the make utility.
Sample Makefile
The following is a sample makefile that you can use as a
model for creating makefiles to build Java projects.
JDK = d:/jdk1.2/lib/classes.zip
JMATH = d:/jmath/src
CLASSPATH = $(JMATH);$(JDK)
COMPILER = javac VM = java
COPTIONS = -g -deprecation
ROPTIONS =
CLASSES = Test.class \
JMathError.class \
JMathException.class \
LinearSystem.class
.SUFFIXES: .java .class
all : $(CLASSES)
# Rebuild (if necessary) and run the JMath test suite. run: $(CLASSES)
$(VM) -classpath "$(CLASSPATH)" jmath.Test
# Remove all class files from the project directory.
clean: rm *.class
# Implicit rule for making Java class files from Java
# source files.
.java.class: $(COMPILER) $(COPTIONS) -classpath "$(CLASSPATH)" $?
Building with Ant
The jde-ant-build command uses the Apache Ant
build tool to build a Java project.
The following variables allow you to control the build
process.
Ant Options
Name
Group
Default
Usage
jde-ant-invocation-method
Ant
script
Specifies how to invoke ant. Ant can be invoked
in one of three ways. The first is via the ant
script/program that comes with ant. The second is
via java and the third is via the Ant Server.
jde-ant-home
Ant
Directory where ant is installed.
jde-ant-user-jar-files
Ant
nil
Specifies jar files that hold user-defined
tasks.
jde-ant-program
Ant
ant
Specifies name of ant program/script.
jde-ant-args
Ant
-emacs
Specifies arguments to be passed to the Ant
program.
jde-ant-buildfile
Ant
build.xml
Specifies the default buildfile to use.
jde-ant-read-buildfile
Ant
off
Specify whether to prompt for a buildfile. If
non-nil, the jde-ant-build command prompts you for
an ant buildfile. Note that
jde-ant-read-buildfile and
jde-ant-enable-find are
incompatible and that
jde-ant-read-buildfile will
override the former.
jde-ant-read-target
Ant
off
Specify whether to prompt for a build target.
If non-nil, the jde-ant-build command prompts you
for an ant target.
jde-ant-interactive-buildfile
Ant
off
Default buildfile to use when prompting
interactively.
jde-ant-read-args
Ant
off
Specify whether to prompt for additional
arguments to pass to Ant. If non-nil, the
jde-ant-build command prompts you
for the additional arguments.
jde-ant-enable-find
Ant
off
Specify whether jde-ant find the
build.xml file based on your
current directory. If non-nil, we will search up the
directory hierarchy from the current directory for
the build definition file. Also note that, if
non-nil, this will relax the requirement for an
explicit jde project file. In order for this to
work jde-ant-read-buildfile must
be nil.
jde-ant-complete-target
Ant
off
Specify whether to enable completion of build
target names in the minibuffer. If non-nil, the
jde-ant-build command allows you
to use tab completion in the minibuffer to specify
the build target name. This list of valid build
targets is determined by parsing the Ant build file.
This option has no effect if
jde-ant-read-target is
nil.
jde-ant-use-global-classpath
Ant
off
Specify whether to enable use of
jde-global-classpath when running
jde-ant.
jde-ant-target-regexp
Ant
<\s-*target\s-[^...]*?name\s-*=\s-*\"\s-*\([^\"]+\)
Regular expression used to match target names in
Ant build files.
jde-ant-build-hook
Ant
nil
List of hook functions run by
jde-ant-build (see
run-hooks in the Emacs
documentation for more information).
Running Java
Applications
The JDE allows you to run a Java application as an Emacs
subprocess. You can run multiple applications concurrently, but
only one instance of each application at a time. The JDE
displays each application's standard and error output in an
Emacs command interface (comint) buffer. You
can interact with applications that accept command line input
via the comint buffer. When interacting with
an application, you can use any of
comint-mode's extensive set of command-line
history commands to speed interaction. To run an application,
enter
M-x jde-run
or select Java
Run App from the Emacs
menubar or type
Cc
Cv
Cr.
Specifying the
Application's Main Class
The term main class refers to the
class that contains the application's main method. The JDE's
Run App command assumes by default that the class in the
current buffer is the application's main class. This can be
inconvenient if you have an application that has multiple
classes. You may want to be able to run the application from
any buffer containing one of the application's classes. To do
this, set the variable
jde-run-application-class to the
fully qualified name of the application's
main class.
You can temporarily override the setting of
jde-run-application-class by typing
C-u - before executing the jde-run command, for example, by
typing C-u - C-c C-r. This causes the JDE to
prompt you to enter the fully qualified
name of the application's main class (as well
application arguments if any).
Specifying a
Startup Directory
The JDE can start an application from any directory that
you specify. By default, the JDE starts an application from
the default directory of the current source buffer. The
default directory of the current source buffer is the
directory containing the source file displayed in the buffer.
You can specify another directory as the startup directory by
setting the JDE customization variable
jde-run-working-directory.
To set this variable,
Display its customization panel.
You can do this by typing
Mx customize-variable jde-run-working-directory
or selecting JDE
OptionsProject
to display the project customization panel
and searching this panel for
jde-run-working-directory.
Screenshow showing customization buffer for
jde-run-working-directory.
Enter the working directory in the variable's edit
field.
Save the new setting.
To save the edited bindings, right click the
[State] button and choose
Set for current
session if you want the
settings to apply only to the current project or
Save for future
sessions if you want the
settings to apply to all projects. In either case, you
should save the new settings in you project file if your
project has a project file. To save the new settings in
your project file, switch to a source buffer and choose
JDE
OptionsSave
Project.
Setting VM Command-Line
Arguments
If you set the customization variable
jde-run-read-vm-args to a
non-nil value, the JDE compile command
prompts you to enter virtual machine options in the
minibuffer. It appends the options that you enter to the
options specified via customization variables. The JDE saves
the arguments that you enter in a minibuffer history list.
You can recall previously entered options by pressing the up
or down arrows on your keyboard.
Setting Command-Line
Application Arguments
Specifying a prefix argument before the
jde-run, e.g., C-u C-c C-v
C-r causes the command to prompt you to enter
arguments to be passed to the application's main
method. The command appends the options that you enter to the
arguments specified via the customization variable
jde-run-option-application-args. The JDE
saves the arguments that you enter in a minibuffer history
list. You can recall previously entered options by pressing
the up or down arrows on your keyboard.
If you set the customization variable
jde-run-read-app-args to a
non-nil value, the JDE run command
prompts you to enter command-line application arguments
by default, i.e., you do not have to specify a prefix
argument each time you execute the command.
Navigating
Exception Traces
If an exception occurs while your program is running, the
Java vm outputs an exception trace. This trace appears in the
run buffer for the application.
Screenshot showing an exception trace in the
JDE's run buffer.
To view the source line corresponding to a point in the
exception stack trace, right-click the corresponding stack trace
line in the run buffer. You can move up and down the stack trace
by typing the key combinations C-c C-v C-[ or
C-c C-v C-].
Run Customization Variables
The JDE allows you to specify run-time options by setting
run variables.You can use the Emacs customization feature to
set run-time variables interactively. To use the customization
feature, select
JDEProjectOptionsRun.
(See Configuring the JDE
for more information on using the customization feature). To
save the compilation settings in the project file (see Using Project Files) for
the current source buffer, select
JDE
ProjectProject
FileSave
Project.
The following table lists the JDE run variables and the
functions used to set them.
Variable
Group
Usage
jde-run-mode-hook
Project
List of hook functions run by
jde-run-mode
jde-run-working-directory
Project
Startup directory for running or debugging Java
applications.
jde-run-application-class
Project
Name of the Java class to run. The
command jde-run-set-app sets the
buffer-local value of this variable.
jde-run-java-vm
Project
Specify Java interpreter for
non-Windows platforms. The command
jde-run-set-vm sets the
buffer-local value of this variable.
jde-run-java-vm-w
Project
Specify Java interpreter for Windows
platforms. The command
jde-run-set-vm-w sets the
buffer-local value of this variable.
jde-global-classpath
Project
Specify class paths for compile,
run, and debug commands. The command
jde-set-global-classpath sets the
buffer-local value of this variable.
jde-run-classic-mode-vm
Project
Specifies that the JDE should run the JDK's
classic version of the Java virtual machine (as
opposed to the HotSpot version). This option applies
only to versions of the JDK that include both a
classic and a HotSpot vm.
jde-run-read-vm-args
Project
Specifies whether to read vm arguments from
the minibuffer.
jde-run-option-classpath
Run
Specifies the classpath for
the Java interpreter. This option overrides the
jde-global-classpath option.
jde-run-option-verbose
Run
Print messages about the running
process.
jde-run-option-properties
Run
Specify property values.
jde-run-option-heap-size
Run
Specify the initial and maximum size
of the interpreter heap.
jde-run-option-stack-size
Run
Specify size of the C and Java
stacks.
jde-run-option-garbage-
collection
Run
Specify garbage collection
options.
jde-run-option-java-profile
Run
Enable Java profiling.
jde-run-option-heap-profile
Run
Output heap profiling data.
jde-run-option-verify
Run
Verify classes.
jde-run-option-vm-args
Run
Specify command-line arguments to be
passed to the Java vm. The command jde-run-set-args
sets the buffer-local value of this
variable.
jde-run-option-application-args
Run
Specify command-line arguments to
pass to the application. The command
jde-run-set-app-args sets the
buffer-local value of this variable.
Working with Applets
The JDE provides specialized commands for running and
debugging applets.
Running Applets
To run an applet:
Open the applet's source file in a buffer.
Choose
JDERun
Applet
.
The JDE searches for an html file in the directory
containing the applet source file and displays the first
file it finds, using your system's default browser. If
the JDE cannot find an html page in the applet's source
file directory, it signals an error by default.
The JDE
Run Applet command
assumes by default that the directory containing the applet's
source also contains an html page for testing that applet. If
this is not true in your case, you have two options. You can
either specify the path of the applet file via the JDE
customization variable jde-run-applet-doc
or you can use the jde-run-applet command
to run your applet. If the
jde-run-applet-doc variable is not a null
string, JDE
Run Applet displays
the
document that the variable specifies instead of searching the source
file directory for a document to display. The
jde-run-applet command prompts you to enter in the
minibuffer the path of an html file to display. If you enter nothing,
the command defaults to the behavior of JDE
Run Applet.
The run commands chooses the viewer as follows. If
jde-run-applet-viewer is a null string (the
default) or browse-url, the JDE uses browse-url to launch the
applet doc in your system's default browser. Otherwise, the
menu command uses comint to launch the viewer (e.g.,
appletviewer) specified by
jde-run-applet-viewer.
Debugging Applets
To debug an applet:
Open the applet's source file in a buffer.
Choose JDE
Debug
Applet.
The JDE searches for an html file in the directory
containing the applet source file. If the JDE cannot find
an html page in the applet's source file directory, it
signals an error by default. Otherwise, it runs
appletviewer in debug mode on the first file that it
finds.
The Emacs window splits into two panes.
The top pane shows the applet's source file with the debug
cursor pointing to the first line of the applet's init file.
The bottom pane displays the debugger's command line
interface. You can now set breakpoints, single-step, or
continue running the applet. See Debugging Applications for more
information.
If you want to specify the document to be used to test the
applet, customize the variable jde-run-applet-doc or execute
M-x jde-db-applet. This command prompts you
to enter the test document's name.
Applet Customization
Variables
The JDE allows you to specify run-time options for applets
by setting JDE configuration variables.You must use the Emacs
customization feature to set applet run-time variables . To
use the customization feature, select
JDEOptionsRun.
(See Configuring the JDE
for more information on using the customization feature). In
some cases, the JDE also provides functions for setting the
buffer-local values of the compilation variables. To save the
compilation settings in the project file (see Using Project Files) for
the current source buffer, select
JDEOptionsUpdate
Project.
The following table lists the JDE applet run-time
variables and the functions used to set them.
Variable
Group
Usage
jde-run-applet-viewer
Project
Specify name of viewer to use to
display page containing the applet. The command
jde-run-set-applet-viewer sets the
buffer-local value of this variable.
jde-run-applet-doc
Project
Specify name of document containing
applet to be viewed. The command
jde-run-set-applet-doc sets the
buffer-local value of this variable.
Debugging Applications
The JDE provides two options for debugging Java applications.
An Emacs interface to jdb, the command-line
debugger that comes with the JDK. See Debugging with jdb for more
information.
JDEbug, a Java debugger developed specifically for use with the JDE.
See JDEbug
User's Guide for more information.
JDEbug provides more debugging features but requires a JDK 1.2
or higher vm. You must use jdb to debug applications
running on earlier vms.
Specifying
Classpaths
The JDE provides customization variables that permit you to
specify a classpath for the JDE's compile, run, debug,
Beanshell, and other commands. The following table lists these
variables.
Classpath Variables
Variable
Applies To ...
jde-global-classpath
All JDE commands that use a
classpath.
jde-compile-option-classpath
Compile command
jde-run-option-classpath
Run App command
jde-db-option-classpath
Debug App command
The jde-global-classpath variable is so
named because it specifies a classpath that is used by all JDE
commands unless overridden by a classpath variable specific to a
particular command. For example, the JDE's
Compile command uses
jde-global-classpath unless the value of
jde-compile-option-classpath is set.
Typically you want to use the same classpath to compile, run,
and debug an application. So typically
jde-global-classpath is the only variable you
need to set.
Setting a Classpath
Variable
As with other JDE customization variables, you must use
Emacs' customize-variable
command to set the JDE's classpath variables. You can use
relative paths, cygwin paths, and paths with tilde notation
and environment variables as values of JDE classpath
variables. See Specifying
Paths for more information.
When setting a classpath variable, you must enter each path as
a separate entry in the customization buffer. Do not enter the
paths as semicolon or colon-separated lists of paths. The
following examples show the right and wrong way to specify a
classpath.
Wrong Way to Specify a Classpath
jde-global-classpath: [Hide]
[INS] [DEL] Path: c:/jde-dev/jmath/classes;c:/jde-dev/jmath/src
[INS]
[State]: this option has been set and saved.
Right Way to Specify a Classpath
jde-global-classpath: [Hide]
[INS] [DEL] Path: c:/jde-dev/jmath/classes
[INS] [DEL] Path: c:/jde-dev/jmath/src
[INS]
[State]: this option has been set and saved.
Including Class
Libraries
If you store your class libraries as jar or zip files in
separate directory, you need specify only the path of the
directory in a JDE classpath variable. Whenever the JDE
encounters a library directory in a classpath variable, it
expands the classpath to include all the jar and zip files in
the library directory.
For example, suppose you organize your project directory as
follows:
myproj classes lib
src
where the src directory contains all of
your source files, the lib directory all
of your jar and zip files, and the
classes directory all of the classes
compiled from the src directory. Further,
suppose you store your project file (see Using Project Files) at the
root of your project directory. Then, you can specify
jde-global-classpath simply as follows.
jde-global-classpath:
[Hide] [INS] [DEL] Path: ./classes [INS] [DEL] Path: ./src
[INS] [DEL] Path: ./lib [INS] [State]: this option has been
set and saved.
If you do not want the JDE to expand library directories, set
the variable jde-expand-classpath-p off.
The JDE expands directories whose names match the regular
expressions specified by
jde-lib-directory-names. The default values
of this variable are ^lib and
^jar. So by default, the JDE expands
names that begin with the string lib or
lib, e.g., lib,
libraries, etc. However, you can
customize jde-lib-directory-names to
reflect any library naming scheme you prefer.
Using Project Files
A project file is a Lisp file that the JDE loads and evaluates
whenever you open a Java source file belonging to a specific
project. Project files allow you to save and restore project-specific
JDE configurations. For example, you can use a project file to
set the value of the jde-global-classpath variable to a
project-specific classpath automatically whenever you load a file
belonging to that project.
How the JDE Finds Project Files
To simplify the task of finding project files, the JDE makes
two assumptions. First, it assumes that all Java source files
relating to a particular project live in a single directory tree.
Second, it assumes that all project files have the same file name.
The name assumed by default is prj.el. You can use the JDE
configuration variable jde-project-file-name to specify
another name.
When you open a Java source file, the JDE looks for
project files in the directory tree containing the source file.
If the JDE finds one or more project files, it loads the
project files in the following manner.
The JDE first sets all the JDE variables to their
Emacs startup values (i.e., the default value or the value
saved in your .emacs file). It then loads
all the project files in the directory tree containing the
current source buffer, starting with the topmost file.
What this means is that you can use project files to extend
and/or override the settings in your
.emacs file and in other project files.
For example, your .emacs file can specify
settings that are common to all your projects. You can put
settings common to a group of projects at the top of the
directory tree containing the projects, settings common to
each project at the top of the directory containing each
projects, and so on.
Project File
Contents
A project file can contain any Lisp code that can be
evaluated correctly as the last step in creating a Java source
buffer. For example, a project file can contain code that sets
the value of JDE configuration variables. In general, a
project file can contain any code that could be implemented
as a jde-mode hook function. In fact, you
can think of a project file as a project-specific
jde-mode hook function.
Creating a Project
File
The easiest way to create a project file is to use the
jde-save-project command (
JDE
ProjectProject
FileSave
Project). This command saves
the current values of all customized JDE configuration
variables in the project file for the selected Java buffer.
(To be precise, the command inserts Lisp code in the project
file that restores the current settings of the configuration
variables; if such code already exists in the file, it
replaces it with updated code.) If the project file does not
exist, the command creates the project file. Thus, to create
a project file that sets JDE configuration variables to
project-specific values:
Open any source file belonging to the project.
Set the values of the JDE configuration variables to
the appropriate values for the project to which the source
file belongs.
See Configuring the
JDE for information on how to set the values of
the JDE configuration variables.
Select
JDE
ProjectProject
FileSave
Project.
The JDE prompts you to enter the path to a directory
in which to store the project file.
Enter the directory where you want to store the project
file or press Enter to store the project
file in the current directory.
Once you have created the project file, you can insert
additional configuration code into the file if desired. Note
that the jde-save-project command edits
rather than replaces existing project files. Thus, you can use
the command to update configuration variable settings without
disturbing any other configuration code that you have inserted
manually into the project file.
Creating Portable Projects
You can use relative paths and environment variables to
construct portable project files. For example, suppose your
project directory has the following structure:
myprj
classes
pkg1
pkg2
src
pkg1
pkg2
prj.el
Further suppose that your project uses beans from a
shared library specified by the environment variable
BEANS. With this setup,
you can specify jde-global-classpath as
./src
./classes
$BEANS/lib/dials.jar
and jde-compile-option-directory as
./classes
This causes the JDE to store classes compiled from your src
directory in the classes directory. Note that you have not
used any absolute paths in creating your project file. This
means you can move your project anywhere without having to update
the project file.
Disabling Context Switching
When you select a buffer that belongs to another
project, the JDE loads the project file for that project
and may update the class list for the project. This
causes a slight delay before you can begin using the
new buffer. The delay can be irritating if you need
to switch frequently among open projects, for example,
when copying or diffing code from different projects.
Accordingly, the JDE provides ways for you to disable
context-switching either permanently or temporarily.
To disable context-switching permanently, toggle
the customizat variable
jde-project-context-switching-enabled-p
off. Be sure to use customize to do this and save the
customization in your
.emacs or prj.el
file. Note that you can use the JDE's project file loading
command, JDE->Project->Project File->Load,
to switch contexts manually.
To disable context-switching temporarily during a session,
select
JDE->Project->Auto Switch or enter
M-x jde-toggle-project-context-switching. To reenable
context-switching, execute the same command again.
Project Hook Functions
The variable jde-project-hooks lists
functions that execute after the JDEE loads a project file. By
writing hook functions and adding them to this list, you can
specify actions to be taken every time the JDEE switches from
one project to another.
Displaying Java Documentation
The JDE provides commands for displaying the JDK API documentation
and context-sensitive help for classes.
Browsing JDK
Documentation
The jde-browse-jdk-doc command
(
JDEHelp
JDK,
Cc
Cv
Cn) opens the
JDK documentation in a browser. By default, this command
displays the JDK documentation page at JavaSoft's web site. To
display a different copy, set the variable
jde-jdk-doc-url to the url of the index
page of the copy you want to be displayed.
Context-Sensitive Class
Help
The JDK provides context-sensitive help for Java classes.
To use this facility, you must first customize the variable
jde-help-docsets to specify the location of
class documentation on your system. The JDE class help
facility supports javadoc documentation by default but it
works with other types of documentation as well.
Once you have specified the location of class
documentation on your system, you can get help for the class
at point in the current buffer by selecting
JDEHelpSymbol
at Point .
Browsing Source Code
The JDE provides the following facilities for browsing Java source code:
Classes index menu
Speedbar
Etags
Classes Index Menu
The Classes
index menu appears by default in the Emacs menubar whenever a
Java source buffer is active. The menu consists of a cascading
list of all classes, methods, fields, and imports defined in
the current buffer plus the package to which the current
buffer belongs. Selecting any item scrolls the buffer to the
statement that defines the item.
Screenshot showing Classes menu.
The top-level menu contains an entry for each each class
defined by the active buffer followed by entries for the
imports and package of the current buffer. Selecting the entry
for a class displays a submenu listing the inner classes,
methods, and fields defined by the class. Selecting the entry
for an inner class displays another submenu for that class,
and so on. Selecting the
imports entry on
the top-level menu displays a submenu listing all the classes
and packages imported by the active buffer.
Special Index
Entries
The index menu includes the following special index
entries:
*Rescan*
Selecting this item causes the JDE to rebuild the
index menu. You should rebuild the menu whenever you
edit the buffer.
*class
def*
Selecting this item takes you to the start of the
definition of the class on whose submenu it appears.
Turn the variable
jde-imenu-include-classdef off to
suppress inclusion of these items in the menu.
Alphabetizing the
Classes Menu
By default the
Classes menu
lists methods and fields in the order in which the active
buffer defines them. Use the variable
jde-imenu-sort to customize the menu to
list methods and fields alphabetically in either ascending
or descending order.
Suppressing Method
Signatures and Field Types
By default the
Classes menu
displays the signatures of methods and the types of fields
displayed in the active buffer. The method signatures enable
you to distinguish overloaded method names. The menu can
also display the names of methods and fields without
signatures and types. Use the variable
jde-imenu-include-signature to turn
signature and type display off or on.
Disabling the
Classes Menu
Set the variable jde-imenu-enable off
to disable the
Classes menu.
When disabled, the menu does not appear in the Emacs
menubar.
Using the Keyboard to Navigate the Classes Menu
Execute M-x imenu to use the keyboard
to navigate the Classes menu. Emacs displays the
top-level items on the Classes menu in a buffer and
prompts you to enter the name of an an item in the
minibuffer. Enter the name of the item to select it.
Note that you can use completion to avoid having to
type the whole name. If you select a submenu, Emacs
displays the contents of the submenu and prompts
you to enter a selection in the keyboard. If you
select an index entry, Emacs scrolls the buffer
to the indexed point in the buffer.
Using the Speedbar
To display the speedbar, select
JDE
Speedbar. The
speedbar opens in a separate frame.
Screenshot showing the speedbar.
The speedbar displays a list of the files and
subdirectories in the directory containing the file displayed
in the current buffer. The speedbar highlights the file
displayed in the current buffer.
Click on the expand (+) button in front of any file. The
node for the file expands
Screenshot showing a speedbar entry.
to show up to three entries, depending on the contents of
the source file.
Package
This item expands to show the package to which the file
belongs.
Screenshot showing a speedbar entry.
Clicking on the package scrolls the buffer to the
corresponding package declaration.
Types
This item expands to show the classes in the selected file.
Screenshot showing a speedbar entry.
Each class expands to show the constructors, methods,
fields, and inner classes defined by the class and the
class's parent, if any. Inner classes also expand and their
inner classes, and so on. The constructors and methods
expand to show arguments and argument types and return
types. Fields expand to show their type.
Clicking on any class, inner class, method, constructor, or
field scrolls the buffer to show that item.
Dependencies
This item expands to show the classes and packages imported by the current source file.
Screenshot showing a speedbar entry.
Click on class or package to scroll the buffer to the
corresponding import statement.
Updating the
Speedbar
If you make changes to a source buffer, you must update
the speedbar view to reflect the changes. To update the
speedbar view of a buffer:
Collapse the speedbar view of the buffer.
This is necessary only if the speedbar view is expanded.
To collapse the speedbar view, click the collapse button
(-) next to the buffer's file name in the speedbar view.
Hold the shift key down while clicking the expand
button (+) next to the buffer's name in the speedbar
view.
Searching Source Code
The JDEE provides commands that enable you to find
All occurences of strings matching a regular expression anywhere
in your project's source path (see Finding
Expressions)
Source code that defines the method, field,
or other symbol at point (see Finding
Symbol Definitions)
Source code for the class at point (see Finding
Classes)
Source for the parent of the class at point
Source for an interface implemented by the class at point
All methods that invoke a specifed method (see Cross-Referencing
Classes)
Finding Expressions
The JDEE provides two commands for finding occurrences of strings
in Java source and other types of text files:
JDE->Find->Expression
(jde-find)
This command uses the minibuffer to prompt you for the
search expression and the paths to be searched. You can
use customization variables to specify values for the
search paths and other search options. The default values
for the customization variables search the Java source
files on the classpaths and sourcepaths for your project.
See Using the Minibuffer-Based
Find Command for more information.
JDE->Find->Expression...
(jde-find-dlg)
This command uses a text dialog buffer to
prompt you for search arguments. The dialog buffer
allows you to specify all search options
interactively. It is thus useful for performing
searches that have special requirements.
See Using the Dialog-Based
Find Command for more information.
Both commands use the Unix grep and
find utilities to perform the searches that
you specify. Before executing a search, both commands search
your system for copies of grep and
find and signal an error if the utilities
are missing. All Unix systems include copies of
grep and find. Versions
of these utilities are available for Microsoft Windows, e.g.,
as part of the Cygwin Unix emulation package for Microsoft
Windows. If you want to use the JDEE's find
commands on Windows, you must install copies of
grep and find on your
system and either include them in your system's command path
or use the variables grep-command and
find-program to specify their respective
locations on your system.
Microsoft Windows/NT and Windows 2000 provide a
find utility that is incompatible with
the Unix find utility. To ensure that the
JDEE finds the right version, you should either put the
Unix-style find command ahead of the
Windows find command in your system
command path or use the find-program
variable to specify the Unix-style command's location.
Using the
Minibuffer-Based Find (jde-find) Command
To find an expression with the minibuffer-based find
command:
Select
C-c
C-v
C-f
Find
Expression
from the JDE menu
or execute the jde-find command.
The JDEE prompts you to enter a regular expression.
Screenshot showing the regular expression prompt.
Enter a regular expression that matches the
expressions you want to find and press Enter.
The JDEE prompts you to enter a list of directories to search.
Screenshot showing the directories prompt.
The prompt may list a default search path. The JDEE determines the
default path by testing each of the following variables in the order
listed.
jde-sourcepath
jde-compile-option-sourcepath
jde-compile-option-classpath
jde-global-classpath
The JDEE uses the directories
specified by the first path variable that has a nonnil
value as the default search path.
Edit the default search path, if desired, in the minibuffer
and press Enter.
The JDEE executes the find command that you have specified
and displays the command's output in a popup grep-mode buffer.
Screenshot showing the search results.
The search results buffer lists each instance of a string
that matches the specified regular expression in the specified
search path. For each match, the listing shows the file
and line number of the match, highlighted in red, and a snippet
of the text in which the match occurred.
To visit the file containing the match, click the
match message in the grep buffer with the middle mouse button
or move point to the message and press Enter
Customizing the
Minibuffer-Based Find Command
The following variables allow you to customize the
minibuffer-based search command:
Variable
Default Value
Description
jde-find-case-sensitive
nil
Specifies whether the jde-find command
performs a case-sensitive search. If non-nil, the
search is case-sensitive; otherwise the search
ignores case.
jde-find-granularity
Character
Specifies the granularity of the expression
search conducted by jde-find: Character
(expression starting on any character), Word (match
words only), Line (match lines only).
jde-find-file-regexp
*.java
Specifies the regular expression that the
jde-find command uses to select
files to be searched. You can use any regular
expression supported by the -name
option of the GNU find
command.
Using the Dialog-Based Find (jde-find-dlg) Command
To find an expression with the dialog-based find command:
Select
Find
Expression...
from the JDE menu
or execute the jde-find command.
The Find Expression Options buffer appears.
Screenshot showing the Find Expression Options buffer.
Edit the buffer to reflect the search options that you desire.
The options you select will appear the
next time you execute the jde-find-dlg command.
Select the Ok button.
The jde-find-dlg invokes the
find and grep commands
with the options you specified and displays the results in a
buffer.
Finding Symbol Definitions
To find the source code that defines the class, interface,
method, or field at point, select
Cc
C
v
Cy
Find
Symbol Definition
from the JDE menu or
execute
Mx
jde-open-class-at-point. The JDEE
displays a buffer containing the source code that defines the
symbol at point in the original buffer.
This command requires that the symbol definition be
located on jde-sourcepath and that the
class referenced at point be located on
jde-global-classpath. The command uses
the beanshell to determine the fully qualified name of the
class referenced at point. If the beanshell is not running,
it launches the beanshell.
Finding Classes
The jde-open-class-source command
finds and opens the Java source file for the class whose
qualified or unqualified name appears at point.
The JDE uses Java reflection to determine the fully
qualified name of the class at point. Therefore, the class
must be on jde-global-classpath.
If more than one class with the same name exists on
jde-global-classpath, this command prompts
you to select one of the classes. The following conditions
must be true for this command to work. First, a class file for
this class must exist on the classpath specified by
jde-global-classpath. Secondly, the source
for the class must exist on one of the paths specified by
jde-sourcepath. This command uses the
Beanshell to determine the fully qualified name of the class
to be found. It starts the Beanshell if necessary. Thus, the
command may respond somewhat slowly the first time you it in a
session.
Cross-Referencing Classes
JDE includes a facility for creating and utilizing a
cross-referencing database to enable you to quickly locate all
the callers of any particular function. This functionality is
very useful for quickly figuring how unfamiliar code works,
and useful for doing certain tasks such as renaming functions.
Be advised that this only finds direct callers, and cannot
detect calls via Java's reflection mechanism. The
cross-reference database must be kept in sync with the project
code, however the database generation is generally quick. The
remainder of this section explains how to configure and use
the cross-referencer.
The JDEE's cross-referencing facility was developed by Andrew Hyatt.
Configuring the Cross-Referencer
JDE's cross-referencing database is built by examining
class files for a particular project. To this end, JDE
needs to know where the built class files for a project
live. This is usually a subset of the classpath.
Then select JDE->Options->Project->General, and go to
the "Jde Built Class Path" option. Insert one path for each
place where built classes wind up. You can add both
directories and zip files (jar/bar/etc). Any file entered
will be assumed to be a zip file.
Now that you have the built class path defined, you can
configure the cross-referencer that uses it. Type M-x
jde-xref-customize. The following are a list the variables
that can be set, and what they do:
jde-xref-db-base-directory
The cross-referencer creates a database to
store the cross-reference information. This variable
defines a directory where that information resides. It
might, for example, be at the base of your project tree,
in a directory called xrefdb
jde-xref-store-prefixes
To reduce database size,
it's useful to ignore all information that doesn't refer
to code you care about. For example, most people don't
need to know who calls java.lang.System.out.println. To
not store this information, insert a package prefix for
each package you are interested in. Typically, this may
be just one string, for example "com.mycompany", to
store only code that references com.mycompany
classes.
jde-xref-cache-size
The caller database can be quite large. However, it
is useful for efficiency reasons to keep part of it in
memory. This variable deterines how many packages to
keep in memory simulatenously. The higher this is, the
faster things will be, but also the more memory will be
taken up by the cross-reference information.
Building the Cross-Reference Database
The next step into getting the cross-reference
functionality working is to build the cross-reference
database. The project must be fully built for this to work,
since it takes cross-reference information directly from the
built classes.
To build the database, type M-x jde-xref-make-xref-db
If all the settings are properly configured, JDE will go
off and create the cross-reference database. This can take
from a few seconds to several minutes depending on the size
of your project. Large class files may take long to parse,
so if it seems to be "stuck", please give it time.
When it is done, it will save the database in the base
directory specified in the jde-xref customization group.
Using the Cross-Reference Database
There are several basic operations that use the
cross-reference database:
M-x jde-xref-first-caller (C-c C-v a)
If your cursor is in the body of a function, then
this will go to the first in a sequence of callers to
this function. If there are no callers, there will be a
message saying so.
M-x jde-xref-next-caller (C-c C-v n)
After calling jde-xref-first-caller, you can go to
each of the callers in sequence with this function. The
first caller function creates a list of callers and goes
to the first one. This navigates to the next caller on
the list. You can keep calling this until there are no
more callers, in which case there will be a message
saying so.
M-x jde-xref-display-call-tree
This displays an interactive tree view of the
function you are in, and it's callers. Each level down
will show you who calls the parent function. In this
way you can quickly get an overview of the context in
which the current function is used in. Each item in the
tree will take you to it's definition if it is clicked
on.
M-x jde-xref-list-uncalled-functions
Called from a java file, this lists all the
functions in the file that have no apparent callers.
It's important to remember that because of Java
reflection, there is no guarantee that the functions are
truly uncalled. It only means they are not called
directly.
All of these functions have two modes, a strict and
non-strict mode. In non-strict mode, the default, more
potential callers are treated as callers, including those
that call an interface that the function implements, or who
call a superclass's function you are overriding. For
example, if you are in Foo.doSomething(), and foo implements
IFoo, and a caller calls IFoo.doSomething(), then this is
treated as a caller in non-strict mode. Also, if you are in
Foo.doSomething, and Foo's superclass is Bar, and there is a
Bar.doSomething(), then Bar.doSomething() is treated as a
caller in non-strict mode. In strict mode, however, the
caller must specify the function directly for it to be
considered a hit. To run these functions with strict mode,
type C-u M-x and then the function-name. So C-u M-x
jde-xref-list-uncalled-functions will list only functions
that are uncalled directly.
Updating the Cross-Reference Database
As the code changes, the cross-referencer must be kept
up to date, or else the jde-xref functions will start taking
you to incorrect places in files, and the callers list
itself will become incorrect. As you change the code, you
can call M-x jde-xref-update after a recompile, and it will
go through and recompute just the part of the database you
have changed.
Another, easier way to update, for those of us who leave
their emacs running all the time, is to add a line such as
this in their .emacs
(run-at-time "11:00pm" 86400 'jde-xref-make-xref-db)
Tags
To use the etags facility, you must
first construct a TAGS file that indexes every symbol in your
source code. The JDE package contains two shell scripts that
you can use to tag your source code, one for
csh shells and the other for
bash. The bash version
is called jtags; the csh
version, jtags.csh.
Tagging Java Source Code
To tag your source code, first copy the appropriate shell
script to a directory in your Emacs path. Then start a shell (
Mx
shell). Change to the top-level directory containing your
source code and then enter jtags. The jtags
script tags every .java file in the current directory
and in all descendants of the current directory, storing the
result in a file called TAGS in the top-level directory.
Finding the Definition of a Symbol
To find the definition of a symbol, put your cursor anywhere
in the symbol and enter
M.. Emacs
responds by locating
and opening (if necessary) the file containing the definition and
positioning the point at the definition. (The first time you type
M., Emacs
prompts you to load the TAGS file.)
Customizing the JDE
This section describes various ways you can customize the JDE.
Customization Variables
JDE customization variables allow you to specify compile, run, debug,
and other JDE options.
The traditional way of customizing Emacs is to use
setq forms to set the values of customization
variables in the Emacs initialization (.emacs)
file. This method does not work for JDE
customization variables. To set a JDE customization variable, you
must use the customization buffer for a variable
(see the Emacs online manual for information on the customization
feature). This is because the JDE context switching code resets all
JDE customization variables to their default or customized (via a
custom buffer) values whenever you open a Java source file or switch
projects.
The following section explains how to use the Emacs
customization feature to set the value of a JDE customization
variable.
Setting a Variable
To set a JDE customization variable:
Determine the name of the variable you want to customize.
Refer to the section of this guide that documents the feature
you want to customize for the name of the corresponding variable. Or
type Ch
v followed by the JDE group prefix
(jde-) or subgroup prefix (e.g.,
jde-compile-option-,
see JDE Customization Groups).
Emacs displays all variables belonging to the JDE group or subgroup. You
can then browse this list, using Emacs search, completion, and
documentation display command, to find the applicable variable.
Display a customization buffer for the variable.
If you know the name of the variable, the easiest way to
display a customization buffer for the variable is to select
HelpCustomize
Specific Option... from the
Emacs menubar or type Mx
customize-variable.
If you know the group to which the variable belongs (.e.g., compile
options), you can display the customization buffer for the group. This
is useful when you want to customize several related variables. See
JDE Customization Groups for
more information.
Edit the value for the variable displayed in the customization
buffer.
Save the value for the variable in your .emacs
or .prj file.
If you want the setting to apply to all projects that do not
have a project file (see Using Project
Files), you should save the variable in your
.emacs file. To save the variable in your
.emacs file, select Save
for Future Sessions from the
State menu for the
variable in the customization buffer.
If you want the setting to apply only to a particular project,
you should save the setting in the .prj file for
that project. To do this, open a source file from that project, select
Set for Current Session
from the State
menu for the variable, select the source buffer, and
select JDE
ProjectProject Files
Save
(Cc
Cv
Cp)
from the Emacs menubar.
If a project file does exist for the
project, the JDE will prompt you to enter a name for the project. It
then creates a project file for the project with the name that you
enter.
Specifying Paths
You can use paths containing environment variables and
or a tilde (~), cygwin paths, and relative paths as a value
of any JDE customization variable that requires a
path.
Environment Variables
The JDE accepts paths that contain envirnoment variables, for
example,
$JDK_HOME/src
The JDE replaces the environment variables with their
actual values before passing the paths to commands (e.g.,
javac) that require them. You must use Unix notation
(i.e., $VARNAME or
${VARNAME}) to specify an environment
variable in a path even on Windows.
Tilde (~) Notation
The JDE accepts paths that begin with a tilde, for example,
~/myproj/classes. The JDE replaces the tilde
with the path to your home directory.
Relative Paths
A relative path is a path that begins with a period, for
example, ./src. If
jde-resolve-relative-paths is
set to a non-nil value (the default), the JDE converts a relative
path to an absolute path by appending the relative path to the
path of the project file that set the path variable, or if no such
file exists, to the path of the current Java source buffer.
You can use your .emacs file to
specify default relative paths for projects. For example,
setting jde-global-classpath to
./classes in your
.emacs file specifies that the
default location of class files is in a subdirectory of
the project file directory named classes.
Cygwin Paths
You can use cygwin style paths in JDE classpath variables
on Windows. The JDE converts such paths to DOS paths before
using them, using a conversion function that you can specify.
The jde-cgywin-path-converter variable allows you
to choose the path conversion function used by the JDE.
jde-cygwin-path-converter-internal
This is the default path conversion function used by
the JDE. It converts any paths of the form //[a-z]/
or //cygdrive/[a-z]/ to the corresponding DOS form. For
example it converts /c/jde/java/classes to
c:/jde/java/classes.
jde-cygwin-path-converter-cygpath
This function invokes the cygwin
cygpath utility to perform the
path conversion. The advantage is that the cygwin path
utility can recognize and convert Unix style paths
that represent mount points in the cygwin mount table.
For example, suppose that you have mounted
d:/javadev as
/javadev in the cygwin mount table.
Then choosing jde-cygwin-path-converter-cygpath
allows you to use paths beginning with
/javadev in JDE classpaths. The
drawback is that the conversion is slow as it requires
running the cygwin utility for each Unix-style path to
be converted.
A custom conversion function that you supply.
JDE Customization Groups
The JDE defines a top-level customization group, the JDE
Group, for JDE customization variables. The JDE Group itself
contains the following subgroups:
Compile Option
Group
Specifies compile options corresponding to the
command-line arguments (e.g., -d) accepted by the JDK
compiler, javac. When you execute the JDE compile command,
the JDE uses the settings of this group to construct a list
of command-line arguments that it passes to the Java
compiler that the JDE uses to compile Java source programs.
The compiler is itself an option that you can specify (see
the Project Option Group). You can specify command-line
arguments directly by setting the value of the
jde-compile-option-command-line-args
variable. You can display the customization buffer for the
Compile Option Group by selecting
JDE
Project-Options
Compile from the
Emacs menubar.
Run Option Group
Specifies run-time options corresponding to the
command-line arguments (for example, -classpath) accepted
by the JDK virtual machine, java. When you execute the JDE
Run command, the JDE uses the settings of this group
to construct a list of command-line arguments that it
passes to the Java interpreter used by the JDE to run
applications. This group also contains options for
specifying non-java command-line arguments (in case you
want to use a VM that accepts a different set of arguments
than java does) and for specifying arguments to be passed
to the application (as opposed to the virtual machine
interpreting the application.) You can display the
customization buffer for the Run Option Group by selecting
JDE
Project-Options
Run from the
Emacs menubar.
Debug Option Group
Specifies run-time options corresponding to the command-line
arguments (for example, -classpath) accepted by the JDK debugger,
jdb. jdb accepts the same command-line arguments as java. However,
the JDE maintains two parallel sets of configuration variables
for these programs in case you want to use a different set of
options for running a program in debug mode then you use for
running it normally. When you execute the JDE Debug command,
the JDE uses the settings of this group to construct a list of
command-line arguments that it passes to the Java debugger used
by the JDE to run applications in debug mode. You can display the
customization buffer for the Debug Option Group by selecting
JDE
Project-Options
Debug
from the Emacs menubar.
Autocode Group
Specifies templates used to generate code automatically.
General Options Group
Specify all other JDE options. You can display the
customization buffer for the General Option Group by selecting
JDE
Project-Options
General
from the Emacs menubar.
Customizing jde-mode
The JDE defines a major mode, named jde-mode, for editing
Java source files. This mode derives from the standard Emacs
Java source editing mode java-mode. In particular, it inherits
all the functions and customization variables defined by
java-mode and adds its own customization variables. When you
load a Java source file, Emacs runs a JDE mode initialization
function called jde-mode. The jde-mode function in turn calls
the Java mode intialization function, java-mode. The last
thing that jde-mode does before returning is to call a JDE
mode function, if it exists. You can customize the JDE by
defining a JDE mode hook function in your .emacs file. The
following is an example of how to do this:
(defun my-jde-mode-hook ()
(message "my-jde-mode-hook function executed"))
(add-hook 'jde-mode-hook 'my-jde-mode-hook)
The preceding example defines a JDE mode hook function named
my-jde-mode-hook and adds it to the list of JDE mode hook
functions, using the Emacs Lisp function add-hook. Now, whenever
you open a Java source file, jde-mode invokes the function my-jde-mode-hook.
Of course, the hook function defined in this example is trivial.
A real-world example might do something more useful, such as
setting a custom indentation style.
Customizing Key Bindings
A key binding establishes an equivalence between a keystroke
or a sequence of keystrokes and an interactive Lisp function. The
keystroke or keystroke combination causes Emacs to execute the
function to which the keystroke (combination) is bound. For
example, the JDE by default binds the keystroke Cc Cv Cc
to the function jde-compile. You can use the JDE
customization facility to change the standard JDE bindings or
create bindings for functions that do not have default bindings.
To customize key bindings:
Open a buffer on the JDE customization variable jde-key-bindings.
You can do this by typing
Mx
customize-variable
jde-key-bindings or by selecting
JDEOptionsProject and searching the
resulting JDE project customization buffer for
jde-key-bindings.
The key bindings panel looks like this:
Screenshot showing key bindings buffer.
Edit the buffer to specify altered or new bindings.
For example, to add a binding, right click the
[INS] button, then enter the key stroke in the
Key field and the interactive function (command)
to which it is bound in the Command field.
Save the edited bindings.
To save the edited bindings, right click the
[State] button and choose
Set for current session if you
want the settings to apply only to the current project or
Save for future
sessionsif you want the settings to apply
to all projects. In either case, you should save the new settings in
you project file if your project has a project file. To save the new
settings in your project file, switch to a source buffer and choose
JDE OptionsSave Project from the Emacs menubar.
Creating and Installing Plugins
Plugins are independently developed applications intended
for use with the JDEE and distributed in the form of a (g)zip or
jar file. The following sections explain how to create and install
plugins.
Installing a Plugin
To install a plugin:
Copy the zip or jar file containing the plugin in to
the JDEE's plugins directory.
By default the JDEE plugin directory is a
subdirectory of the JDEE directory named
plugins. If you want to keep your
plugins in another directory, set
jde-plugins-directory to the path of
that directory.
Execute M-h jde-pi-install-plugins.
This command installs any plugins at the top level of the plugins
directory in the plugins directory.
If the plugin adds any menu items to the JDEE's plugins menu
(named JDEpi), you should now be able to see the
items on the plugins menu.
Creating a Plugin
The following sections explain how to create a JDEE plugin.
Plugin Requirements
A JDEE plugin must meet the following requirements:
Packaging
The plugin must be distributed as a compressed file that can be
decompressed by Java's jar program. Compressed file formats that meet this
requirement include zip, gzip, and jar.
Directory Structure
Decompressing the plugin should create a subdirectory in the
current directory whose name is the plugin's name and that contains
at least one directory named lisp. The
plugin directory can contain any number of other directories.
The other directories can have any names. However, it would be
nice if plugins standardized on the following directory structure
and names.
plugin
bsh
doc
scripts
help
info
html
src (e.g., xml files used to generate info and html)
java
class
doc
lib (e.g, jar files)
src
lisp
Bootstrap File
The plugin's lisp directory must contain a Lisp file
named jde-PLUGIN.el where PLUGIN is
the same as the plugin's toplevel directory name. This
file is called a bootstrap file because it is the only
file directly loaded by the JDEE. It is responsible for
registering the plugin with the JDEE and loading any other
Lisp files required by the plugin.
Registering a Plugin
A plugin's bootstrap file must register the plugin with
the JDEE when it is loaded. The bootstrap file should do
this by invoking the JDEE's
jde-pi-register function. This function
takes a single argument: an instance of
jde-plugin class that optionally
specifies the plugin's menu and its contribution to the
classpath of the instance of the BeanShell run by the
JDEE.
Running Java Code from a Plugin
A plugin can use the JDEE's instance of the BeanShell to
invoke Java methods and display their output in an Emacs
buffer. The JDEE provides the following functions for this
purpose:
jde-jeval
Evaluate a Java statement in the JDEE's BeanShell
instance and return the resulting BeanShell
output.
jde-jeval-r
Evaluate a Java statement in the JDEE's BeanShell
instance, use the Emacs Lisp interpreter to evaluate the
resulting BeanShell output, and return the result. This
function assumes that the Java statement emits Emacs
Lisp code, i.e., that the Java code was developed
specifically to cause Emacs to do something.
jde-jeval-cm
Evaluate a Java statement in the JDEE's BeanShell
instance and display the resulting BeanShell output in
an Emacs compilation buffer. This function is intended
to run Java applications, such as style checkers, that
output error messages keyed to specific lines in a
source file.
See the doc strings for these functions for more information.
Bootstrap File Example
The following is an example of the bootstrap file
for a plugin named pi1.
;; jde-pi1.el
(defun jde-pi1-cmd ()
(interactive)
(message "plugin 1"))
(jde-pi-register
(jde-plugin
"pi1"
:bsh-cp (list
(expand-file-name "lib/lib1.jar" (jde-pi-get-plugin-dir "pi1"))
(expand-file-name "lib/lib2.jar" (jde-pi-get-plugin-dir "pi1")))
:menu-spec (list (list "Pi1" ["cmd" jde-pi1-cmd :active t]))))
(provide 'jde-pi1)