java.lang.isolate
Class IsolateStartupException

java.lang.Object
  |
  +--java.lang.Throwable
        |
        +--java.lang.Exception
              |
              +--java.lang.isolate.IsolateStartupException

All Implemented Interfaces:

Serializable

public class IsolateStartupException

extends Exception

An exception thrown when the implementation is unable to start execution of a new isolate due to an error or exceptional condition in the setup or bootstrap code for the new isolate (i.e., before the application starts). Generally, this exception implies the new isolate was misconfigured, and the misconfiguration was detected when the isolate was initializing.

Any errors or exceptions thrown by application code in the new isolate will be handled by the default ThreadGroup.uncaughtException and will not manifest as an IsolateStartupException in the creating isolate.

The underlying exception can be either "local" (it occurred in the isolate that invoked the isolate constructor or the Isolate.start method). Or, the exception is "remote" (it occurred in the new isolate very early in its bootstrap stage). A "local" exception is chained in the normal manner, while a "remote" exception is accessible through the remote exception accessors (getRemoteName, getRemoteMessage and getRemoteStackTrace). If the exception is "local", the remote accessors will return null; if the exception is "remote" the cause will be null.

Because a "remote" exception occurred in a different isolate the exception cannot be directly chained (generally, the exception type may not be available in the creator).

The detail message in an IsolateStartupException will be the toString string of the underlying exception, if available. The backtrace associated with an IsolateStartupException will always be from the current thread's stack.

Since:

1.5

See Also:

Isolate.Isolate(java.lang.String, java.lang.String[], java.util.prefs.TransientPreferences, java.lang.isolate.IsolateMessage, java.lang.isolate.IsolateMessage, java.lang.isolate.IsolateMessage), Isolate.start(java.lang.isolate.IsolateMessage[]), Serialized Form

Constructor Summary

IsolateStartupException()
Constructs an IsolateStartupException with no specified detail message or cause.

IsolateStartupException(String detail)
Constructs an IsolateStartupException with specified detail message (which may be null) and no cause.

IsolateStartupException(String detail, String remoteName, String remoteMessage, StackTraceElement[] trace)
Constructs an IsolateStartupException with specified detail message and specified information on the remote exception.

IsolateStartupException(String detail, Throwable cause)
Constructs an IsolateStartupException with specified detail message (which may be null) and local cause exception.

IsolateStartupException(Throwable cause)
Constructs an IsolateStartupException with no specified detail message and the given local cause exception.

Method Summary

Throwable	getCause() Returns the chained Throwable object that was the cause of this exception.
String	getRemoteMessage() Returns the detail message string for the remote exception (which may be null even if a remote exception occurred).
String	getRemoteName() Returns either the name of the exception type of the remote exception or null if there was no reportable remote Java exception.
StackTraceElement[]	getRemoteStackTrace() Returns an array of StackTraceElements representing the stack trace in the remote isolate.
void	printRemoteStackTrace() Prints the remote exception name, message, and stack trace, like Throwable.printStackTrace() does for the local exception.
void	printRemoteStackTrace(PrintStream ps) Prints the remote exception like printRemoteStackTrace() to the given PrintStream.
void	printRemoteStackTrace(PrintWriter pw) Prints the remote exception like printRemoteStackTrace() to the given PrintWriter.

Methods inherited from class java.lang.Throwable

fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

IsolateStartupException

public IsolateStartupException()

Constructs an IsolateStartupException with no specified detail message or cause.

IsolateStartupException

public IsolateStartupException(Throwable cause)

Constructs an IsolateStartupException with no specified detail message and the given local cause exception. A null cause is permitted and indicates that the cause is nonexistent or unknown.

Parameters:

cause - the local cause exception or null.

IsolateStartupException

public IsolateStartupException(String detail)

Constructs an IsolateStartupException with specified detail message (which may be null) and no cause.

Parameters:

detail - the detail message

IsolateStartupException

public IsolateStartupException(String detail,
                               Throwable cause)

Constructs an IsolateStartupException with specified detail message (which may be null) and local cause exception. A null cause is permitted and indicates that the cause is nonexistent or unknown.

Parameters:

detail - the detail message or null

cause - the local cause exception or null

IsolateStartupException

public IsolateStartupException(String detail,
                               String remoteName,
                               String remoteMessage,
                               StackTraceElement[] trace)

Constructs an IsolateStartupException with specified detail message and specified information on the remote exception. Any of the remote exception information may be null. If remoteName is null that implies there was no "remote" exception.

Parameters:

detail - the detail message or null

remoteName - name of the type of remote exception or null

remoteMessage - message from the remote exception or null

trace - trace of the remote exception or null

This API element may not be present in some J2ME profiles.

Method Detail

getRemoteName

public String getRemoteName()

Returns either the name of the exception type of the remote exception or null if there was no reportable remote Java exception.

Returns:

the name of the exception type of the remote exception

getRemoteMessage

public String getRemoteMessage()

Returns the detail message string for the remote exception (which may be null even if a remote exception occurred).

Returns:

the detail message string for the remote exception

See Also:

getRemoteName()

getRemoteStackTrace

public StackTraceElement[] getRemoteStackTrace()

Returns an array of StackTraceElements representing the stack trace in the remote isolate. The returned stack trace has the same structure and definition as one returned from Throwable.getStackTrace. Will return null if there was no reportable Java exception in the new isolate.

Returns:

an array of stack trace elements representing the stack trace pertaining to the remote exception

This API element may not be present in some J2ME profiles.

printRemoteStackTrace

public void printRemoteStackTrace()

Prints the remote exception name, message, and stack trace, like Throwable.printStackTrace() does for the local exception. If no exception information is available, nothing will be printed.

printRemoteStackTrace

public void printRemoteStackTrace(PrintStream ps)

Prints the remote exception like printRemoteStackTrace() to the given PrintStream. If no exception information is available nothing will be printed.

Parameters:

ps - PrintStream to use for output

Throws:

NullPointerException - if ps is null

printRemoteStackTrace

public void printRemoteStackTrace(PrintWriter pw)

Prints the remote exception like printRemoteStackTrace() to the given PrintWriter. If no exception information is available nothing will be printed.

Parameters:

pw - PrintWriter to use for output

Throws:

NullPointerException - if pw is null

This API element may not be present in some J2ME profiles.

This API element must be present with the following J2ME configurations, profiles, or optional packages:

CDCv1.0

getCause

public Throwable getCause()

Returns the chained Throwable object that was the cause of this exception.

Overrides:

getCause in class Throwable

Returns:

the cause exception or null if nonexistent