javax.realtime

Interface StaticThrowable

All Known Implementing Classes:

StaticRuntimeException, UninitializedStateException

public interface StaticThrowable

A marker interface to indicate that a Throwable is intended to be created once and reused. Throwables that implement this interface kept their state in a RealtimeThread local data structure instead of the object itself. This means that data is only valid until the next StaticThrowable is thrown in the context of the current thread. Instances AsyncBaseEventHandler always have some instance of RealtimeThread when executing. Having a marker interface makes it easier to provide checking tools to ensure the proper throw sequence for all Throwables thrown from application code.

Throwables which implement this interface should define a get() method that returns the singleton throwable of that class. It should also initialize the stack backtrace. The message and cause should be cleared.

An application which throws a static exception should use the following paradigm:

throw LateStartException.get().initMessage("....").initCause(...);

The message must be initialized before the cause, because initMessage is defined on StaticThrowable but not Throwable. Setting the message and the cause are both optional.

Applications which define static throwables should extend one of StaticError, StaticCheckedException, or StaticRuntimeException

Since:

RTSJ 2.0

See Also:

ConfigurationParameters

Method Summary

Modifier and Type	Method and Description
java.lang.Throwable	fillInStackTrace() Calls into the virtual machine to capture the current stack trace in SO local memory.
java.lang.Throwable	getCause() getCause returns the cause of this exception or null when no cause was set.
java.lang.String	getLocalizedMessage() Subclasses may override this message to get an error message that is localized to the default locale.
java.lang.String	getMessage() get the message describing the problem from SO local memory.
java.lang.StackTraceElement[]	getStackTrace() Get the stack trace created by fillInStackTrace for this Throwable as an array of StackTraceElements.
java.lang.Throwable	initCause(java.lang.Throwable causingThrowable) Initializes the cause to the given Throwable is SO local memory.
java.lang.Throwable	initMessage(java.lang.String message) Set the message in SO local storage.
void	printStackTrace() Print stack trace of this Throwable to System.err.
void	printStackTrace(java.io.PrintStream stream) Print the stack trace of this Throwable to the given stream.
void	printStackTrace(java.io.PrintWriter s) Print the stack trace of this Throwable to the given PrintWriter.
void	setStackTrace(java.lang.StackTraceElement[] new_stackTrace) This method allows overriding the stack trace that was filled during construction of this object.

Method Detail

initMessage

java.lang.Throwable initMessage(java.lang.String message)

Set the message in SO local storage. This is the only method not defined in java.lang.Throwable.

Parameters:

message - is the text to save.

getMessage

java.lang.String getMessage()

get the message describing the problem from SO local memory.

Returns:

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

getLocalizedMessage

java.lang.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().

initCause

java.lang.Throwable initCause(java.lang.Throwable causingThrowable)

Initializes the cause to the given Throwable is SO local memory.

Parameters:

causingThrowable - the reason why this Throwable gets Thrown.

Returns:

the reference to this Throwable.

Throws:

java.lang.IllegalArgumentException - when the cause is this Throwable itself.

getCause

java.lang.Throwable getCause()

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

Returns:

The cause or null.

fillInStackTrace

java.lang.Throwable fillInStackTrace()

Calls into the virtual machine to capture the current stack trace in SO local memory.

Returns:

a reference to this Throwable.

setStackTrace

void setStackTrace(java.lang.StackTraceElement[] new_stackTrace)
            throws java.lang.NullPointerException

This method allows overriding 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:

java.lang.NullPointerException - when new_stackTrace or any element of new_stackTrace is null.

getStackTrace

java.lang.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.

When 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.

printStackTrace

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 when available.

printStackTrace

void printStackTrace(java.io.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 when available.

Parameters:

stream - the stream to print to.

printStackTrace

void printStackTrace(java.io.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 when available.

Parameters:

s - the PrintWriter to write to.