In a perfect world, users would never enter data in the wrong form, files they choose to open would always exist, and code would never have bugs. So far, we have mostly presented code as though we lived in this kind of perfect world. It is now time to turn to the mechanisms the Java programming language has for dealing with the real world of bad data and buggy code.
Encountering errors is unpleasant. If a user loses all the work he or she did during a program session because of a programming mistake or some external circumstance, that user may forever turn away from your program. At the very least, you must
Notify the user of an error;
Save all work;
Allow users to gracefully exit the program.
For exceptional situations, such as bad input data with the potential to bomb the program, Java uses a form of error trapping called, naturally enough, exception handling. Exception handling in Java is similar to that in C++ or Delphi. The first part of this chapter covers Java’s exceptions.
The second part of this chapter concerns finding bugs in your code before they cause exceptions at run time. Unfortunately, if you use just the JDK, then bug detection is the same as it was back in the Dark Ages. We give you some tips and a few tools to ease the pain. Then, we explain how to use the command-line debugger as a tool of last resort.
For the serious Java developer, products such as Eclipse, NetBeans, and JBuilder have quite useful debuggers. We introduce you to the Eclipse debugger.
Suppose an error occurs while a Java program is running. The error might be caused by a file containing wrong information, a flaky network connection, or (we hate to mention it) use of an invalid array index or an attempt to use an object reference that hasn’t yet been assigned to an object. Users expect that programs will act sensibly when errors happen. If an operation cannot be completed because of an error, the program ought to either
Return to a safe state and enable the user to execute other commands; or
Allow the user to save all work and terminate the program gracefully.
This may not be easy to do, because the code that detects (or even causes) the error condition is usually far removed from the code that can roll back the data to a safe state or the code that can save the user’s work and exit cheerfully. The mission of exception handling is to transfer control from where the error occurred to an error handler that can deal with the situation. To handle exceptional situations in your program, you must take into account the errors and problems that may occur. What sorts of problems do you need to consider?
User input errors. In addition to the inevitable typos, some users like to blaze their own trail instead of following directions. Suppose, for example, that a user asks to connect to a URL that is syntactically wrong. Your code should check the syntax, but suppose it does not. Then the network package will complain.
Device errors. Hardware does not always do what you want it to. The printer may be turned off. A web page may be temporarily unavailable. Devices will often fail in the middle of a task. For example, a printer may run out of paper in the middle of a printout.
Physical limitations. Disks can fill up; you can run out of available memory.
Code errors. A method may not perform correctly. For example, it could deliver wrong answers or use other methods incorrectly. Computing an invalid array index, trying to find a nonexistent entry in a hash table, and trying to pop an empty stack are all examples of a code error.
The traditional reaction to an error in a method is to return a special error code that the calling method analyzes. For example, methods that read information back from files often return a –1 end-of-file value marker rather than a standard character. This can be an efficient method for dealing with many exceptional conditions. Another common return value to denote an error condition is the null
reference. In Chapter 10, you saw an example of this with the getParameter
method of the Applet
class that returns null
if the queried parameter is not present.
Unfortunately, it is not always possible to return an error code. There may be no obvious way of distinguishing valid and invalid data. A method returning an integer cannot simply return –1 to denote the error—the value –1 might be a perfectly valid result.
Instead, as we mentioned back in Chapter 5, Java allows every method an alternative exit path if it is unable to complete its task in the normal way. In this situation, the method does not return a value. Instead, it throws an object that encapsulates the error information. Note that the method exits immediately; it does not return its normal (or any) value. Moreover, execution does not resume at the code that called the method; instead, the exception-handling mechanism begins its search for an exception handler that can deal with this particular error condition.
Exceptions have their own syntax and are part of a special inheritance hierarchy. We take up the syntax first and then give a few hints on how to use this language feature effectively.
In the Java programming language, an exception object is always an instance of a class derived from Throwable
. As you will soon see, you can create your own exception classes if the ones built into Java do not suit your needs.
Figure 11–1 is a simplified diagram of the exception hierarchy in Java.
Notice that all exceptions descend from Throwable
, but the hierarchy immediately splits into two branches: Error
and Exception
.
The Error
hierarchy describes internal errors and resource exhaustion inside the Java runtime system. You should not throw an object of this type. There is little you can do if such an internal error occurs, beyond notifying the user and trying to terminate the program gracefully. These situations are quite rare.
When doing Java programming, you focus on the Exception
hierarchy. The Exception
hierarchy also splits into two branches: exceptions that derive from RuntimeException
and those that do not. The general rule is this: A RuntimeException
happens because you made a programming error. Any other exception occurs because a bad thing, such as an I/O error, happened to your otherwise good program.
Exceptions that inherit from RuntimeException
include such problems as
Exceptions that do not inherit from RuntimeException
include
Trying to read past the end of a file;
Trying to open a malformed URL;
Trying to find a Class
object for a string that does not denote an existing class.
The rule “If it is a RuntimeException
, it was your fault” works pretty well. You could have avoided that ArrayIndexOutOfBoundsException
by testing the array index against the array bounds. The NullPointerException
would not have happened had you checked whether the variable was null
before using it.
How about a malformed URL? Isn’t it also possible to find out whether it is “malformed” before using it? Well, different browsers can handle different kinds of URLs. For example, Netscape can deal with a mailto:
URL, whereas the applet viewer cannot. Thus, the notion of “malformed” depends on the environment, not just on your code.
The Java Language Specification calls any exception that derives from the class Error
or the class RuntimeException
an unchecked exception. All other exceptions are called checked exceptions. This is useful terminology that we also adopt. The compiler checks that you provide exception handlers for all checked exceptions.
The name RuntimeException
is somewhat confusing. Of course, all of the errors we are discussing occur at run time.
If you are familiar with the (much more limited) exception hierarchy of the standard C++ library, you will be really confused at this point. C++ has two fundamental exception classes, runtime_error
and logic_error
. The logic_error
class is the equivalent of Java’s RuntimeException
and also denotes logical errors in the program. The runtime_error
class is the base class for exceptions caused by unpredictable problems. It is equivalent to exceptions in Java that are not of type RuntimeException
.
A Java method can throw an exception if it encounters a situation it cannot handle. The idea is simple: a method will not only tell the Java compiler what values it can return, it is also going to tell the compiler what can go wrong. For example, code that attempts to read from a file knows that the file might not exist or that it might be empty. The code that tries to process the information in a file therefore will need to notify the compiler that it can throw some sort of IOException
.
The place in which you advertise that your method can throw an exception is the header of the method; the header changes to reflect the checked exceptions the method can throw. For example, here is the declaration of one of the constructors of the FileInputStream
class from the standard library. (See Chapter 12 for more on streams.)
public FileInputStream(String name) throws FileNotFoundException
The declaration says that this constructor produces a FileInputStream
object from a String
parameter but that it also can go wrong in a special way—by throwing a FileNotFoundException
. If this sad state should come to pass, the constructor call will not initialize a new FileInputStream
object but instead will throw an object of the FileNotFoundException
class. If it does, then the runtime system will begin to search for an exception handler that knows how to deal with FileNotFoundException
objects.
When you write your own methods, you don’t have to advertise every possible throwable object that your method might actually throw. To understand when (and what) you have to advertise in the throws
clause of the methods you write, keep in mind that an exception is thrown in any of the following four situations:
You call a method that throws a checked exception, for example, the FileInputStream
constructor.
You detect an error and throw a checked exception with the throw
statement (we cover the throw
statement in the next section).
You make a programming error, such as a[-1] = 0
that gives rise to an unchecked exception such as an ArrayIndexOutOfBoundsException
.
An internal error occurs in the virtual machine or runtime library.
If either of the first two scenarios occurs, you must tell the programmers who will use your method about the possibility of an exception. Why? Any method that throws an exception is a potential death trap. If no handler catches the exception, the current thread of execution terminates.
As with Java methods that are part of the supplied classes, you declare that your method may throw an exception with an exception specification in the method header.
class MyAnimation
{
. . .
public Image loadImage(String s) throws IOException
{
. . .
}
}
If a method might throw more than one checked exception type, you must list all exception classes in the header. Separate them by a comma as in the following example:
class MyAnimation
{
. . .
public Image loadImage(String s) throws EOFException, MalformedURLException
{
. . .
}
}
However, you do not need to advertise internal Java errors, that is, exceptions inheriting from Error
. Any code could potentially throw those exceptions, and they are entirely beyond your control.
Similarly, you should not advertise unchecked exceptions inheriting from RuntimeException
.
class MyAnimation
{
. . .
void drawImage(int i) throws ArrayIndexOutOfBoundsException // bad style
{
. . .
}
}
These runtime errors are completely under your control. If you are so concerned about array index errors, you should spend the time needed to fix them instead of advertising the possibility that they can happen.
In summary, a method must declare all the checked exceptions that it might throw. Unchecked exceptions are either beyond your control (Error
) or result from conditions that you should not have allowed in the first place (RuntimeException
). If your method fails to faithfully declare all checked exceptions, the compiler will issue an error message.
Of course, as you have already seen in quite a few examples, instead of declaring the exception, you can also catch it. Then the exception won’t be thrown out of the method, and no throws
specification is necessary. You see later in this chapter how to decide whether to catch an exception or to enable someone else to catch it.
If you override a method from a superclass, the checked exceptions that the subclass method declares cannot be more general than those of the superclass method. (It is Ok to throw more specific exceptions, or not to throw any exceptions in the subclass method.) In particular, if the superclass method throws no checked exception at all, neither can the subclass. For example, if you override JComponent.paintComponent
, your paintComponent
method must not throw any checked exceptions, because the superclass method doesn’t throw any.
When a method in a class declares that it throws an exception that is an instance of a particular class, then it may throw an exception of that class or of any of its subclasses. For example, the FileInputStream
constructor could have declared that it throws an IOException
. In that case, you would not have known what kind of IOException
. It could be a plain IOException
or an object of one of the various subclasses, such as FileNotFoundException
.
The throws
specifier is the same as the throw
specifier in C++, with one important difference. In C++, throw
specifiers are enforced at run time, not at compile time. That is, the C++ compiler pays no attention to exception specifications. But if an exception is thrown in a function that is not part of the throw
list, then the unexpected
function is called, and, by default, the programterminates.
Also, in C++, a function may throw any exception if no throw
specification is given. In Java, a method without a throws
specifier may not throw any checked exception at all.
Let us suppose something terrible has happened in your code. You have a method, readData
, that is reading in a file whose header promised
Content-length: 1024
But, you get an end of file after 733 characters. You decide this situation is so abnormal that you want to throw an exception.
You need to decide what exception type to throw. Some kind of IOException
would be a good choice. Perusing the Java API documentation, you find an EOFException
with the description “Signals that an EOF has been reached unexpectedly during input.” Perfect. Here is how you throw it:
throw new EOFException();
or, if you prefer,
EOFException e = new EOFException(); throw e;
Here is how it all fits together:
String readData(Scanner in) throws EOFException { . . . while (. . .) { if (!in.hasNext()) // EOF encountered { if (n < len) throw new EOFException(); } . . . } return s; }
The EOFException
has a second constructor that takes a string argument. You can put this to good use by describing the exceptional condition more carefully.
String gripe = "Content-length: " + len + ", Received: " + n; throw new EOFException(gripe);
As you can see, throwing an exception is easy if one of the existing exception classes works for you. In this case:
Find an appropriate exception class.
Make an object of that class.
Throw it.
Once a method throws an exception, the method does not return to its caller. This means that you do not have to worry about cooking up a default return value or an error code.
Your code may run into a problem that is not adequately described by any of the standard exception classes. In this case, it is easy enough to create your own exception class. Just derive it from Exception
or from a child class of Exception
such as IOException
. It is customary to give both a default constructor and a constructor that contains a detailed message. (The toString
method of the Throwable
superclass prints that detailed message, which is handy for debugging.)
class FileFormatException extends IOException { public FileFormatException() {} public FileFormatException(String gripe) { super(gripe); } }
Now you are ready to throw your very own exception type.
String readData(BufferedReader in) throws FileFormatException
{
. . .
while (. . .)
{
if (ch == -1) // EOF encountered
{
if (n < len)
throw new FileFormatException();
}
. . .
}
return s;
}
java.lang.Throwable 1.0
Throwable()
constructs a new Throwable
object with no detailed message.
Throwable(String message)
constructs a new Throwable
object with the specified detailed message. By convention, all derived exception classes support both a default constructor and a constructor with a detailed message.
String getMessage()
gets the detailed message of the Throwable
object.
You now know how to throw an exception. It is pretty easy. You throw it and you forget it. Of course, some code has to catch the exception. Catching exceptions requires more planning.
If an exception occurs that is not caught anywhere, the program will terminate and print a message to the console, giving the type of the exception and a stack trace. Graphics programs (both applets and applications) catch exceptions, print stack trace messages, and then go back to the user interface processing loop. (When you are debugging a graphically based program, it is a good idea to keep the console available on the screen and not minimized.)
To catch an exception, you set up a try/catch
block. The simplest form of the try
block is as follows:
try
{
code more code more code}
catch (
ExceptionType e)
{
handler for this type}
If any of the code inside the try
block throws an exception of the class specified in the catch
clause, then
The program skips the remainder of the code in the try
block;
The program executes the handler code inside the catch
clause.
If none of the code inside the try
block throws an exception, then the program skips the catch
clause.
If any of the code in a method throws an exception of a type other than the one named in the catch
clause, this method exits immediately. (Hopefully, one of its callers has already coded a catch
clause for that type.)
To show this at work, we show some fairly typical code for reading in text:
public void read(String filename)
{
try
{
InputStream in = new FileInputStream(filename);
int b;
while ((b = in.read()) !=-1)
{
process input }
}
catch (IOException exception)
{
exception.printStackTrace();
}
}
Notice that most of the code in the try
clause is straightforward: it reads and processes lines until we encounter the end of the file. As you can see by looking at the Java API, there is the possibility that the read
method will throw an IOException
. In that case, we skip out of the entire while
loop, enter the catch
clause and generate a stack trace. For a toy program, that seems like a reasonable way to deal with this exception. What other choice do you have?
Often, the best choice is to do nothing at all and simply pass the exception on to the caller. If an error occurs in the read
method, let the caller of the read
method worry about it! If we take that approach, then we have to advertise the fact that the method may throw an IOException
.
public void read(String filename)
throws IOException
{
InputStream in = new FileInputStream(filename);
int b;
while ((b = in.read()) !=-1)
{
process input }
}
Remember, the compiler strictly enforces the throws
specifiers. If you call a method that throws a checked exception, you must either handle it or pass it on.
Which of the two is better? As a general rule, you should catch those exceptions that you know how to handle and propagate those that you do not know how to handle. When you propagate an exception, you must add a throws
specifier to alert the caller that an exception may be thrown.
Look at the Java API documentation to see what methods throw which exceptions. Then decide whether you should handle them or add them to the throws
list. There is nothing embarrassing about the latter choice. It is better to direct an exception to a competent handler than to squelch it.
Please keep in mind that there is one exception to this rule, as we mentioned earlier. If you are writing a method that overrides a superclass method that throws no exceptions (such as paintComponent
in JComponent
), then you must catch each checked exception in the method’s code. You are not allowed to add more throws
specifiers to a subclass method than are present in the superclass method.
Catching exceptions is almost the same in Java and in C++. Strictly speaking, the analog of
catch (Exception e) // Java
is
catch (Exception& e) // C++
There is no analog to the C++ catch (...)
. This is not needed in Java because all exceptions derive from a common superclass.
You can catch multiple exception types in a try
block and handle each type differently. You use a separate catch
clause for each type as in the following example:
try
{
code that might throw exceptions}
catch (
MalformedURLException e1
)
{
emergency action for malformed URLs}
catch (
UnknownHostException e2
)
{
emergency action for unknown hosts}
catch (
IOException e3
)
{
emergency action for all other I/O problems}
The exception object (e1, e2, e3
) may contain information about the nature of the exception. To find out more about the object, try
e3.getMessage()
to get the detailed error message (if there is one), or
e3.getClass().getName()
to get the actual type of the exception object.
You can throw an exception in a catch
clause. Typically, you do this because you want to change the exception type. If you build a subsystem that other programmers use, it makes a lot of sense to use an exception type that indicates a failure of the subsystem. An example of such an exception type is the ServletException
. The code that executes a servlet may not want to know in minute detail what went wrong, but it definitely wants to know that the servlet was at fault.
Here is how you can catch an exception and rethrow it.
try
{
access the database}
catch (SQLException e)
{
throw new ServletException("database error: " + e.getMessage());
}
Here, the ServletException
is constructed with the message text of the exception. As of JDK 1.4, you can do better than that and set the original exception as the “cause” of the new exception:
try
{
access the database}
catch (SQLException e)
{
Throwable se = new ServletException("database error");
se.setCause(e);
throw se;
}
When the exception is caught, the original exception can be retrieved:
Throwable e = se.getCause();
This wrapping technique is highly recommended. It allows you to throw high-level exceptions in subsystems without losing the details of the original failure.
The wrapping technique is also useful if a checked exception occurs in a method that is not allowed to throw a checked exception. You can catch the checked exception and wrap it into a runtime exception.
A number of exception classes, such as ClassNotFoundException
, InvocationTargetException
, and RuntimeException
, have had their own chaining schemes. As of JDK 1.4, these have been brought into conformance with the “cause” mechanism. You can still retrieve the chained exception in the historical way or just call getCause
. Unfortunately, the chained exception most commonly used by application programmers, SQLException
, has not been retrofitted.
When your code throws an exception, it stops processing the remaining code in your method and exits the method. This is a problem if the method has acquired some local resource that only it knows about and if that resource must be cleaned up. One solution is to catch and rethrow all exceptions. But this solution is tedious because you need to clean up the resource allocation in two places, in the normal code and in the exception code.
Java has a better solution, the finally
clause. Here we show you how to properly dispose of a Graphics
object. If you do any database programming in Java, you will need to use the same techniques to close connections to the database. As you will see in Chapter 4 of Volume 2, it is very important to close all database connections properly, even when exceptions occur.
The code in the finally
clause executes whether or not an exception was caught. In the following example, the program will dispose of the graphics context under all circumstances.
Graphics g = image.getGraphics();
try
{
// 1
code that might throw exceptions // 2
}
catch (IOException e)
{
// 3
show error dialog // 4
}
finally
{
// 5
g.dispose();
}
// 6
Let us look at the three possible situations in which the program will execute the finally
clause.
The code throws no exceptions. In this event, the program first executes all the code in the try
block. Then, it executes the code in the finally
clause. Afterwards, execution continues with the first statement after the try
block. In other words, execution passes through points 1, 2, 5, and 6.
The code throws an exception that is caught in a catch
clause, in our case, an IOException
. For this, the program executes all code in the try
block, up to the point at which the exception was thrown. The remaining code in the try
block is skipped. The program then executes the code in the matching catch
clause, then the code in the finally
clause.
If the catch
clause does not throw an exception, then the program executes the first line after the try
block. In this scenario, execution passes through points 1, 3, 4, 5, and 6.
If the catch
clause throws an exception, then the exception is thrown back to the caller of this method, and execution passes through points 1, 3, and 5 only.
The code throws an exception that is not caught in any catch
clause. For this, the program executes all code in the try
block until the exception is thrown. The remaining code in the try
block is skipped. Then, the code in the finally
clause is executed, and the exception is thrown back to the caller of this method. Execution passes through points 1 and 5 only.
You can use the finally
clause without a catch
clause. For example, consider the following try
statement:
Graphics g = image.getGraphics();
try
{
code that might throw exceptions}
finally
{
g.dispose();
}
The g.dispose()
command in the finally
clause is executed whether or not an exception is encountered in the try
block. Of course, if an exception is encountered, it is rethrown and must be caught in another catch
clause.
In fact, as explained in the following tip, we think it is a very good idea to use the finally
clause in this way.
We strongly suggest that you decouple try/catch
and try/finally
blocks. This makes your code far less confusing. For example,
InputStream in = ...;
try
{
try
{
code that might throw exceptions }
finally
{
in.close();
}
}
catch (IOException e)
{
show error dialog}
The inner try
block has a single responsibility: to make sure that the input stream is closed. The outer try
block has a single responsibility: to ensure that errors are reported. Not only is this solution clearer, it is also more functional: errors in the finally
clause are reported.
A finally
clause can yield unexpected results when it contains return
statements. Suppose you exit the middle of a try
block with a return
statement. Before the method returns, the contents of the finally
block are executed. If the finally
block also contains a return
statement, then it masks the original return value. Consider this contrived example:
public static int f(int n) { try { int r = n * n; return r; } finally { if (n == 2) return 0; } }
If you call f(2)
, then the try
block computes r = 4
and executes the return
statement. However, the finally
clause is executed before the method actually returns. The finally
clause causes the method to return 0, ignoring the original return value of 4.
Sometimes the finally
clause gives you grief, namely if the cleanup method can also throw an exception. A typical case is closing a stream. (See Chapter 12 for more information on streams.) Suppose you want to make sure that you close a stream when an exception hits in the stream processing code.
InputStream in = ...;
try
{
code that might throw exceptions}
catch (IOException e)
{
show error dialog}
finally
{
in.close();
}
Now suppose that the code in the try
block throws some exception other than an IOException
that is of interest to the caller of the code. The finally
block executes, and the close
method is called. That method can itself throw an IOException
! When it does, then the original exception is lost and the IOException
is thrown instead. That is very much against the spirit of exception handling.
It is always a good idea—unfortunately not one that the designers of the InputStream
class chose to follow—to throw no exceptions in cleanup operations such as dispose
, close
, and so on, that you expect users to call in finally
blocks.
There is one fundamental difference between C++ and Java with regard to exception handling. Java has no destructors; thus, there is no stack unwinding as in C++. This means that the Java programmer must manually place code to reclaim resources in finally
blocks. Of course, because Java does garbage collection, there are far fewer resources that require manual deallocation.
A stack trace is a listing of all pending method calls at a particular point in the execution of a program. You have almost certainly seen stack trace listings—they are displayed whenever a Java program terminates with an uncaught exception.
The stack trace only traces back to the statement that throws the exception, not necessarily to the root cause of the error.
Before JDK 1.4, you could access the text description of a stack trace by calling the printStackTrace
method of the Throwable
class. Now you can call the getStackTrace
method to get an array of StackTraceElement
objects that you can analyze in your program. For example,
Throwable t = new Throwable();
StackTraceElement[] frames = t.getStackTrace();
for (StackTraceElement frame : frames)
analyze frame
The StackTraceElement
class has methods to obtain the file name and line number, as well as the class and method name, of the executing line of code. The toString
method yields a formatted string containing all of this information.
JDK 5.0 adds the static Thread.getAllStackTraces
method that yields the stack traces of all threads. Here is how you use that method:
Map<Thread, StackTraceElement[]> map = Thread.getAllStackTraces();
for (Thread t : map.keySet())
{
StackTraceElement[] frames = map.get(t);
analyze frames
}
See Volume 2 for more information on threads and the Map
interface.
Example 11–1 prints the stack trace of a recursive factorial function. For example, if you compute factorial(3)
, the printout is
factorial(3): StackTraceTest.factorial(StackTraceTest.java:8) StackTraceTest.main(StackTraceTest.java:23) factorial(2): StackTraceTest.factorial(StackTraceTest.java:8) StackTraceTest.factorial(StackTraceTest.java:14) StackTraceTest.main(StackTraceTest.java:23) factorial(1): StackTraceTest.factorial(StackTraceTest.java:8) StackTraceTest.factorial(StackTraceTest.java:14) StackTraceTest.factorial(StackTraceTest.java:14) StackTraceTest.main(StackTraceTest.java:23) return 1 return 2 return 6
Example 11–1. StackTraceTest.java
1. import java.util.*; 2. 3. /** 4. A program that displays a trace feature of a recursive 5. method call. 6. */ 7. public class StackTraceTest 8. { 9. /** 10. Computes the factorial of a number 11. @param n a nonnegative integer 12. @return n! = 1 * 2 * . . . * n 13. */ 14. public static int factorial(int n) 15. { 16. System.out.println("factorial(" + n + "):"); 17. Throwable t = new Throwable(); 18. StackTraceElement[] frames = t.getStackTrace(); 19. for (StackTraceElement f : frames) 20. System.out.println(f); 21. int r; 22. if (n <= 1) r = 1; 23. else r = n * factorial(n - 1); 24. System.out.println("return " + r); 25. return r; 26. } 27. 28. public static void main(String[] args) 29. { 30. Scanner in = new Scanner(System.in); 31. System.out.print("Enter n: "); 32. int n = in.nextInt(); 33. factorial(n); 34. } 35. }
java.lang.Throwable 1.0
Throwable(Throwable cause)
1.4
Throwable(String message, Throwable cause)
1.4
construct a Throwable
with a given cause.
Throwable initCause(Throwable cause)
1.4
sets the cause for this object or throws an exception if this object already has a cause. Returns this
.
Throwable getCause()
1.4
gets the exception object that was set as the cause for this object, or null
if no cause was set.
StackTraceElement[] getStackTrace()
1.4
gets the trace of the call stack at the time this object was constructed.
Exception(Throwable cause)
1.4
Exception(String message, Throwable cause)
construct an Exception
with a given cause.
java.lang.RuntimeException 1.0
RuntimeException(Throwable cause)
1.4
RuntimeException(String message, Throwable cause)
1.4
construct a RuntimeException
with a given cause.
java.lang.StackTraceElement 1.4
String getFileName()
gets the name of the source file containing the execution point of this element, or null
if the information is not available.
int getLineNumber()
gets the line number of the source file containing the execution point of this element, or −1 if the information is not available.
String getClassName()
gets the fully qualified name of the class containing the execution point of this element.
String getMethodName()
gets the name of the method containing the execution point of this element. The name of a constructor is <init>
. The name of a static initializer is <clinit>
. You can’t distinguish between overloaded methods with the same name.
boolean isNativeMethod()
returns true
if the execution point of this element is inside a native method.
String toString()
returns a formatted string containing the class and method name and the file name and line number, if available.
Example 11–2 deliberately generates a number of different errors and catches various exceptions (see Figure 11–2).
Try it out. Click on the buttons and see what exceptions are thrown.
As you know, a programmer error such as a bad array index throws a RuntimeException
. An attempt to open a nonexistent file triggers an IOException
. Perhaps surprisingly, floating-point computations such as dividing by 0.0 or taking the square root of −1 do not generate exceptions. Instead, they yield the special “infinity” and “not a number” values that we discussed in Chapter 3. However, integer division by 0 throws an ArithmeticException
.
We trap the exceptions that the actionPerformed
methods throw in the fireActionPerformed
method of the radio buttons and display them in the text field. However, the actionPerformed
method is declared to throw no checked exceptions. Thus, the handler for the “No such file” button must catch the IOException
.
If you click on the “Throw unknown” button, an UnknownError
object is thrown. This is not a subclass of Exception
, so our program does not catch it. Instead, the user interface code prints an error message and a stack trace to the console.
Example 11–2. ExceptTest.java
1. import java.awt.*; 2. import java.awt.event.*; 3. import javax.swing.*; 4. import java.io.*; 5. 6. public class ExceptTest 7. { 8. public static void main(String[] args) 9. { 10. ExceptTestFrame frame = new ExceptTestFrame(); 11. frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE); 12. frame.setVisible(true); 13. } 14. } 15. 16. /** 17. A frame with a panel for testing various exceptions 18. */ 19. class ExceptTestFrame extends JFrame 20. { 21. public ExceptTestFrame() 22. { 23. setTitle("ExceptTest"); 24. ExceptTestPanel panel = new ExceptTestPanel(); 25. add(panel); 26. pack(); 27. } 28. } 29. 30. /** 31. A panel with radio buttons for running code snippets 32. and studying their exception behavior 33. */ 34. class ExceptTestPanel extends Box 35. { 36. public ExceptTestPanel() 37. { 38. super(BoxLayout.Y_AXIS); 39. group = new ButtonGroup(); 40. 41. // add radio buttons for code snippets 42. 43. addRadioButton("Integer divide by zero", new 44. ActionListener() 45. { 46. public void actionPerformed(ActionEvent event) 47. { 48. a[1] = 1 / (a.length - a.length); 49. } 50. }); 51. 52. addRadioButton("Floating point divide by zero", new 53. ActionListener() 54. { 55. public void actionPerformed(ActionEvent event) 56. { 57. a[1] = a[2] / (a[3] - a[3]); 58. } 59. }); 60. 61. addRadioButton("Array bounds", new 62. ActionListener() 63. { 64. public void actionPerformed(ActionEvent event) 65. { 66. a[1] = a[10]; 67. } 68. }); 69. 70. addRadioButton("Bad cast", new 71. ActionListener() 72. { 73. public void actionPerformed(ActionEvent event) 74. { 75. a = (double[])event.getSource(); 76. } 77. }); 78. 79. addRadioButton("Null pointer", new 80. ActionListener() 81. { 82. public void actionPerformed(ActionEvent event) 83. { 84. event = null; 85. System.out.println(event.getSource()); 86. } 87. }); 88. 89. addRadioButton("sqrt(-1)", new 90. ActionListener() 91. { 92. public void actionPerformed(ActionEvent event) 93. { 94. a[1] = Math.sqrt(-1); 95. } 96. }); 97. 98. addRadioButton("Overflow", new 99. ActionListener() 100. { 101. public void actionPerformed(ActionEvent event) 102. { 103. a[1] = 1000 * 1000 * 1000 * 1000; 104. int n = (int) a[1]; 105. } 106. }); 107. 108. addRadioButton("No such file", new 109. ActionListener() 110. { 111. public void actionPerformed(ActionEvent event) 112. { 113. try 114. { 115. InputStream in = new FileInputStream("woozle.txt"); 116. } 117. catch (IOException e) 118. { 119. textField.setText(e.toString()); 120. } 121. } 122. }); 123. 124. addRadioButton("Throw unknown", new 125. ActionListener() 126. { 127. public void actionPerformed(ActionEvent event) 128. { 129. throw new UnknownError(); 130. } 131. }); 132. 133. // add the text field for exception display 134. textField = new JTextField(30); 135. add(textField); 136. } 137. 138. /** 139. Adds a radio button with a given listener to the 140. panel. Traps any exceptions in the actionPerformed 141. method of the listener. 142. @param s the label of the radio button 143. @param listener the action listener for the radio button 144. */ 145. private void addRadioButton(String s, ActionListener listener) 146. { 147. JRadioButton button = new JRadioButton(s, false) 148. { 149. // the button calls this method to fire an 150. // action event. We override it to trap exceptions 151. protected void fireActionPerformed(ActionEvent event) 152. { 153. try 154. { 155. textField.setText("No exception"); 156. super.fireActionPerformed(event); 157. } 158. catch (Exception e) 159. { 160. textField.setText(e.toString()); 161. } 162. } 163. }; 164. 165. button.addActionListener(listener); 166. add(button); 167. group.add(button); 168. } 169. 170. private ButtonGroup group; 171. private JTextField textField; 172. private double[] a = new double[10]; 173. }
There is a certain amount of controversy about the proper use of exceptions. Some programmers believe that all checked exceptions are a nuisance, others can’t seem to throw enough of them. We think that exceptions (even checked exceptions) have their place, and offer you these tips for their proper use.
Exception handling is not supposed to replace a simple test.
As an example of this, we wrote some code that uses the built-in Stack
class. The code in Example 11–3 tries 1,000,000 times to pop an empty stack. It first does this by finding out whether the stack is empty.
if (!s.empty()) s.pop();
Next, we tell it to pop the stack no matter what. Then, we catch the EmptyStackException
that tells us that we should not have done that.
try() { s.pop(); } catch (EmptyStackException e) { }
On our test machine, we got the timing data in Table 11–1.
As you can see, it took far longer to catch an exception than it did to perform a simple test. The moral is: Use exceptions for exceptional circumstances only.
Do not micromanage exceptions.
Many programmers wrap every statement in a separate try
block.
OutputStream out; Stack s; for (i = 0; i < 100; i++) { try { n = s.pop(); } catch (EmptyStackException s) { // stack was empty } try { out.writeInt(n); } catch (IOException e) { // problem writing to file } }
This approach blows up your code dramatically. Think about the task that you want the code to accomplish. Here we want to pop 100 numbers off a stack and save them to a file. (Never mind why—it is just a toy example.) There is nothing we can do if a problem rears its ugly head. If the stack is empty, it will not become occupied. If the file contains an error, the error will not magically go away. It therefore makes sense to wrap the entire task in a try
block. If any one operation fails, you can then abandon the task.
try { for (i = 0; i < 100; i++) { n = s.pop(); out.writeInt(n); } } catch (IOException e) { // problem writing to file } catch (EmptyStackException s) { // stack was empty }
This code looks much cleaner. It fulfills one of the promises of exception handling, to separate normal processing from error handling.
Make good use of the exception hierarchy.
Don’t just throw a RuntimeException
. Find an appropriate subclass or create your own.
Don’t just catch Throwable
. It makes your code hard to read and maintain.
Respect the difference between checked and unchecked exceptions. Checked exceptions are inherently burdensome—don’t throw them for logic errors. (For example, the reflection library gets this wrong. Callers often need to catch exceptions that they know can never happen.)
Do not hesitate to turn an exception into another exception that is more appropriate. For example, when you parse an integer in a file, catch the NumberFormatException
and turn it into a subclass of IOException
or MySubsystemException
.
Do not squelch exceptions.
In Java, there is the tremendous temptation to shut up exceptions. You write a method that calls a method that might throw an exception once a century. The compiler whines because you have not declared the exception in the throws
list of your method. You do not want to put it in the throws
list because then the compiler will whine about all the methods that call your method. So you just shut it up:
public Image loadImage(String s)
{
try
{
code that threatens to throw checked exceptions }
catch (Exception e)
{} // so there
}
Now your code will compile without a hitch. It will run fine, except when an exception occurs. Then, the exception will be silently ignored. If you believe that exceptions are at all important, you should make some effort to handle them right.
When you detect an error, “tough love“ works better than indulgence.
Some programmers worry about throwing exceptions when they detect errors. Maybe it would be better to return a dummy value rather than throw an exception when a method is called with invalid parameters. For example, should Stack.pop
return null
rather than throw an exception when a stack is empty? We think it is better to throw a EmptyStackException
at the point of failure than to have a NullPointerException
occur at later time.
Propagating exceptions is not a sign of shame.
Many programmers feel compelled to catch all exceptions that are thrown. If they call a method that throws an exception, such as the FileInputStream
constructor or the readLine
method, they instinctively catch the exception that may be generated. Often, it is actually better to propagate the exception instead of catching it:
public void readStuff(String filename) throws IOException // not a sign of shame! { InputStream in = new FileInputStream(filename); . . . }
Higher-level methods are often better equipped to inform the user of errors or to abandon unsuccessful commands.
Example 11–3. ExceptionalTest.java
1. import java.util.*; 2. 3. public class ExceptionalTest 4. { 5. public static void main(String[] args) 6. { 7. int i = 0; 8. int ntry = 1000000; 9. Stack s = new Stack(); 10. long s1; 11. long s2; 12. 13. // test a stack for emptiness ntry times 14. System.out.println("Testing for empty stack"); 15. s1 = new Date().getTime(); 16. for (i = 0; i <= ntry; i++) 17. if (!s.empty()) s.pop(); 18. s2 = new Date().getTime(); 19. System.out.println((s2 - s1) + " milliseconds"); 20. 21. // pop an empty stack ntry times and catch the 22. // resulting exception 23. System.out.println("Catching EmptyStackException"); 24. s1 = new Date().getTime(); 25. for (i = 0; i <= ntry; i++) 26. { 27. try 28. { 29. s.pop(); 30. } 31. catch(EmptyStackException e) 32. { 33. } 34. } 35. s2 = new Date().getTime(); 36. System.out.println((s2 - s1) + " milliseconds"); 37. } 38. }
Every Java programmer is familiar with the process of inserting calls to System.out.println
into troublesome code to gain insight into program behavior. Of course, once you have figured out the cause of trouble, you remove the print statements, only to put them back in when the next problem surfaces. The logging API of JDK 1.4 is designed to overcome this problem. Here are the principal advantages of the API.
It is easy to suppress all log records or just those below a certain level, and just as easy to turn them back on.
Suppressed logs are very cheap, so that there is only a minimal penalty for leaving the logging code in your application.
Log records can be directed to different handlers, for display in the console, for storage in a file, and so on.
Both loggers and handlers can filter records. Filters discard boring log entries, using any criteria supplied by the filter implementor.
Log records can be formatted in different ways, for example, in plain text or XML.
Applications can use multiple loggers, with hierarchical names such as com.mycompany.myapp
, similar to package names.
By default, the logging configuration is controlled by a configuration file. Applications can replace this mechanism if desired.
Let’s get started with the simplest possible case. The logging system manages a default logger Logger.global
that you can use instead of System.out
. Use the info
method to log an information message:
Logger.global.info("File->Open menu item selected");
By default, the record is printed like this:
May 10, 2004 10:12:15 PM LoggingImageViewer fileOpen INFO: File->Open menu item selected
(Note that the time and the names of the calling class and method are automatically included.) But if you call
Logger.global.setLevel(Level.OFF);
at an appropriate place (such as the beginning of main
), then all logging is suppressed.
Now that you have seen “logging for dummies,” let’s go on to industrial-strength logging. In a professional application, you wouldn’t want to log all records to a single global logger. Instead, you can define your own loggers.
When you request a logger with a given name for the first time, it is created.
Logger myLogger = Logger.getLogger("com.mycompany.myapp");
Subsequent calls to the same name yield the same logger object.
Similar to package names, logger names are hierarchical. In fact, they are more hierarchical than packages. There is no semantic relationship between a package and its parent, but logger parents and children share certain properties. For example, if you set the log level on the logger "com.mycompany"
, then the child loggers inherit that level.
There are seven logging levels:
SEVERE
WARNING
INFO
CONFIG
FINE
FINER
FINEST
By default, the top three levels are actually logged. You can set a different level, for example,
logger.setLevel(Level.FINE);
Now all levels of FINE
and higher are logged.
You can also use Level.ALL
to turn on logging for all levels or Level.OFF
to turn all logging off.
There are logging methods for all levels, such as
logger.warning(message); logger.fine(message);
and so on. Alternatively, you can use the log
method and supply the level, such as
logger.log(Level.FINE, message);
The default logging configuration logs all records with level of INFO
or higher. Therefore, you should use the levels CONFIG
, FINE
, FINER
, and FINEST
for debugging messages that are useful for diagnostics but meaningless to the program user.
If you set the logging level to a value finer than INFO
, then you also need to change the log handler configuration. The default log handler suppresses messages below INFO
. See the next section for details.
The default log record shows the name of the class and method that contain the logging call, as inferred from the call stack. However, if the virtual machine optimizes execution, accurate call information may not be available. You can use the logp
method to give the precise location of the calling class and method. The method signature is
void logp(Level l, String className, String methodName, String message)
There are convenience methods for tracing execution flow:
void entering(String className, String methodName) void entering(String className, String methodName, Object param) void entering(String className, String methodName, Object[] params) void exiting(String className, String methodName) void exiting(String className, String methodName, Object result)
For example,
int read(String file, String pattern) { logger.entering("com.mycompany.mylib.Reader", "read", new Object[] { file, pattern }); . . . logger.exiting("com.mycompany.mylib.Reader", "read", count); return count; }
These calls generate log records of level FINER
that start with the strings ENTRY
and RETURN
.
At some point in the future, the logging methods will be rewritten to support variable parameter lists (“varargs”). Then you will be able to make calls such as logger.entering("com.mycompany.mylib.Reader", "read", file, pattern)
.
A common use for logging is to log unexpected exceptions. Two convenience methods include a description of the exception in the log record.
void throwing(String className, String methodName, Throwable t) void log(Level l, String message, Throwable t)
Typical uses are
if (. . .) { IOException exception = new IOException(". . ."); logger.throwing("com.mycompany.mylib.Reader", "read", exception); throw exception; }
and
try { . . . } catch (IOException e) { Logger.getLogger("com.mycompany.myapp").log(Level.WARNING, "Reading image", e); }
The throwing
call logs a record with level FINER
and a message that starts with THROW
.
You can change various properties of the logging system by editing a configuration file. The default configuration file is located at
jre/lib/logging.properties
To use another file, set the java.util.logging.config.file
property to the file location by starting your application with
java -Djava.util.logging.config.file=
configFile MainClass
Calling System.setProperty("java.util.logging.config.file", file)
in main
has no effect because the log manager is initialized during VM startup, before main
executes.
To change the default logging level, edit the configuration file and modify the line
.level=INFO
You can specify the logging levels for your own loggers by adding lines such as
com.mycompany.myapp.level=FINE
That is, append the .level
suffix to the logger name.
As you see later in this section, the loggers don’t actually send the messages to the console—that is the job of the handlers. Handlers also have levels. To see FINE
messages on the console, you also need to set
java.util.logging.ConsoleHandler.level=FINE
The settings in the log manager configuration are not system properties. Starting a program with -Dcom.mycompany.myapp.level=FINE
does not have any influence on the logger.
The logging properties file is processed by the java.util.logging.LogManager
class. It is possible to specify a different log manager by setting the java.util.logging.manager
system property to the name of a subclass. Alternatively, you can keep the standard log manager and still bypass the initialization from the logging properties file. Set the java.util.logging.config.class
system property to the name of a class that sets log manager properties in some other way. See the API documentation for the LogManager
class for more information.
You may want to localize logging messages so that they are readable for international users. Internationalization of applications is the topic of Chapter 10 of Volume 2. Briefly, here are the points to keep in mind when localizing logging messages.
Localized applications contain locale-specific information in resource bundles. A resource bundle consists of a set of mappings for various locales (such as United States or Germany). For example, a resource bundle may map the string "readingFile"
into strings "Reading file"
in English or "Achtung! Datei wird eingelesen"
in German.
A program may contain multiple resource bundles, perhaps one for menus and another for log messages. Each resource bundle has a name (such as "com.mycompany.logmessages"
). To add mappings to a resource bundle, you supply a file for each locale. English message mappings are in a file com/mycompany/logmessages_en.properties
, and German message mappings are in a file com/mycompany/logmessages_de.properties
. (The en
, de
codes are the language codes.) You place the files together with the class files of your application, so that the ResourceBundle
class will automatically locate them. These files are plain text files, consisting of entries such as
readingFile=Achtung! Datei wird eingelesen renamingFile=Datei wird umbenannt ...
When requesting a logger, you can specify a resource bundle:
Logger logger = Logger.getLogger(loggerName, "com.mycompany.logmessages");
Then you specify the resource bundle key, not the actual message string, for the log message.
logger.info("readingFile");
You often need to include arguments into localized messages. Then the message should contain placeholders {0}
, {1}
, and so on. For example, to include the file name with a log message, include the placeholder like this:
Reading file {0}. Achtung! Datei {0} wird eingelesen.
You then pass values into the placeholders by calling one of the following methods:
logger.log(Level.INFO, "readingFile", fileName); logger.log(Level.INFO, "renamingFile", new Object[] { oldName, newName });
By default, loggers send records to a ConsoleHandler
that prints them to the System.err
stream. Specifically, the logger sends the record to the parent handler, and the ultimate ancestor (with name ""
) has a ConsoleHandler
.
Like loggers, handlers have a logging level. For a record to be logged, its logging level must be above the threshold of both the logger and the handler. The log manager configuration file sets the logging level of the default console handler as
java.util.logging.ConsoleHandler.level=INFO
To log records with level FINE
, change both the default logger level and the handler level in the configuration. Alternatively, you can bypass the configuration file altogether and install your own handler.
Logger logger = Logger.getLogger("com.mycompany.myapp"); logger.setLevel(Level.FINE); logger.setUseParentHandlers(false); Handler handler = new ConsoleHandler(); handler.setLevel(Level.FINE); logger.addHandler(handler);
By default, a logger sends records both to its own handlers and the handlers of the parent. Our logger is a child of the primordial logger (with name ""
) that sends all records with level INFO
or higher to the console. But we don’t want to see those records twice. For that reason, we set the useParentHandlers
property to false
.
To send log records elsewhere, add another handler. The logging API provides two useful handlers for this purpose, a FileHandler
and a SocketHandler
. The SocketHandler
sends records to a specified host and port. Of greater interest is the FileHandler
that collects records in a file.
You can simply send records to a default file handler, like this:
FileHandler handler = new FileHandler(); logger.addHandler(handler);
The records are sent to a file javan.log
in the user’s home directory, where n is a number to make the file unique. If a user’s system has no concept of the user’s home directory (for example, in Windows 95/98/Me), then the file is stored in a default location such as C:Windows
. By default, the records are formatted in XML. A typical log record has the form
<record> <date>2002-02-04T07:45:15</date> <millis>1012837515710</millis> <sequence>1</sequence> <logger>com.mycompany.myapp</logger> <level>INFO</level> <class>com.mycompany.mylib.Reader</class> <method>read</method> <thread>10</thread> <message>Reading file corejava.gif</message> </record>
You can modify the default behavior of the file handler by setting various parameters in the log manager configuration (see Table 11–2), or by using another constructor (see the API notes at the end of this section).
Configuration Property | Description | Default |
---|---|---|
| The approximate maximum number of bytes to write in a file before opening another. (0 = no limit). | 0 (no limit) in the |
| The pattern for the log file name. See Table 11–3 for pattern variables. |
|
| The number of logs in a rotation sequence. | 1 (no rotation) |
| The filter class to use. | No filtering |
| The character encoding to use. | The platform encoding |
| The record formatter. |
|
You probably don’t want to use the default log file name. Therefore, you should use another pattern, such as %h/myapp.log.
(See Table 11–3 for an explanation of the pattern variables.)
If multiple applications (or multiple copies of the same application) use the same log file, then you should turn the “append” flag on. Alternatively, use %u
in the file name pattern so that each application creates a unique copy of the log.
It is also a good idea to turn file rotation on. Log files are kept in a rotation sequence, such as myapp.log.0
, myapp.log.1, myapp.log.2,
and so on. Whenever a file exceeds the size limit, the oldest log is deleted, the other files are renamed, and a new file with generation number 0 is created.
Many programmers use logging as an aid for the technical support staff. If a program misbehaves in the field, then the user can send back the log files for inspection. In that case, you should turn the “append” flag on, use rotating logs, or both.
You can also define your own handlers by extending the Handler
or the StreamHandler
class. We define such a handler in the example program at the end of this section. That handler displays the records in a window (see Figure 11–3).
The handler extends the StreamHandler
class and installs a stream whose write
methods display the stream output in a text area.
class WindowHandler extends StreamHandler { public WindowHandler() { . . . final JTextArea output = new JTextArea(); setOutputStream(new OutputStream() { public void write(int b) {} // not called public void write(byte[] b, int off, int len) { output.append(new String(b, off, len)); } }); } . . . }
There is just one problem with this approach—the handler buffers the records and only writes them to the stream when the buffer is full. Therefore, we override the publish
method to flush the buffer after each record:
class WindowHandler extends StreamHandler { . . . public void publish(LogRecord record) { super.publish(record); flush(); } }
If you want to write more exotic stream handlers, extend the Handler
class and define the publish
, flush
, and close
methods.
By default, records are filtered according to their logging levels. Each logger and handler can have an optional filter to perform added filtering. You define a filter by implementing the Filter
interface and defining the method
boolean isLoggable(LogRecord record)
Analyze the log record, using any criteria that you desire, and return true
for those records that should be included in the log. For example, a particular filter may only be interested in the messages generated by the entering
and exiting
methods. The filter should then call record.getMessage()
and check whether it starts with ENTRY or RETURN.
To install a filter into a logger or handler, simply call the setFilter
method. Note that you can have at most one filter at a time.
The ConsoleHandler
and FileHandler
classes emit the log records in text and XML formats. However, you can define your own formats as well. You need to extend the Formatter
class and override the method
String format(LogRecord record)
Format the information in the record in any way you like and return the resulting string. In your format
method, you may want to call the method
String formatMessage(LogRecord record)
That method formats the message part of the record, substituting parameters and applying localization.
Many file formats (such as XML) require a head and tail part that surrounds the formatted records. In that case, override the methods
String getHead(Handler h) String getTail(Handler h)
Finally, call the setFormatter
method to install the formatter into the handler.
With so many options for logging, it is easy to lose track of the fundamentals. The “Logging Cookbook” sidebar summarizes the most common operations.
Example 11–4 presents the code for the image viewer that logs events to a log window.
Example 11–4. LoggingImageViewer.java
1. import java.awt.*; 2. import java.awt.event.*; 3. import java.awt.image.*; 4. import java.io.*; 5. import java.util.logging.*; 6. import javax.swing.*; 7. 8. /** 9. A modification of the image viewer program that logs 10. various events. 11. */ 12. public class LoggingImageViewer 13. { 14. public static void main(String[] args) 15. { 16. 17. if (System.getProperty("java.util.logging.config.class") == null 18. && System.getProperty("java.util.logging.config.file") == null) 19. { 20. try 21. { 22. Logger.getLogger("").setLevel(Level.ALL); 23. final int LOG_ROTATION_COUNT = 10; 24. Handler handler = new FileHandler("%h/LoggingImageViewer.log", 0, LOG_ROTATION_COUNT); 25. Logger.getLogger("").addHandler(handler); 26. } 27. catch (IOException e) 28. { 29. Logger.getLogger("com.horstmann.corejava").log(Level.SEVERE, 30. "Can't create log file handler", e); 31. } 32. } 33. 34. Handler windowHandler = new WindowHandler(); 35. windowHandler.setLevel(Level.ALL); 36. Logger.getLogger("com.horstmann.corejava").addHandler(windowHandler); 37. 38. JFrame frame = new ImageViewerFrame(); 39. frame.setTitle("LoggingImageViewer"); 40. frame.setSize(300, 400); 41. frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE); 42. 43. Logger.getLogger("com.horstmann.corejava").fine("Showing frame"); 44. frame.setVisible(true); 45. } 46. } 47. 48. /** 49. The frame that shows the image. 50. */ 51. class ImageViewerFrame extends JFrame 52. { 53. public ImageViewerFrame() 54. { 55. logger.entering("ImageViewerFrame", "<init>"); 56. // set up menu bar 57. JMenuBar menuBar = new JMenuBar(); 58. setJMenuBar(menuBar); 59. 60. JMenu menu = new JMenu("File"); 61. menuBar.add(menu); 62. 63. JMenuItem openItem = new JMenuItem("Open"); 64. menu.add(openItem); 65. openItem.addActionListener(new FileOpenListener()); 66. 67. JMenuItem exitItem = new JMenuItem("Exit"); 68. menu.add(exitItem); 69. exitItem.addActionListener(new 70. ActionListener() 71. { 72. public void actionPerformed(ActionEvent event) 73. { 74. logger.fine("Exiting."); 75. System.exit(0); 76. } 77. }); 78. 79. // use a label to display the images 80. label = new JLabel(); 81. add(label); 82. logger.exiting("ImageViewerFrame", "<init>"); 83. } 84. 85. private class FileOpenListener implements ActionListener 86. { 87. public void actionPerformed(ActionEvent event) 88. { 89. logger.entering("ImageViewerFrame.FileOpenListener", "actionPerformed", event); 90. 91. // set up file chooser 92. JFileChooser chooser = new JFileChooser(); 93. chooser.setCurrentDirectory(new File(".")); 94. 95. // accept all files ending with .gif 96. chooser.setFileFilter(new 97. javax.swing.filechooser.FileFilter() 98. { 99. public boolean accept(File f) 100. { 101. return f.getName().toLowerCase().endsWith(".gif") || f.isDirectory(); 102. } 103. public String getDescription() 104. { 105. return "GIF Images"; 106. } 107. }); 108. 109. // show file chooser dialog 110. int r = chooser.showOpenDialog(ImageViewerFrame.this); 111. 112. // if image file accepted, set it as icon of the label 113. if (r == JFileChooser.APPROVE_OPTION) 114. { 115. String name = chooser.getSelectedFile().getPath(); 116. logger.log(Level.FINE, "Reading file {0}", name); 117. label.setIcon(new ImageIcon(name)); 118. } 119. else 120. logger.fine("File open dialog canceled."); 121. logger.exiting("ImageViewerFrame.FileOpenListener", "actionPerformed"); 122. } 123. } 124. 125. private JLabel label; 126. private static Logger logger = Logger.getLogger("com.horstmann.corejava"); 127. } 128. 129. /** 130. A handler for displaying log records in a window. 131. */ 132. class WindowHandler extends StreamHandler 133. { 134. public WindowHandler() 135. { 136. frame = new JFrame(); 137. final JTextArea output = new JTextArea(); 138. output.setEditable(false); 139. frame.setSize(200, 200); 140. frame.add(new JScrollPane(output)); 141. frame.setFocusableWindowState(false); 142. frame.setVisible(true); 143. setOutputStream(new 144. OutputStream() 145. { 146. public void write(int b) {} // not called 147. public void write(byte[] b, int off, int len) 148. { 149. output.append(new String(b, off, len)); 150. } 151. }); 152. } 153. 154. public void publish(LogRecord record) 155. { 156. if (!frame.isVisible()) return; 157. super.publish(record); 158. flush(); 159. } 160. 161. private JFrame frame; 162. }
Logger getLogger(String loggerName)
Logger getLogger(String loggerName, String bundleName)
get the logger with the given name. If the logger doesn’t exist, it is created.
Parameters: |
| The hierarchical logger name, such as |
| The name of the resource bundle for looking up localized messages |
void severe(String message)
void warning(String message)
void info(String message)
void config(String message)
void fine(String message)
void finer(String message)
void finest(String message)
log a record with the level indicated by the method name and the given message.
void entering(String className, String methodName)
void entering(String className, String methodName, Object param)
void entering(String className, String methodName, Object[] param)
void exiting(String className, String methodName)
void exiting(String className, String methodName, Object result)
log a record that describes entering or exiting a method with the given parameter(s) or return value.
void throwing(String className, String methodName, Throwable t)
logs a record that describes throwing of the given exception object.
void log(Level level, String message)
void log(Level level, String message, Object obj)
void log(Level level, String message, Object[] objs)
void log(Level level, String message, Throwable t)
log a record with the given level and message, optionally including objects or a throwable. To include objects, the message must contain formatting placeholders {0}
, {1}
, and so on.
void logp(Level level, String className, String methodName, String message)
void logp(Level level, String className, String methodName, String message, Object obj)
void logp(Level level, String className, String methodName, String message, Object[] objs)
void logp(Level level, String className, String methodName, String message, Throwable t)
log a record with the given level, precise caller information, and message, optionally including objects or a throwable.
void logrb(Level level, String className, String methodName, String bundleName, String message)
void logrb(Level level, String className, String methodName, String bundleName, String message, Object obj)
void logrb(Level level, String className, String methodName, String bundleName, String message, Object[] objs)
void logrb(Level level, String className, String methodName, String bundleName, String message, Throwable t)
log a record with the given level, precise caller information, resource bundle name, and message, optionally including objects or a throwable.
Level getLevel()
void setLevel(Level l)
get and set the level of this logger.
Logger getParent()
void setParent(Logger l)
get and set the parent logger of this logger.
Handler[] getHandlers()
gets all handlers of this logger.
void addHandler(Handler h)
void removeHandler(Handler h)
add or remove a handler for this logger.
boolean getUseParentHandlers()
void setUseParentHandlers(boolean b)
get and set the “use parent handler” property. If this property is true
, the logger forwards all logged records to the handlers of its parent.
Filter getFilter()
void setFilter(Filter f)
get and set the filter of this logger.
abstract void publish(LogRecord record)
sends the record to the intended destination.
abstract void flush()
flushes any buffered data.
abstract void close()
flushes any buffered data and releases all associated resources.
Filter getFilter()
void setFilter(Filter f)
get and set the filter of this handler.
Formatter getFormatter()
void setFormatter(Formatter f)
get and set the formatter of this handler.
Level getLevel()
void setLevel(Level l)
get and set the level of this handler.
ConsoleHandler()
constructs a new console handler.
FileHandler(String pattern)
FileHandler(String pattern, boolean append)
FileHandler(String pattern, int limit, int count)
FileHandler(String pattern, int limit, int count, boolean append)
construct a file handler.
Parameters: |
| The pattern for constructing the log file name. See Table 11–3 on page 585 for pattern variables. |
| The approximate maximum number of bytes before a new log file is opened. | |
| The number of files in a rotation sequence. | |
|
|
Level getLevel()
gets the logging level of this record.
String getLoggerName()
gets the name of the logger that is logging this record.
ResourceBundle getResourceBundle()
String getResourceBundleName()
get the resource bundle, or its name, to be used for localizing the message, or null
if none is provided.
String getMessage()
gets the “raw” message before localization or formatting.
Object[] getParameters()
gets the parameter objects, or null
if none is provided.
Throwable getThrown()
gets the thrown object, or null
if none is provided.
String getSourceClassName()
String getSourceMethodName()
get the location of the code that logged this record. This information may be supplied by the logging code or automatically inferred from the runtime stack. It might be inaccurate, if the logging code supplied the wrong value or if the running code was optimized and the exact location cannot be inferred.
long getMillis()
gets the creation time, in milliseconds, since 1970.
long getSequenceNumber()
gets the unique sequence number of this record.
int getThreadID()
gets the unique ID for the thread in which this record was created. These IDs are assigned by the LogRecord
class and have no relationship to other thread IDs.
boolean isLoggable(LogRecord record)
returns true
if the given log record should be logged.
java.util.logging.Formatter 1.4
abstract String format(LogRecord record)
returns the string that results from formatting the given log record.
String getHead(Handler h)
String getTail(Handler h)
return the strings that should appear at the head and tail of the document containing the log records. The Formatter
superclass defines these methods to return the empty string; override them if necessary.
String formatMessage(LogRecord record)
returns the localized and formatted message part of the log record.
Assertions are a commonly used idiom for defensive programming. Suppose you are convinced that a particular property is fulfilled, and you rely on that property in your code. For example, you may be computing
double y = Math.sqrt(x);
You are certain that x
is not negative. Perhaps it is the result of another computation that can’t have a negative result, or it is a parameter of a method that requires its callers to supply only positive inputs. Still, you want to double-check rather than having confusing “not a number” floating-point values creep into your computation. You could, of course, throw an exception:
if (x < 0) throw new IllegalArgumentException("x < 0");
But this code stays in the program, even after testing is complete. If you have lots of checks of this kind, the program runs quite a bit slower than it should.
The assertion mechanism allows you to put in checks during testing and to have them automatically removed in the production code.
As of JDK 1.4, the Java language has a keyword assert
. There are two forms:
assert
condition;
and
Both statements evaluate the condition and throw an AssertionError
if it is false
. In the second statement, the expression is passed to the constructor of the AssertionError
object and turned into a message string.
The sole purpose of the expression part is to produce a message string. The AssertionError
object does not store the actual expression value, so you can’t query it later. As the JDK documentation states with paternalistic charm, doing so “would encourage programmers to attempt to recover from assertion failure, which defeats the purpose of the facility.”
To assert that x
is nonnegative, you can simply use the statement
assert x >= 0;
Or you can pass the actual value of x
into the AssertionError
object, so that it gets displayed later.
assert x >= 0 : x;
The assert
macro of the C language turns the assertion condition into a string that is printed if the assertion fails. For example, if assert(x >= 0)
fails, it prints that "x >= 0"
is the failing condition. In Java, the condition is not automatically part of the error report. If you want to see it, you have to pass it as a string into the AssertionError
object: assert x >= 0 : "x >= 0"
.
If you use JDK 1.4, you must tell the compiler that you are using the assert
keyword. Use the -source 1.4
option, like this:
javac -source 1.4 MyClass.java
Starting with JDK 5.0, support for assertions is enabled by default.
By default, assertions are disabled. You enable them by running the program with the -enableassertions
or -ea
option:
java -enableassertions MyApp
Note that you do not have to recompile your program to enable or disable assertions. Enabling or disabling assertions is a function of the class loader. When assertions are disabled, the class loader strips out the assertion code so that it won’t slow execution.
You can even turn on assertions in specific classes or in entire packages. For example,
java -ea:MyClass -ea:com.mycompany.mylib... MyApp
This command turns on assertions for the class MyClass
and all classes in the com.mycompany.mylib
package and its subpackages. The option -ea...
turns on assertions in all classes of the default package.
You can also disable assertions in certain classes and packages with the -disableassertions
or -da
option:
java -ea:... -da:MyClass MyApp
Some classes are not loaded by a class loader but directly by the virtual machine. You can use these switches to selectively enable or disable assertions in those classes. However, the -ea
and -da
switches that enable or disable all assertions do not apply to the “system classes” without class loaders. Use the -enablesystemassertions/-esa
switch to enable assertions in system classes.
It is also possible to programmatically control the assertion status of class loaders. See the API notes at the end of this section.
The Java language gives you three mechanisms to deal with system failures:
Throwing an exception
Logging
Using assertions
When should you choose assertions? Keep these points in mind:
Assertion failures are intended to be fatal, unrecoverable errors.
Assertion checks are turned on only during development and testing. (This is sometimes jokingly described as “wearing a life jacket when you are close to shore, and throwing it overboard once you are in the middle of the ocean.”)
Therefore, you would not use assertions for signaling recoverable conditions to another part of the program or for communicating problems to the program user. Assertions should only be used to locate internal program errors during testing.
Let’s look at a common scenario—the checking of method parameters. Should you use assertions to check for illegal index values or null
references? To answer that question, you have to look at the documentation of the method. For example, consider the Arrays.sort
method from the standard library.
/** Sorts the specified range of the specified array into ascending numerical order. The range to be sorted extends from fromIndex, inclusive, to toIndex, exclusive. @param a the array to be sorted. @param fromIndex the index of the first element (inclusive) to be sorted. @param toIndex the index of the last element (exclusive) to be sorted. @throws IllegalArgumentException if fromIndex > toIndex @throws ArrayIndexOutOfBoundsException if fromIndex < 0 or toIndex > a.length */ static void sort(int[] a, int fromIndex, int toIndex)
The documentation states that the method throws an exception if the index values are incorrect. That behavior is part of the contract that the method makes with its callers. If you implement the method, you have to respect that contract and throw the indicated exceptions. It would not be appropriate to use assertions instead.
Should you assert that a
is not null
? That is not appropriate either. The method documentation is silent on the behavior of the method when a
is null
. The callers have the right to assume that the method will return successfully in that case and not throw an assertion error.
However, suppose the method contract had been slightly different:
@param a the array to be sorted. (Must not be null)
Now the callers of the method have been put on notice that it is illegal to call the method with a null
array. Then the method may start with the assertion
assert a != null;
Computer scientists call this kind of contract a precondition. The original method had no preconditions on its parameters—it promised a well-defined behavior in all cases. The revised method has a single precondition: that a
is not null
. If the caller fails to fulfill the precondition, then all bets are off and the method can do anything it wants. In fact, with the assertion in place, the method has a rather unpredictable behavior when it is called illegally. It sometimes throws an assertion error, and sometimes a null pointer exception, depending on how its class loader is configured.
In JDK 5.0, the Arrays.sort
method throws a NullPointerException
if you call it with a null
array. That is a bug, either in the specification or the implementation.
Many programmers use comments to document their underlying assumptions. The JDK documentation contains a good example:
if (i % 3 == 0) . . . else if (i % 3 == 1) . . . else // (i % 3 == 2) . . .
In this case, it makes a lot of sense to use an assertion instead.
if (i % 3 == 0) . . . else if (i % 3 == 1) . . . else { assert i % 3 == 2; . . . }
Of course, it would make even more sense to think through the issue a bit more thoroughly. What are the possible values of i % 3
? If i
is positive, the remainders must be 0, 1, or 2. If i
is negative, then the remainders can be −1 or −2. Thus, the real assumption is that i
is not negative. A better assertion would be
assert i >= 0;
before the if
statement.
At any rate, this example shows a good use of assertions as a self-check for the programmer. As you can see, assertions are a tactical tool for testing and debugging, whereas logging is a strategic tool for the entire life cycle of a program.
void setDefaultAssertionStatus(boolean b)
1.4
enables or disables assertions for all classes loaded by this class loader that don’t have an explicit class or package assertion status.
void setClassAssertionStatus(String className, boolean b)
1.4
enables or disables assertions for the given class and its inner classes.
void setPackageAssertionStatus(String packageName, boolean b)
1.4
enables or disables assertions for all classes in the given package and its subpackages.
void clearAssertionStatus()
1.4
removes all explicit class and package assertion status settings and disables assertions for all classes loaded by this class loader.
Suppose you wrote your program and made it bulletproof by catching and properly handling all exceptions. Then you run it, and it does not work right. Now what? (If you never have this problem, you can skip the remainder of this chapter.)
Of course, it is best if you have a convenient and powerful debugger. Debuggers are available as a part of professional development environments such as Eclipse, NetBeans, or JBuilder. However, if you use a new version of Java that is not yet supported by development environments or if you work on an unusual platform, you will need to do a great deal of debugging by the time-honored method of inserting logging statements into your code.
Here are some tips for efficient debugging if you have to do it all yourself.
You can print or log the value of any variable with code like this:
System.out.println("x=" + x);
or
Logger.global.info("x=" + x);
If x
is a number, it is converted to its string equivalent. If x
is an object, then Java calls its toString
method. To get the state of the implicit parameter object, print the state of the this
object.
Logger.global.info("this=" + this);
Most of the classes in the Java library are very conscientious about overriding the toString
method to give you useful information about the class. This is a real boon for debugging. You should make the same effort in your classes.
One seemingly little-known but very useful trick is that you can put a separate main
method in each class. Inside it, you can put a unit test stub that lets you test the class in isolation.
public class MyClass
{
methods and fields . . .
public static void main(String[] args)
{
test code }
}
Make a few objects, call all methods, and check that each of them does the right thing. You can leave all these main
methods in place and launch the Java virtual machine separately on each of the files to run the tests. When you run an applet, none of these main
methods are ever called. When you run an application, the Java virtual machine calls only the main
method of the startup class.
If you liked the preceding tip, you should check out JUnit from http://junit.org. JUnit is a very popular unit testing framework that makes it easy to organize suites of test cases. Run the tests whenever you make changes to a class, and add another test case whenever you find a bug.
A logging proxy is an object of a subclass that intercepts method calls, logs them, and then calls the superclass. For example, if you have trouble with the setBackground
method of a panel, you can create a proxy object as an instance of an anonymous subclass:
JPanel panel = new JPanel() { public void setBackground(Color c) { Logger.global.info("setBackground: c=" + c); super.setBackground(c); } };
Whenever the setBackground
method is called, a log message is generated. To find out who called the method, generate a stack trace—see the next tip.
You can get a stack trace from any exception object with the printStackTrace
method in the Throwable
class. The following code catches any exception, prints the exception object and the stack trace, and rethrows the exception so it can find its intended handler.
try { . . . } catch (Throwable t) { t.printStackTrace(); throw t; }
You don’t even need to catch an exception to generate a stack trace. Simply insert the statement
Thread.dumpStack();
anywhere into your code to get a stack trace.
Normally, the stack trace is displayed on System.err.
You can send it to a file with the void printStackTrace(PrintWriter s)
method. Or, if you want to log or display the stack trace, here is how you can capture it into a string:
StringWriter out = new StringWriter(); new Throwable().printStackTrace(new PrintWriter(out)); String trace = out.toString();
(See Chapter 12 for the PrintWriter
and StringWriter
classes.)
It is often handy to trap program errors in a file. However, errors are sent to System.err
, not System.out
. Therefore, you cannot simply trap them by running
java MyProgram > errors.txt
In UNIX and Windows NT/2000/XP, this is not a problem. For example, if you use bash
as your shell, simply capture the error stream as
java MyProgram 2> errors.txt
To capture both System.err
and System.out
in the same file, use
java MyProgram 2>&1 errors.txt
Some operating systems (such as Windows 95/98/Me) do not have such a convenient method. Here is a remedy. Use the following Java program:
import java.io.*; public class Errout { public static void main(String[] args) throws IOException { Process p = Runtime.getRuntime().exec(args); BufferedReader err = new BufferedReader(new InputStreamReader(p.getErrorStream())); String line; while ((line = err.readLine()) != null) System.out.println(line); } }
Then run your program as
java Errout java MyProgram > errors.txt
A more efficient way of getting the same result in Windows is to compile this C program into a file, errout.exe
:
#include <io.h> #include <stdio.h> #include <process.h> int main(int argc, char* argv[]) { dup2(1, 2); /* make stderr go to stdout */ execvp(argv[1], argv + 1); return 0; }
Then you can run
errout java MyProgram > errors.txt
To watch class loading, launch the Java virtual machine with the -verbose
flag. You get a printout such as:
[Opened /usr/local/jdk5.0/jre/lib/rt.jar] [Opened /usr/local/jdk5.0/jre/lib/jsse.jar] [Opened /usr/local/jdk5.0/jre/lib/jce.jar] [Opened /usr/local/jdk5.0/jre/lib/charsets.jar] [Loaded java.lang.Object from shared objects file] [Loaded java.io.Serializable from shared objects file] [Loaded java.lang.Comparable from shared objects file] [Loaded java.lang.CharSequence from shared objects file] [Loaded java.lang.String from shared objects file] [Loaded java.lang.reflect.GenericDeclaration from shared objects file] [Loaded java.lang.reflect.Type from shared objects file] [Loaded java.lang.reflect.AnnotatedElement from shared objects file] [Loaded java.lang.Class from shared objects file] [Loaded java.lang.Cloneable from shared objects file] ...
This can occasionally be helpful to diagnose class path problems.
If you ever looked at a Swing window and wondered how its designer managed to get all the components to line up so nicely, you can spy on the contents. Press CTRL+SHIFT+F1, and you get a printout of all components in the hierarchy:
FontDialog[frame0,0,0,300x200,layout=java.awt.BorderLayout,... javax.swing.JRootPane[,4,23,292x173,layout=javax.swing.JRootPane$RootLayout,... javax.swing.JPanel[null.glassPane,0,0,292x173,hidden,layout=java.awt.FlowLayout,... javax.swing.JLayeredPane[null.layeredPane,0,0,292x173,... javax.swing.JPanel[null.contentPane,0,0,292x173,layout=java.awt.GridBagLayout,... javax.swing.JList[,0,0,73x152,alignmentX=null,alignmentY=null,... javax.swing.CellRendererPane[,0,0,0x0,hidden] javax.swing.DefaultListCellRenderer$UIResource[,-73,-19,0x0,... javax.swing.JCheckBox[,157,13,50x25,layout=javax.swing.OverlayLayout,... javax.swing.JCheckBox[,156,65,52x25,layout=javax.swing.OverlayLayout,... javax.swing.JLabel[,114,119,30x17,alignmentX=0.0,alignmentY=null,... javax.swing.JTextField[,186,117,105x21,alignmentX=null,alignmentY=null,... javax.swing.JTextField[,0,152,291x21,alignmentX=null,alignmentY=null,...
If you design your own custom Swing component and it doesn’t seem to be displayed correctly, you’ll really love the Swing graphics debugger. And even if you don’t write your own component classes, it is instructive and fun to see exactly how the contents of a
component are drawn. To turn on debugging for a Swing component, use the setDebugGraphicsOptions
method of the JComponent
class. The following options are available:
| Flashes each line, rectangle, and text in red before drawing it |
| Prints a message for each drawing operation |
| Displays the operations that are performed on the off-screen buffer |
| Turns graphics debugging off |
We have found that for the flash option to work, you must disable “double buffering,” the strategy used by Swing to reduce flicker when updating a window. The magic incantation for turning on the flash option is:
RepaintManager.currentManager(getRootPane()).setDoubleBufferingEnabled(false); ((JComponent) getContentPane()).setDebugGraphicsOptions(DebugGraphics.FLASH_OPTION);
Simply place these lines at the end of your frame constructor. When the program runs, you will see the content pane filled in slow motion. Or, for more localized debugging, just call setDebugGraphicsOptions
for a single component. Control freaks can set the duration, count, and color of the flashes—see the on-line documentation of the DebugGraphics
class for details.
JDK 5.0 adds the -Xlint
option to the compiler for spotting common code problems. For example, if you compile with the command
javac -Xlint:fallthrough
then the compiler reports missing break
statements in switch
statements. (The term “lint” originally described a tool for locating potential problems in C programs, and is now generically applied to tools that flag constructs that are questionable but not illegal.)
The following options are available:
| Carries out all checks |
| Same as |
| Checks for missing |
| Warns about |
| Carries out none of the checks |
| Checks that all directories on the class path and source path exist |
| Warns about serializable classes without |
| Warns of unsafe conversions between generic and raw types (see Chapter 13) |
JDK 5.0 adds support for monitoring and management of Java applications, allowing the installation of agents in the virtual machine that track memory consumption, thread usage, class loading, and so on. This feature is particularly important for large and long-running Java programs such as application servers. As a demonstration of these capabilities, the JDK ships with a graphical tool called jconsole
that displays statistics about the performance of a virtual machine (see Figure 11–4). To enable monitoring, start the virtual machine with the -Dcom.sun.management.jmxremote
option. Then find out the ID of the operating system process that runs the virtual machine. In UNIX/Linux, run the ps
utility; in Windows, use the task manager. Then launch the jconsole
program:
java -Dcom.sun.management.jmxremote MyProgram.java
jconsole
processID
If you launch the Java virtual machine with the -Xprof
flag, it runs a rudimentary profiler that keeps track of the methods in your code that were executed most often. The profiling information is sent to System.out
. The output also tells you which methods were compiled by the just-in-time compiler.
If you run an applet inside a browser, you may not be able to see any messages that are sent to System.out
. Most browsers will have some sort of Java Console window. (Check the help system for your browser.) For example, Netscape Navigator has one, as does Internet Explorer 4 and above. If you use the Java Plug-in, check the Show Java Console box in the configuration panel (see Chapter 10).
Moreover, the Java Console window has a set of scrollbars, so you can retrieve messages that have scrolled off the window. Windows users will find this a definite advantage over the DOS shell window in which the System.out
output normally appears.
We give you a similar window class so you can enjoy the same benefit of seeing your debugging messages in a window when debugging a program. Figure 11–5 shows our ConsoleWindow
class in action.
The class is easy to use. Simply call:
ConsoleWindow.init()
Then print to System.out
or System.err
in the normal way.
Example 11–5 lists the code for the ConsoleWindow
class. As you can see, the class is quite simple. Messages are displayed in a JTextArea
inside a JScrollPane
. We call the System.setOut
and System.setErr
methods to set the output and error streams to a special stream that adds all messages to the text area.
Example 11–5. ConsoleWindow.java
1. import java.awt.*; 2. import java.awt.event.*; 3. import javax.swing.*; 4. import java.io.*; 5. 6. /** 7. A window that displays the bytes sent to System.out 8. and System.err 9. */ 10. public class ConsoleWindow 11. { 12. public static void init() 13. { 14. JFrame frame = new JFrame(); 15. frame.setTitle("ConsoleWindow"); 16. final JTextArea output = new JTextArea(); 17. output.setEditable(false); 18. frame.add(new JScrollPane(output)); 19. frame.setSize(DEFAULT_WIDTH, DEFAULT_HEIGHT); 20. frame.setLocation(DEFAULT_LEFT, DEFAULT_TOP); 21. frame.setFocusableWindowState(false); 22. frame.setVisible(true); 23. 24. // define a PrintStream that sends its bytes to the 25. // output text area 26. PrintStream consoleStream = new PrintStream(new 27. OutputStream() 28. { 29. public void write(int b) {} // never called 30. public void write(byte[] b, int off, int len) 31. { 32. output.append(new String(b, off, len)); 33. } 34. }); 35. 36. // set both System.out and System.err to that stream 37. System.setOut(consoleStream); 38. System.setErr(consoleStream); 39. } 40. 41. public static final int DEFAULT_WIDTH = 300; 42. public static final int DEFAULT_HEIGHT = 200; 43. public static final int DEFAULT_LEFT = 200; 44. public static final int DEFAULT_TOP = 200; 45. }
When you write a fancy user interface in Java, you need to know what events AWT sends to what components. Unfortunately, the AWT documentation is somewhat sketchy in this regard. For example, suppose you want to show hints in the status line when the user moves the mouse over different parts of the screen. The AWT generates mouse and focus events that you may be able to trap.
We give you a useful EventTrace
class to spy on these events. It prints out all event handling methods and their parameters. See Figure 11–6 for a display of the traced events.
To spy on messages, add the component whose events you want to trace to an event tracer:
EventTracer tracer = new EventTracer(); tracer.add(frame);
That prints a textual description of all events, like this:
public abstract void java.awt.event.MouseListener.mouseExited(java.awt.event.MouseEvent): java.awt.event.MouseEvent[MOUSE_EXITED,(408,14),button=0,clickCount=0] on javax.swing .JButton[,0,345,400x25,...] public abstract void java.awt.event.FocusListener.focusLost(java.awt.event.FocusEvent): java.awt.event.FocusEvent[FOCUS_LOST,temporary,opposite=null] on javax.swing.JButton[,0 ,345,400x25,...]
You may want to capture this output in a file or a console window, as explained in the preceding sections.
Example 11–6 is the EventTracer
class. The idea behind the class is easy even if the implementation is a bit mysterious.
When you add a component to the event tracer in the add
method, the JavaBeans introspection class analyzes the component for methods of the form void addXxxListener(XxxEvent)
. (See Chapter 8 of Volume 2 for more information on JavaBeans.) For each matching method, an EventSetDescriptor
is generated. We pass each descriptor to the addListener
method.
If the component is a container, we enumerate its components and recursively call add
for each of them.
The addListener
method is called with two parameters: the component on whose events we want to spy and the event set descriptor. The getListenerType
method of the EventSetDescriptor
class returns a Class
object that describes the event listener interface such as ActionListener
or ChangeListener
. We create a proxy object for that interface. The proxy handler simply prints the name and event parameter of the invoked event method. The getAddListenerMethod
method of the EventSetDescriptor
class returns a Method
object that we use to add the proxy object as the event listener to the component.
This program is a good example of the power of the reflection mechanism. We don’t have to hardwire the fact that the JButton
class has a method addActionListener
whereas a JSlider
has a method addChangeListener
. The reflection mechanism discovers these facts for us.
The proxy mechanism makes this program dramatically easier. In prior editions of this book, we needed to define a listener that simultaneously implements the MouseListener, ComponentListener, FocusListener, KeyListener, ContainerListener, WindowListener, TextListener, AdjustmentListener, ActionListener
, and ItemListener
interfaces and a couple of dozen methods that print the event parameter. The proxy mechanism is explained at the end of Chapter 6.
Example 11–7 tests the event tracer. The program displays a frame with a button and a slider and traces the events that these components generate.
Example 11–6. EventTracer.java
1. import java.awt.*; 2. import java.awt.event.*; 3. import java.beans.*; 4. import java.lang.reflect.*; 5. 6. public class EventTracer 7. { 8. public EventTracer() 9. { 10. // the handler for all event proxies 11. handler = new 12. InvocationHandler() 13. { 14. public Object invoke(Object proxy, Method method, Object[] args) 15. { 16. System.out.println(method + ":" + args[0]); 17. return null; 18. } 19. }; 20. } 21. 22. /** 23. Adds event tracers for all events to which this component 24. and its children can listen 25. @param c a component 26. */ 27. public void add(Component c) 28. { 29. try 30. { 31. // get all events to which this component can listen 32. BeanInfo info = Introspector.getBeanInfo(c.getClass()); 33. 34. EventSetDescriptor[] eventSets = info.getEventSetDescriptors(); 35. for (EventSetDescriptor eventSet : eventSets) 36. addListener(c, eventSet); 37. } 38. catch (IntrospectionException e) {} 39. // ok not to add listeners if exception is thrown 40. 41. if (c instanceof Container) 42. { 43. // get all children and call add recursively 44. for (Component comp : ((Container) c).getComponents()) 45. add(comp); 46. } 47. } 48. 49. /** 50. Add a listener to the given event set 51. @param c a component 52. @param eventSet a descriptor of a listener interface 53. */ 54. public void addListener(Component c, EventSetDescriptor eventSet) 55. { 56. // make proxy object for this listener type and route all calls to the handler 57. Object proxy = Proxy.newProxyInstance(null, 58. new Class[] { eventSet.getListenerType() }, handler); 59. 60. // add the proxy as a listener to the component 61. Method addListenerMethod = eventSet.getAddListenerMethod(); 62. try 63. { 64. addListenerMethod.invoke(c, proxy); 65. } 66. catch(InvocationTargetException e) {} 67. catch(IllegalAccessException e) {} 68. // ok not to add listener if exception is thrown 69. } 70. 71. private InvocationHandler handler; 72. }
Example 11–7. EventTracerTest.java
1. import java.awt.*; 2. import java.awt.event.*; 3. import javax.swing.*; 4. 5. public class EventTracerTest 6. { 7. public static void main(String[] args) 8. { 9. JFrame frame = new EventTracerFrame(); 10. frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE); 11. frame.setVisible(true); 12. } 13. } 14. 15. class EventTracerFrame extends JFrame 16. { 17. public EventTracerFrame() 18. { 19. setTitle("EventTracerTest"); 20. setSize(DEFAULT_WIDTH, DEFAULT_HEIGHT); 21. 22. // add a slider and a button 23. add(new JSlider(), BorderLayout.NORTH); 24. add(new JButton("Test"), BorderLayout.SOUTH); 25. 26. // trap all events of components inside the frame 27. EventTracer tracer = new EventTracer(); 28. tracer.add(this); 29. } 30. 31. public static final int DEFAULT_WIDTH = 400; 32. public static final int DEFAULT_HEIGHT = 400; 33. }
Version 1.3 of the Java 2 Platform adds a Robot
class that you can use to send keystrokes and mouse clicks to any AWT program. This class is intended for automatic testing of user interfaces.
To get a robot, you need to first get a GraphicsDevice
object. You get the default screen device through the sequence of calls:
GraphicsEnvironment environment = GraphicsEnvironment.getLocalGraphicsEnvironment(); GraphicsDevice screen = environment.getDefaultScreenDevice();
Then you construct a robot as:
Robot robot = new Robot(screen);
To send a keystroke, tell the robot to simulate a key press and a key release:
robot.keyPress(KeyEvent.VK_TAB); robot.keyRelease(KeyEvent.VK_TAB);
For a mouse click, you first need to move the mouse and then press and release a button:
robot.mouseMove(x, y); // x and y are absolute screen pixel coordinates. robot.mousePress(InputEvent.BUTTON1_MASK); robot.mouseRelease(InputEvent.BUTTON1_MASK);
The idea is that you simulate key and mouse input and afterwards take a screen snapshot to see whether the application did what it was supposed to. You capture the screen with the createScreenCapture
method:
Rectangle rect = new Rectangle(x, y, width, height); BufferedImage image = robot.createScreenCapture(rect);
The rectangle coordinates also refer to absolute screen pixels.
Finally, you usually want to add a small delay between robot instructions so that the application can catch up. Use the delay
method and give it the number of milliseconds to delay. For example:
robot.delay(1000); // delay by 1000 milliseconds
The program in Example 11–8 shows how you can use the robot. A robot tests the button test program that you saw in Chapter 8. First, pressing the space bar activates the leftmost button. Then the robot waits for two seconds so that you can see what it has done. After the delay, the robot simulates the tab key and another space bar press to click on the next button. Finally, we simulate a mouse click on the third button. (You may need to adjust the x
and y
coordinates of the program to actually press the button.) The program ends by taking a screen capture and displaying it in another frame (see Figure 11–7).
As you can see from this example, the Robot
class is not by itself suitable for convenient user interface testing. Instead, it is a basic building block that can be a foundational part of a testing tool. A professional testing tool can capture, store, and replay user interaction scenarios and find out the screen locations of the components so that mouse clicks aren’t guesswork. At the time of this writing, the robot is brand new and we are not aware of any sophisticated testing tools for Java user interfaces. We expect these tools to materialize in the future.
Example 11–8. RobotTest.java
1. import java.awt.*; 2. import java.awt.event.*; 3. import java.awt.image.*; 4. import javax.swing.*; 5. 6. public class RobotTest 7. { 8. public static void main(String[] args) 9. { 10. // make frame with a button panel 11. 12. ButtonFrame frame = new ButtonFrame(); 13. frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE); 14. frame.setVisible(true); 15. 16. // attach a robot to the screen device 17. 18. GraphicsEnvironment environment = GraphicsEnvironment.getLocalGraphicsEnvironment(); 19. GraphicsDevice screen = environment.getDefaultScreenDevice(); 20. 21. try 22. { 23. Robot robot = new Robot(screen); 24. run(robot); 25. } 26. catch (AWTException e) 27. { 28. e.printStackTrace(); 29. } 30. } 31. 32. /** 33. Runs a sample test procedure 34. @param robot the robot attached to the screen device 35. */ 36. public static void run(Robot robot) 37. { 38. // simulate a space bar press 39. robot.keyPress(' '), 40. robot.keyRelease(' '), 41. 42. // simulate a tab key followed by a space 43. robot.delay(2000); 44. robot.keyPress(KeyEvent.VK_TAB); 45. robot.keyRelease(KeyEvent.VK_TAB); 46. robot.keyPress(' '), 47. robot.keyRelease(' '), 48. 49. // simulate a mouse click over the rightmost button 50. robot.delay(2000); 51. robot.mouseMove(200, 50); 52. robot.mousePress(InputEvent.BUTTON1_MASK); 53. robot.mouseRelease(InputEvent.BUTTON1_MASK); 54. 55. // capture the screen and show the resulting image 56. robot.delay(2000); 57. BufferedImage image = robot.createScreenCapture(new Rectangle(0, 0, 400, 300)); 58. 59. ImageFrame frame = new ImageFrame(image); 60. frame.setVisible(true); 61. } 62. } 63. 64. /** 65. A frame to display a captured image 66. */ 67. class ImageFrame extends JFrame 68. { 69. /** 70. @param image the image to display 71. */ 72. public ImageFrame(Image image) 73. { 74. setTitle("Capture"); 75. setSize(DEFAULT_WIDTH, DEFAULT_HEIGHT); 76. 77. JLabel label = new JLabel(new ImageIcon(image)); 78. add(label); 79. } 80. 81. public static final int DEFAULT_WIDTH = 450; 82. public static final int DEFAULT_HEIGHT = 350; 83. }
static GraphicsEnvironment getLocalGraphicsEnvironment()
returns the local graphics environment.
GraphicsDevice getDefaultScreenDevice()
returns the default screen device. Note that computers with multiple monitors have one graphics device per screen—use the getScreenDevices
method to obtain an array of all screen devices.
java.awt.Robot 1.3
Robot(GraphicsDevice device)
constructs a robot that can interact with the given device.
void keyPress(int key)
void keyRelease(int key)
simulate a key press or release.
Parameters: |
| The key code. See the |
void mouseMove(int x, int y)
simulates a mouse move.
Parameters: |
| The mouse position in absolute pixel coordinates |
void mousePress(int eventMask)
void mouseRelease(int eventMask)
simulate a mouse button press or release.
Parameters: |
| The event mask describing the mouse buttons. See the |
void delay(int milliseconds)
delays the robot for the given number of milliseconds.
BufferedImage createScreenCapture(Rectangle rect)
captures a portion of the screen.
Parameters: |
| The rectangle to be captured, in absolute pixel coordinates |
Debugging with print statements is not one of life’s more joyful experiences. You constantly find yourself adding and removing the statements, then recompiling the program. Using a debugger is better. A debugger runs your program in full motion until it reaches a breakpoint, and then you can look at everything that interests you.
The JDK includes JDB, an extremely rudimentary command-line debugger. Its user interface is so minimal that you will not want to use it except as a last resort. It really is more a proof of concept than a usable tool. We nevertheless briefly introduce it because there are situations in which it is better than no debugger at all. Of course, many Java programming environments have far more convenient debuggers. The main principles of all debuggers are the same, and you may want to use the example in this section to learn to use the debugger in your environment instead of JDB.
Examples 11–9 through 11–11 show a deliberately corrupted version of the ButtonTest
program from Chapter 8. (We broke up the program and placed each class into a separate file because some debuggers have trouble dealing with multiple classes in the same file.)
When you click on any of the buttons, nothing happens. Look at the source code—button clicks are supposed to set the background color to the color specified by the button name.
Example 11–9. BuggyButtonTest.java
1. import javax.swing.*; 2. 3. public class BuggyButtonTest 4. { 5. public static void main(String[] args) 6. { 7. BuggyButtonFrame frame = new BuggyButtonFrame(); 8. frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE); 9. frame.setVisible(true); 10. } 11. }
Example 11–10. BuggyButtonFrame.java
1. import java.awt.*; 2. import javax.swing.*; 3. 4. public class BuggyButtonFrame extends JFrame 5. { 6. public BuggyButtonFrame() 7. { 8. setTitle("BuggyButtonTest"); 9. setSize(DEFAULT_WIDTH, DEFAULT_HEIGHT); 10. 11. // add panel to frame 12. 13. BuggyButtonPanel panel = new BuggyButtonPanel(); 14. add(panel); 15. } 16. 17. public static final int DEFAULT_WIDTH = 300; 18. public static final int DEFAULT_HEIGHT = 200; 19. }
Example 11–11. BuggyButtonPanel.java
1. import java.awt.*; 2. import java.awt.event.*; 3. import javax.swing.*; 4. 5. class BuggyButtonPanel extends JPanel 6. { 7. public BuggyButtonPanel() 8. { 9. ActionListener listener = new ButtonListener(); 10. 11. JButton yellowButton = new JButton("Yellow"); 12. add(yellowButton); 13. yellowButton.addActionListener(listener); 14. 15. JButton blueButton = new JButton("Blue"); 16. add(blueButton); 17. blueButton.addActionListener(listener); 18. 19. JButton redButton = new JButton("Red"); 20. add(redButton); 21. redButton.addActionListener(listener); 22. } 23. 24. private class ButtonListener implements ActionListener 25. { 26. public void actionPerformed(ActionEvent event) 27. { 28. String arg = event.getActionCommand(); 29. if (arg.equals("yellow")) 30. setBackground(Color.yellow); 31. else if (arg.equals("blue")) 32. setBackground(Color.blue); 33. else if (arg.equals("red")) 34. setBackground(Color.red); 35. } 36. } 37. }
In a program this short, you may be able to find the bug just by reading the source code. Let us pretend that scanning the source code for errors is not practical. Here is how you can run the debugger to locate the error.
To use JDB, you must first compile your program with the -g
option, for example:
javac -g BuggyButtonTest.java BuggyButtonFrame.java BuggyButtonPanel.java
When you compile with this option, the compiler adds the names of local variables and other debugging information into the class files. Then you launch the debugger:
jdb BuggyButtonTest
Once you launch the debugger, you will see a display that looks something like this:
Initializing jdb... >
The >
prompt indicates the debugger is waiting for a command. Table 11–4 shows all the debugger commands. Items enclosed in [...] are optional, and the suffix (s) means that you can supply one or more arguments separated by spaces.
Table 11–4. Debugging Commands
| Lists threads |
| Sets default thread |
| Suspends threads (default: all) |
| Resumes threads (default: all) |
| Dumps a thread’s stack |
| Dumps a thread’s stack and program counter info |
| Lists thread groups |
| Sets current thread group |
| Prints object or field |
| Prints all object information |
| Prints all current local variables |
| Lists currently known classes |
| Lists a class’s methods |
| Sets a breakpoint in a method |
| Sets a breakpoint at a line |
| Moves up a thread’s stack |
| Moves down a thread’s stack |
| Clears a breakpoint |
| Executes the current line, stepping inside calls |
| Executes the current instruction |
| Executes until the end of the current method |
| Executes the current line, stepping over calls |
| Continues execution from breakpoint |
| Breaks for the specified exception |
| Ignores the specified exception |
| Prints source code |
| Displays or changes the source path |
| Reports memory usage |
| Frees unused objects |
| Loads Java class to be debugged |
| Starts execution of a loaded Java class |
| Repeats last command |
| Lists commands |
| Exits debugger |
We cover only the most useful JDB commands in this section. The basic idea, though, is simple: you set one or more breakpoints, then run the program. When the program reaches one of the breakpoints you set, it stops. You can inspect the values of the local variables to see if they are what they are supposed to be.
To set a breakpoint, use
stop in
class.method
or the command
stop at
class:line
For example, let us set a breakpoint in the actionPerformed
method of BuggyButtonTest
. To do this, enter
stop in BuggyButtonPanel$ButtonListener.actionPerformed
Now we want to run the program up to the breakpoint, so enter
run
The program will run, but the breakpoint won’t be hit until Java starts processing code in the actionPerformed
method. For this, click on the Yellow button. The debugger breaks at the start of the actionPerformed
method. You’ll see:
Breakpoint hit: thread="AWT-EventQueue-0", BuggyButtonPanel$ButtonListener.actionPerformed (), line=28, bci=0 28 String arg = event.getActionCommand();
The list
command lets you find out where you are. The debugger will show you the current line and a few lines above and below. You also see the line numbers. For example:
24 private class ButtonListener implements ActionListener 25 { 26 public void actionPerformed(ActionEvent event) 27 { 28=> String arg = event.getActionCommand(); 29 if (arg.equals("yellow")) 30 setBackground(Color.yellow); 31 else if (arg.equals("blue")) 32 setBackground(Color.blue); 33 else if (arg.equals("red"))
Type locals
to see all local variables. For example,
Method arguments: event = instance of java.awt.event.ActionEvent(id=698) Local variables:
For more detail, use
dump
variable
For example,
dump event
displays all instance fields of the evt
variable.
event = instance of java.awt.event.ActionEvent(id=698) { SHIFT_MASK: 1 CTRL_MASK: 2 META_MASK: 4 ALT_MASK: 8 ACTION_FIRST: 1001 ACTION_LAST: 1001 ACTION_PERFORMED: 1001 actionCommand: "Yellow" modifiers: 0 serialVersionUID: -7671078796273832149 . . .
There are two basic commands to single-step through a program. The step
command steps into every method call. The next
command goes to the next line without stepping inside any further method calls. Type next
twice and then type list
to see where you are.
The program stops in line 31.
27 { 28 String arg = event.getActionCommand(); 29 if (arg.equals("yellow")) 30 setBackground(Color.yellow); 31=> else if (arg.equals("blue")) 32 setBackground(Color.blue); 33 else if (arg.equals("red")) 34 setBackground(Color.red); 35 }
That is not what should have happened. The program was supposed to call setColor(Color.yellow)
and then exit the method.
Dump the arg
variable.
arg = "Yellow"
Now you can see what happened. The value of arg
was "Yellow"
, with an uppercase Y, but the comparison tested
if (arg.equals("yellow"))
with a lowercase y
. Mystery solved.
To quit the debugger, type:
quit
As you can see from this example, the jdb
debugger can be used to find an error, but the command-line interface is very inconvenient. Remember to use list
and locals
whenever you are confused about where you are. But if you have any choice at all, use a better debugger for serious debugging work.
Eclipse has a modern and convenient debugger that has many of the amenities that you would expect. In particular, you can set breakpoints, inspect variables, and single-step through a program.
To set a breakpoint, move the cursor to the desired line and select Run -> Toggle Line Breakpoint from the menu. The breakpoint line is highlighted (see Figure 11–8).
To start debugging, select Run -> Debug As -> Java Application from the menu. The program starts running. Set a breakpoint in the first line of the actionPerformed
method.
When the debugger stops at a breakpoint, you can see the call stack and the local variables (see Figure 11–9).
To single-step through the application, use the Run -> Step into (F5) or Run -> Step over (F6) commands. In our example, press the F6 key twice to see how the program skips over the setBackground(Color.yellow)
command. Then watch the value of arg
to see the reason (see Figure 11–10).
As you can see, the Eclipse debugger is much easier to use than JDB because you have visual feedback to indicate where you are in the program. Setting breakpoints and inspecting variables is also much easier. This is typical of debuggers that are a part of an integrated development environment.
This chapter introduced you to exception handling and gave you some useful hints for testing and debugging. The next chapter covers streams.