FileDocCategorySizeDatePackage
Throwable.javaAPI DocAndroid 1.5 API14440Wed May 06 22:41:04 BST 2009java.lang

Throwable

public class Throwable extends Object implements Serializable
The superclass of all classes which can be thrown by the virtual machine. The two direct subclasses are recoverable exceptions ({@code Exception}) and unrecoverable errors ({@code Error}). This class provides common methods for accessing a string message which provides extra information about the circumstances in which the {@code 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 {@code Throwable} can also include a cause, which is a nested {@code Throwable} that represents the original problem that led to this {@code Throwable}. It is often used for wrapping various types of errors into a common {@code Throwable} without losing the detailed original error information. When printing the stack trace, the trace of the cause is included.

see
Error
see
Exception
see
RuntimeException
since
Android 1.0

Fields Summary
private static final long
serialVersionUID
private String
detailMessage
The message provided when the exception was created.
private Throwable
cause
The cause of this Throwable. Null when there is no cause.
private volatile Object
stackState
An intermediate representation of the stack trace. This field may be accessed by the VM; do not rename.
private StackTraceElement[]
stackTrace
A fully-expanded representation of the stack trace.
Constructors Summary
public Throwable()
Constructs a new {@code Throwable} that includes the current stack trace.

since
Android 1.0


                        
      
        super();
        fillInStackTrace();
public Throwable(String detailMessage)
Constructs a new {@code Throwable} with the current stack trace and the specified detail message.

param
detailMessage the detail message for this {@code Throwable}.
since
Android 1.0

        this();
        this.detailMessage = detailMessage;
public Throwable(String detailMessage, Throwable throwable)
Constructs a new {@code Throwable} with the current stack trace, the specified detail message and the specified cause.

param
detailMessage the detail message for this {@code Throwable}.
param
throwable the cause of this {@code Throwable}.
since
Android 1.0

        this();
        this.detailMessage = detailMessage;
        cause = throwable;
public Throwable(Throwable throwable)
Constructs a new {@code Throwable} with the current stack trace and the specified cause.

param
throwable the cause of this {@code Throwable}.
since
Android 1.0

        this();
        this.detailMessage = throwable == null ? null : throwable.toString();
        cause = throwable;
Methods Summary
private static intcountDuplicates(java.lang.StackTraceElement[] currentStack, java.lang.StackTraceElement[] parentStack)
Counts the number of duplicate stack frames, starting from the end of the stack.

param
currentStack a stack to compare
param
parentStack a stack to compare
return
the number of duplicate stack frames.

        int duplicates = 0;
        int parentIndex = parentStack.length;
        for (int i = currentStack.length; --i >= 0 && --parentIndex >= 0;) {
            StackTraceElement parentFrame = parentStack[parentIndex];
            if (parentFrame.equals(currentStack[i])) {
                duplicates++;
            } else {
                break;
            }
        }
        return duplicates;
public java.lang.ThrowablefillInStackTrace()
Records the stack trace from the point where this method has been called to this {@code Throwable}. The method is public so that code which catches a {@code Throwable} and then re-throws it can adjust the stack trace to represent the location where the exception was re-thrown.

return
this {@code Throwable} instance.
since
Android 1.0

        // Fill in the intermediate representation
        stackState = nativeFillInStackTrace();
        // Mark the full representation as empty
        stackTrace = null;
        return this;
public java.lang.ThrowablegetCause()
Returns the cause of this {@code Throwable}, or {@code null} if there is no cause.

return
Throwable this {@code Throwable}'s cause.
since
Android 1.0

        if (cause == this) {
            return null;
        }
        return cause;
private java.lang.StackTraceElement[]getInternalStackTrace()
Returns an array of StackTraceElement. Each StackTraceElement represents a entry on the stack.

return
an array of StackTraceElement representing the stack

        if (stackTrace == null) {
            // BEGIN android-changed
            stackTrace = nativeGetStackTrace(stackState);
            stackState = null; // Clean up intermediate representation
            // END android-changed
        }
        return stackTrace;
public java.lang.StringgetLocalizedMessage()
Returns the extra information message which was provided when this {@code Throwable} was created. Returns {@code 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.

return
this {@code Throwable}'s localized detail message.
since
Android 1.0

        return getMessage();
public java.lang.StringgetMessage()
Returns the extra information message which was provided when this {@code Throwable} was created. Returns {@code null} if no message was provided at creation time.

return
this {@code Throwable}'s detail message.
since
Android 1.0

        return detailMessage;
public java.lang.StackTraceElement[]getStackTrace()
Returns the array of stack trace elements of this {@code Throwable}. Each {@code 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 {@code Throwable} is thrown.

return
a copy of the array of {@code StackTraceElement}s representing the call stack. Changes in the array obtained from this call will not change the call stack stored in this {@code Throwable}.
see
#printStackTrace()
since
Android 1.0

        return getInternalStackTrace().clone();
public java.lang.ThrowableinitCause(java.lang.Throwable throwable)
Initializes the cause of this {@code Throwable}. The cause can only be initialized once.

param
throwable the cause of this {@code Throwable}.
return
this {@code Throwable} instance.
throws
IllegalArgumentException if {@code Throwable} is this object.
throws
IllegalStateException if the cause has already been initialized.
since
Android 1.0

        // BEGIN android-note
        // removed synchronized modifier
        // END android-note
        if (cause == this) {
            if (throwable != this) {
                cause = throwable;
                return this;
            }
            throw new IllegalArgumentException("Cause cannot be the receiver");
        }
        throw new IllegalStateException("Cause already initialized");
private static native java.lang.ObjectnativeFillInStackTrace()

private static native java.lang.StackTraceElement[]nativeGetStackTrace(java.lang.Object stackState)
public voidprintStackTrace()
Writes a printable representation of this {@code Throwable}'s stack trace
to the {@code System.err} stream.
since
Android 1.0
        printStackTrace(System.err);
    
public voidprintStackTrace(java.io.PrintStream err)
Writes a printable representation of this {@code Throwable}'s stack trace
to the specified print stream. If the {@code Throwable} contains a
{@link #getCause() cause}, the method will be invoked recursively for
the nested {@code Throwable}.
param
err
the stream to write the stack trace on.
since
Android 1.0
        err.println(toString());
        // Don't use getStackTrace() as it calls clone()
        // Get stackTrace, in case stackTrace is reassigned
        StackTraceElement[] stack = getInternalStackTrace();
        for (java.lang.StackTraceElement element : stack) {
            err.println("\tat " + element);
        }

        StackTraceElement[] parentStack = stack;
        Throwable throwable = getCause();
        while (throwable != null) {
            err.print("Caused by: ");
            err.println(throwable);
            StackTraceElement[] currentStack = throwable.getInternalStackTrace();
            int duplicates = countDuplicates(currentStack, parentStack);
            for (int i = 0; i < currentStack.length - duplicates; i++) {
                err.println("\tat " + currentStack[i]);
            }
            if (duplicates > 0) {
                err.println("\t... " + duplicates + " more");
            }
            parentStack = currentStack;
            throwable = throwable.getCause();
        }
    
public voidprintStackTrace(java.io.PrintWriter err)
Writes a printable representation of this {@code Throwable}'s stack trace
to the specified print writer. If the {@code Throwable} contains a
{@link #getCause() cause}, the method will be invoked recursively for the
nested {@code Throwable}.
param
err
the writer to write the stack trace on.
since
Android 1.0
        err.println(toString());
        // Don't use getStackTrace() as it calls clone()
        // Get stackTrace, in case stackTrace is reassigned
        StackTraceElement[] stack = getInternalStackTrace();
        for (java.lang.StackTraceElement element : stack) {
            err.println("\tat " + element);
        }

        StackTraceElement[] parentStack = stack;
        Throwable throwable = getCause();
        while (throwable != null) {
            err.print("Caused by: ");
            err.println(throwable);
            StackTraceElement[] currentStack = throwable.getInternalStackTrace();
            int duplicates = countDuplicates(currentStack, parentStack);
            for (int i = 0; i < currentStack.length - duplicates; i++) {
                err.println("\tat " + currentStack[i]);
            }
            if (duplicates > 0) {
                err.println("\t... " + duplicates + " more");
            }
            parentStack = currentStack;
            throwable = throwable.getCause();
        }
    
public voidsetStackTrace(java.lang.StackTraceElement[] trace)
Sets the array of stack trace elements. Each {@code StackTraceElement}
represents an entry in the call stack. A copy of the specified array is
stored in this {@code Throwable}. will be returned by {@code
getStackTrace()} and printed by {@code printStackTrace()}.
param
trace
the new array of {@code StackTraceElement}s. A copy of the
array is stored in this {@code Throwable}, so subsequent
changes to {@code trace} will not change the call stack stored
in this {@code Throwable}.
throws
NullPointerException
if any element in {@code trace} is {@code null}.
see
#printStackTrace()
since
Android 1.0
        StackTraceElement[] newTrace = trace.clone();
        for (java.lang.StackTraceElement element : newTrace) {
            if (element == null) {
                throw new NullPointerException();
            }
        }
        stackTrace = newTrace;
    
public java.lang.StringtoString()
        String msg = getLocalizedMessage();
        String name = getClass().getName();
        if (msg == null) {
            return name;
        }
        return new StringBuffer(name.length() + 2 + msg.length()).append(name).append(": ")
                .append(msg).toString();
    
private voidwriteObject(java.io.ObjectOutputStream s)
        // ensure the stackTrace field is initialized
        getInternalStackTrace();
        s.defaultWriteObject();