JavaTM 2 Platform
Std. Ed. v1.3.1

java.lang
Class Throwable

java.lang.Object
  |
  +--java.lang.Throwable
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
Error, Exception

public class Throwable
extends Object
implements Serializable

The Throwable class is the superclass of all errors and exceptions in the Java language. Only objects that are instances of this class (or of one of its subclasses) are thrown by the Java Virtual Machine or can be thrown by the Java throw statement. Similarly, only this class or one of its subclasses can be the argument type in a catch clause.

Instances of two subclasses, Error and Exception, are conventionally used to indicate that exceptional situations have occurred. Typically, these instances are freshly created in the context of the exceptional situation so as to include relevant information (such as stack trace data).

By convention, class Throwable and its subclasses have two constructors, one that takes no arguments and one that takes a String argument that can be used to produce an error message.

A Throwable class contains a snapshot of the execution stack of its thread at the time it was created. It can also contain a message string that gives more information about the error.

Here is one example of catching an exception:

     try {
         int a[] = new int[2];
         a[4];
     } catch (ArrayIndexOutOfBoundsException e) {
         System.out.println("exception: " + e.getMessage());
         e.printStackTrace();
     }
 

Since:
JDK1.0
See Also:
Serialized Form

Constructor Summary
Throwable()
          Constructs a new Throwable with null as its error message string.
Throwable(String message)
          Constructs a new Throwable with the specified error message.
 
Method Summary
 Throwable fillInStackTrace()
          Fills in the execution stack trace.
 String getLocalizedMessage()
          Creates a localized description of this Throwable.
 String getMessage()
          Returns the error message string of this throwable object.
 void printStackTrace()
          Prints this Throwable and its backtrace to the standard error stream.
 void printStackTrace(PrintStream s)
          Prints this Throwable and its backtrace to the specified print stream.
 void printStackTrace(PrintWriter s)
          Prints this Throwable and its backtrace to the specified print writer.
 String toString()
          Returns a short description of this throwable object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Throwable

public Throwable()
Constructs a new Throwable with null as its error message string. Also, the method fillInStackTrace() is called for this object.

Throwable

public Throwable(String message)
Constructs a new Throwable with the specified error message. Also, the method fillInStackTrace() is called for this object.
Parameters:
message - the error message. The error message is saved for later retrieval by the getMessage() method.
Method Detail

getMessage

public String getMessage()
Returns the error message string of this throwable object.
Returns:
the error message string of this Throwable object if it was created with an error message string; or null if it was created with no error message.

getLocalizedMessage

public String getLocalizedMessage()
Creates a localized description of this Throwable. Subclasses may override this method in order to produce a locale-specific message. For subclasses that do not override this method, the default implementation returns the same result as getMessage().
Returns:
The localized description of this Throwable.
Since:
JDK1.1

toString

public String toString()
Returns a short description of this throwable object. If this Throwable object was created with an error message string, then the result is the concatenation of three strings: If this Throwable object was created with no error message string, then the name of the actual class of this object is returned.
Overrides:
toString in class Object
Returns:
a string representation of this Throwable.

printStackTrace

public void printStackTrace()
Prints this Throwable and its backtrace to the standard error stream. This method prints a stack trace for this Throwable object on the error output stream that is the value of the field System.err. The first line of output contains the result of the toString() method for this object. Remaining lines represent data previously recorded by the method fillInStackTrace(). The format of this information depends on the implementation, but the following example may be regarded as typical:
 java.lang.NullPointerException
         at MyClass.mash(MyClass.java:9)
         at MyClass.crunch(MyClass.java:6)
         at MyClass.main(MyClass.java:3)
 
This example was produced by running the program:
 
 class MyClass {
 
     public static void main(String[] argv) {
         crunch(null);
     }
     static void crunch(int[] a) {
         mash(a);
     }
 
     static void mash(int[] b) {
         System.out.println(b[0]);
     }
 }
 
See Also:
System.err

printStackTrace

public void printStackTrace(PrintStream s)
Prints this Throwable and its backtrace to the specified print stream.
Parameters:
s - PrintStream to use for output

printStackTrace

public void printStackTrace(PrintWriter s)
Prints this Throwable and its backtrace to the specified print writer.
Parameters:
s - PrintWriter to use for output
Since:
JDK1.1

fillInStackTrace

public Throwable fillInStackTrace()
Fills in the execution stack trace. This method records within this Throwable object information about the current state of the stack frames for the current thread. This method is useful when an application is re-throwing an error or exception. For example:

     try {
         a = b / c;
     } catch(ArithmeticThrowable e) {
         a = Double.MAX_VALUE;
         throw e.fillInStackTrace();
     }
 
Returns:
this Throwable object.
See Also:
printStackTrace()

JavaTM 2 Platform
Std. Ed. v1.3.1

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Java, Java 2D, and JDBC are trademarks or registered trademarks of Oracle and/or its affiliates, in the US and other countries.
Copyright © 1995, 2010 Oracle and/or its affiliates. All rights reserved.