JDK Commander

User's Guide
Version 25-August-2000

What is JDK Commander?

JDK Commander is a tools integration program that has been designed as an entry level Java development tool for Microsoft Windows PCs. It complements Sun's Java Development Kit (JDK) by wrapping the JDK in a graphical user interface. JDK Commander was written by someone who appreciated the functionality of the tools in the JDK, but was frustrated by the awkward DOS command line interface. The design goals were

Absolutely no interactive DOS windows.
No command line interface except where unavoidable: Only the jdb debugger requires command line interaction.
No installation problems. (More on installing JDK Commander)
Flexibility in using multiple versions of JDK. (More on supporting multiple versions)
Support for multiple public classes in a single source file. Although this does not conform to the standards established by Sun, this feature has been implemented (with an appropriate warning) for compatibility with other Java development tools. (More on source files)
No cost (to be in line with JDK). JDK Commander may be freely distributed, although it is strongly recommended to contact the web site http://www.geocities.com/jdkcommander/ (or e-mail the author) for the current version.

JDK Commander has been tested on Windows 95 and Windows NT 4.0. There are no special hardware requirements. Any PC that can run Sun's Java Development Kit should also be able to run JDK Commander.

Installation

The installation has been simplified to almost zero: JDK Commander is distributed as an immediately executable program. The following must be done:

Download Sun's JDK and install it on your PC. Note: The installation instructions that come with the JDK suggest including the JDK directory in the path (by editing AUTOEXEC.BAT if Win95). This is not necessary at all when you have JDK Commander. JDK Commander has a graphical configuration menu to select the directory where the JDK tools are. In addition, you can maintain multiple named configurations, so you can have multiple JDK versions on your PC and easily switch between them. Did you ever consider installing early beta versions of JDK?
Copy JDKcommander.exe to the directory where you want it to reside. Note that JDK Commander will create small configuration data files in this directory. Perhaps you will also keep the files related to this user guide in that directory.
Optionally create shortcuts to JDKcommander.exe on the Windows desktop or in the start menu. Consult Windows Help for instructions on how to create shortcuts.

Control Panel

The control panel is the display that you usually get when you start JDK Commander. Generally speaking, JDK Commander always starts by displaying the control panel, unless it doesn't have a valid set of configuration data. Therefore, when you start JDK Commander for the first time, you will not see this control panel, but rather the configuration menu.

This is what the control panel looks like. Click on an area of the picture about which you want to know more.

The control panel has 3 control groups:

Source : This control group is for functions related to source code.
Object : This control group is for functions related to class files, i.e. files that have been created by the javac compiler.
Applet : This control group is related to applet execution by means of the JDK appletviewer.

In addition, there are 4 miscellaneous buttons at the bottom:

The Settings button opens the configuration menu. Press this button if you want to change or look up the current JDK Commander configuration settings.
The javadoc button opens the javadoc menu. Press this button to run the javadoc utility.
The jar button opens the jar menu. Press this button to run the jar utility.
The Exit button terminates JDK Commander.

Source (.java) group

These controls are the interface to all functions related to Java source files. Let's first take a look at the buttons and then add a few comments on the source files that JDK Commander can process.

The javac button calls the JDK javac compiler to compile the currently selected source file. See below how to select a source file. When javac has finished, you either see nothing (except that the mouse pointer changes from hourglass to normal) or an editor window appears that displays diagnostics generated by javac. No editor window means no diagnostics which means a successful compilation. However, you will also get a diagnostics display of a compilation without errors if the compilation option -verbose is selected.

You can select compilation options in the javac configuration menu.

See the tools configuration menu for more details about the editor window that displays diagnostics.

The Edit button calls the editor. If an existing source file is selected (see below how to select a source file), the editor will be called to open this file. If no file is selected, the editor is called without opening any file, so you can create a new one.

Selecting an existing source file: There are two ways to select a source file. You can press the Browse button to open a file dialog and select a file by opening it in the dialog. As a result, the file name and the complete path will be displayed in the edit control below the Browse button. The second way is directly entering the file name and its path in the edit control, or modifying a file specification that is displayed in it.

A hint for when you work on a moderately complex project with multiple related source files: You can start multiple instances of JDK Commander and select a different source file in each instance. Then you can edit and/or compile a particular java file by simply pressing a single button without going through a file navigation/selection.

Source files that JDK Commander can process: Source files are basically text files. JDK Commander works for files created in Windows/DOS, UNIX and Mac environments (They differ in the way lines are separated. Not every editor will handle all formats.).

javac accepts only files that contain not more than one class with the attribute public. This restriction is based on the fact that javac creates one class file per java file and on the runtime binding mechanism of java that relies on class file names being identical to the name of the public class they contain. For reasons of compatibility with some other java development tools, JDK Commander also accepts source files with multiple public classes. JDK Commander makes these files acceptable to javac by splitting them up into smaller temporary source files containing one class each. Therefore, the result of a javac compilation may be multiple class files. This approach has some side effects:

JDK Commander must analyze the source files in order to see what classes they contain. In order to do this, it must check all occurrences of { and }. If they are not balanced, JDK Commander will report this fact by means of a pop-up message. You get this diagnostic before javac gets a chance to write its own diagnostic output.
Source files with multiple public classes are not very portable since they violate the standard established by Sun. Therefore, JDK Commander displays a warning (you can temporarily disable it) if it is asked to compile such a file.
When splitting a source file, JDK Commander creates new temporary source files with the name of the class they contain. Therefore, the original source file must have a name that is different from any name of the classes it contains (or the original file would be overwritten). JDK Commander will not accept files that do not conform to this rule.

Object (.class) group

These controls are related to the execution of files with the extension .class, also referred to as byte code. They are created by the javac compiler from .java source files.

Before you can execute a program, you must select a .class file. There are two ways to select a class file. You can press the Browse button to open a file dialog and select a file by opening it in the dialog. As a result, the file name and the complete path will be displayed in the edit control below the Browse button. The second way is directly entering the file name and its path in the edit control, or modifying a file specification that is displayed in it. Also use the edit control for runtime arguments.

The java button starts the execution of the currently selected class file. You can select java execution options in the java configuration menu. When you press the java button, a new window will appear (in addition to the ones your application may create). This window handles the java I/O streams System.in, System.out and System.err. That is, if you want to type input to your application, you type it into this java streams window. If your application writes to System.out and/or System.err, the output will appear in this window. The streams are distinguishable by individual colors as shown by the following example:

//
// Streamsexample1.java
//
import java.io.*;
public class Streamsexample1
{ public static void main (String[] args)
{ System.out.println("This is System.out");
    System.err.println("This is System.err");
    try
    { BufferedReader stdIn = new BufferedReader(new InputStreamReader(System.in));
      stdIn.readLine(); // Accept a line of input from the keyboard
    } catch (Exception e) { System.err.println("System.in error " +e); }
}
} As an exercise, you can open the source code editor by pressing JDK Commander's Edit button, create a new file containing the above code and save it in the editor as Streamsexample1.java in a directory of your choice. Then press the javac button to compile it. Since the source file is known so far only to the editor, but not to JDK Commander, a file dialog will open, so that you can inform JDK Commander which source file you want to compile. When the compilation is done, press the java button, and a window will open containing the following:

It is also possible that these two lines appear as one single line on your PC. This is dependent on internal timing conditions. The java virtual machine writes independently the following to two buffered streams:

The program's string "This is System.out"to system.out
A new line character to system.out
The program's string "This is System.err" to system.err
A new line character to system.err

The components of the two streams may appear mixed up in the window because the two lines are written almost simultaneously and the java virtual machine buffers separate streams individually. In the example run presented here, the components are displayed in the order 1 - 2 - 3 - 4, but the sequence 1 - 3 - 2 - 4 is also possible. You would always get 1 - 2 - 3 - 4 if the program wrote both strings to the same stream.

Then the little java program expects you to type a line (e.g. This is keyboard input to System.in) and terminate it with the Enter key. This results in the following display:

You can see here that System.out is blue, System.err is red and System.in is black. In addition, there is a green line that is displayed after the java program terminates. The window will disappear when you press any key or close it by clicking on the top right corner.

The window's file menu shown below offers the following:

Save current display to file: Save in a file everything that is currently displayed (more precisely: everything that is currently in the scroll buffer. The scroll buffer contains up to 1500 lines. If your application displays more lines, the top lines will be lost).
Start recording lines: Save in a file all lines displayed in the future, without the currently displayed ones. The Stop recording lines function will stop this and close the file.

Some programs require runtime arguments. For instance, if you write an application that replaces all tabs in a text file by spaces, you would supply the name of the text file as an argument and access it in the program via the main(String[] args) mechanism. You can supply runtime arguments by typing them directly in the edit control for class file selection after the file name. Here is an example. First press Browse to select a class file. You may get something like this:

Next, you manually append the runtime argument to the class file specification:

Finally press java to run the application.

The jdb button starts the execution of the currently selected class file under control of the JDK debugger. Otherwise it is just like java (except that you can't use the -v option).

! Note that jdb versions earlier than JDK 1.3 require you to have a connection to the internet while jdb is initializing. Otherwise jdb hangs. I have always considered this very annoying. But with JDK 1.3, this has changed (and a few other quirks have also disappeared). So, if you want to do debugging, I strongly suggest to not use any JDK less than version 1.3!

Applet (.htm*) group

These controls permit selecting an html page containing an applet and executing it with the JDK appletviewer. This is very similar to executing an application by pressing java, so no further explanations are given here, except for a reminder that there are also appletviewer options in the configuration menu. In contrast to java execution, you will get the System streams I/O window only in debug mode because then you will need to interact with jdb. If not in debug mode, any output written by the applet will be displayed after appletviewer termination by means of an editor (see also javac for more on displaying diagnostics).

Note that the appletviewer may require an online connection to the internet for starting properly. This seems to be somehow related to jdb: With JDK 1.3 I can run appletviewer completely offline.

Configuration Menu

When you start JDK Commander for the first time, you will first see its configuration menu. In addition, whenever JDK Commander thinks that the configuration data available to it are not sufficient, it will display the configuration menu.

This is what the configuration menu looks like. Each tab is shown (with its default settings) and briefly explained:

Tools: common parameters
javac
java
appletViewer
Sourcecode editor

Tools: common parameters

The Tools common parameters tab has common definitions for the collection of tools that are included in the JDK. The most important component here is the Tools .exe directory parameter. Here you inform JDK Commander where the file javac.exe (the javac compiler) is located. You do this by navigating through the file menu that opens when you press Browse, or by entering the file specification directly in the edit control. JDK Commander then expects to find the other JDK executables (java, appletviewer ....) in the same directory.

I suggest not to put JDK Commander in the same directory as Sun's JDK executables.

For a description of the four path settings see the JDK documentation. The paths consist basically of a list of directories which JDK Commander lets you compose by means of the Add and Clear buttons. With every Add you get a dialog where you can select one directory. When you press Add again, the selected direcory is added to the list that you see in the edit control. With Clear you can wipe out the entire list. Of course you can manually edit the contents of the edit box.

You can then choose how you want diagnostics displayed. This applies to diagnostics from both javac and appletviewer. By default, the Windows Notepad displays them, but you can choose your sourcecode editor to be called for displaying the diagnostics.

The individual configurations box is common to all configuration tabs. It permits saving and restoring complete configurations and referring to them by name. Although the current configuration is always saved as the default, you may wish to keep different settings that you can restore easily.

If you want to save your current configuration settings simply as the default settings, press OK. If you want to save them as a named configuration, press Save to open a file save dialog.

When you want to reload a named configuration later on: Open the configuration menu from the control panel, then press the Load button in the individual configurations group to open a file dialog.

Possible uses for this feature are

Debug / no debug configurations.
Multiple JDK versions installed on your PC in different directories (e.g. a proven old release and a suspect Beta version).
Project specific configuration settings, e.g. with specific class paths or other specialized options.

javac parameters

The javac configuration tab is for parameters that are related to javac only. The Sound checkboxes control an acoustic signal that may be turned on for an audible notification of the end of a javac compilation. For an explanation of the other parameters consult the JDK documentation.

Just a comment to the target controls: The default (as shown in the above screen shot) is other with an empty edit box. The result of this is that JDK Commander will call javac with no target option at all, so that javac will apply its default. You could however enter something in the edit box, although there is currently nothing meaningful you could do. But I have added it to be open-ended: If you use JDK Commander in 20 years with JDK version 98.7, you may well wish to specify some target option.

I encourage you to use the target option, so you get the benefits of the latest virtual machines.

java parameters

The java configuration tab contains no JDK Commander specific controls. They are all related to JDK's java. For a description consult the JDK documentation. The settings shown above are the defaults chosen by JDK Commander. Just a remark to the jdb launch option: This is the -launch option described in the JDK documentation in the section on jdb. I decided to not create a separate jdb configuration sheet, so you find the option here. Also note that this option is not available in JDK releases less than 1.3!

appletviewer parameters

The appletviewer configuration tab contains no JDK Commander specific controls. They are all related to JDK's appletviewer. For a description consult the JDK documentation.

Sourcecode editor parameters

The sourcecode editor tab is for the definition of the editor you want to use for editing your java source files. JDK Commander does not come with its own editor, but you can plug-in your favorite editor. If you don't have one, you can work with the standard Windows Notepad by checking the Notepad checkbox in this control group. If you check the 'some other editor' box, you must tell JDK Commander which executable to start. You do this by either entering the full path and name in the edit control or by navigating in the file menu that opens when you press the Browse button.
JDK Commander supports editors that are either Win32 executable files (.exe) or java archives (.jar).

Note that the default configuration settings are inconsistent: They indicate to use some other editor, but have no file specification. This has been done intentionally to force new users to take a look at the configuration. You must either select Notepad or specify the path to your preferred editor.

If you are not sure about which editor to use, I have three suggestions. They are very different, and each may serve as an example for many similar ones:

The complete perfect editor: UltraEdit

UltraEdit is a really fine editor: very rich in functionality, lots of useful features, fast .... it's a pleasure to work with.

+ A great editor

- It's shareware. You have to pay for a license (after a free trial period).

The fast and stable work horse: PFE (Programmer's File Editor) at http://www.lancs.ac.uk/people/cpaap/pfe/ or WinSite or Simtel

PFE is not very sophisticated, but it's an absolutely clean implementation and easy to work with.

+ It's free!

+ Runs fast without requiring a powerful machine.

- Doesn't have many bells and whistles.

The java beauty: jEdit at http://www.gjt.org/~sp/jedit.html or http://sourceforge.net/

jEdit is an editor run by java, so it is supplied as a .jar rather than a .exe which makes it platform independent. It is a very nice editor with quite a few useful features and a hook for plugins, so it is extensible. And it looks gorgeous! (want to see a picture? )

+ It's free!

+ Nice features, looks great.

- Java editors are much slower that any Win32 variety. If you have a slow machine it will take ages to start, and the pulldown menus feel sticky. You really need a powerful CPU to accomodate the java virtual machine.

- On some PCs there seem to be occasional problems with starting multiple copies of the same program. This is not related to jEdit (I believe) but rather to some quirk with the java virtual machine on Windows. Give it a try - it may work for you.

But any other editor will work, even the Windows Wordpad or Word. Let me know about your favorite!

javadoc menu

The javadoc menu is JDK Commander's way of providing javadoc access from the bottom of the control panel. That is, whenever you want to run javadoc, you get this menu. There is no single-click shortcut to javadoc because

javadoc is quite a complex tool with so many options.
you will probably not run it as many times as you compile, so you are prepared to spend more time on javadoc details.
with many of these options being saved across JDK Commander sessions, you will not have to enter all of them again and again.

The parameters for javadoc are grouped by 5 types of variables:

source files
javadoc files and paths
javadoc options
doclet files and paths
doclet options

source files

The first box (java files) lets you select java source files. Besides entering them manually, you can select them by means of the Add and Clear buttons. With Add you get a file dialog that lets you select multiple files from a single directory. When you press Add again, another file dialog opens, and you can select more files from another directory. These will be added to the list of java files. Clear wipes out all files that are currently listed in the edit control.
Note that you can manually enter things like *.java. This will usually work if the files are at a location included in the sourcepath.
If your sourcepath contains directory names with embedded blanks, javadoc will probably not accept them. If you insist on using embedded blanks, use the file dialog selection.

The second box (packages) lets you manually enter packages. You might as well type in here java source file names because on the command line that JDK Commander will set up internally, packages and java files can appear in any order. There is a special box here for packages to make a clear distinction between files selectable by dialog and other input.

javadoc files and paths

Please consult the JDK documentation (section javadoc options) for an explanation what these options mean. Just let me add the following JDK Commander specific details:

The four path options also have the Add/Clear buttons that let you compose a list of directories step by step, or clear the field alltogether.
The path options are inherited from the main configuration. This means whenever you open the javadoc menu, the path options will be initialized with the values from the main configuration. You can then override them here. The overriding values become effective for javadoc, but are not propagated back to the main configuration. So next time you run javadoc, you will see again the original values from the main configuration.
The settings of the options not subject to inheritance from the main configuration are persistent.

javadoc options

Here you can enter javadoc options not directly related to files. Again, consult the JDK documentation (section javadoc options) for an explanation of these options.

The field doclet options is not described in the JDK documentation. You can type in here any sort of additional arguments. The main purpose of this is to provide a means of specifying arguments that are input to a user written doclet. If you don't have your own doclet, leave the doclet options field empty. The following option tabs are provided for specifying options to the standard doclet.

doclet files and paths

This panel is for options related to the standard doclet. For an explanation, consult the JDK documentation (section Options Provided by the Standard Doclet).
The destination control lets you select a directory where javadoc will store its results. This destination option is independent of the javac destination option which you can set in the main configuration menu.

doclet options

These are more options for the standard doclet. I have nothing to add to the JDK documentation.

jar menu

The jar menu is JDK Commander's way of providing jar access from the bottom of the control panel. That is, whenever you want to run jar, you get this menu. There is no single-click shortcut to jar for similar reasons as for javadoc.

This is what the jar menu looks like (at least when you open it for the first time). You will find a few controls that are enabled, and quite a few more that are disabled (greyed out). However, they will become enabled as you enter parameters.

On this menu, the controls are arranged for a top-to-bottom click order.

First, select an archive, either by creating a new one or opening an existing one for update. The respective buttons are in the top left corner.

Optionally, select your own manifest file. Consult the JDK documentation for more information on manifest files.

Not optional: The base folder. This is the folder from where jar will start collecting files. In the JDK documentation, this corresponds to the default directory from where you would call jar if you used the DOS command line.

As soon as JDK Commander has an archive file specification and a base folder, it will enable the dialog items for selecting files to include in the archive. Now you can

Either check the box "Add all files including all subfolders" which will tell jar to recursively include all files starting with the base folder.
Or use the fields that let you specify individual files or subfolders.

The Select files field lets you choose arbitrary files. They will be included in the jar archive with their name, but without their path. One way to select files is using the Select button which lets you choose multiple files from any directory (but all from the same directory). If they are not in the base folder, JDK Commander will use the jar option -C. The other way is to manually enter something. This way, you can also use wildcards, e.g. like this:

This will include all class files in the base folder.
This screen shot shows you also that the button at the bottom to the left of the Cancel button is a "polymorphic" button: Its text changes according to the circumstances. While the button's text in the first screen shot was Run jar (it was disabled there), it is now Create archive because (in this particular case) JDK Commander knows that the user wants a new archive to be created. If you pressed the Update existing archive button at the top, the text of the button at the bottom would now read Update archive. Whatever it says, this is the button that will close this dialog window and start jar with all your parameters. If you want to see the jar command line generated by JDK Commander: Check the verbose checkbox!

To the left of this polymorphic Run button, there is the Create index button. It is only enabled when you select an existing archive for update. If you press it, jar will be started with the -i option (see JDK documentation) to create an index in the archive. All input file selections are ignored in this case. Note that this function is not available in JDK versions less than 1.3. JDK Commander does not know what JDK version you are using and will not protect you from a jar error if you try creating an index with an older JDK release.

There are two more things in this dialog I want to mention:

The Select subfolders item lets you chose folders located in the base folder that you want included recursively in the archive. You can either add all of them (and then manually wipe out the ones you don't want) or add one by one using the Add button. If you consider using this feature: Maybe the "Add all files including all subfolders" checkbox is a quicker approach to what you need.

Finally, there is the checkbox Open jar archive as zip after jar operation at the bottom left. When this is checked, JDK Commander will, after having run jar, start your zip program to open the jar archive. I have tested this feature only with WinZip. I don't know how well this works with other zip programs. This feature will present your archive with your favorite archive utility that lets you inspect the contents and delete unwanted files. (In fact, I have chosen this approach to avoid reinventing the wheel. I can hardly do better than WinZip.)

If the zip checkbox is disabled (greyed out), this means that JDK Commander has examined your system and was not able to locate a program for opening zip archives. Check your zip utility installation!

Feedback

Although JDK Commander enhancements are unpredictable due to my limited time, it may receive some improvements over time, with top priority for bug fixes. Feedback, comments and inquiries are always welcome. Please send them to ulrich.waldispuhl@compaq.com. For the latest version see http://www.geocities.com/jdkcommander/.