Chapter 5

Java Tools and the JDK: A Primer

CONTENTS

• Tools in the Java Developer's Kit
• Command-line Tools in the JDK
  • The Java Compiler and Associated Environment Tools
  • The Java Interpreter
  • The Java Applet Viewer
• Graphical Developer's Tools
  • Macintosh Developer's Tools
  • Java WorkShop
• Summary

Programming in any language is easier if you have the proper tools. The Java Developer's Kit includes a complete toolkit for Java development. Beyond the JDK tools are tools featuring graphical interfaces. The more you understand about the tools used for Java development, the better prepared you will be to take advantage of everything the Java programming language has to offer. This chapter discusses the essential tools for creating, developing, and debugging Java programs with a focus on how to get the most out of them.

Tools in the Java Developer's Kit

A thorough understanding of the tools in the Java Developer's Kit is essential for your success in Java programming. Previous chapters discuss the basics of using some of these tools, but the focus in those early chapters is on how to use the tools and not on the features of the tools. As you will see in this chapter, each tool has unique features that are designed to help you do the following:

• Get more out of the Java programming language
• Troubleshoot problems in your programs
• Change environment defaults
• Optimize Java for your development or target system

Most versions of the JDK include seven tools for Java development:

• Java compiler
• Java API documentation generator
• Java header and stub file generator
• Java interpreter
• Java applet viewer
• Java class file disassembler
• Java debugger

As you saw in Chapter 2, "Getting Started with the JDK," the JDK is available for most operating systems. For Windows 95/NT, OS/2, and UNIX platforms, the developer's tools in JDK version 1.0 have a command-line interface. For Macintosh (and soon for other platforms as well), the developer's tools in JDK version 1.0 feature a graphical user interface. Graphical development environments for UNIX and Windows-based platforms are also available. Because you will get more out of this chapter if I break down the discussion according to the interface the tools use, it features two main sections. The first section is on command-line tools, and the second section is on graphical tools.

Command-line Tools in the JDK

For Windows 95/NT, OS/2, and UNIX platforms, the tools in the Java Developer's Kit version 1.0 execute from the command line. Although SunSoft and many third-party vendors have produced graphical developer's environments for Java, current programmers and system administrators may prefer the simplicity of the original command-line tools.

The advantage of using tools that do not have a graphical user interface is that they are streamlined, are generally more versatile, and use minimal system resources. Command-line tools also let you perform complex assignments and handle tasks with parameters easily.

The Java Compiler and Associated Environment Tools

Most discussions on compiling Java programs relate to the Java compiler, but there is a set of related tools you might want to use at compile time. These related tools include the Java compiler, the Java API documentation generator, and the Java header and stub file generator.

javac

When you compile Java programs, you use the Java compiler. The JDK includes two versions of the Java compiler. The first version, javac, is optimized for normal use and has only limited debugging capabilities. The second version, javac_g, is optimized for debugging and is intended for use with the Java debugger.

You run the Java compiler from the command line and pass it the full name of your Java source file. The Java compiler expects the source code to be in a file named with the .java extension. Additionally, when the source file contains multiple class declarations, the source file must be named after the primary class declaration. Therefore, it is best to always name your source files after the primary class declaration.

For each class declaration in the source file, the Java compiler creates a class file with a .class extension. Because the compiler is case sensitive, the first part of the class file will be named exactly as you typed it in the source file. By default, the class files are placed in the same directory as the source file. You can override this default with the -d option. The -d option of the Java compiler lets you specify the destination directory for your class files.

On UNIX platforms, you can specify a default destination directory as follows:

javac -d $HOME/jb_apps/myclasses QuizMaker.java

On Windows 95/NT and OS/2 platforms, you can specify a default destination directory as follows:

javac -d C:\jb_apps\myclasses QuizMaker.java

If the application you are compiling references any classes that are not stored in the current directory, you should either set the CLASSPATH environment variable or use the -classpath option. The -classpath option lets you specify a path for your class files that overrides the default or current CLASSPATH setting. Because this option takes precedence, you should set it to include the current directory, the location of your personal or third-party class files, and the location of the Java API classes.

On UNIX platforms, you can specify a path for class files as follows:

javac -classpath .:/usr/jb_apps/vendorclasses:java/classes:
Âjava/lib/classes.zip QuizMaker.java

On Windows 95/NT and OS/2 platforms, you can specify a path for class files as follows:

javac -classpath .;C:\jb_apps;C:\java\classes;
ÂC:\java\lib\classes.zip QuizMaker.java

You can generate debugging tables with the -g option. Debugging tables contain information about the program organized by line numbers. A similar and more useful option is the -debug option. This option generates a full trace of compiler activity that primarily relates to methods and declarations. If you change to the directory containing the source for the FirstApp program discussed in Chapter 4, "The Java Language: A Primer," and type the following,

javac -debug FirstApp.java

you will see output similar to this:

public static void main(java.lang.String[]);
{
    (method (System#0.out) println "My first stand-alone application
Âis a success.");
}
[check field FirstApp.main]
{
    (method (System#0.out) println "My first stand-alone application
Âis a success.");
}
{
    (method (java.lang.System.out) println "My first stand-alone application
Âis a success.");
}
[check field FirstApp.<init>]

{
}
{
    (method super <init>);
    {
    }
}
[inline field FirstApp.main]
[inlined field FirstApp.main]
(method (<empty>.out) println "My first stand-alone application
Âis a success.");
[code field FirstApp.main]
[inline field FirstApp.<init>]
[inlined field FirstApp.<init>]
(method super <init>);
[code field FirstApp.<init>]

As you can see, the -debug option generates an awful lot of output even for small programs. The output is useful, however, to get a line-by-line picture of what the compiler is doing with methods and declarations.

Although the -g and the -debug options come in handy for advanced programs, you will find that for basic- to intermediate-level programs you really will not need to use them. Another option you might not need unless you are developing advanced programs is the -nowarn option. If you use this option, the compiler does not print out warnings. (Because warnings are not actual errors, you might sometimes want to stop the compiler's incessant displaying of them.) Typically, though, you will not see warnings anyway with basic- to intermediate-level programs.

One of the most useful command-line arguments for the compiler is the -O option. With this option, you can optimize your source code so that it runs faster and uses fewer system resources. The compiler optimizes your code by creating inline references to static, final, and private methods.

Anytime when speed and system resources are a consideration, I highly recommend optimizing your code. However, there is a trade-off to be made between the compiled size of your program and the optimization of your program, which again primarily comes into play for advanced programs. Because optimized code contains inline references, it is sometimes-but not always-larger than non-optimized code. The Java compiler also takes longer to finish the compilation when you optimize the code.

Another useful compiler option is -verbose. With this option, you can turn on verbose messaging and see everything the compiler and linker are doing. Not only will verbose messaging tell you what source files are being read, but you can also see

• How long it took to parse each source file
• When and from where the compiler is loading each class
• When classes are being checked
• When the class file is being written to
• How long it took to complete the compilation

Because the -verbose option tells you what the compiler is doing to class and source files, you can use it in conjunction with the -debug option to get a complete picture of everything the compiler is doing. If you change to the directory containing the source for the FirstApplet program discussed in the previous chapter and type the following,

javac -verbose FirstApplet.java

you will see output similar to this:

[parsed FirstApplet.java in 500ms]
[loaded C:\JAVA\LIB\CLASSES.ZIP(java/applet/Applet.class) in 110ms]
[checking class FirstApplet]
[loaded C:\JAVA\LIB\CLASSES.ZIP(java/awt/Panel.class) in 0ms]
[loaded C:\JAVA\LIB\CLASSES.ZIP(java/awt/Container.class) in 110ms]
[loaded C:\JAVA\LIB\CLASSES.ZIP(java/awt/Component.class) in 160ms]
[loaded C:\JAVA\LIB\CLASSES.ZIP(java/lang/Object.class) in 0ms]
[loaded C:\JAVA\LIB\CLASSES.ZIP(java/awt/image/ImageObserver.class) in 0ms]
[loaded C:\JAVA\LIB\CLASSES.ZIP(java/awt/Image.class) in 60ms]
[loaded C:\JAVA\LIB\CLASSES.ZIP(java/awt/Graphics.class) in 60ms]
[wrote FirstApplet.class]
[done in 2030ms]

You can pass multiple parameters to the compiler, but you must precede each option with a hyphen. If you wanted to optimize the code and use the -verbose option, you would type the following:

javac -O -verbose QuizMaker.java

The command-line syntax for the compiler is

javac [options] filename.java

The compiler takes these options:

javah

The Java C Header and Stub File Generator is an extremely useful environment tool. You will use it when you need to implement native methods. C header and stub files are necessary for Java and C programs to interact. As C programmers know, header and stub files are used by C programs to reference an object's instance variables. If you plan to interface your Java program to C or C++, you should generate header and stub files after compiling the Java source code.

The JDK includes two versions of this tool. The first version, javah, is optimized for normal use and has only limited debugging capabilities. The second version, javah_g, is optimized for debugging and is intended for use with the Java debugger.

You run the Java C Header and Stub File Generator from the command line and pass it the name of your Java class file without the .class extension. By default, javah creates a header file with the .h extension for each class name you pass to it and stores the file in the current directory. Header files are named with the class name and the .h extension. You can override this default with the -o option.

The -o option lets you specify a single output file for all generated source information. This is useful when you have Java programs that contain multiple class files and you want to store the associated header and stub information in one file. As javah stores the output in the exact file you name, you should always specify the .h extension in the destination filename. The following example creates a header file called concat.h for a Java program that has four classes associated with it:

javah -o concat.h RGBcanvas RGBcontrols HexInt RGB2Hex

Generated header files contain C struct definitions, define all the variables you might need, and create a handle for passing values back and forth between C and Java. The layout of the header file approximates the layout of the original class file with fields that correspond to instance variables. For every class you use in the Java program, there will be a struct definition with the package name prepended to the class name. Java replaces file path separators with the underscore character. Here are some examples:

struct Hjava_awt_peer_ComponentPeer;

struct Hjava_awt_Container;

struct Hjava_awt_Color;

Whereas header files are generated automatically, you must use the -stubs option to create a stub file with C declarations. Stub files are named with the class name and the .c extension-in the C programming language source files named with this extension. You can use this option as follows:

javah -stubs RGB2Hex

During the generation of header and stub files, javah builds temporary files. These files are generally stored in the \tmp directory on UNIX systems and on the C:\temp directory on Windows-based systems. If you are compiling all classes associated with an advanced application, these files can grow to be quite large. You can override the default directory with the -td option, which lets you specify the location of the temporary directory. Specifying a new location for the temporary directory is often useful, especially if your primary disk or the root partition doesn't have a lot of free space.

On UNIX platforms, you can set the location of the temporary directory as follows:

javah -td \usr\temp RGB2Hex

On Windows 95/NT and OS/2 platforms, you can set the location of the temporary directory as follows:

javah -td C:\windows\temp RGB2Hex

Other options you can use include the -v option and the -classpath option. The -v option turns on verbose messaging, which lets you see what classes and temporary directory javah is using. The -classpath option lets you override the default and current CLASSPATH setting. If the program for which you are creating header and stub files makes use of any classes that are not stored in the current directory, you should either set the CLASSPATH environment variable or use the -classpath option.

The command-line syntax for the header and stub file generator is

javah [options] classname

or

javah [options] classname1 classname2 classname3 …

The header and stub file generator takes these options:

javadoc

The Java API Documentation Generator, as the name implies, is used to generate documentation from source files. Because the documentation is in the form of HTML documents, you can view it online with any HTML browser. The great thing about HTML documentation is that all object names are linked together. As a programmer, you will appreciate how thorough the documentation this tool creates is, especially if you are tired of having to write your own documentation. In fact, Sun used this tool to create the documentation files for the API.

You run the API Documentation Generator from the command line and pass it the full name of your Java source file. Here's an example:

javadoc FirstApplet.java

The API Documentation Generator expects the source code to be in a file named with the .java extension. You can also pass javadoc the name of a package and it will generate documentation for the entire package.

The only options you can use with the documentation generator are -classpath, -d, and -verbose. If the program for which you are creating documentation makes use of any classes that are not stored in the current directory, you should either set the CLASSPATH environment variable or use the
-classpath option. The -d option lets you specify the destination directory for the HTML documentation. The -verbose option turns on verbose messaging and lets you see what classes and source files the compiler and linker are using.

The command-line syntax for the header and stub file generator is

javadoc [options] sourcefile.java

or

javadoc [options] packagename

The documentation generator takes these options:

Using javadoc

The documentation generator parses declarations and document-style comments in Java source files and formats this into a set of HTML documents. For a source file containing class declarations, javadoc creates one documentation file for each class declaration. The name of the file is the class name plus the .html extension. These class documents contain a complete breakdown of the class. Three additional documentation files are always created as well:

• packages.html-Documentation file used for packages; is generally empty if you created documentation for a source file with class declarations.
• AllNames.html-Index file of all fields and methods used in the source file.
• tree.html-Documentation file that shows the class hierarchy used in the source file.

If you create documentation for packages, the packages.html file will contain an entry for each package. These entries will be linked to an appropriately named package file, such as Package-PackageName.html.

To better understand what javadoc does and how it does it, let's create documentation for the FirstApplet program. The first thing you will notice when you create documentation with javadoc is that it expects you to have the Java API documentation in HTML format installed on your system. It also expects you to have the source file in the base directory for the API documentation. Primarily, this is because of the way javadoc links object names back to the API documentation and because the documentation uses images from the API documentation.

To get around this problem, you could move your source file to the directory containing the API documentation and then run javadoc. However, by doing so you will overwrite the packages.html file that already exists in this directory. Also, if you generated any previous documentation with javadoc, you would overwrite the existing AllNames.html and tree.html files.

Avoiding Problems with the Documentation Generator

To avoid overwriting existing documentation and to be able to use the documentation with the API documentation, you might want to do the following:

1. Make a new directory.
2. Move the source file to the new directory.
3. Run javadoc in this directory on the source file.
4. If you are not creating documentation for a package, remove the packages.html file.
5. Using a text editor, edit the tree.html file. Prepend the name of your class for all references to the file AllNames.html. You could do this by searching on the keyword AllNames.html and replacing it with the appropriate name. There is generally only one reference you have to update.
6. Using a text editor, edit the AllNames.html file. Prepend the name of your class for all references to the file tree.html. You could do this by searching on the keyword tree.html and replacing it with the appropriate name. There is generally only one reference you have to update.
7. Move all remaining files to the directory containing the API documentation.

You can now use the documentation for your class with the API documentation and don't have to worry about it being overwritten the next time you create documentation.

To avoid overwriting existing documentation and to keep your documentation separate from the API documentation, you might want to do the following:

1. Make a directory for your documentation.
2. Change to your documentation directory and make a subdirectory called images.
3. Copy the contents of the images directory from the Java API documentation to the images directory you just made.

Then, each time you want to create documentation for a new class, you can do the following to update your personal documentation:

1. Move the source to a temporary directory.
2. Run javadoc in this directory on the source file.
3. If you are not creating documentation for a package, remove the packages.html file.
4. Using a text editor, edit the tree.html file. Prepend the name of your class for all references to the file AllNames.html. You could do this by searching on the keyword AllNames.html and replacing it with the appropriate name. There is generally only one reference you have to update.
5. Using a text editor, edit the AllNames.html file. Prepend the name of your class for all references to the file tree.html. You could do this by searching on the keyword tree.html and replacing it with the appropriate name. There is generally only one reference you have to update.
6. Move all remaining files to your documentation directory.

You can now use the documentation for your class and don't have to worry about it being overwritten the next time you create documentation.

Generating Documentation for FirstApplet

You can create documentation for the FirstApplet program following the steps listed in the pre-vious section. Figure 5.1 shows what the resulting AllNames.html file should look like. Each of the underlined phrases is a hypertext link to key information within the document and to other documents.

Figure 5.1 : An automatically generated index for FirstApplet.

The documentation generator puts a useful header on the document that allows you to quickly locate fields and methods alphabetically. Each of the entries in the main section of the document also contains hypertext links that let you quickly and easily navigate through lengthy documentation. You can access the tree.html file by clicking on the link titled "Class Hierarchy."

A partial view of the tree.html file is shown in Figure 5.2. This file contains a listing of every class used by the FirstApplet program. All class references are linked back to the Java API documentation.

Figure 5.2 : An automatically generated class hierarchy for FirstApplet.

The most useful file in the documentation is the class file. For this example, the class file is named FirstApplet.html. The first section of this file is shown in Figure 5.3. From the class diagram shown at the top of the figure, you can see exactly where the FirstApplet class fits into the class hierarchy. As you can see, the FirstApplet class extends the Applet class, which in turn is an extension of other classes.

Figure 5.3 : An automatically generated overview of FirstApplet.

As shown in Figure 5.4, the next section of the document breaks the FirstApplet class into constructors and methods. Because this documentation is primarily for more advanced programs than this one, there is a constructor index and a method index that contain hypertext links to each constructor and method used in the program.

Figure 5.4 : Methods and constructors are broken down clearly in the documentation.

In the constructor section, each class is broken down by its class declaration. In the method section, each method is broken down by its method declaration and shows the relationship of your method to the methods in the API. Because the init() method of the FirstApplet class overrides the init() method of the Applet class, the FirstApplet class documentation contains the following definition for this method:

 public void init()

     Overrides:
          init in class Applet

Enhancing the Documentation

You can enhance the documentation that javadoc creates using document-style comments. The most basic form of document-style comments allows you to add descriptions to the classes, methods, and variable declarations you use in your programs. You should always add comments just before the section or declaration to which the comments pertain. The documentation generator uses these comments to add a description to your classes, methods, and variables.

See Chapter 6, "Fundamentals of the Java Language," for a complete discussion about using comments in Java.

Add the following document-style comment to the FirstApplet program just before the class declaration:

/**
 * Peter Norton's Guide to Java Programming
 * The FirstApplet program creates a basic
 * applet with multimedia features.
 */

The documentation generator will include the description in the first section of the FirstApplet.html file. To support more advanced control over documentation, javadoc also lets you place markup instructions within the comments. There are two ways you can do this.

The first way is with HTML markup. To be useful, HTML markup should not interfere with tags and formatting that javadoc generates automatically. This means you should not use header tags, horizontal rules, or tags that denote head or body sections. One way to use HTML is to show code examples:

/**
 * The getImage() method is used to add an image to an applet
 * <PRE> NewImage = getImage(getCodeBase(),"New.gif"); </PRE>
*/

The documentation generator also supports a special set of documenting tags that are defined with the at symbol (@) and are always defined within document-style comments. With these tags, you can add many types of inline references including links to other documents, author entries, and version control. To use these tags, you specify the name of the tag followed by the reference text, like this:

/**
 * Peter Norton's Guide to Java Programming
 * The FirstApplet program creates a basic
 * applet with multimedia features.
 * @version     1.5 March 15, 1996
 */

When the documentation sees the version tag, it adds a version entry in the HTML document for the associated class. The entry would appear as follows:

Version:
     1.5 March 15, 1996

The six special tags that javadoc supports, as well as their corresponding entries in the documentation, are shown in Table 5.1. Your doc tags must be placed at the beginning of a line. Although you can use multiple tags of the same type within a document, you should keep tags of the same type together. For example, if there are multiple authors of the program, your entry should look something like this:

/**
 * Peter Norton's Guide to Java Programming
 * The FirstApplet program creates a basic
 * applet with multimedia features.
 * @author      Peter Norton
 * @author      William Stanek
 * @version     1.5 March 15, 1996
 */

The Java Interpreter

The Java interpreter executes Java bytecode files. You will use the interpreter to run Java applications. Before the interpreter runs any program, it verifies that the classes associated with the program are valid and do not violate any language constraints.

The JDK includes two versions of the interpreter. The first version, java, is optimized for normal use and has only limited debugging capabilities. The second version, java_g, is optimized for debugging and is intended for use with the Java debugger.

You run the interpreter from the command line and pass it the name of your Java class file without the .class extension. For applications that include many classes, you will want to pass the interpreter the name of the class that declares the application's main() method. The interpreter executes the main() method and any threads specified in the main() method. If no threads are created by the main() method, the interpreter executes the main() method and then exits. If threads are created by the main() method, the interpreter exits when the last thread exits.

Because the interpreter expects the class file to contain a main() method, you generally cannot use the interpreter to run Java applets. If you want to run Java applets, you should use the Java applet viewer discussed in the next section of this chapter. The interpreter uses the following syntax:

java [options] classname [args]

Like other tools in the JDK, the Java interpreter accepts many options. Unlike other tools in the JDK, the interpreter also allows you to pass arguments to the class's main() method. You do this by putting the values for the arguments after the class name.

The -classpath option lets you specify a path for your class files that overrides the default or current CLASSPATH setting. Because this option takes precedence, you should set it to include the current directory, the location of your personal or third-party class files, and the location of the Java API classes.

On UNIX platforms, you can specify a path for class files as follows:

java -classpath .:\usr\jb_apps\vendorclasses:java\classes:
Âjava\lib\classes.zip QuizMaker

On Windows 95/NT and OS/2 platforms, you can specify a path for class files as follows:

java -classpath .;C:\jb_apps\vendor;C:\java\classes;
ÂC:\java\lib\classes.zip QuizMaker

An option of the interpreter that is sure to be a quick favorite in large development environments is -checksource. This option instructs the interpreter to make sure the compiled classes are current and to recompile the source files if they are not. The interpreter does this by comparing the modification date on the source files to the modification date on the class files. If any source file has a more recent date, that source file is recompiled before the interpreter uses the associated class. You can instruct the interpreter to check the source using either -checksource or -cs, like this:

java -cs FirstApp

Another useful option is -debug, which lets you attach the Java debugger tool to an interpreter session. When you use this option, the interpreter displays a password that must be used when starting the debugging session. The password is randomly allocated by session.

To track interpreter activity, you will want to use the -verbose or -v option. With this option, you can turn on verbose messaging and see what class files the interpreter is using. The classes the interpreter loads at runtime are very different from the classes used when the source is compiled. If you change to the directory containing the source for the FirstApp program discussed in Chapter 4 and type the following:

java -verbose FirstApp

You will see output similar to the following:

[Loaded java/lang/Cloneable.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/lang/ThreadGroup.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/lang/System.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/io/BufferedInputStream.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/lang/Thread.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/lang/Object.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/lang/Class.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/lang/String.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/lang/ThreadDeath.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/lang/Error.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/lang/Throwable.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/lang/Exception.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/lang/RuntimeException.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/lang/Cloneable.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/lang/ThreadGroup.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/lang/System.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/io/BufferedInputStream.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/io/FilterInputStream.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/io/InputStream.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/io/FileInputStream.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/io/FileDescriptor.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/io/PrintStream.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/io/FilterOutputStream.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/io/OutputStream.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/io/BufferedOutputStream.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/io/FileOutputStream.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/lang/StringBuffer.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/lang/Integer.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/lang/Number.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/lang/NoClassDefFoundError.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/lang/LinkageError.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/lang/OutOfMemoryError.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/lang/VirtualMachineError.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded .\FirstApp.class]
[Loaded java/lang/Compiler.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/util/Properties.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/util/Hashtable.class from C:\JAVA\LIB\CLASSES.ZIP]
[Loaded java/util/Dictionary.class from C:\JAVA\LIB\CLASSES.ZIP]

[Loaded java/util/HashtableEntry.class from C:\JAVA\LIB\CLASSES.ZIP]

Another way to track interpreter activity is with the -t option. This option traces every instruction the Java virtual machine executes and is used only with the debugging version of the interpreter, java_g. Although this option is useful for advanced debugging, the listing is too lengthy for any other use. The instruction list for the five-line FirstApp program filled 175 pages.

If you want to check where your program is spending the most time during execution, you can use the -prof option. This option of the interpreter effectively replaced the profiler tool that was included in the Alpha release of the Java programming language. Using the -prof option, you can pinpoint areas of the code that are eating up more system time than they should. Often, you can rework the related section of code and improve the performance of the program.

When you run the interpreter with the -prof option, it dumps the profile information to a file called java.prof in the current directory. If you use the profile option on the FirstApp program, you will generate a file that fills three printed pages. Profiling information is broken down into sections. Each section is preceded by a comment statement that tells you the order of columns in the output. You can profile the FirstApp program using the following command:

java -prof FirstApp

The example that follows has two sections of profile information. The first section shows you the system count, the object called, the calling object, and the system time. The second section shows you how many handles were used, the number of free handles, the amount of heap used, and the amount of heap free. Here's the example:

# count callee caller time
4 java/lang/System.arraycopy(Ljava/lang/Object;ILjava/lang/Object;II)V
Âjava/lang/String.getChars(II[CI)V 0
39 java/lang/System.arraycopy(Ljava/lang/Object;ILjava/lang/Object;II)V
Âjava/lang/String.<init>([C)V 0
1 java/lang/Thread.getThreadGroup()Ljava/lang/ThreadGroup; java/lang/
ÂThreadGroup.<init>(Ljava/lang/String;)V 0
1 java/lang/String.valueOf(I)Ljava/lang/String; java/lang/StringBuffer.
Âappend(I)Ljava/lang/StringBuffer; 10

# handles-used, handles-free heap-used heap-free

124 78518 5232 2511344

The interpreter includes a set of options for optimizing the runtime environment. Each program running on the Java runtime environment has a memory allocation pool assigned to it. The memory allocation pool is also referred to as the garbage-collected heap or simply the heap.

The -mx option lets you specify the maximum number of bytes to be allocated to the heap. All values you specify for the heap must be greater than 1,000 bytes and can be allocated in kilobytes or megabytes. By default, the interpreter sets this value to 16MB.

To set the maximum heap size in kilobytes, follow the value by k, with no intervening space, like this:

java -mx 900k FirstApp

To set the maximum heap size in megabytes, follow the value by m, with no intervening space, like this:

java -mx 1m FirstApp

You can set the startup size of the heap using the -ms option. All values you specify must be greater than 1,000 bytes and can be allocated in kilobytes or megabytes. By default, the interpreter sets this value to 1MB.

Java is a multithreaded programming environment. Each thread running on the Java runtime environment has two stacks associated with it. The first stack is used for Java code, and the second stack is used for C code. Memory used by these stacks draws from the total system memory pool. Whenever a new thread starts execution, it is assigned a maximum stack size for Java code and for C code.

The default maximum stack size for Java code is 400KB. You can override this default with the -oss option. All values you specify must be greater than 1,000 bytes and can be allocated in kilobytes or megabytes, such as

java -oss 100k FirstApp

The default maximum stack size for C code is 128KB. You can override this default with the -ss option. All values you specify must be greater than 1,000 bytes and can be allocated in kilobytes or megabytes, such as

java -ss 100k FirstApp

The interpreter provides you with control over garbage collection. Normally, garbage collection is performed automatically as a background thread, and the runtime environment goes about its business without telling anyone what it is doing. You can override this in two ways. You can either set the verbose flag for garbage collection using the -verbosegc option, which tells the runtime environment to print out messages whenever it frees memory, or you can turn off background garbage collection using -noasyncgc, the no asynchronous garbage-collection flag.

When you set the -noasyncgc option, no garbage collection takes place unless the program runs out of memory or explicitly tells the system to perform garbage collection. If it seems like a bad thing to let the program run out of memory before freeing memory, that's because it usually is. Garbage collection is a powerful feature of Java, and you should turn it off only in an extremely limited set of circumstances.

Before executing any program loaded over the network, the interpreter checks the validity of the class files. Part of the validation process is to ensure that the class file does not violate system security. This default option is called -verifyremote. The interpreter allows you to make verification more strict with the -verify option and to turn off verification completely with the -noverify option. Whereas the -verify option causes the interpreter to check the validity of all classes prior to execution, the -noverify option goes to the other extreme and tells the interpreter to never validate classes.

To override property values set in any program, you can use the -D option. This option redefines a named property value to a value you set. You can use the -D option to change the background color of text, windows, or buttons. The syntax for this option is

java -DpropertyName=newValue classname

The command-line syntax for the interpreter is

java [options] classname [args]

The interpreter takes the following options:

The Java Applet Viewer

The Java applet viewer enables you to view applets without a Web browser. Because applets extend the Applet class and are made for viewing in Web documents, you must create an HTML document with the appropriate markup before you can use the applet viewer. After you have created such a document, you can use the applet viewer to view your applets.

You run the applet viewer from the command line by passing it the name or path to an HTML document that references one or more applets, such as

appletviewer example.html

Before displaying any applets, the applet viewer verifies that the HTML document contains an <APPLET> tag with three specific attributes: CODE, WIDTH, and HEIGHT. The CODE attribute tells the viewer what class file to load. The WIDTH and HEIGHT attributes tell the viewer what the size of the applet's canvas should be. The viewer also looks for the optional <PARAM> tag that sets input parameters for your applets. (See Chapter 15, "Creating Java-Powered Web Presentations with Applets," for a complete discussion on creating Java-enhanced HTML documents.)

The applet viewer does not make use of any other HTML tags within the document. This means your HTML document will not look the same as it would when viewed with a Java-capable Web browser. For each defined <APPLET> tag in the document, the applet viewer starts up a separate window, the height and width of which are determined by the attributes you set. This means that if you add three applets to a document, the applet viewer will place the applets in three separate windows. If you want to see how it looks to have three applets running in separate windows, view the Web presentation you create in Chapter 15 with the applet viewer.

The only option the applet viewer takes from the command line is the -debug option, which starts a debugging session with the Java debugger. With this option, you can debug your applets. (See Chapter 23 for more information on the Java debugger.)

The command-line syntax for the applet viewer is

appletviewer [option] document.html

The applet viewer takes the following option:

Additional Options Available While Running the Applet Viewer

When you are running an applet, an additional menu called Applets is available from the menu bar. After editing the HTML document associated with an applet, you can reload the document and the applet by selecting Reload from the Applets menu. Another useful option of the viewer is Clone. If you select Clone from the Applets menu, you can make a new copy of the applet window and restart the associated applet. This is useful if you are testing the behavior of the applet. Instead of reloading all the files associated with an applet or cloning an applet, you might want to restart the applet. To do that, you can select Restart from the Applets menu.

Two other options available from the menu can provide you information about an applet. The Tag option displays the <APPLET> tag associated with the currently running applet. The Info option shows additional information about the applet. Finally, the Close option closes the applet viewer window, and the Quit option exits the applet viewer.

When an applet is running in the applet viewer, these options are available from the viewer's menu:

Applet Viewer Security Mechanisms

The applet viewer loads local and remote applets using two different mechanisms. Applets that exist on the local file system and in a directory defined in the CLASSPATH environment variable are loaded by the file system loader. Applets downloaded from the network or that are not in a directory defined in the CLASSPATH environment variable are loaded by the applet class loader.

Applets loaded by the applet class loader are subject to the restrictions of the applet security manager. The security manager adds an additional layer of security controls to untrusted applets, which ensures the integrity of the client machine is not compromised when accessing remote information. These security controls place restrictions on what untrusted applets can and cannot do on the client system.

Specifically, untrusted applets cannot

• Read or write files
• Make directories
• List files in a directory
• Check file type, size, or modification date
• Start another program on the client
• Access other clients or IP addresses
• Access native code or libraries

Although applets loaded by the file system loader are trusted, the applet viewer still maintains security controls over them. These security controls can be relaxed by setting property values. You set property values in the file called, appropriately, properties. This file is located in the .hotjava directory under the Java installation directory and can be edited with a plain text editor.

Allowing Applets to Read Files and Directories

You can allow local applets to read files and directories by adding them to the access control list. To do this, set the property value acl.read equal to the files or directories you want applets to be able to read.

Reading Files on UNIX Systems

On a UNIX system, if you want applets to read a file called numbers.txt in the $HOME\java directory, edit the properties file and insert the following line:

acl.read=$HOME\java\numbers.txt

If you want applets to be able to access all the files in the $HOME\java directory, you can do this by setting the value for acl.read to

acl.read=$HOME\java

If you want applets to be able to read multiple directories or files, separate each entry by colons, like this:

acl.read=\java\applets\docs:\usr\images\gifs:\usr\temp

Reading Files on Windows and OS/2 Systems

On a Windows or OS/2 system, if you want applets to read a file called numbers.txt in the C:\java directory, edit the properties file and insert the following line:

acl.read=C:\java\numbers.txt

If you want applets to be able to access all the files in the C:\java directory, you can do this by setting the value for acl.read to

acl.read=C:\java

If you want applets to be able to read multiple directories or files, separate each entry by semicolons, like this:

acl.read=C:\java;C:\java\applets\docs

Allowing Applets to Write to Files and Directories

You can allow local applets to write to files and directories by adding them to the access control list. To do this, set the property value acl.write equal to the files or directories to which you want applets to be able to write.

Writing to Files on UNIX Systems

On a UNIX system, if you want applets to write to a file called numbers.txt in the $HOME\java directory, edit the properties file and insert the following line:

acl.write=$HOME\java\numbers.txt

If you want applets to be able to write to files in the $HOME\java directory, you can do this by setting the value for acl.write to

acl.write=$HOME\java

If you want applets to be able to write to multiple directories or files, separate each entry by colons, like this:

acl.write=\java\applets\docs:\usr\images\gifs:\usr\temp

Writing to Files on Windows and OS/2 Systems

On a Windows or OS/2 system, if you want applets to write to a file called numbers.txt in the C:\java directory, edit the properties file and insert the following line:

acl.write=C:\java\numbers.txt

If you want applets to be able to write to files in the C:\java directory, you can do this by setting the value for acl.write to

acl.write=C:\java

If you want applets to be able to write to multiple directories or files, separate each entry by semi-colons, like this:

acl.write=C:\java;C:\java\applets\docs

Applet Viewer Property Values

As you have seen, setting property values for local applets can be very useful. Many other property values are available to local applets as well. To access additional property values from within an applet, you can use the getProperty() method of the System class. Here's how:

String s = System.getProperty("valuename");

where valuename is the name of the property value you want to check, such as

String s = System.getProperty("java.version");

As shown in Table 5.2, local applets can access some property values by default. To remove access to these values, you can set them to null in the .hotjava\properties file, such as

os.arch=null

As shown in Table 5.3, there are other property values that local applets can access only if they are set to true in the .hotjava\properties file. You enter these values in the form valuename.applet=true. Here's how you could allow applets to read the user.name value:

user.name.applet=true

Graphical Developer's Tools

Graphical developer's tools for Java are available directly from Sun and from third-party vendors. This section examines the developer's tools available from Sun and its subsidiaries.

Macintosh Developer's Tools

The Macintosh has an entirely graphical user interface. For this reason, the JDK for Macintosh is much more than a simple port of the UNIX version. The first thing you will notice about the JDK tools is that they have a familiar look and feel. You can drag-and-drop files onto any of the tool icons to start them. You also can start the tools by clicking on their icons. After the tools are started, you can access pull-down menus that provide you with options and let you set or change defaults.

Key Differences in Java Tools for the Macintosh

Where the Java developer's tools differ from Macintosh applications is behind the scenes. Unlike the Solaris and Windows 95/NT operating systems, the Macintosh operating system is not inherently multithreaded. Because some multithreaded operations such as memory management are automatic in Java, the lack of built-in multithreading posed a major problem to the JDK developers.

The workaround was to perform multithreading at a higher level than on other systems. This provides Macintosh users with most of the advantages of a multithreaded environment. However, some operations that are controlled at the operating-system level or otherwise beyond Java's control block other threads. For example, when a menu is down, all other operations are blocked.

Memory management is an example of an operation that is sometimes blocking. Java is designed to automatically manage memory for you as a background task, yet on the Macintosh background memory management is not always possible. Periodically, Java tries to free memory by deleting objects that are no longer referenced. If Java cannot satisfy a request for memory, memory management moves temporarily from the background to the foreground. When this happens, you will see a busy cursor as Java searches for objects that can be freed.

You can avoid most memory problems by increasing the default settings for memory heaps to fit your needs and your system. On the Macintosh, Java maintains two memory heaps. The Macintosh Application Heap is used entirely for Macintosh allocations such as menus, windows, and buttons. The garbage-collected heap, or GC heap, is used by Java.

Whenever you start a new Java application, some memory is allocated to both the application heap and the GC heap. You can determine how much memory a Java application is allocated by checking the value associated with the largest unused block of memory before and after starting the application. This value can be found by clicking on About this Macintosh from the Finder.

Changing Heap Settings

You can change the heap settings in the Finder. To change the Macintosh Application Heap setting, follow these steps:

1. Access the Finder tool.
2. Click on the Get Info command.
3. Change the setting for the application heap in the space provided.

To change the garbage-collected heap setting, follow these steps:

1. Access the Finder tool.
2. Click on the Get Info command.
3. Change the setting for MultiFinder Temporary Memory.

Warning: Before you change the heap settings, you should experiment with Java on your system.

The Java Compiler for Macintosh

When you compile Java programs, you will use the Java compiler. The Java compiler expects source code to be in a file named with the .java extension. Additionally, when the source file contains multiple class declarations, the source file must be named after the primary class declaration. Therefore, it is good to always name your source files after the primary class declaration. By default, the compiler uses between 800KB and 6000KB of temporary memory.

A handy feature of the compiler is the capability to link in a text editor that can be controlled by AppleEvents. This provides you with direct access to Java source files from within the compiler. Some of the text editors you can use include SimpleText, BBEdit 3.5 or later versions, and CodeWarrior IDE versions 7 or 8. You can set your preferred editor by selecting Preferences from the menu.

The Preferences submenu also lets you set compiler and debugging options. To better understand what these various options offer you, review the section on the command-line version of the Java compiler in this chapter.

The Java compiler automatically compiles your source code when you do one of the following:

• Drag-and-drop a source file with the .java extension onto the compiler icon.
• Click on the compiler icon. After the compiler is started, select Open from the File menu.

For each class declaration in the source file, the Java compiler creates a class file with a .class extension. Because the compiler is case sensitive, the first part of the class file will be named exactly as you typed it in the source file. By default, the class files are placed in the same directory as the source file.

When you start the compiler, a status window appears. From the status window you can determine

• The current free memory in the Java garbage-collected heap
• The current compiler activity
• The number of simultaneous compiles

Errors that occur during compiling are shown in a pop-up window. You can use the error report to pinpoint problems in the code. If you have set a preferred editor, you can go directly into an editor session by doing one of the following:

• Double-clicking on the errors shown in the error window
• Selecting Edit from the File menu

After you correct errors, save the file. You can now recompile the source file simply by selecting Rebuild from the File menu. The Rebuild option tells the compiler to recompile the last source file you tried to compile. If the source file still has errors, they will be listed to an error window.

To close pop-up windows started by the compiler, you can select the Close option from the menu. Each time you select Close, the frontmost window will close. If the status window is the frontmost window, the compiler will exit. You can also exit the compiler simply by selecting Quit from the menu. Because all current compiler actions are aborted when you quit, you generally should wait until the compiler completes what it is doing before exiting.

The compiler has the following menu options:

The Applet Viewer for Macintosh

On the Macintosh, the Java applet viewer is designated by the AppletViewer icon. The applet viewer allows you to view applets without a Web browser. Because applets extend the Applet class and are made for viewing in Web documents, you must create an HTML document with the appropriate markup before you can use the applet viewer. After you have created such a document, you can use the applet viewer to view your applets.

To view an applet with the applet viewer, you can do one of the following:

• Drag-and-drop an HTML document with the .html extension onto the AppletViewer icon.
• Click on the AppletViewer icon. After the applet viewer is started, select Open Local from the File menu.

Before displaying any applets, the applet viewer verifies that the HTML document contains an <APPLET> tag with three specific attributes: CODE, WIDTH, and HEIGHT. The CODE attribute tells the viewer what class file to load. The WIDTH and HEIGHT attributes tell the viewer what the size of the applet's canvas should be. The viewer also looks for the optional <PARAM> tag that sets input parameters for your applets. (See Chapter 15 for a complete discussion on creating Java-enhanced HTML documents.)

The applet viewer does not make use of any other HTML tags within the document. This means your HTML document will not look the same as it would when viewed with a Java-capable Web browser. For each defined <APPLET> tag in the document, the applet viewer starts up a separate window, the height and width of which are determined by the attributes you set. This means that if you add three applets to a document, the applet viewer will place the applets in three separate windows. If you want to see how it looks to have three applets running in separate windows, use the applet viewer to view the Web presentation you create in Chapter 15.

By default, the applet viewer uses 300KB to 3000KB of temporary memory. When you start the applet viewer, a status window appears. From the status window you can determine

• The current free memory in the Java garbage-collected heap
• The number of applets currently running on the system

The Macintosh applet viewer lets you access applets on the Web. You can do this by selecting Open URL from the menu. If you type in the URL to an HTML document on the Web containing an applet, the applet viewer will display the applet. This lets any Mac user with the JDK installed on his system view applets even if his browser does not support them.

Just as you can configure a text editor for the compiler, you can configure a text editor for the applet viewer. Again, the text editor must be controllable by AppleEvents. You can set your preferred editor by selecting Properties from the menu. The Properties submenu also lets you set applet viewer options such as automatic verification of the class file and network access.

When you are running an applet, an additional menu called Applets is available from the menu bar. If you have set a preferred editor for the applet viewer, you can go directly into an editor session by selecting Edit from the Applets menu. You can use the editor session to edit the HTML document associated with the running applet. After you have made the necessary changes, save the HTML document. You can then reload the document and its associated applet by selecting Reload from the Applets menu.

Another useful option of the viewer is Clone. If you select Clone from the Applets menu, you can make a new copy of the applet window and restart the associated applet. This is useful if you are testing the behavior of the applet. Instead of reloading all the files associated with an applet or cloning an applet, you might want to restart the applet. To restart an applet, you can select Restart from the Applets menu.

Two additional options available from the menu can provide you information about an applet. The Tag option displays the <APPLET> tag associated with the currently running applet. The Info option shows additional information about the applet.

The applet viewer has the following menu options when no applets are running:

When an applet is running in the viewer, these options are added under the Applets menu:

The Java Interpreter for Macintosh

The Java interpreter executes Java bytecode files. You will use the interpreter to run Java applications. Before the interpreter runs any program, it verifies that the classes associated with the program are valid and do not violate any language constraints. For applications that include many classes, you will want to pass the interpreter the class file that declares the application's main() method.

The interpreter executes the main() method and any threads specified in the main() method. If no threads are created by the main() method, the interpreter executes the main() method and then exits. If threads are created by the main() method, the interpreter exits when the last thread exits. Because the interpreter expects the class file to contain a main() method, you generally cannot use the interpreter to run Java applets. If you want to run Java applets, you should use the Java applet viewer discussed in the previous section of this chapter.

To view a Java application with the interpreter, you can

• Drag-and-drop the class file with the main() method onto the interpreter icon.
• Click on the interpreter icon. After the interpreter is started, select Open from the File menu.

Most of the interpreter features are similar to those discussed in the previous sections of this chapter. You can set properties for the interpreter in the Properties menu. You can reload an application by selecting Reload from the File menu. To quit the current interpreter session, you select Quit from the File menu.

The interpreter has the following menu options:

Java WorkShop

The Java WorkShop is an integrated development environment that helps you develop and manage just about any type of programming project. Java WorkShop is a commercial product currently in development by SunSoft.

Java WorkShop is currently available for Solaris and Windows 95/NT. Free developers versions of Java WorkShop are available directly from SunSoft at

http://www.sun.com/sunsoft/Developer-products/java/

Navigating the WorkShop

Java WorkShop's entire graphical development environment is placed within a Webified desktop. This makes Java WorkShop as easy to use as your favorite Web browser. Figure 5.5 shows the main window for WorkShop. The navigation buttons depicted on the menu bar are accessible from any part of the desktop.

Figure 5.5 : Navigating the WorkShop.

By clicking on a menu button, you can move quickly from tool to tool. The suitcase button takes you to a Portfolio Manager. The puzzle button takes you to a Project Manager. The pencil-and-notepad button takes you to the source editor. The wrench button takes you to a build session. The magnifying glass takes you to a source browser. The ladybug button takes you to the debugger. The light-switch button runs the current applet or application. The question-mark button takes you to WorkShop's online help.

Each tool in Java WorkShop displays in an HTML page that contains a specialized applet that performs a specific function such as debugging your code. Some applets launch an associated editor or browser. For example, the debugger applet starts a debugger browser. Let's look at each of the key tools in Java WorkShop.

Built-in Help

You can access Java WorkShop's online help system at any time by clicking on the Help button icon-the question mark on the main toolbar. The online help system is organized into eight subject areas:

• Contents-A list of all the help pages
• Index-A subject index of help topics
• Getting Started-An overview of Java WorkShop
• Debugging Applets-How to use Java WorkShop to debug Java programs
• Building Applets-How to use Java WorkShop to build Java programs
• Managing Applets-How to manage projects and portfolios using Java WorkShop
• Editing Source-How to use Java WorkShop to edit source files
• Browsing Source-How to use Java WorkShop to browse source files

You can access any of the help topics using the help toolbar. As you can see from Figure 5.6, the help toolbar is clearly labeled for easy navigation.

Figure 5.6 : Using the built in help.

The Portfolio Manager

You can access Java WorkShop's Portfolio Manager at any time by clicking on the Portfolio Manager icon-the suitcase icon on the main toolbar. The purpose of the Portfolio Manager is to help you create and manage groups of projects called portfolios. Figure 5.7 shows the project-creation page in Java WorkShop. Your WorkShop projects can include local applets, remote applets, stand-alone applications, images, and Java packages.

Figure 5.7 : Creating a new project with the Portfolio Manager.

By grouping projects into a portfolio, Java WorkShop allows you to quickly build, browse, and debug portfolio components. For example, each project in the portfolio is assigned an icon and a name. When you are on the Portfolio Manager page, you can compile all source files associated with a project by selecting its icon and then selecting the Build button on the main toolbar.

Editing Projects

When you create a project using the Portfolio Manager, you define attributes for the project-the puzzle icon on the main toolbar. These attributes can be changed with the Project Editor. You can access Java WorkShop's Project Editor at any time by clicking on the Project Editor icon-the puzzle icon on the main toolbar.

As you can see from Figure 5.8, the Project Editor contains five folders in which you can assign default attributes for the project:

Figure 5.8 : Editing your Java projects.

• General-Allows you to specify general information for the project including the name, type, and source directory of the project.
• Build-Allows you to specify information used when the project is compiled
• Debug/Browse-Allows you to specify information used when you debug and browse source files
• Run-Allows you to specify information used when you run an applet or stand-alone application
• Publish-Allows you to specify information used when you publish the project for others to use it.

You can access any of these folders simply by clicking on its associated tab. Whenever you change information in a folder, you should apply the changes before moving to another folder.

The Source Editor

When you want to create source files in Java WorkShop, you click on the Source Editor icon-the pencil-and-notepad icon on the main toolbar. The Source Editor in Java WorkShop is a stand-alone text editor. Although the features of the editor are very basic, it is easy to use and performs most of the tasks you would want a source code editor to do. Figure 5.9 shows the Source Editor.

Figure 5.9 : The Source Editor in Java WorkShop.

Building Projects

Java WorkShop allows you to compile and build at any stage of a project. To start a build session, you simply press the Build button-the wrench icon on the main toolbar.

As you can see from Figure 5.10, the Program Builder allows you to compile entire projects or single files. If you build a project, the Program Builder uses the information you specified in the Project Manager or Project Editor information session. If you build a single file, the Program Builder uses the default settings for the current project to compile the file.

Figure 5.10 : Building your Java project.

The Source Browser

When you want to view relationships in your source code, you will use the Source Browser. The Source Browser displays documentation for your WorkShop projects that resembles the documentation generated by the Java API documentation generator-javadoc. The advantage of the Source Browser is that you can view relationships at any time during or after the creation of a project simply by pressing the Source Browser button-the magnifying-glass icon on the main toolbar.

Figure 5.11 shows some of the classes used in the CheckersGame class, which is part of a demo applet that comes with Java WorkShop. To ensure this documentation is easy to use for programs of any size, the Source Browser includes a utility that allows you to search for references in specified source files.

Figure 5.11 : The Source Browser.

The Debugger

To debug your code, you will use the WorkShop debugger, which is accessible at any time from the main toolbar. When you start a debugging session by clicking on the Debugger button-the lady- bug icon on the main toolbar-Java WorkShop moves to the debugger screen and starts a debugging browser. The purpose of the debugging browser is to let you see how specific changes affect the appearance of your Java program.

Debugging functions are organized into six folders. You can see the tabs for these folders in Figure 5.12, which also shows the debugging browser. Each folder provides you with control over a specific set of related functions. For example, the Thread/Stacks folder lets you view the current status of threads and stacks, start and stop threads, and add or remove items from the stack.

Figure 5.12 : The debugger and debugging browser.

After you start a debugging session, Java WorkShop allows you to perform limited debugging functions in the Source Editor. To do this, the editor automatically displays a new toolbar with icons for common debugging functions. These functions allow you to stop at a breakpoint, clear breakpoints, resume execution of all threads, step into the program line by line, run to the current cursor location, move up the stack, and move down the stack.

Figure 5.13 shows the Source Editor with the debugging toolbar. If you compare Figure 5.13 with Figure 5.9, you can easily identify the changes.

Figure 5.13 : The Source Editor with the debugging toolbar.

Running Projects in Java WorkShop

Running your project is as easy as clicking the Run button-the light-switch icon on the main toolbar. Depending on the type of project you are creating, WorkShop will either open a browser session or create a shell tool. Figure 5.14 shows the Checkers applet running in WorkShop's main window.

Figure 5.14 : Running the project.

Summary

Whether you use a UNIX-based system or a Windows-based system, the Java Developer's Kit provides you with a complete toolkit for developing powerful Java programs. The tools you will use most often are the Java compiler, interpreter, and applet viewer. Other tools in the JDK have a more limited purpose but are useful as well. You can use the Java API documentation generator to create online documentation. You will use the Java header and stub file generator when you want Java classes to interact with C/C++ libraries. You will use the Java class file disassembler when you want to gain insight into the inner workings of class files.