JDEE User's Guide

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:

The JDE requires the following software:

The JDEE distribution includes the following files:

See Downloading the JDE on the JDE website for instructions on downloading the most recent version of the JDE.

See the JDE Installation Guide on the JDE website for information on installing the JDE on your system.

Please send bug reports and enhancement suggestions to Paul Kinnucan.

To register a version of the JDK with the JDEE:

To select a JDK:

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.

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->Options->Javadoc 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.

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 by default for a project, select JDE->Project->Options ->General and toggle the boolean variable jde-enable-abbrev-mode. To toggle abbreviation mode on or off during a session, select JDE->Code Generation->Modes->Abbrev. To change, remove, or add an abbreviation, edit the variable jde-mode-abbreviations in the project customization buffer.

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.

	  ife
	

	  if ( ) { } // end of if () else } // end of if ()else
	

	  (jde-gen-define-abbrev-template "melse" '('> "else {" '> 'n
	  '> 'r 'n "}"))
	

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:

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.

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.

	    String s; s.get ^
	  

	    String s; s.getClass( ^
	  

	    java.lang.Class getClass()
	  

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

The JDEE provides a set of commands that generate and organize import statements in the current buffer. The commands automate the following tasks:

  import java.io.*;
	  

  import java.io.BufferedReader;
  import java.io.InputStreamReader;
  import java.io.IOException;
	  

  import java.io.BufferedReader;
  import java.io.InputStreamReader;
  import java.io.IOException;

  import java.io.*;

  import java.io.InputStreamReader;
  import java.util.Hashtable;
  import javax.swing.JFrame;
  import javax.swing.JPanel;

  import jmath.LinearSystem;
  import jmath.Test;

The JDE provides a set of procedural code generators called code wizards. They include:

The compile command displays the output of the compiler in a separate compilation buffer.

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.

The JDEE supports the following Java compilers.

To specify one of these compilers for the current project or all projects:

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.

To select a build method:

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.

	  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)" $? 
	

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.

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).

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,

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.

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.

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.

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 JDE->Project->Options->Run. (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-> Project->Project File->Save Project.

The following table lists the JDE run variables and the functions used to set them.  

To run an applet:

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.

To debug an applet:

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.

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 JDE->Options->Run. (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 JDE->Options->Update Project.

The following table lists the JDE applet run-time variables and the functions used to set them.

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.

          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.
	

          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.
	

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.

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.

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.

The easiest way to create a project file is to use the jde-create-new-project command (JDE->Project->Project File->Create New). This command creates a new project file and 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.) Thus, to create a project file that sets JDE configuration variables to project-specific values:

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.

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.

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.

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.

The jde-browse-jdk-doc command (JDE->Help->JDK, C-c  C-v C-n) 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.

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 JDE->Help->Symbol at Point .

The JDEE uses the browsers or browsers specified by the customization variable browse-url-browser-function. See the documentation for this variable for more information.

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.

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.

To display the speedbar, select JDE-> Speedbar. The speedbar opens in a separate frame.

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

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.

Clicking on the package scrolls the buffer to the corresponding package declaration.

Types

This item expands to show the classes in the selected file.

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.

Click on class or package to scroll the buffer to the corresponding import statement.

The JDEE provides two commands for finding occurrences of strings in Java source and other types of text files:

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.

To find the source code that defines the class, interface, method, or field at point, select Find->Symbol Definition (C-c  C-v  C-y) from the JDE menu or execute M-x jde-open-class-at-point. The JDEE displays a buffer containing the source code that defines the symbol at point in the original buffer.

The jde-open-class-source command finds and opens the Java source file for the class whose qualified or unqualified name appears at point.

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.

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.

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

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.

JDE customization variables allow you to specify compile, run, debug, and other JDE options.

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

	      $JDK_HOME/src
	    

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.

To install a plugin:

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.

The following sections explain how to create a JDEE plugin.

   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
	  

  ;; 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)