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

Throwable is the root class of all classes whose instances may be thrown as exceptions. It contains basic exception information such as a detailed error message, a cause and stack trace information.

The main subclasses of this class are Error and Exception.

Since:

1.0

See Also:

Serialized Form

Constructor Summary

Throwable()
Default constructor to create a Throwable with no detail message and with no cause set.

Throwable(String message)
Create Throwable with the given detail message and with no cause set.

Throwable(String message, Throwable cause)
Create Throwable with the given message and cause.

Throwable(Throwable cause)
Create Throwable with the given cause and detail message set to cause.toString() in case cause is not null, or no detail message otherwise.

Method Summary

Throwable	fillInStackTrace() Calls into the virtual machine to fill the current stack trace of this Throwable.
Throwable	getCause() getCause returns the cause of this exception or null if no cause was set.
String	getLocalizedMessage() Subclasses may override this message to get an error message that is localized to the default locale.
String	getMessage() getMessage returns the message describing the problem.
StackTraceElement[]	getStackTrace() Get the stack trace created by fillInStackTrace for this Throwable as an array of StackTraceElements.
Throwable	initCause(Throwable causingThrowable) Initializes the cause to the given Throwable.
void	printStackTrace() Print stack trace of this Throwable to System.err.
void	printStackTrace(PrintStream stream) Print the stack trace of this Throwable to the given stream.
void	printStackTrace(PrintWriter s) Print the stack trace of this Throwable to the given PrintWriter.
void	setStackTrace(StackTraceElement[] new_stackTrace) This method allows to override the stack trace that was filled during construction of this object.
String	toString() Creates a string describing this Throwable.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Throwable

public Throwable()

Default constructor to create a Throwable with no detail message and with no cause set.

Throwable

public Throwable(String message)

Create Throwable with the given detail message and with no cause set.

ensure

   (getMessage() == message);
 

Parameters:

message - describing the problem.

Throwable

public Throwable(Throwable cause)

Create Throwable with the given cause and detail message set to cause.toString() in case cause is not null, or no detail message otherwise.

ensure

   (   (getCause() == cause)
    && (cause!=null || getMessage() == null)
    && (cause==null || getMessage().equals(cause.toString());
 

Parameters:

cause - of the problem

Since:

1.4

Throwable

public Throwable(String message,
                 Throwable cause)

Create Throwable with the given message and cause.

Parameters:

message - describing the problem.

cause - cause of the problem.

Since:

1.4

Method Detail

fillInStackTrace

public Throwable fillInStackTrace()

Calls into the virtual machine to fill the current stack trace of this Throwable.

Returns:

a reference to this Throwable.

getMessage

public String getMessage()

getMessage returns the message describing the problem.

Returns:

the message given to the constructor or null if no message was set.

getCause

public Throwable getCause()

getCause returns the cause of this exception or null if no cause was set. The cause is another exception that was caught before this exception was created.

Returns:

The cause or null.

Since:

1.4

getLocalizedMessage

public String getLocalizedMessage()

Subclasses may override this message to get an error message that is localized to the default locale.

By default it returns getMessage().

Returns:

the value of getMessage().

Since:

1.1

initCause

public Throwable initCause(Throwable causingThrowable)

Initializes the cause to the given Throwable. This method allows also legacy Errors and Exceptions that do not have a chaining aware constructor to be initialized.

Parameters:

causingThrowable - the reason why this Throwable gets Thrown.

Returns:

the reference to this Throwable.

Throws:

IllegalArgumentException - if the cause is this Throwable itself.

IllegalStateException - if the cause of this Throwable has already been initialized.

Since:

1.4

toString

public String toString()

Creates a string describing this Throwable.

Overrides:

toString in class Object

Returns:

the name of the class, if a message was set the string ": "+getMessage() is concatenated to the result.

printStackTrace

public void printStackTrace()

Print stack trace of this Throwable to System.err.

The printed stack trace contains the result of toString() as the first line followed by one line for each stack trace element that contains the name of the method or constructor, optionally followed by the source file name and source file line number if available.

For JamaicaVM, this routine also works before System was initialized by using low-level exception printing mechanisms provided by class com.aicas.jamaica.lang.Debug.

printStackTrace

public void printStackTrace(PrintStream stream)

Print the stack trace of this Throwable to the given stream.

The printed stack trace contains the result of toString() as the first line followed by one line for each stack trace element that contains the name of the method or constructor, optionally followed by the source file name and source file line number if available.

For JamaicaVM, if printing to the stream causes another exception, low-level exception printing mechanisms provided by class com.aicas.jamaica.lang.Debug will be used to print the exception to stderr.

Parameters:

stream - the stream to print to.

printStackTrace

public void printStackTrace(PrintWriter s)

Print the stack trace of this Throwable to the given PrintWriter.

The printed stack trace contains the result of toString() as the first line followed by one line for each stack trace element that contains the name of the method or constructor, optionally followed by the source file name and source file line number if available.

For JamaicaVM, if printing to the PrintWriter causes another exception, low-level exception printing mechanisms provided by class com.aicas.jamaica.lang.Debug will be used to print the exception to stderr.

Parameters:

s - the PrintWriter to write to.

Since:

1.1

getStackTrace

public StackTraceElement[] getStackTrace()

Get the stack trace created by fillInStackTrace for this Throwable as an array of StackTraceElements.

The stack trace does not need to contain entries for all methods that are actually on the call stack, the virtual machine may decide to skip some stack trace entries. Even an empty array is a valid result of this function.

Repeated calls of this function without intervening calls to fillInStackTrace will return the same result.

For JamaicaVM, the stack trace may omit methods that are compiled by the static compiler. Particularly, methods are compiled and that do not contain an exception handler themselves usually do not require the creation of a stack frame at runtime. To improve performance, no stack frame is generated in these cases.

If memory areas of the RTSJ are used (see MemoryArea), and this Throwable was allocated in a different memory area than the current allocation context, the resulting stack trace will be allocated in either the same memory area this was allocated in or the current memory area, depending on which is the least deeply nested, thereby creating objects that are assignment compatible with both areas.

Returns:

array representing the stack trace, never null.

Since:

1.4

setStackTrace

public void setStackTrace(StackTraceElement[] new_stackTrace)

This method allows to override the stack trace that was filled during construction of this object. It is intended to be used in a serialization context when the stack trace of a remote exception should be treated like a local.

Parameters:

new_stackTrace - the stack trace to replace be used.

Throws:

NullPointerException - if new_stackTrace or any element of new_stackTrace is null.

Since:

1.4