public class

Throwable

extends Object
implements Serializable
java.lang.Object
   ↳ java.lang.Throwable
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

The superclass of all classes which can be thrown by the virtual machine. The two direct subclasses are recoverable exceptions (Exception) and unrecoverable errors (Error). This class provides common methods for accessing a string message which provides extra information about the circumstances in which the Throwable was created (basically an error message in most cases), and for saving a stack trace (that is, a record of the call stack at a particular point in time) which can be printed later.

A Throwable can also include a cause, which is a nested Throwable that represents the original problem that led to this Throwable. It is often used for wrapping various types of errors into a common Throwable without losing the detailed original error information. When printing the stack trace, the trace of the cause is included.

Summary

Public Constructors
Throwable()
Constructs a new Throwable that includes the current stack trace.
Throwable(String detailMessage)
Constructs a new Throwable with the current stack trace and the specified detail message.
Throwable(String detailMessage, Throwable throwable)
Constructs a new Throwable with the current stack trace, the specified detail message and the specified cause.
Throwable(Throwable throwable)
Constructs a new Throwable with the current stack trace and the specified cause.
Public Methods
Throwable fillInStackTrace()
Records the stack trace from the point where this method has been called to this Throwable.
Throwable getCause()
Returns the cause of this Throwable, or null if there is no cause.
String getLocalizedMessage()
Returns the extra information message which was provided when this Throwable was created.
String getMessage()
Returns the extra information message which was provided when this Throwable was created.
StackTraceElement[] getStackTrace()
Returns the array of stack trace elements of this Throwable.
Throwable initCause(Throwable throwable)
Initializes the cause of this Throwable.
void printStackTrace()
Writes a printable representation of this Throwable's stack trace to the System.err stream.
void printStackTrace(PrintWriter err)
Writes a printable representation of this Throwable's stack trace to the specified print writer.
void printStackTrace(PrintStream err)
Writes a printable representation of this Throwable's stack trace to the specified print stream.
void setStackTrace(StackTraceElement[] trace)
Sets the array of stack trace elements.
String toString()
Returns a string containing a concise, human-readable description of this object.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public Throwable ()

Constructs a new Throwable that includes the current stack trace.

public Throwable (String detailMessage)

Constructs a new Throwable with the current stack trace and the specified detail message.

Parameters
detailMessage the detail message for this Throwable.

public Throwable (String detailMessage, Throwable throwable)

Constructs a new Throwable with the current stack trace, the specified detail message and the specified cause.

Parameters
detailMessage the detail message for this Throwable.
throwable the cause of this Throwable.

public Throwable (Throwable throwable)

Constructs a new Throwable with the current stack trace and the specified cause.

Parameters
throwable the cause of this Throwable.

Public Methods

public Throwable fillInStackTrace ()

Records the stack trace from the point where this method has been called to this Throwable. The method is public so that code which catches a Throwable and then re-throws it can adjust the stack trace to represent the location where the exception was re-thrown.

Returns
  • this Throwable instance.

public Throwable getCause ()

Returns the cause of this Throwable, or null if there is no cause.

Returns
  • Throwable this Throwable's cause.

public String getLocalizedMessage ()

Returns the extra information message which was provided when this Throwable was created. Returns null if no message was provided at creation time. Subclasses may override this method to return localized text for the message. The Android reference implementation returns the unlocalized detail message.

Returns
  • this Throwable's localized detail message.

public String getMessage ()

Returns the extra information message which was provided when this Throwable was created. Returns null if no message was provided at creation time.

Returns
  • this Throwable's detail message.

public StackTraceElement[] getStackTrace ()

Returns the array of stack trace elements of this Throwable. Each StackTraceElement represents an entry in the call stack. The element at position 0 is the top of the stack, that is, the stack frame where this Throwable is thrown.

Returns
  • a copy of the array of StackTraceElements representing the call stack. Changes in the array obtained from this call will not change the call stack stored in this Throwable.

public Throwable initCause (Throwable throwable)

Initializes the cause of this Throwable. The cause can only be initialized once.

Parameters
throwable the cause of this Throwable.
Returns
  • this Throwable instance.
Throws
IllegalArgumentException if Throwable is this object.
IllegalStateException if the cause has already been initialized.

public void printStackTrace ()

Writes a printable representation of this Throwable's stack trace to the System.err stream.

public void printStackTrace (PrintWriter err)

Writes a printable representation of this Throwable's stack trace to the specified print writer. If the Throwable contains a cause, the method will be invoked recursively for the nested Throwable.

Parameters
err the writer to write the stack trace on.

public void printStackTrace (PrintStream err)

Writes a printable representation of this Throwable's stack trace to the specified print stream. If the Throwable contains a cause, the method will be invoked recursively for the nested Throwable.

Parameters
err the stream to write the stack trace on.

public void setStackTrace (StackTraceElement[] trace)

Sets the array of stack trace elements. Each StackTraceElement represents an entry in the call stack. A copy of the specified array is stored in this Throwable. will be returned by getStackTrace() and printed by printStackTrace().

Parameters
trace the new array of StackTraceElements. A copy of the array is stored in this Throwable, so subsequent changes to trace will not change the call stack stored in this Throwable.
Throws
NullPointerException if any element in trace is null.

public String toString ()

Returns a string containing a concise, human-readable description of this object. Subclasses are encouraged to override this method and provide an implementation that takes into account the object's type and data. The default implementation simply concatenates the class name, the '@' sign and a hexadecimal representation of the object's hashCode(), that is, it is equivalent to the following expression:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 

Returns
  • a printable representation of this object.