Java Cookbook | O'Reilly Media

BUY THIS BOOK

Print Book $49.95

Print+PDF $64.94

PDF $39.99

Safari Books Online

What is this?

Print Book £31.95

What is this?

Looking to Reprint or License this content?

Tell a friend

Java Cookbook, Second Edition

By Ian F. Darwin
Book Price: $49.95 USD
£31.95 GBP
PDF Price: $39.99

Cover | Table of Contents | Colophon

Chapter 1: Getting Started: Compiling, Running, and Debugging

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

This chapter covers some entry-level tasks that you need to know how to do before you can go on—it is said you must crawl before you can walk, and walk before you can ride a bicycle. Before you can try out anything in this book, you need to be able to compile and run your Java code, so I start there, showing several ways: the JDK way, the Ant way, and the Integrated Development Environment (IDE) way. Another issue people run into is setting CLASSPATH correctly, so that's dealt with next. Then I'll discuss a few details about applets, in case you are working on them. Deprecation warnings come next, as you're likely to meet them in maintaining "old" Java code. The chapter ends with some general information about conditional compilation, unit testing, assertions, and debugging.

If you're already happy with your IDE, you may wish to skip some or all of this material. It's here to ensure that everybody can compile and debug their programs before we move on.

You need to compile and run your Java program.

This is one of the few areas where your computer's operating system impinges on Java's portability, so let's get it out of the way first.

Section : JDK

Using the command-line Java Development Kit (JDK) may be the best way to keep up with the very latest improvements from Sun. This is not the fastest compiler available by any means; the compiler is written in Java and interpreted at compile time, making it a sensible bootstrapping solution, but not necessarily optimal for speed of development. Nonetheless, using Sun's JDK, the commands are javac to compile and java to run your program (and, on Windows only, javaw to run a program without a console window). For example:

C:\javasrc>javac HelloWorld.java

C:\javasrc>java HelloWorld
Hello, World

C:\javasrc>

As you can see from the compiler's (lack of) output, this compiler works on the Unix "no news is good news" philosophy: if a program was able to do what you asked it to, it shouldn't bother nattering at you to say that it did so. Many people use this compiler or one of its clones.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Introduction

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

If you're already happy with your IDE, you may wish to skip some or all of this material. It's here to ensure that everybody can compile and debug their programs before we move on.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Compiling and Running Java: JDK

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You need to compile and run your Java program.

This is one of the few areas where your computer's operating system impinges on Java's portability, so let's get it out of the way first.

Section : JDK

C:\javasrc>javac HelloWorld.java

C:\javasrc>java HelloWorld
Hello, World

C:\javasrc>

There is an optional setting called CLASSPATH, discussed in Recipe 1.4, that controls where Java looks for classes. CLASSPATH, if set, is used by both javac and java. In older versions of Java you had to set your CLASSPATH to include ".", even to run a simple program from the current directory; this is no longer true on Sun's current Java implementations. It may be true on some of the clones.

Section : Command-line alternatives

Sun's javac compiler is the official reference implementation. But it is itself written in Java, and hence must be interpreted at runtime. Some other Java compilers are written in C/C++, so they are quite a bit faster than an interpreted Java compiler. In order to speed up my compilations, I have used Jikes, which is fast (C++), free, and available both for Windows and for Unix. It's also easy to install and is included with the Mac OS X Developer Tools package. For Windows, Linux, and other Unix systems, you can find binaries of the current version on IBM's Jikes web site. If you are using OpenBSD, NetBSD, or FreeBSD, you should only need to run something like:

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Editing and Compiling with a Color-Highlighting Editor

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You are tired of command-line tools but not ready for an IDE.

Use a color-highlighting editor.

It's less than an IDE (see the next recipe), but more than a command line. What is it? It's an editor with Java support. Tools such as TextPad (http://www.textpad.com), Visual Slick Edit, and others are low-cost windowed editors (primarily for Windows) that have some amount of Java recognition built-in and the ability to compile from within the editor. TextPad recognizes quite a number of file types, including batch files and shell scripts, C, C++, Java, JSP, JavaScript, and many others. For each of these, it uses color highlighting to show which part of the file being edited comprises keywords, comments, quoted strings, and so on. This is very useful in spotting when part of your code has been swallowed up by an unterminated /* comment or a missing quote. While this isn't the same as the deep understanding of Java that a full IDE might possess, experience has shown that it definitely aids programmer productivity. TextPad also has a "compile Java" command and a "run external program" command. Both of these have the advantage of capturing the entire command output into a window, which may be easier to scroll than a command-line window on some platforms. On the other hand, you don't see the command results until the program terminates, which can be most uncomfortable if your GUI application throws an exception before it puts up its main window. Despite this minor drawback, TextPad is a very useful tool. Other editors that include color highlighting include vim (an enhanced version of the Unix tool vi, available for Windows and Unix platforms from http://www.vim.org), the ever-popular Emacs editor, and many others.

And speaking of Emacs, since it is so extensible, it's natural that people have built enhanced Java capabilities for it. One example is JDEE (Java Development Environment for Emacs), an Emacs "major mode" (

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Compiling, Running, and Testing with an IDE

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Several tools are too many.

Use an integrated development environment.

Many programmers find that using a handful of separate tools—a text editor, a compiler, and a runner program, not to mention a debugger (see Recipe 1.13)—is too many. An integrated development environment (IDE) incorporates all of these into a single toolset with a (hopefully consistent) graphical user interface. Many IDEs are available, ranging all the way up to fully integrated tools with their own compilers and virtual machines. Class browsers and other features of IDEs round out the purported ease-of-use feature-sets of these tools. It has been argued many times whether an IDE really makes you more productive or if you just have more fun doing the same thing. However, even the JDK maintainers at Sun admit (perhaps for the benefit of their advertisers) that an IDE is often more productive, although it hides many implementation details and tends to generate code that locks you into a particular IDE. Sun's Java Jumpstart CD (part of Developer Essentials) said, at one time:

The JDK software comes with a minimal set of tools. Serious developers are advised to use a professional Integrated Development Environment with JDK 1.2 software. Click on one of the images below to visit external sites and learn more.

This is followed by some (presumably paid) advertising links to various commercial development suites. I do find that IDEs with "incremental compiling" features—which note and report compilation errors as you type, instead of waiting until you are finished typing—do provide somewhat increased productivity for most programmers. Beyond that, I don't plan to debate the IDE versus the command-line process; I use both modes at different times and on different projects. I'm just going to show a few examples of using a couple of the Java-based IDEs.

One IDE that runs on both Windows and Unix platforms is NetBeans, which is a free download. Originally created by NetBeans.com, this IDE was so good that Sun bought the company and now distributes the IDE in two versions that share a lot of code: NetBeans (formerly called Forte, distributed as open source), and Sun One Studio (commercial, not open sourced). There is a plug-in API; some

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Using CLASSPATH Effectively

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You need to keep your class files in a common directory, or you're wrestling with CLASSPATH.

Set CLASSPATH to the list of directories and/or JAR files that contain the classes you want.

CLASSPATH is one of the more "interesting" aspects of using Java. You can store your class files in any of a number of directories, JAR files, or zip files. Just like the PATH your system uses for finding programs, the CLASSPATH is used by the Java runtime to find classes. Even when you type something as simple as java HelloWorld, the Java interpreter looks in each of the places named in your CLASSPATH until it finds a match. Let's work through an example.

The CLASSPATH can be set as an environment variable on systems that support this (Unix, including Mac OS X, and Windows). You set it the same way you set other environment variables, such as your PATH environment variable.

Alternatively, you can specify the CLASSPATH for a given command on its command line:

               java -classpath \c:\ian\classes MyProg

Suppose your CLASSPATH were set to C:\classes;. on Windows or ~/classes:. on Unix (on the Mac, you can set the CLASSPATH with JBindery). Suppose you had just compiled a file named HelloWorld.java into HelloWorld.class and tried to run it. On Unix, if you run one of the kernel tracing tools (trace, strace, truss, ktrace), you would probably see the Java program open (or stat, or access) the following files:

Some file(s) in the JDK directory
Then ~/classes/HelloWorld.class, which it probably wouldn't find
And ./HelloWorld.class, which it would find, open, and read into memory

The vague "some file(s) in the JDK directory" is release-dependent. On Sun's JDK it can be found in the system properties:

sun.boot.class.path = C:\JDK1.4\JRE\lib\rt.jar;C:\JDK1.4\JRE\lib\i18n.jar;C:\JDK1.4\
JRE\classes

The file rt.jar is the runtime stuff; i18n.jar is the internationalization; and classes is an optional directory where you can install additional classes.

Suppose you had also installed the JAR file containing the supporting classes for programs from this book,

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Using the com.darwinsys API Classes from This Book

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to try out my example code and/or use my utility classes.

I have built up a fairly sizeable collection of reusable classes into my own API, which I use in my own Java projects. I use example code from it throughout this book, and I use classes from it in many of the other examples. So, if you're going to be downloading and compiling the examples individually, you should first download the file darwinsys.jar and include it in your CLASSPATH. Note that if you are going to build all of my source code (as in Recipe 1.6), you can skip this download because the top-level Ant file starts off by building the JAR file for this API.

I have split the com.darwinsys.util package from the first edition of this book into about a dozen com.darwinsys packages, listed in Table 1-1. I have also added many new classes; these packages now include approximately 50 classes and interfaces. You can peruse the documentation online at http://javacook.darwinsys.com/docs/api.

Table 1-1: The com.darwinsys packages
Package name	Package description
`com.darwinsys.database`	Classes for dealing with databases in a general way
`com.darwinsys.html`	Classes (only one so far) for dealing with HTML
`com.darwinsys.io`	Classes for input and output operations, using Java's underlying I/O classes
`com.darwinsys.lang`

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Compiling the Source Code Examples from This Book

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to try out my examples.

Download the latest archive of the book source files, unpack it, edit build.properties, and run Ant (see Recipe 1.7) to compile the files.

You can download the latest version of the source code for all the examples in this book from the book's web site, http://javacook.darwinsys.com/. You can get it all as one large file containing all the source code, in a file called javacooksrc.jar, which you should unzip into an empty directory someplace convenient, wherever you like to keep source code. You should then edit the file build.properties, specifying the locations of some jar files. Editing build.properties and then running ant in this directory first creates a file called darwinsys.jar containing the com.darwinsys API described in Recipe 1.5 (you will probably want to add this file to your CLASSPATH—see Recipe 1.4—or to your JDKHOME/jre/lib/ext directory). Ant goes on to build as many of the other examples as it can given the settings in build.properties, your Java runtime, and your operating system. The files are roughly organized in per-chapter directories, but there is a lot of overlap and cross-referencing. Because of this, I have prepared a cross-reference file named index-bychapter.html. A mechanically generated file called index-byname.html can be used if you know the name of the file you want (and remember that Java source files almost always have the same name as the public class they contain). The canonical index file, index.html, links to both these files.

If you have JDK 1.3 or 1.4 instead of 1.5, a few files will not compile, but the compiler prints a comment about needing 1.4 or 1.5. And the "native code" examples may not compile at all. Most everything else should compile correctly.

If you're not using Ant, well, you should! But if you can't, or won't, after you've set your CLASSPATH, you should compile what you need. You will need the darwinsys.jar file; you should probably just download it. In some directories you can simply say javac *.java or jikes *.java. But in others, you have to set your CLASSPATH manually; if some files that you need won't compile, you'll have to look in the Ant file

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Automating Compilation with Ant

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You get tired of typing javac and java commands.

Use the Ant program to direct your compilations.

The intricacies of Makefiles have led to the development of a pure Java solution for automating the build process. Ant is free software; it is available in source form or ready-to-run from the Apache Foundation's Jakarta Project web site, at http://jakarta.apache.org/ant/. Like make, Ant uses a file or files—written in XML—listing what to do and, if necessary, how to do it. These rules are intended to be platform-independent, though you can of course write platform-specific recipes if necessary.

To use Ant, you must create a 15 to 30 line file specifying various options. This file should be called build.xml; if you call it anything else, you'll have to give a special command-line argument every time you run Ant. Example 1-1 shows the build script used to build the files in the starting directory. See Recipe 21.0 for a discussion of the XML syntax. For now, note that the

<!-
-

tag begins an XML comment, which extends to the

-
->

tag.

Example 1-1. Ant example file (build.xml)

<project name="Java Cookbook Examples" default="compile" basedir=".">

  <!-- Set global properties for this build -->
  <property name="src" value="."/>
  <property name="build" value="build"/>
  <!-- Specify the compiler to use. 
    Using jikes is supported but requires rt.jar in classpath. -->
  <property name="build.compiler" value="modern"/>

  <target name="init">
    <!-- Create the time stamp -->
    <tstamp/>
    <!-- Create the build directory structure used by compile -->
    <mkdir dir="${build}"/>
  </target>

  <!-- Specify what to compile. This builds everything -->
  <target name="compile" depends="init">

    <!-- Compile the java code from ${src} into ${build} -->
    <javac srcdir="${src}" destdir="${build}"
          classpath="../darwinsys.jar"/>
  </target>

</project>

When you run Ant, it produces a reasonable amount of notification as it goes :

$ ant  compile
Buildfile: build.xml
Project base dir set to: /home/ian/javasrc/starting
Executing Target: init
Executing Target: compile
Compiling 19 source files to /home/ian/javasrc/starting/build
Performing a Modern Compile
Copying 22 support files to /home/ian/javasrc/starting/build
Completed in 8 seconds
$

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Running Applets

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to run an applet.

Write a class that extends java.applet.Applet; write some HTML and point a browser at it.

An applet is simply a Java class that extends java.applet.Applet, and in doing so inherits the functionality it needs to be viewable inside a web page in a Java-enabled web browser. All that's necessary is an HTML page referring to the applet. This HTML page requires an applet tag with a minimum of three attributes , or modifiers: the name of the applet itself and its onscreen width and height in screen dots or pixels. This is not the place for me to teach you HTML syntax—there is some of that in Recipe 18.1—but I'll show my HTML applet template file. Many of the IDEs write a page like this if you use their "build new applet" wizards:

<html>
<head><title>A Demonstration</title></head>
<body>
<h1>My TEMPLATE Applet</h1>
<applet code="CCC"  width="200" height="200">
</applet>
</body>
</html>

You can probably intuit from this just about all you need to get started. For a little more detail, see Recipe 18.1. Once you've created this file (replacing the CCC with the fully qualified class name of your applet—e.g., code="com.foo.MyApplet") and placed it in the same directory as the class file, you need only tell a Java-enabled web browser to view the HTML page, and the applet should be included in it.

All right, so the applet appeared and it even almost worked. Make a change to the Java source and recompile. Click the browser's Reload button. Chances are you're still running the old version! Browsers aren't very good at debugging applets. You can sometimes get around this by holding down the Shift key while you click Reload. But to be sure, use AppletViewer , a kind of mini-browser included in the JDK. You need to give it the HTML file, just like a regular browser. Sun's AppletViewer (shown in Figure 1-9 under Windows) has an explicit Reload button that actually reloads the applet. And it has other features, such as debugging hooks, and other information displays. It also has a View

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Dealing with Deprecation Warnings

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Your code used to compile cleanly, but now it gives deprecation warnings.

You must have blinked. Either live—dangerously—with the warnings or revise your code to eliminate them.

Each new release of Java includes a lot of powerful new functionality, but at a price: during the evolution of this new stuff, Java's maintainers find some old stuff that wasn't done right and shouldn't be used anymore because they can't really fix it. In building JDK 1.1, for example, they realized that the java.util.Date class had some serious limitations with regard to internationalization. Accordingly, many of the Date class methods and constructors are marked "deprecated." To deprecate something means, according to the American Heritage Dictionary, to "express disapproval of; deplore." Java's developers are therefore disapproving of the old way of doing things. Try compiling this code:

import java.util.Date;

/** Demonstrate deprecation warning */
public class Deprec {

    public static void main(String[] av) {

        // Create a Date object for May 5, 1986
        // EXPECT DEPRECATION WARNING
        Date d = new Date(86, 04, 05);        // May 5, 1986
        System.out.println("Date is " + d);
    }
}

What happened? When I compile it, I get this warning:

C:\javasrc>javac Deprec.java
Note: Deprec.java uses or overrides a deprecated API.  Recompile with 
"-deprecation" for details.
1 warning
C:\javasrc>

So, we follow orders. Recompile with -deprecation (if using Ant, use <javac deprecation= 'true '...>) for details:

C:\javasrc>javac -deprecation Deprec.java
Deprec.java:10: warning: constructor Date(int,int,int) in class java.util.Date has 
been deprecated
                Date d = new Date(86, 04, 05);          // May 5, 1986
                         ^
1 warning

C:\javasrc>

The warning is simple: the Date constructor that takes three integer arguments has been deprecated. How do you fix it? The answer is, as in most questions of usage, to refer to the Javadoc documentation for the class. In Java 2, the introduction to the

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Conditional Debugging Without #ifdef

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want conditional compilation and Java doesn't seem to provide it.

Use constants, command-line arguments, or assertions (Recipe 1.12), depending upon the goal.

Some older languages such as C, PL/I, and C++ provide a feature known as conditional compilation. Conditional compilation means that parts of the program can be included or excluded at compile time based upon some condition. One thing it's often used for is to include or exclude debugging print statements. When the program appears to be working, the developer is struck by a fit of hubris and removes all the error checking. A more common rationale is that the developer wants to make the finished program smaller—a worthy goal—or make it run faster by removing conditional statements.

Section : Conditional compilation?

Although Java lacks any explicit conditional compilation, a kind of conditional compilation is implicit in the language. All Java compilers must do flow analysis to ensure that all paths to a local variable's usage pass through a statement that assigns it a value first, that all returns from a function pass out via someplace that provides a return value, and so on. Imagine what the compiler will do when it finds an if statement whose value is known to be false at compile time. Why should it even generate code for the condition? True, you say, but how can the results of an if statement be known at compile time? Simple: through final boolean variables. Further, if the value of the if condition is known to be false, then the body of the if statement should not be emitted by the compiler either. Presto—instant conditional compilation!

// IfDef.java
final boolean DEBUG = false;
System.out.println("Hello, World ");
if (DEBUG) {
        System.out.println("Life is a voyage, not a destination");
}

Compilation of this program and examination of the resulting class file reveals that the string "Hello" does appear, but the conditionally printed epigram does not. The entire

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Debugging Printouts

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to have debugging statements left in your code enabled at runtime.

Use my Debug class.

Instead of using the conditional compilation mechanism of Recipe Recipe 1.10, you may want to leave your debugging statements in the code but enable them only at runtime when a problem surfaces. This is a good technique for all but the most compute-intensive applications, because the overhead of a simple if statement is not all that great. Let's combine the flexibility of runtime checking with the simple if statement to debug a hypothetical fetch( ) method (part of Fetch.java):

String name = "poem";
if (System.getProperty("debug.fetch") != null) {
    System.err.println("Fetching " + name);
}
value = fetch(name);

Then, we can compile and run this normally and the debugging statement is omitted. But if we run it with a -D argument to enable debug.fetch, the printout occurs:

> java Fetch          # See? No output
> java -Ddebug.fetch Fetch
Fetching poem
>

Of course this kind of if statement is tedious to write in large quantities, so I have encapsulated it into a Debug class, which is part of my com.darwinsys.util package. Debug.java appears in full in Recipe 1.17 at the end of this chapter. My Debug class also provides the string "debug." as part of the argument to

System.getProperty(
)

, so we can simplify the previous Fetch example as follows (code in FetchDebug.java):

String name = "poem", value;
Fetch f = new Fetch( );
Debug.println("fetch", "Fetching " + name);
value = f.fetch(name);

Running it behaves identically to the original Fetch:

> java FetchDebug     # again, no output
> java -Ddebug.fetch FetchDebug
Fetching poem
>

Some more comprehensive and flexible "debug printout" mechanisms—including ones that can log across a network connection—are covered in Recipes Recipe 17.7, Recipe 17.8, and Recipe 17.9.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Maintaining Program Correctness with Assertions

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to leave tests in your code but not have runtime checking overhead until you need it.

Use the JDK 1.4 Assertions mechanism.

JDK 1.4 introduced a new keyword into the language: assert. The assert keyword takes two arguments separated by a colon (by analogy with the conditional operator): an expression that is asserted by the developer to be true, and a message to be included in the exception that is thrown if the expression is false. To provide for backward compatibility with programs that might have used "assert" as an identifier name on prior JDK versions, JDK 1.4 requires a command-line switch (-source 1.4) that must be provided for assert to be recognized as a keyword. Normally, assertions are meant to be left in place (unlike quick and dirty print statements, which are often put in during one test and then removed). To reduce runtime overhead, assertion checking is not enabled by default; it must be enabled explicitly with the -enableassertions (or -ea) command-line flag. Here is a simple demo program that shows the use of the assertion mechanism:

ian:147$  cd testing;
ian:148$ cat AssertDemo.java
public class AssertDemo {
        public static void main(String[] args) {
                int i = 4;
                if (args.length == 1) {
                        i = Integer.parseInt(args[0]);
                }
                assert i > 0 : "i is non-positive";
                System.out.println("Hello after an assertion");
        }
}
ian:149$ javac -source 1.4 AssertDemo.java  # will not compile without 1.4 flag
ian:150$ java AssertDemo  -1
Hello after an assertion
ian:151$ java -ea  AssertDemo  -1
Exception in thread "main" java.lang.AssertionError: i is non-positive
        at AssertDemo.main(AssertDemo.java:15)
ian:152$

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Debugging with JDB

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

The use of debugging printouts and assertions in your code is still not enough.

Use a debugger, preferably the one that comes with your IDE.

The JDK includes a command-line-based debugger, jdb, and any number of IDEs include their own debugging tools. If you've focused on one IDE, learn to use the debugger that it provides. If you're a command-line junkie, you may want to learn at least the basic operations of jdb.

Here is a buggy program. It intentionally has bugs introduced so that you can see their effects in a debugger:

/** This program exhibits some bugs, so we can use a debugger */
public class Buggy {
    static String name;

    public static void main(String[] args) {
        int n = name.length( );    // bug # 1

        System.out.println(n);

        name += "; The end.";    // bug #2
        System.out.println(name); // #3
    }
}

Here is a session using jdb to find these bugs:

ian> java Buggy
Exception in thread "main" java.lang.NullPointerException
        at Buggy.main(Compiled Code)
ian> jdb Buggy
Initializing jdb...
0xb2:class(Buggy)
> run
run Buggy 
running ...
main[1] 
Uncaught exception: java.lang.NullPointerException
        at Buggy.main(Buggy.java:6)
        at sun.tools.agent.MainThread.runMain(Native Method)
        at sun.tools.agent.MainThread.run(MainThread.java:49)

main[1] list
2          public class Buggy {
3               static String name;
4          
5               public static void main(String[] args) {
6       =>              int n = name.length( );  // bug # 1
7          
8                       System.out.println(n);
9          
10                      name += "; The end.";   // bug #2
main[1] print Buggy.name
Buggy.name = null
main[1] help
** command list **
threads [threadgroup]     -- list threads
thread <thread id>        -- set default thread
suspend [thread id(s)]    -- suspend threads (default: all)
resume [thread id(s)]     -- resume threads (default: all)
where [thread id] | all   -- dump a thread's stack
wherei [thread id] | all  -- dump a thread's stack, with pc info
threadgroups              -- list threadgroups
threadgroup <name>        -- set current threadgroup

print <id> [id(s)]        -- print object or field
dump <id> [id(s)]         -- print all object information

locals                    -- print all local variables in current stack frame

classes                   -- list currently known classes
methods <class id>        -- list a class's methods

stop in <class id>.<method>[(argument_type,...)] -- set a breakpoint in a method
stop at <class id>:<line> -- set a breakpoint at a line
up [n frames]             -- move up a thread's stack
down [n frames]           -- move down a thread's stack
clear <class id>.<method>[(argument_type,...)]   -- clear a breakpoint in a method
clear <class id>:<line>   -- clear a breakpoint at a line
step                      -- execute current line
step up                   -- execute until the current method returns to its caller
stepi                     -- execute current instruction
next                      -- step one line (step OVER calls)
cont                      -- continue execution from breakpoint

catch <class id>          -- break for the specified exception
ignore <class id>         -- ignore when the specified exception

list [line number|method] -- print source code
use [source file path]    -- display or change the source path

memory                    -- report memory usage
gc                        -- free unused objects

load classname            -- load Java class to be debugged
run <class> [args]        -- start execution of a loaded Java class
!!                        -- repeat last command
help (or ?)               -- list commands
exit (or quit)            -- exit debugger
main[1] exit
ian>

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Unit Testing: Avoid the Need for Debuggers

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You don't want to have to debug your code.

Use unit testing to validate each class as you develop it.

Stopping to use a debugger is time-consuming; it's better to test beforehand. The methodology of unit testing has been around for a long time but has been overshadowed by newer methodologies. Unit testing is a tried and true means of getting your code tested in small blocks. Typically, in an OO language like Java, unit testing is applied to individual classes, in contrast to "black box" testing where the entire application is tested.

I have long been an advocate of this very basic testing methodology. Indeed, developers of the software methodology known as Extreme Programming (XP for short; see http://www.extremeprogramming.org) advocate writing the unit tests before you write the code, and they also advocate running your tests almost every time you compile. This group of extremists has some very well-known leaders, including Gamma and Beck of Design Patterns fame. I definitely go along with their advocacy of unit testing.

Indeed, many of my classes come with a "built-in" unit test. Classes that are not main programs in their own right often include a main method that just tests out the functionality of the class. Here is an example:

/** A simple class used to demonstrate unit testing. */
public class Person {
    protected String fullName;
    protected String firstName, lastName;

    /** Construct a Person using his/her first+last names. */
    public Person(String firstName, String lastName) {
        this.firstName = firstName;
        this.lastName = lastName;
    }

    /** Get the person's full name */
    public String getFullName( ) {
        if (fullName != null)
            return fullName;
        return firstName + " " + lastName;
    }

    /** Simple test program. */
    public static void main(String[] argv) {
        Person p = new Person("Ian", "Darwin");
        String f = p.getFullName( );
        if (!f.equals("Ian Darwin"))
            throw new IllegalStateException("Name concatenation broken");
        System.out.println("Fullname " + f + " looks good");
    }
}

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Getting Readable Tracebacks

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You're getting an exception stack trace at runtime, but most of the important parts don't have line numbers.

Be sure you have compiled with debugging enabled. On older systems, disable JIT and run it again, or use the current HotSpot runtime.

When a Java program throws an exception, the exception propagates up the call stack until there is a catch clause that matches it. If none is found, the Java interpreter program that invoked your

main(
)

method catches the exception and prints a stack traceback showing all the method calls that got from the top of the program to the place where the exception was thrown. You can print this traceback yourself in any catch clause: the Throwable class has several methods called printStackTrace( ).

The traceback includes line numbers only if they were compiled in. When using Sun's javac, this is the default. When using Ant's javac task, this is not the default; you must be sure you have used <javac debug="true" ...> in your build.xml file if you want line numbers.

The Just-In-Time (JIT) translation process consists of having the Java runtime convert part of your compiled class file into machine language so that it can run at full execution speed. This is a necessary step for making Java programs run under interpretation and still be acceptably fast. However, in the early days of Java, its one drawback was that it generally lost the line numbers. Hence, when your program died, you still got a stack traceback but it no longer showed the line numbers where the error occurred. So we have the trade-off of making the program run faster, but harder to debug. Modern versions of Sun's Java runtime include the HotSpot Just-In-Time translator, which doesn't have this problem.

If you're still using an older (or non-Sun) JIT, there is a way around this. If the program is getting a stack traceback and you want to make it readable, you need only disable the JIT processing. How you do this depends upon what release of Java you are using. On JDK 1.2 and above, you need only set the environment variable JAVA_COMPILER to the value NONE, using the appropriate

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Finding More Java Source Code

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want even more Java code examples to look at.

Use The Source, Luke.

Java source code is everywhere. As mentioned in the Preface, all the code examples from this book can be downloaded from the O'Reilly site (http://java.oreilly.com/). What I didn't tell you, but what you might have realized by extension, is that the source examples from all the O'Reilly Java books are available there, too: the examples from Java Examples in a Nutshell, Java Swing—all of them.

Another valuable resource is the source code for the Java API. You may not have realized it, but the source code for all the public parts of the Java API are included with each release of the Java Development Kit. Want to know how java.util.ArrayList actually works? You have the source code. Got a problem making a JTable behave? Sun's JDK includes the source for all the public classes! Look for a file called src.zip or src.jar ; some versions unzip this and some do not.

If that's not enough, you can get the source for the whole JDK for free over the Internet, just by committing to the Sun Java Community Source License and downloading a large file. This includes the source for the public and non-public parts of the API, as well as the compiler (written in Java) and a large body of code written in C/C++ (the runtime itself and the interfaces to the native library). For example, java.io.Reader has a method called

read(
)

, which reads bytes of data from a file or network connection. This is written in C because it actually calls the read( ) system call for Unix, Windows, Mac OS, BeOS, or whatever. The JDK source kit includes the source for all this stuff.

And ever since the early days of Java, there have been a number of web sites set up to distribute free software or open source Java, just as with most other modern "evangelized" languages, such as Perl, Python, Tk/Tcl, and others. (In fact, if you need native code to deal with some oddball filesystem mechanism in a portable way, beyond the material in Chapter 11 of this book, the source code for these runtime systems might be a good place to look.)

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Program: Debug

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Most of the chapters of this book end with a "Program" recipe that illustrates some aspect of the material covered in the chapter. Example 1-2 is the source code for the Debug utility mentioned in Recipe 1.11.

Example 1-2. Debug.java

package com.darwinsys.util;

/** Utilities for debugging
 */
public class Debug {
    /** Static method to see if a given category of debugging is enabled.
     * Enable by setting e.g., -Ddebug.fileio to debug file I/O operations.
     * Use like this:<BR>
     * if (Debug.isEnabled("fileio"))<BR>
     *     System.out.println("Starting to read file " + fileName);
     */
    public static boolean isEnabled(String category) {
        return System.getProperty("debug." + category) != null;
    }

    /** Static method to println a given message if the
     * given category is enabled for debugging.
     */
    public static void println(String category, String msg) {
        if (isEnabled(category))
            System.out.println(msg);
    }
    /** Same thing but for non-String objects (think of the other
     * form as an optimization of this).
     */
    public static void println(String category, Object stuff) {
        println(category, stuff.toString( ));
    }
}

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Chapter 2: Interacting with the Environment

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

This chapter describes how your Java program can deal with its immediate surroundings, with what we call the runtime environment . In one sense, everything you do in a Java program using almost any Java API involves the environment. Here we focus more narrowly on things that directly surround your program. Along the way we'll meet the System class, which knows a lot about your particular system.

Two other runtime classes deserve brief mention. The first, java.lang.Runtime , lies behind many of the methods in the System class.

System.exit(
)

, for example, just calls

Runtime.exit(
)

. It is technically part of "the environment," but the only time we use it directly is to run other programs, which is covered in Recipe 26.1. The java.awt.Toolkit object is also part of the environment and is discussed in Chapter 13.

You want to get the value of "environment variables" from within your Java program.

Don't (JDK 1.4 and earlier). Go ahead, but be careful (JDK 1.5).

The seventh edition of Unix, released in 1979, had an exciting new feature known as environment variables. Environment variables are in all modern Unix systems (including Mac OS X) and in most later command-line systems, such as the DOS subsystem underlying Windows, but are not in some older platforms or other Java runtimes. Environment variables are commonly used for customizing an individual computer user's runtime environment, hence the name. To take one familiar example, on Unix or DOS the environment variable PATH determines where the system looks for executable programs. So of course the issue comes up: "How do I get at environment variables from my Java program?"

The answer is that you can do this in some versions of Java, but you shouldn't. Java is designed to be a portable runtime environment. As such, you should not depend on operating system features that don't exist on every single Java platform. I just mentioned several Java platforms that don't have environment variables.

Section : 1.4 and earlier

Oh, all right, if you insist. Let's try it out using a

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Introduction

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Two other runtime classes deserve brief mention. The first, java.lang.Runtime , lies behind many of the methods in the System class.

System.exit(
)

, for example, just calls

Runtime.exit(
)

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Getting Environment Variables

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to get the value of "environment variables" from within your Java program.

Don't (JDK 1.4 and earlier). Go ahead, but be careful (JDK 1.5).

Section : 1.4 and earlier

Oh, all right, if you insist. Let's try it out using a static method called

getenv(
)

in class java.lang.System . But remember, you made me do it. First, the code. All we need is the little program shown in Example 2-1.

Example 2-1. GetEnv.java

public class GetEnv {
       public static void main(String[] argv) {
               System.out.println("System.getenv(\"PATH\") = " + System.getenv("PATH"));
       }
}

Let's try compiling it:

C:\javasrc>javac GetEnv.java
Note: GetEnv.java uses or overrides a deprecated API. Recompile with -deprecation for 
details.

That message is seldom welcome news. We'll do as it says:

C:\javasrc>javac -deprecation GetEnv.java
GetEnv.java:9: Note: The method java.lang.String getenv(java.lang.String) in class 
java.lang.System has been deprecated.
System.out.println("System.getenv(\"PATH\") = " + System.getenv("PATH"));
                                                         ^
Note: GetEnv.java uses or overrides a deprecated API.  Please consult the 
documentation for a better alternative.
1 warning

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

System Properties

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You need to get information from the system properties.

Use

System.getProperty(
)

System.getProperties(
)

What is a property anyway? A property is just a name and value pair stored in a java.util.Properties object, which we discuss more fully in Recipe 7.7. So if I chose to, I could store the following properties in a Properties object called ian:

name=Ian Darwin
favorite_popsicle=cherry
favorite_rock group=Fleetwood Mac
favorite_programming_language=Java
pencil color=green

The Properties class has several forms of its retrieval method. You could, for example, say ian.getProperty("pencil color") and get back the string "green". You can also provide a default: say ian.getProperty("pencil color", "black"), and, if the property has not been set, you get the default value "black".

For now, we're concerned with the System class and its role as keeper of the particular Properties object that controls and describes the Java runtime. The System class has a static Properties member whose content is the merger of operating system specifics (os.name, for example), system and user tailoring (java.class.path), and properties defined on the command line (as we'll see in a moment). Note that the use of periods in these names (like os.arch, os.version, java.class.path, and java.lang.version) makes it look as though there is a hierarchical relationship similar to that for class names. The Properties class, however, imposes no such relationships: each key is just a string, and dots are not special.

To retrieve one system-provided property, use System.getProperty( ). If you want them all, use System.getProperties( ). Accordingly, if I wanted to find out if the System Properties had a property named "pencil color", I could say:

String color = System.getProperty("pencil color");

But what does that return? Surely Java isn't clever enough to know about everybody's favorite pencil color? Right you are! But we can easily tell Java about our pencil color (or anything else we want to tell it) using the

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Writing JDK Release-Dependent Code

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You need to write code that depends on the JDK release.

Don't do this.

Although Java is meant to be portable, Java runtimes have some significant variations. Sometimes you need to work around a feature that may be missing in older runtimes, but you want to use it if it's present. So one of the first things you want to know is how to find out the JDK release corresponding to the Java runtime. This is easily obtained with System.getProperty( ):

System.out.println(System.getProperty("java.specification.version"));

Accordingly, you may want to test for the presence or absence of particular classes. One way to do this is with Class.forName("class") , which throws an exception if the class cannot be loaded—a good indication that it's not present in the runtime's library. Here is code for this, from an application wanting to find out whether the JDK 1.1 or later components are avai