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 that.
Applets are programs, written in Java, that are designed to run imbedded 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:
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.
Table 4.1 Appletviewer Option
| Option | Description |
| -debug | Starts the applet viewer in the Java debugger |
| - jdb | Allowing you to debug the applets in the HTML document. |
The Appletviewer also has an Applet menu in the Appletviewer window that enables you to set a number of different functions of the Appletviewer. Those menu options are as follows:
The Appletviewer's Tag window.
The Appletviewer's Applet Info window.
The Appletviewer's Properties window.
The Java interpreter is what you use to run your compiled Java application.
The syntax for the interpreter is:
where classname only includes the name of the class and not the extension (.class). The Java interpreter options are listed in table 4.2.
Table 4.2 Java Interpreter Options
| Options | Description |
| -help | Display all of the options. |
| -version | Display the version of the JDK that was used to compile the source code. |
| -v (also -verbose) | Display 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, than the new version of source is compiled. |
| -noasyncgc | Turns off asynchronous garbage collection. |
| -verbosegc | Prints out a message each time garbage collection occurs. |
| -verify | Verify all classes that are loaded. |
| -noverify | Turns off class verification. |
| -verifyremote | Verify 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 later debugged with the jdb tool. The interpreter generates a password for you which is used in the jdb's -password option(see “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 setCLASSPATH=.; 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 are printed. The syntax for the Java disassembler is:
Multiple classes can be disassembled. Use a single space to separate each class. The options available for the disassembler are shown in table 4.3.
Table 4.3 javap Options
| 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. |
| -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:
where classname is the name of the Java class file without the .class extension. See table 4.4 for a list of javah options.
Table 4.4 javah Options
| Option | Description |
| -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/or 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.5 and 4.6 for information regarding options and tags.
Table 4.5 javadoc Options
| 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. |
Table 4.6 javadoc Tags
| Tag | Description |
| @see class | Puts a See Also link in the HTML file to the class specified by class. |
| @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 be covered in this chapter. See table 4.7 for information regarding jdb options.
Table 4.7 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. |
Now that we've covered the JDK tools, let's look at the one variable upon which they all depend the CLASSPATH variable.
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.
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 the 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 Appletviewer'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.
The Appletviewer File menu contains the following options:
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 hand 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:
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.
| Previous Chapter | Next Chapter |
| Que Home Page | Digital Bookshelf | Disclaimer |
To order books from QUE, call us at 800-716-0044 or 317-361-5400.
For comments or technical support for our books and software, select Talk to Us.
© 1996, QUE Corporation, an imprint of Macmillan Publishing USA, a Simon and Schuster Company.
