by Joe Carpenter
This chapter is intended to cover all of the tools that are included in the Java Developer's Kit. You learn about each tool, what it does, all of its associated options, and the environment variables it references. If you're just beginning programming in Java, this chapter serves as an introduction to the tools of the JDK. If you're a hard-core Java hacker, this chapter is more of a reference tool, so you don't have to waste precious CPU cycles bringing the rather ugly man page reference materials. Either way, reading this chapter gives you a pretty good idea of what the JDK tools can do, and how to make them do it.
Applets are programs written in Java that are designed to run embedded in an HTML document, just like a Web page. Under most circumstances, they don't have the ability to run by themselves. The Appletviewer is a small program that lets you run applets without the overhead of launching a system that hogs the Web browser. It's a quick and easy way to test your applets as you're developing them.
You call the Appletviewer with the following command:
appletviewer [ options ] urls ...
The urls in the command line are the Uniform Resource Locator to HTML files that
contain applet tags. If you're in a directory that has an applet and an HTML file
that has an applet, you can call the Appletviewer simply by typing in the name of
the HTML file that contains the applet tag:
| Option | Description |
| -debug | Starts the Appletviewer in the Java debugger -jdb, thus allowing you to debug the applets in the HTML document. |
FIG. 4.1
The Appletviewer's Tag window.
FIG. 4.2
The Appletviewer's Applet Info window.
FIG. 4.3
The Appletviewer's Properties window.
The Java interpreter is what you use to run your compiled Java application.
The syntax for the interpreter is:
java [options] classname
where classname only includes the name of the class and not the extension (.class).
The Java interpreter options are listed in Table 4.1.
| Option | Description |
| -help | Displays all of the options. |
| -version | Displays the version of the JDK that was used to compile the source code. |
| -v (also -verbose) | Displays all the classes as they are loaded. (Performs the same functions as in the javac tool.) |
| -cs (also -checksource) | Checks to see if the source code is newer (not yet compiled) than its class file. If this is the case, then the new version of source is compiled. |
| -noasyncgc | Turns off asynchronous garbage collection. |
| -verbosegc | Prints out a message each time garbage collection occurs. |
| -verify | Verifies all classes that are loaded. |
| -noclassgc | Disables class garbage collection. |
| -noverify | Turns off class verification. |
| -classgc | Disables class garbage collection. |
| -verifyremote | Verifies classes that were imported, or inherited. This is the default setting. |
| -mx val | Sets the maximum Java heap size to the value specified by val. The minimum heap size is 1K (-mx 1k) and the default is 16M (-mx 16m). (Use the letters m and k to specify megabytes or kilobytes for the value of val.) |
| -ms val | Sets the initial Java heap size to the value specified by val. The minimum heap size is 1K (-mx 1k) and the default is 1M (-mx 1m). (Use the letters m and k to specify megabytes or kilobytes for the value of val.) |
| -ss val | Sets the value of the stack size for a C process to the value specified in val. The stack size must be greater than 1K (-ss 1k). (Use the letters m and k to specify megabytes or kilobytes for the value of val.) |
| -oss val | Sets the stack size of a Java process to the specified value in val.(Use the letters m and k to specify megabytes or kilobytes for the value of val.) |
| -debug | Used with remote Java files that are to be debugged later with the jdb tool. The interpreter generates a password for you which is used in the jdb's -password option (see the section "jdb Options" later in this chapter.) |
| -prof | Output profiling information to file \JAVA.PROF. |
| -classpath dirs | Looks for class files, included in the source file, in the specified directories--DIRS. For multiple directories, a colon (in UNIX) or semicolon (in DOS) is used to separate each directory. For example, on a DOS machine the classpath might look like set CLASSPATH=.;C:\users\dac\classes;C:\tools\java\classes. |
The Java disassembler is used to disassemble Java bytecode that has already been compiled. After disassembling the code, information about the member variables and methods is printed. The syntax for the Java disassembler is:
javap [options] classnames
Multiple classes can be disassembled. Use a single space to separate each class.
The options available for the disassembler are shown in Table 4.2.
| Option | Description |
| -version | Displays the version of the JDK that javap is being executed from. |
| -p | Prints out private and public member variables and methods. (By default, javap only prints out public member variables and methods.) |
| -c | Disassembles the source file, and displays the bytecodes produced by the compiler. |
| -l | Prints the local variable tables. |
| -h | Outputs information on the particular class that can be used in C- header file to be used by a C program that wants to use the methods in that class. |
| -classpath dirs | Looks for class files, included in the source file, in the specified directories--DIRS. For multiple directories, a colon (UNIX) or semicolon (DOS) is used to separate each directory. For example, on a DOS machine the classpath might look like set CLASSPATH=.;C:\users\dac\classes;C:\tools\java\classes. |
| -verify | Runs the verifier on the source, and checks the classes being loaded. |
| -v | Displays information on the source code in detail as it disassembles. |
The javah tool creates C-header and stub files needed to extend your Java code
with the
C language. (Chapter 41 talks about extending Java in more
detail.)
The syntax of the javah tool is:
javah [options] classname
where classname is the name of the Java class file without the .class extension. See Table 4.3 for a list of javah options.
| Option | Description |
| -help | Prints out the help screen. This is the same as typing javah by itself. |
| -jni | Creates a header file for use in JNI. |
| -td | Identifies the temporary directory for javah to use. |
| -trace | Causes trace information to be added to the stub files. |
| -classpath | Specify the classpath for use with javah. |
| -stubs | Creates stub files instead of the default header files. |
| -d dir | Tells the javah tool in what directory to create the header or stub files. |
| -v | Prints out the status as it creates the header or stub file. |
| -o filename | Puts both the stub and header files into the file specified by file name. This file could be a regular text file or even a header (FILENAME.H) or stub (FILENAME.C) file. |
| -version | Prints out the build version. |
The javadoc tool creates an HTML file based on the tags that are embedded in the /** */ type of comments within a Java source file. These HTML files are used to store information about the classes and methods that you can easily view with any Web browser.
Javadoc was actually used by the creators of the JDK to create the Java API Documentation (refer to http://www.javasoft.com/doc for more information). You can view the API online and you can also see the source code used to generate it in your \JAVA\SRC\JAVA directory. See Tables 4.4 and 4.5 for information regarding options and tags.
| Option | Description |
| -verbose | Displays more information about what files are being documented. |
| -d directory | Specifies the directory where javadoc stores the generated HTML files. For example: javadoc -d C:\usrs\dac\public_html\doc java.lang. |
| -classpath dirs | Looks for class files, included in the source file, in the specified directories--DIRS. For multiple directories, a colon (UNIX) or semicolon (DOS) is used to separate each directory. For example, on a DOS machine the classpath might look like set CLASSPATH=.;C:\users\dac\classes;C:\tools\java\classes. |
| -sourcefile dirs | Specifies in colon-separated directories the list of files to use. |
| -doctype | Specifies the type of file to output the information in. The default is HTML but it can be set to MIF. |
| -nodepreciated | Causes javadoc to ignore @depreciated paragraphs. |
| -author | Causes javadoc to utilize the @author paragraphs. |
| -noindex | Javadoc will not create an index file. |
| -notree | Javadoc will not create a tree file. |
| -J<flag> | The specified flag will be passed directly to the Java runtime. |
| Tag | Description |
| @see class | Puts a See Also link in the HTML file to the class specified by clss. |
| @see class#method | Puts a See Also link in the HTML file to the method specified by method. |
| @param param descr | Describes method arguments. |
| @version ver | Specifies the version of the program. |
| @author name | Includes the author's name in the HTML file. |
| @return descr | Describes a method's return value. |
| @exception class | Creates a link to the exceptions thrown by the class specified by class. |
The Java debugger is the debugging tool for the Java environment. The debugger
is completely command-line driven. You can use the debugger to debug files located
on your local system, or files that are located on a remote system. For remote Java
files, the jdb must be used with the
-host and -password options described in the table of options. The jdb also consists
of a list of commands that are not covered in this chapter. See Table 4.6 for information
regarding jdb options.
| Options | Description |
| -host hostname | Tells the jdb where the remote Java program resides. hostname is the name of the remote computer (such as well.com or sun.com). |
| -password password | Passes to the jdb the password for the remote Java file, issued by the Java interpreter using the -debug option. |
There is really only one environment variable used by the various tools of the JDK. This is the CLASSPATH variable, and it is essential that it be set correctly. If it is not, the compiler, interpreter, and other JDK tools will not be able to find the .class files they need to complete their tasks.
The CLASSPATH variable points to the directories where all of the classes that are available to import from reside. CLASSPATH lets you put your own class files in various directories, and lets the JDK tools know where they are.
On UNIX machines, the CLASSPATH variable is a colon-separated list of directories in the form:
setenv CLASSPATH .:/users/java/:/usr/local/java/classes/
This command can be put in your .login file so it's set properly every time you log in.
In DOS land, it's a semicolon-separated list of directories in the form:
set CLASSPATH=.;C:\users\dac\classes;C:\tools\java\classes
This line can be put in your AUTOEXEC.BAT file so that the CLASSPATH is set properly every time you boot your machine.
The first period points the CLASSPATH at the current working directory, which is quite helpful if you don't feel like typing in full path names every time you want to do something with the Java program you're working on at a given moment.
The UNIX and Win32 versions of the JDK are quite similar, and most of the commands that work for one work for the other. The Macintosh version of the JDK has some significant differences, however.
Because the Mac doesn't have a command-line interface, the tools for the JDK are slightly different on the Mac than they are on other platforms.
NOTE: The most notable difference is that there are fewer tools that come with the Mac JDK than for other platforms. Hopefully, this will change soon, but until then, Mac users have to make due without some of the most basic tools, such as the Java debugger, javadoc, and the Java disassembler.
The Mac JDK includes four tools:
For the most part, these do the same things as their non-GUI counterparts, but have some interface issues that make them different. Some tools, like the AppletViewer, are quite similar to the versions on other platforms. Other tools, like the Java Runner, are completely different. Here's the basic information on those tools, and where they differ from their cross-platform counterparts.
When opened, the Mac Appletviewer has the standard Mac File and Edit menus. There
is also a status box, which shows the current amount of memory allotted to the Applet-
viewer's Java Virtual Machine, and how much of that memory is taken. That box also
shows progress bars indicating the status of any information being loaded into the
Appletviewer, like .class files or GIF image files.
NOTE: If you are running a Mac that supports drag and drop (Supported in Mac OS 7.1 and above), you can launch applets off of your hard drive by simply dragging the HTML file that contains the <applet> tag onto the little Duke icon of the Appletviewer. Or you can double-click the Appletviewer Duke icon, and use one of the two Open menus to open an applet.
The AppletViewer also has an Edit menu, but this is not enabled as of this writing. Hopefully, it will be enabled soon, at the very least, so you don't have to type in long URLs in the Open URL dialog box.
When an applet is running, an Applet menu also appears. The commands available in that menu are as follows:
The Mac Java Runner is the Mac equivalent of the java command described earlier. Because the Mac has no command line, it has a very rudimentary GUI to set the various options. To make matters slightly worse, that GUI doesn't quite follow the Apple Human Interface Guidelines, which means there's a menu where you wouldn't normally expect it.
You normally launch the Java Runner by double-clicking a .class file that has a main() method. You use the Java compiler to create that .class file, and so it appears on the desktop, or in the folder from which it was launched, as a document icon with Duke in the middle, and 1s and 0s in the upper-left corner of the icon.
Alternatively, you can drag the .class file onto the Java Runner icon, or double-click the Java Runner icon, and select the .class file in the Open File dialog box that appears.
The Java Runner's menus are cleverly hidden as a submenu in the Apple, Java Runtime menu so that they don't interfere with any menus created by the Java application that is running:
The Java compiler has a basic GUI that lets you set the options that are available
as
command-line arguments to the other systems. You can compile files by either dragging
the .java files onto the compiler, or by choosing File, Compile File. Other menu
options are as follows:
CAUTION
As of version 1.02 of the MacJDK, the Close menu item appears to have a bug that will cause a method not found exception when used. Until that bug is fixed, do not use the Close menu item.
JavaH is provided so that you can link native methods into Java code. At this time, it only works for PowerPC-based Macs. It has no menus of its own outside of the standard Java Runner in the Apple menu, such as the all-important Quit command. To use JavaH, you need a third-party compiler such as Metrowerks Codewarrior in order to generate the C code to actually link in with the Java.
