Skip to content

Most visited

Recently visited

navigation
Added in API level 1

Throwable

public class Throwable
extends Object implements Serializable

java.lang.Object
   ↳ java.lang.Throwable
Known Direct Subclasses
Known Indirect Subclasses


The superclass of all classes which can be thrown by the VM. 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.

See also:

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 given detail message.

Throwable(String detailMessage, Throwable cause)

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

Throwable(Throwable cause)

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

Protected constructors

Throwable(String detailMessage, Throwable cause, boolean enableSuppression, boolean writableStackTrace)

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

Public methods

final void addSuppressed(Throwable throwable)

Adds throwable to the list of throwables suppressed by this.

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 detail message which was provided when this Throwable was created.

String getMessage()

Returns the detail message which was provided when this Throwable was created.

StackTraceElement[] getStackTrace()

Returns a clone of the array of stack trace elements of this Throwable.

final Throwable[] getSuppressed()

Returns the throwables suppressed by this.

Throwable initCause(Throwable throwable)

Initializes the cause of this Throwable.

void printStackTrace(PrintStream err)

Writes a printable representation of this Throwable's stack trace to the given print stream.

void printStackTrace(PrintWriter err)

Writes a printable representation of this Throwable's stack trace to the specified print writer.

void printStackTrace()

Writes a printable representation of this Throwable's stack trace to the System.err 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.

Inherited methods

From class java.lang.Object

Public constructors

Throwable

Added in API level 1
Throwable ()

Constructs a new Throwable that includes the current stack trace.

Throwable

Added in API level 1
Throwable (String detailMessage)

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

Parameters
detailMessage String

Throwable

Added in API level 1
Throwable (String detailMessage, 
                Throwable cause)

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

Parameters
detailMessage String
cause Throwable

Throwable

Added in API level 1
Throwable (Throwable cause)

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

Parameters
cause Throwable

Protected constructors

Throwable

Added in API level 19
Throwable (String detailMessage, 
                Throwable cause, 
                boolean enableSuppression, 
                boolean writableStackTrace)

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

Parameters
detailMessage String
cause Throwable
enableSuppression boolean: if false, addSuppressed(Throwable) will be a no-op.
writableStackTrace boolean: if false, fillInStackTrace() will not be called, this object's stackTrace will be null, calls to fillInStackTrace() and setStackTrace(StackTraceElement[]) will be no-ops, and getStackTrace() will return a zero-length array.

Public methods

addSuppressed

Added in API level 19
void addSuppressed (Throwable throwable)

Adds throwable to the list of throwables suppressed by this. The throwable will included when this exception's stack trace is printed.

Parameters
throwable Throwable
Throws
IllegalArgumentException if throwable == this.
NullPointerException if throwable == null.

fillInStackTrace

Added in API level 1
Throwable fillInStackTrace ()

Records the stack trace from the point where this method has been called to this Throwable. This method is invoked by the Throwable constructors.

This method is public so that code (such as an RPC system) which catches a Throwable and then re-throws it can replace the construction-time stack trace with a stack trace from the location where the exception was re-thrown, by calling fillInStackTrace.

This method is non-final so that non-Java language implementations can disable VM stack traces for their language. Filling in the stack trace is relatively expensive. Overriding this method in the root of a language's exception hierarchy allows the language to avoid paying for something it doesn't need.

Returns
Throwable this Throwable instance.

getCause

Added in API level 1
Throwable getCause ()

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

Returns
Throwable

getLocalizedMessage

Added in API level 1
String getLocalizedMessage ()

Returns the detail 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. Android returns the regular detail message.

Returns
String

getMessage

Added in API level 1
String getMessage ()

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

Returns
String

getStackTrace

Added in API level 1
StackTraceElement[] getStackTrace ()

Returns a clone of 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
StackTraceElement[]

See also:

getSuppressed

Added in API level 19
Throwable[] getSuppressed ()

Returns the throwables suppressed by this.

Returns
Throwable[]

initCause

Added in API level 1
Throwable initCause (Throwable throwable)

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

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

printStackTrace

Added in API level 1
void printStackTrace (PrintStream err)

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

Parameters
err PrintStream

printStackTrace

Added in API level 1
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 PrintWriter: the writer to write the stack trace on.

printStackTrace

Added in API level 1
void printStackTrace ()

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

setStackTrace

Added in API level 1
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 StackTraceElement: 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.

See also:

toString

Added in API level 1
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 is equivalent to the following expression:

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

See Writing a useful toString method if you intend implementing your own toString method.

Returns
String a printable representation of this object.
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.