javax.realtime

Interface StaticThrowable<T extends StaticThrowable<T>>

All Known Implementing Classes:

AlignmentError, ArrivalTimeQueueOverflowException, AsynchronouslyInterruptedException, AsynchronouslyInterruptedException, BackingStoreAllocationException, CeilingViolationException, ConstraintExceededException, ConstructorCheckedException, DeregistrationException, EventQueueOverflowException, ForEachTerminationException, IllegalAssignmentError, IllegalTaskStateException, InaccessibleAreaException, LateStartException, MemoryAccessError, MemoryInUseException, MemoryScopeException, MemoryTypeConflictException, MITViolationException, OffsetOutOfBoundsException, POSIXInvalidSignalException, POSIXInvalidTargetException, POSIXSignalPermissionException, ProcessorAffinityException, RangeOutOfBoundsException, RegistrationException, ResourceLimitError, ScopedCycleException, SizeOutOfBoundsException, StaticIllegalArgumentException, StaticIllegalStateException, StaticOutOfMemoryError, StaticSecurityException, StaticUnsupportedOperationException, ThrowBoundaryError, Timed, Timed, UninitializedStateException, UnsupportedRawMemoryRegionException

public interface StaticThrowable<T extends StaticThrowable<T>>

A marker interface to indicate that a Throwable is intended to be created once and reused. Throwables that implement this interface keep their state in a ThreadLocal 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 of AsyncBaseEventHandler always have some instance of Thread 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 fill the stack backtrace and clear the message and cause.

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

throw LateStartException.get().init(message, cause);

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 a static throwable by implementing StaticThrowable should extend one of predefined classes: StaticError, StaticCheckedException, or StaticRuntimeException. When this is not possible because one needs to extend an existing conventional Java exception, the new throwable must override its methods and redirect them to the local instance of StaticThrowableStorage. For example, the following code snippet reimplements initMessage using StaticThrowableStorage:

 public Throwable initMessage(String message)
 {
   StaticThrowableStorage.getCurrent().initMessage(message);
   return this;
 }
 

Stack trace, message, and cause must be stored in and retrieved from this thread's local storage structure.

Since:

RTSJ 2.0

See Also:

ConfigurationParameters

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	StaticThrowable.Hidden A marker for static throwable support methods that should not be seen in a stack trace.

Method Summary

Modifier and Type	Method and Description
java.lang.Throwable	fillInStackTrace() Calls into the virtual machine to capture the current stack trace in the instance of StaticThrowableStorage associated with this task.
java.lang.Throwable	getCause() Gets the cause from thread local memory of the calling 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() Gets the message describing the exception's cause from thread local memory.
StaticThrowable<?>	getSingleton() For the case of legacy code that creates an RTSJ exception explicity, this provides a means of obtaining its singleton version.
java.lang.StackTraceElement[]	getStackTrace() Gets the stack trace created by fillInStackTrace for this Throwable from the current thread local storage as an array of StackTraceElements.
default T	init() Store the message of the calling exception in the instance of StaticThrowableStorage associated with this task.
default T	init(java.lang.String message) Store the message of the calling exception in the instance of StaticThrowableStorage associated with this task.
default T	init(java.lang.String message, java.lang.Throwable cause) Store the message of the calling exception in the instance of StaticThrowableStorage associated with this task.
default T	init(java.lang.Throwable cause) Store the message of the calling exception in the instance of StaticThrowableStorage associated with this task.
java.lang.Throwable	initCause(java.lang.Throwable causingThrowable) Store the cause of calling exception in the instance of StaticThrowableStorage associated with this task.
default boolean	isStatic() Determine whether or not this is the static instance of this Throwable.
void	printStackTrace() Prints stack trace of this Throwable to System.err.
void	printStackTrace(java.io.PrintStream stream) Prints the stack trace of this Throwable to the given stream.
void	printStackTrace(java.io.PrintWriter s) Prints the stack trace of this Throwable to the given PrintWriter.
void	setStackTrace(java.lang.StackTraceElement[] new_stackTrace) This method enables overriding the stack trace that was filled during construction of this object.
default java.lang.Object	writeReplace() Replace this objected with a special transport object when serializing.

Method Detail

init

default T init()

Store the message of the calling exception in the instance of StaticThrowableStorage associated with this task. This is the only method not defined in java.lang.Throwable.

Returns:

this object.

Since:

RTSJ 2.0 implemented by all static throwables

init

default T init(java.lang.String message)

Store the message of the calling exception in the instance of StaticThrowableStorage associated with this task. This is the only method not defined in java.lang.Throwable.

Parameters:

message - Text to be saved describing the exception's cause.

Returns:

this object.

Since:

RTSJ 2.0 implemented by all static throwables

init

default T init(java.lang.String message,
               java.lang.Throwable cause)

Store the message of the calling exception in the instance of StaticThrowableStorage associated with this task. This is the only method not defined in java.lang.Throwable.

Parameters:

message - Text to be saved describing the exception's cause.

cause - Another throwable that lead to this one being throwm.

Returns:

this object.

Since:

RTSJ 2.0 implemented by all static throwables

init

default T init(java.lang.Throwable cause)

Store the message of the calling exception in the instance of StaticThrowableStorage associated with this task. This is the only method not defined in java.lang.Throwable.

Parameters:

cause - Another throwable that lead to this one being throwm.

Returns:

this object.

Since:

RTSJ 2.0 implemented by all static throwables

writeReplace

default java.lang.Object writeReplace()

Replace this objected with a special transport object when serializing.

Returns:

the proxy object.

getSingleton

StaticThrowable<?> getSingleton()

For the case of legacy code that creates an RTSJ exception explicity, this provides a means of obtaining its singleton version.

Returns:

the singleton version of this exception.

Since:

RTSJ 2.0 implemented by all static throwables

isStatic

default boolean isStatic()

Determine whether or not this is the static instance of this Throwable.

Returns:

true when it is the singleton instance and false otherwise.

Since:

RTSJ 2.0 implemented by all static throwables

getMessage

java.lang.String getMessage()

Gets the message describing the exception's cause from thread local memory.

Returns:

the message when this was the last method thrown and message was set for it or null.

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)

Store the cause of calling exception in the instance of StaticThrowableStorage associated with this task.

Parameters:

causingThrowable - The reason why this Throwable gets thrown.

Returns:

the reference to this Throwable.

Throws:

StaticIllegalArgumentException - when the cause is this Throwable itself.

getCause

java.lang.Throwable getCause()

Gets the cause from thread local memory of the calling exception or null when no cause was set. The cause is another exception that was caught before the current exception is to be thrown.

Returns:

the cause when this was the last thrown exception and cause was set or null.

fillInStackTrace

java.lang.Throwable fillInStackTrace()

Calls into the virtual machine to capture the current stack trace in the instance of StaticThrowableStorage associated with this task.

Returns:

a reference to this Throwable.

setStackTrace

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

This method enables 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 be used as replace.

Throws:

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

getStackTrace

java.lang.StackTraceElement[] getStackTrace()

Gets the stack trace created by fillInStackTrace for this Throwable from the current thread local storage 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:

An array representing the stack trace when this was the last message thrown or an empty trace array, but never null.

printStackTrace

void printStackTrace()

Prints 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)

Prints 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)

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