javax.realtime

Class StaticThrowableStorage

java.lang.Object

java.lang.Throwable

javax.realtime.StaticThrowableStorage

All Implemented Interfaces:

Serializable

public class StaticThrowableStorage
extends Throwable

Provides the methods for managing the thread local memory used for storing the data needed by preallocated throwables, i.e., exceptions and errors which implement StaticThrowable. This call is visible so that an application can extend an existing conventional Java throwable and still implement StaticThrowable; its methods can be implemented using the methods defined in this class. An application defined throwable that does not need to extend an existing conventional Java throwable should extend one of StaticCheckedException, StaticRuntimeException, or StaticError instead.

Since:

RTSJ 2.0

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static char[]	BAD_MESSAGE
static javax.realtime.StaticThrowableStorage.StaticStackTraceElement[]	EMPTY_TRACE A single copy of an empty stack trace.

Method Summary

Modifier and Type	Method and Description
Throwable	fillInStackTrace() Captures the current thread's stack trace and saves it in thread local storage.
Throwable	getCause() Gets the cause from thread local storage that was saved by the last preallocated exception thrown.
static StaticThrowableStorage	getCurrent() A means of obtaining the storage object for the current task and throwable.
StaticThrowable<?>	getLastThrown() Determine for what throwable the data is valid;
String	getLocalizedMessage() Creates a localized description of this throwable.
String	getMessage() Gets the message from thread local storage that was saved by the last preallocated exception thrown.
StackTraceElement[]	getStackTrace() Gets the stack trace from thread local storage that was saved by the last preallocated exception thrown.
Throwable	initCause(Throwable cause) Saves the message in thread local storage for later retrieval.
static StaticThrowableStorage	initCurrent(StaticThrowable<?> throwable) Obtaining the storage object for the current task and initialize it.
StaticThrowableStorage	initMessage(String message) Saves the message in thread local storage for later retrieval.
void	printStackTrace() Prints this throwable and its backtrace to the standard error stream.
void	printStackTrace(PrintStream stream) Prints this throwable and its backtrace to the specified print stream.
void	printStackTrace(PrintWriter writer) Prints this throwable and its backtrace to the specified print writer.
void	setStackTrace(StackTraceElement[] stackTrace) Sets the stack trace elements that will be returned by Throwable.getStackTrace() and printed by Throwable.printStackTrace() and related methods.

Methods inherited from class java.lang.Throwable

addSuppressed, getSuppressed, toString

Methods inherited from class java.lang.Object

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

Field Detail

EMPTY_TRACE

public static final javax.realtime.StaticThrowableStorage.StaticStackTraceElement[] EMPTY_TRACE

A single copy of an empty stack trace.

BAD_MESSAGE

public static final char[] BAD_MESSAGE

Method Detail

getCurrent

public static StaticThrowableStorage getCurrent()

A means of obtaining the storage object for the current task and throwable.

Returns:

the storage object for the current task.

initCurrent

public static StaticThrowableStorage initCurrent(StaticThrowable<?> throwable)

Obtaining the storage object for the current task and initialize it.

Throws:

NullPointerException - when throwable is null

Returns:

the storage object for the current task.

getLastThrown

public StaticThrowable<?> getLastThrown()

Determine for what throwable the data is valid;

Returns:

the current context for the throwable data stored in this object.

fillInStackTrace

public Throwable fillInStackTrace()

Captures the current thread's stack trace and saves it in thread local storage. Only the part of the stack trace that fits in the preallocated buffer is stored. This method should be called by a preallocated exception to implement its method of the same name.

Overrides:

fillInStackTrace in class Throwable

Returns:

this

See Also:

Throwable.printStackTrace()

getMessage

public String getMessage()

Gets the message from thread local storage that was saved by the last preallocated exception thrown. This method should be called by a preallocated exception to implement its method of the same name.

Overrides:

getMessage in class Throwable

Returns:

the message.

initMessage

public StaticThrowableStorage initMessage(String message)

Saves the message in thread local storage for later retrieval. Only the part of the message that fits in the preallocated buffer is stored. This method should be called by a preallocated exception to implement its method of the same name.

Parameters:

message - The description to save.

Returns:

this

getCause

public Throwable getCause()

Gets the cause from thread local storage that was saved by the last preallocated exception thrown. The actual exception of cause is not saved, but just a reference to its type. This returns a newly allocated exception without any valid content, i.e., no valid stack trace. This method should be called by a preallocated exception to implement its method of the same name.

Overrides:

getCause in class Throwable

Returns:

the throwable that caused the condition or null when none was set.

initCause

public Throwable initCause(Throwable cause)

Saves the message in thread local storage for later retrieval. Only a reference to the exception class is stored. The rest of its information is lost. This method should be called by a preallocated exception to implement its method of the same name.

Overrides:

initCause in class Throwable

Parameters:

cause - In the case of cascading throwables, the exception or error that was the original cause.

Returns:

this

getStackTrace

public StackTraceElement[] getStackTrace()

Gets the stack trace from thread local storage that was saved by the last preallocated exception thrown. This method should be called by a preallocated exception to implement its method of the same name.

Overrides:

getStackTrace in class Throwable

Returns:

an array of the elements of the stack trace.

getLocalizedMessage

public String getLocalizedMessage()

Description copied from class: Throwable

Creates a localized description of this throwable. Subclasses may override this method in order to produce a locale-specific message. For subclasses that do not override this method, the default implementation returns the same result as getMessage().

Overrides:

getLocalizedMessage in class Throwable

Returns:

The localized description of this throwable.

setStackTrace

public void setStackTrace(StackTraceElement[] stackTrace)

Description copied from class: Throwable

Sets the stack trace elements that will be returned by Throwable.getStackTrace() and printed by Throwable.printStackTrace() and related methods. This method, which is designed for use by RPC frameworks and other advanced systems, allows the client to override the default stack trace that is either generated by Throwable.fillInStackTrace() when a throwable is constructed or deserialized when a throwable is read from a serialization stream.

If the stack trace of this Throwable is not writable, calling this method has no effect other than validating its argument.

Overrides:

setStackTrace in class Throwable

Parameters:

stackTrace - the stack trace elements to be associated with this Throwable. The specified array is copied by this call; changes in the specified array after the method invocation returns will have no affect on this Throwable's stack trace.

printStackTrace

public void printStackTrace()

Description copied from class: Throwable

Prints this throwable and its backtrace to the standard error stream. This method prints a stack trace for this Throwable object on the error output stream that is the value of the field System.err. The first line of output contains the result of the Throwable.toString() method for this object. Remaining lines represent data previously recorded by the method Throwable.fillInStackTrace(). The format of this information depends on the implementation, but the following example may be regarded as typical:

 java.lang.NullPointerException
         at MyClass.mash(MyClass.java:9)
         at MyClass.crunch(MyClass.java:6)
         at MyClass.main(MyClass.java:3)
 

This example was produced by running the program:

 class MyClass {
     public static void main(String[] args) {
         crunch(null);
     }
     static void crunch(int[] a) {
         mash(a);
     }
     static void mash(int[] b) {
         System.out.println(b[0]);
     }
 }
 

The backtrace for a throwable with an initialized, non-null cause should generally include the backtrace for the cause. The format of this information depends on the implementation, but the following example may be regarded as typical:

 HighLevelException: MidLevelException: LowLevelException
         at Junk.a(Junk.java:13)
         at Junk.main(Junk.java:4)
 Caused by: MidLevelException: LowLevelException
         at Junk.c(Junk.java:23)
         at Junk.b(Junk.java:17)
         at Junk.a(Junk.java:11)
         ... 1 more
 Caused by: LowLevelException
         at Junk.e(Junk.java:30)
         at Junk.d(Junk.java:27)
         at Junk.c(Junk.java:21)
         ... 3 more
 

Note the presence of lines containing the characters "...". These lines indicate that the remainder of the stack trace for this exception matches the indicated number of frames from the bottom of the stack trace of the exception that was caused by this exception (the "enclosing" exception). This shorthand can greatly reduce the length of the output in the common case where a wrapped exception is thrown from same method as the "causative exception" is caught. The above example was produced by running the program:

 public class Junk {
     public static void main(String args[]) {
         try {
             a();
         } catch(HighLevelException e) {
             e.printStackTrace();
         }
     }
     static void a() throws HighLevelException {
         try {
             b();
         } catch(MidLevelException e) {
             throw new HighLevelException(e);
         }
     }
     static void b() throws MidLevelException {
         c();
     }
     static void c() throws MidLevelException {
         try {
             d();
         } catch(LowLevelException e) {
             throw new MidLevelException(e);
         }
     }
     static void d() throws LowLevelException {
        e();
     }
     static void e() throws LowLevelException {
         throw new LowLevelException();
     }
 }

 class HighLevelException extends Exception {
     HighLevelException(Throwable cause) { super(cause); }
 }

 class MidLevelException extends Exception {
     MidLevelException(Throwable cause)  { super(cause); }
 }

 class LowLevelException extends Exception {
 }
 

As of release 7, the platform supports the notion of suppressed exceptions (in conjunction with the try-with-resources statement). Any exceptions that were suppressed in order to deliver an exception are printed out beneath the stack trace. The format of this information depends on the implementation, but the following example may be regarded as typical:

 Exception in thread "main" java.lang.Exception: Something happened
  at Foo.bar(Foo.java:10)
  at Foo.main(Foo.java:5)
  Suppressed: Resource$CloseFailException: Resource ID = 0
          at Resource.close(Resource.java:26)
          at Foo.bar(Foo.java:9)
          ... 1 more
 

Note that the "... n more" notation is used on suppressed exceptions just at it is used on causes. Unlike causes, suppressed exceptions are indented beyond their "containing exceptions."

An exception can have both a cause and one or more suppressed exceptions:

 Exception in thread "main" java.lang.Exception: Main block
  at Foo3.main(Foo3.java:7)
  Suppressed: Resource$CloseFailException: Resource ID = 2
          at Resource.close(Resource.java:26)
          at Foo3.main(Foo3.java:5)
  Suppressed: Resource$CloseFailException: Resource ID = 1
          at Resource.close(Resource.java:26)
          at Foo3.main(Foo3.java:5)
 Caused by: java.lang.Exception: I did it
  at Foo3.main(Foo3.java:8)
 

Likewise, a suppressed exception can have a cause:

 Exception in thread "main" java.lang.Exception: Main block
  at Foo4.main(Foo4.java:6)
  Suppressed: Resource2$CloseFailException: Resource ID = 1
          at Resource2.close(Resource2.java:20)
          at Foo4.main(Foo4.java:5)
  Caused by: java.lang.Exception: Rats, you caught me
          at Resource2$CloseFailException.<init>(Resource2.java:45)
          ... 2 more
 

Overrides:

printStackTrace in class Throwable

printStackTrace

public void printStackTrace(PrintStream stream)

Description copied from class: Throwable

Prints this throwable and its backtrace to the specified print stream.

Overrides:

printStackTrace in class Throwable

Parameters:

stream - PrintStream to use for output

printStackTrace

public void printStackTrace(PrintWriter writer)

Description copied from class: Throwable

Prints this throwable and its backtrace to the specified print writer.

Overrides:

printStackTrace in class Throwable

Parameters:

writer - PrintWriter to use for output