Throughout this book, you've concentrated on building applets for use on Web pages. As you built these applets, you've learned only the very basics about Java's development tools, which include not only the compiler (javac) and the interpreter (java), but also several other useful tools that help you create more powerful applets and applications. Now that you have many hundreds of pages of Java experience behind you, you'll probably want to know more about the tools you've been using (and the tools you haven't been using!). In this chapter, you get a quick look at the Java tools that come with the JDK. Because the compiler and interpreter are the most important tools, they have their own chapters, which follow this chapter.
The JDK comes with several development tools, a couple of which
you must use frequently as you develop and run applets. Others,
you may never use, but it's always good to know they're there
should you need them. Table 33.1 lists the tools and their descriptions.
| Tool | Description |
| appletviewer | This tool enables you to run Java applets without actually loading the applets into a Java-compatible browser. |
| hotjava | This is the original Java-compatible Web browser. |
| java | This is the Java interpreter, which runs applets and applications by reading and interpreting byte-code .CLASS files. |
| javac | This is the Java compiler, which converts your Java source-code to byte-code files that the interpreter can understand. |
| javadoc | This tool creates HTML-format documentation from Java source code files. |
| javah | This tool produces header files for use with native methods. |
| javap | This tool is the Java disassembler, which enables you to convert byte-code files into a program description. |
| jdb | This is the Java debugger. |
The two most important tools in Table 33.1 are the Java compiler, javac, and the Java interpreter, java. Because you will be using these tools a lot, they will be discussed in their own chapters. Specifically, for more information on javac and java, check out Chapter 34, "Using the Compiler," and Chapter 35, "Using the Interpreter."
Outside of what you already know, there's not much to using the Appletviewer application. As you already know, to run an applet with Appletviewer, you type a command line like this:
appletviewer applet.html
The appletviewer portion of the command runs Appletviewer and the command line's parameter, applet.html, is the HTML document that loads the applet you want to view. One interesting thing about Appletviewer is that you can have more than one applet in the HTML file, in which case, Appletviewer loads each of the applets into its own window.
Suppose you've been working on the applets presented in Chapter 25, "Mouse and Keyboard Events," and you want to test KeyApplet, MouseApplet, and MouseApplet2 all at once. No problem! Listing 33.1 is an HTML file that loads and runs these three applets. To run the applets, you would type
appletviewer allapplets.html
at your command-line prompt. When you do, you'll see a screen something like Figure 33.1 as Appletviewer loads and runs the three applets referenced in the HTML document.
Figure 33.1 : Appletviewer can load and run several applets at once.
Listing 33.1 ALLAPPLETS.htmL: An HTML Document That Loads Three Applets.
<title>Applet Test Page</title>
<h1>Applet Test Page</h1>
<applet
code="KeyApplet.class"
width=250
height=150
name="KeyApplet">
</applet>
<applet
code="MouseApplet.class"
width=250
height=150
name="MouseApplet">
</applet>
<applet
code="MouseApplet2.class"
width=250
height=150
name="MouseApplet2">
</applet>
In addition to being able to run several applets at once, Appletviewer can also start a debugging session with an applet. In fact, running the Java debugger, jdb, is the only parameter, besides the name of the HTML document, you can use with Appletviewer. To run an applet with the debugger, you would type a command like this:
appletviewer -debug applet.html
For more information about Java's debugger, refer to the section "Using the Debugger" later in this chapter.
HotJava is a complete Web browser that was written using the Java language. Although it's a good example of how much mileage you can get out of the Java language, it hasn't been kept up to date. In fact, even though HotJava was the first Java-compatible browser, it can no longer load and run most current applets. This is because, as the Java language progressed from its beta versions to the version 1.0 release, the HotJava browser was not kept up to date. As a result, HotJava can load and run only applets that were created using the old version of Java. A set of these applets come with HotJava so that you can check them out. Figure 33.2, for example, shows HotJava running the Hang Duke applet.
Figure 33.2 : HotJava can only run applets that were created with the early beta version of Java.
Although you can still use HotJava to browse the World Wide Web, you're probably better off getting a copy of Netscape Navigator 2.0, which is available for download at http://www.netscape.com. Netscape Navigator 2.0 not only is a much more powerful Web browser, it can also load and run applets created with the latest version of Java. (It cannot, however, load the older applets, which are considered to be obsolete at this point.) Figure 33.3 shows Netscape Navigator 2.0 running the Fractal sample applet.
Figure 33.3 : Currently, Netscape Navigator 2.0 is the Java-compatible Web browser to use.
The javadoc tool won't help you write better Java source code, but it'll sure go a long way towards helping other people use your code, not to mention help you remember six months from now what your code is doing. Basically, javadoc reads through your source-code files and creates HTML files that document your packages and classes, including methods and data fields. You can run javadoc on any old source code, but it works better if you document your code properly as you work.
For example, if you want javadoc to include descriptions of your methods in the HTML files it creates, you need to include a doc-comment block before each method. A doc-comment block begins with the characters /** and ends like a normal C comment. Listing 33.2 is an example of a simple doc-comment block:
Listing 33.2 LST33_2.TXT: A Simple Doc-Comment Block.
/** * Creates the applet's textfield controls and adds * the controls to the applet's display, */
When javadoc sees this comment block beginning with the characters /**, it'll know to include the text of the comment in the method's description.
In order to simplify the documentation process even more, javadoc can understand special symbols called doc tags. Doc tags begin with the @ symbol. After the @ are the words see, version, param, return, exception, or author followed by the text associated with the symbol. The doc tag
@author Jeremy Bender
for example, creates an author entry in the class documentation files, whereas the doc tag
@version 1.0
adds a version entry to the class documentation.
Use the @param tag to decribe a method's parameters, like this:
@param paramName Description
Here, paramName is the parameter's name and Description is the text you want displayed as the parameter's description. The other tags are used like this:
@return Description @exception exceptionName Description
The first line above describes the return value of the method, whereas the second line describes the exception that may be thrown by the method.
One of the most useful doc tags is @see, which enables you to create "See Also" hyperlinks in the HTML documents created by javac. By using @see tags in a method's doc-comment block, for example, you can add a convenient link in the documentation that can jump the user straight to a related method with a single mouse click. If you have complementary methods called GetString() and PutString(), for example, you might have a doc-comment block like the one shown in Listing 33.3.
Listing 33.3 LST33_3.TXT: Creating Hypertext Links in Doc-Comment Blocks.
/** * Retrieves a test string from the user. * * @param userNum The user's ID number * @return The string the user entered * @see #PutString() */
To give you a real-world example of documenting a class with javadoc, you'll now examine an applet from an earlier chapter in this book with doc-comment blocks added. Listing 33.4 shows the newly documented applet. To create the HTML documents for the class, copy the ArcApplet.java file to your CLASSES folder and type javadoc arcapplet.java to start the documentation process. After javadoc finishes, you'll have four new HTML files in your CLASSES folder: ARCAPPLET.htmL (Figure 33.4), ALLNAMES.htmL (Figure 33.5), TREE.htmL (Figure 33.6), and PACKAGES.htmL (which, in this case, contains nothing of value).
Figure 33.4 : This is the ARCAPPLET.htmL file viewed in Netscape Navigator.
Figure 33.5 : This is ALLNAMES.htmL viewed in Netscape Navigator.
Figure 33.6 : This is TREE.htmL viewed in Netscape Navigator.
Listing 33.4 ArcApplet.java: An Applet Prepared for Javadoc.
import java.awt.*;
import java.applet.*;
/**
* ArcApplet demonstrates drawing arcs by enabling the user
* to input the arc's parameters.
*
* @version 1.0, 1/15/96
* @author Clayton Walnum
*/
public class ArcApplet extends Applet
{
TextField textField1, textField2;
/**
* Creates the applet's textfield controls and adds
* the controls to the applet's display.
*
* @return None
*/
public void init()
{
textField1 = new TextField(10);
textField2 = new TextField(10);
add(textField1);
add(textField2);
textField1.setText("0");
textField2.setText("360");
}
/**
* Retrieves the user-defined parameters from the text
* boxes, converts them to integers, and uses them
* to display an arc.
*
* @return None
* @param g The applet's Graphics object
* @see #action
*/
public void paint(Graphics g)
{
String s = textField1.getText();
int start = Integer.parseInt(s);
s = textField2.getText();
int sweep = Integer.parseInt(s);
g.drawArc(35, 50, 125, 180, start, sweep);
}
/**
* Responds when the user presses Enter from one of the
* applet's text boxes. Calls repaint() to force the applet
* to redraw its display with the new parameters.
*
* @return A boolean value indicating whether the
* event was handled.
* @param event The action's event object
* @param arg Event-dependent information
*/
public boolean action(Event event, Object arg)
{
repaint();
return true;
}
}
When you run javadoc, you can specify where your source-code files are located, where the generated HTML files should be stored, and how much information javadoc displays as it runs. The parameters associated with these options are -classpath, -d, and -verbose, respectively. Here's an example of using these options from the command line.
javadoc -classpath c:\classes -d c:\classes -verbose arcapplet.java
The javap tool is Java's disassembler, which is a program that can take a byte-code (.CLASS) file and change it into a description of the original source code. However, if you've ever seen the output from javap, you know that I'm using the word "description" loosely. This is because there's only so much information that a disassembler can determine from a compiled program. The bottom line is that the output of javap doesn't look anything like a Java program, and unless you really understand the internals of the Java language, you won't be able to make heads or tails out of a fully disassembled file.
Still, if you're brave, you can give javap a try, using the following command line:
javap classFile.class
In the above, classFile.class is the name of the byte-code file you want to disassemble. When you use javap without specifying any options, the program displays the public data fields and methods of the class-not too hard to understand. The javap disassembler supports several command-line options that enable you to customize how javap does its disassembly. Those options are -p, which tells javap to display private and protected fields and methods along with the public ones; -c, which tells javap to display the byte-code instructions in the file; and -classpath, which gives the path javap uses to find class files.
Another tool that you probably won't use much is javah, which creates header and stub files for use with native methods. What's a native method? Well, because Java is an interpreted language, it tends to run a little slower than fully compiled languages like C. For this reason, Java's creators decided to enable programmers to write methods in C when they need some extra speed and then call those methods from within a Java program. The process of using native methods, however, is fairly complex, a process that even your humble author hasn't dug too deeply into. Because Java is fast enough for 99% of the applets you'll want to write, you're not likely to have to deal with native methods.
To put it simply, though, javah creates C source-code files that enable the programmer to reference a Java class's data fields from source code written in C. If the previous sentence didn't make sense to you then, believe me, you don't have to worry about javah at all. If you're interested in this stuff, however, you can find information on creating native methods in your Java online documentation. There was also a pretty decent tutorial at http://java.sun.com/tutorial/index.html on the World Wide Web at the time of this writing. If it's still there, you should check it out.
To give you a quick overview, though, you run javah against the class files created by the Java compiler. The javah command line looks like this:
javah className
As is the case with many of Java's tools, javah can accept a number
of command-line options. When you specify these options in the
command line, you place them before the class name. Table 33.2
lists the options and their descriptions.
| Option | Description |
| -classpath path | Sets the path for finding classes. |
| -d directory | Sets the directory where the output files will be stored. |
| -o outputfile | Places all the output into the file specified by outputfile. |
| -stubs | Tells javah to generate C declarations from the input file. |
| -td directory | Sets the directory where temporary files will be stored. |
| -verbose | Tells javah to display status information as it works. |
As I write this, the Java debugger, jdb, is still not complete. Good documentation on how to use the debugger is nonexistent, with only a very brief description of the debugger available online at Sun. Still, the dubugger does run, and-who knows?-by the time you read this, it may be fully functional.
To use the debugger, you run your Java program with the debugger rather than the interpreter. For example, if you were debugging this book's FaceApp application, you'd use a command line like this to start the application with the debugger:
jdb FaceApp
At this point, the debugger is running, and it has loaded the FaceApp application into memory. However, FaceApp is not yet running. Instead, the debugger is waiting for its first command, which you enter at the command prompt (Figure 33.7).
Figure 33.7 : After you load a program into the debugger, it waits for a command.
To see the list of commands supported by the debugger (not all of which work yet), type help at the command prompt. Another command you're likely to use a lot is stop at, which sets a breakpoint at a specific line in a class. A breakpoint is a place where you want program execution to stop and wait for another command. For example, if you've loaded the FaceApp application into the debugger as described previously, you can now type the following command to set a breakpoint at the first line of executable code (the "4" is the line number):
stop at FaceApp:4
As you can see, the stop at command requires the class name and line number at which to stop, separated by a colon. When you enter the above command, jdb lets you know that the breakpoint was set okay (Figure 33.8).
Figure 33.8 : Setting breakpoints is something you do a lot with a debugger.
Now, that you have a breakpoint set, when you tell the program to execute, it'll run until it hits the breakpoint, at which time the debugger suspends program execution and waits for another command. To set this string of events into motion, type run at the debugger's command prompt. When you do, the debugger informs you that it's running FaceApp, right after which it informs you that it has hit a breakpoint. The debugger shows the location of the breakpoint and waits for another command (Figure 33.9).
Figure 33.9 : When the debugger hits a breakpoint, it stops and waits for your next command.
At this point, you'd probably want to do something called single-stepping through the program, which means telling the debugger to execute the next line of code and stop. In this way, you can trace through a program line-by-line in order to figure out where problems might be. Unfortunately, the debugger's step command is not yet functional, so you'll have to wait until the debugger's complete to try out single-stepping.
If you want to try something else with the debugger, type memory and press Enter. Now, the debugger tells you how much memory remains, as well as how much total memory there is in your system. If you type threads, the debugger lists all the Java threads in this system. Currently, there's only the main FaceApp thread, and, because you set a breakpoint, that thread is currently suspended. Typing threadgroups, on the other hand, gives you a list of all thread groups in the system. At this point, those groups would be system, main, and FaceApp.
If you want to see the methods for any class that's loaded, you can type methods followed by the class's name. To get the FaceApp application running again, type cont. To stop the debugger and get back to your regular operating system prompt, you can type exit or quit.
| CAUTION |
As I tested the debugger for this chapter, my system kept locking up, and I wasn't always able to get the results I expected. If you decide to experiment with the debugger, make sure you don't have anything else running. Be especially sure that you don't have documents that need to be saved, because the debug-ger's unpredictability is liable to cost you any work you've done on those documents. Hopefully, though, by the time you read this chapter, the debugger will be in full working order. |
The most important Java tools are javac (the compiler) and java (the interpreter). However, there are several other tools you can use when developing applets and applications with Java. Some of these tools, like Appletviewer and javadoc, are handy utilities that make writing Java programs easier. Others, like javah and javap, are used in only special circumstances. In fact, it's likely that you'll never need to use these tools. Because javac and java are the most important Java tools, they are covered in their own chapters, which immediately follow this one.