public interface StaticThrowable<T extends StaticThrowable<T>>
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.
ConfigurationParameters
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.
|
default T init()
StaticThrowableStorage
associated with this task.
This is the only method not defined in java.lang.Throwable
.this
object.default T init(java.lang.String message)
StaticThrowableStorage
associated with this task.
This is the only method not defined in java.lang.Throwable
.message
- Text to be saved describing the exception's cause.this
object.default T init(java.lang.String message, java.lang.Throwable cause)
StaticThrowableStorage
associated with this task.
This is the only method not defined in java.lang.Throwable
.message
- Text to be saved describing the exception's cause.cause
- Another throwable that lead to this one being throwm.this
object.default T init(java.lang.Throwable cause)
StaticThrowableStorage
associated with this task.
This is the only method not defined in java.lang.Throwable
.cause
- Another throwable that lead to this one being throwm.this
object.default java.lang.Object writeReplace()
StaticThrowable<?> getSingleton()
default boolean isStatic()
Throwable
.true
when it is the singleton instance and false
otherwise.java.lang.String getMessage()
null
.java.lang.String getLocalizedMessage()
By default it returns getMessage()
.
getMessage()
.java.lang.Throwable initCause(java.lang.Throwable causingThrowable)
StaticThrowableStorage
associated with this task.causingThrowable
- The reason why this Throwable
gets thrown.Throwable
.StaticIllegalArgumentException
- when the cause is this
Throwable
itself.java.lang.Throwable getCause()
null
when no cause was set. The cause is another
exception that was caught before the current exception is to be thrown.null
.java.lang.Throwable fillInStackTrace()
StaticThrowableStorage
associated with this task.Throwable
.void setStackTrace(java.lang.StackTraceElement[] new_stackTrace) throws java.lang.NullPointerException
new_stackTrace
- the stack trace to be used as replace.java.lang.NullPointerException
- when new_stackTrace or any element of
new_stackTrace is null
.java.lang.StackTraceElement[] getStackTrace()
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.
null
.void printStackTrace()
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.
void printStackTrace(java.io.PrintStream stream)
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.
stream
- The stream to print to.void printStackTrace(java.io.PrintWriter s)
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.
s
- The PrintWriter to write to.