com.plumtree.openfoundation.util
Class XPException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          java.lang.RuntimeException
              com.plumtree.openfoundation.util.XPException

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

XPArithmeticException, XPArrayTypeMismatchException, XPClassCastException, XPClassNotFoundException, XPCryptoException, XPFormatException, XPIllegalAccessException, XPIllegalArgumentException, XPIllegalStateException, XPIndexOutOfBoundsException, XPInvocationTargetException, XPIOException, XPMalformedURLException, XPNoSuchMethodException, XPNotImplementedException, XPNullPointerException, XPParseException, XPSecurityException, XPThreadInterruptedException, XPUnsupportedEncodingException, XPUnsupportedOperationException

public class XPException
extends java.lang.RuntimeException

XPException indicates error conditions that an application might want to catch. Since .Net does not support checked exceptions and we are looking for matching interface behavior, the Java implementation of XPException extends RuntimeException. Preferred usage of XPException is: try { ... } catch (Exception e) { xpe = XPException.GetInstance(e); ... } The GetInstance(e) method wraps the platform-specific exception subtype in a corresponding subtype of XPException.

See Also:

Serialized Form

Constructor Summary

XPException()
Constructs an XPException without any user defined message or native Exception to wrap.

XPException(java.lang.String message)
Constructs an XPException with a user defined error message.

XPException(java.lang.String message, java.lang.Throwable innerException)
This constructor creates an XPException that wraps the native exception with custom message CAUTION: The XPException.GetInstance() method is preferred in most cases, because it maps native exceptions to more specific subtypes of XPException which can be tested for in a cross-platform way.

XPException(java.lang.Throwable innerException)
Constructs an XPException that wraps a native exception.

Method Summary

static java.lang.String	exceptionToString(java.lang.Throwable exception) Deprecated. Use XPException.ExceptionToString() by preference in translatable code to match the preferred DotNet uppercase method style.
static java.lang.String	ExceptionToString(java.lang.Throwable exception) Returns string representation of an exception, with type, message, and stack trace.
java.lang.Throwable	GetInnerException() Return a reference to the inner native exception instance wrapped by this exception.
static XPException	GetInstance(java.lang.String strErrorMsg, java.lang.Throwable e) Wraps a native exception instance as a corresponding subtype of XPException, supplying a context message, and is generally preferred to the XPException constructor for this purpose; XPException instances are augmented with a new "rethrow" stack trace and the new message, but the same instance is returned.
static XPException	GetInstance(java.lang.Throwable e) Creates an instance of a more specific subtype of XPException corresponding to the platform type passed as an argument and wrapping the argument as an inner exception, or returns an XPException unchanged.
java.lang.String	getMessage() Deprecated. Use GetMessage() instead.
java.lang.String	GetMessage() Produces a detailed message string describing the XPException.
java.lang.String	GetStackTrace() Gets a string representation of this exception's stack trace, including rethrow stack traces from XPException.GetInstance() and stack trace from an inner exception if present.
void	printStackTrace() This method prints the stack trace of this exception on the standard error output stream.
void	PrintStackTrace() This method prints the stack trace of this exception on the standard error output stream.
void	printStackTrace(java.io.PrintWriter pw) Deprecated. PrintStackTrace() is preferred for translatable code.
java.lang.String	ToString() Exception message formated as String or the String with which Exception is created.

Methods inherited from class java.lang.Throwable

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

Methods inherited from class java.lang.Object

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

Constructor Detail

XPException

public XPException()

Constructs an XPException without any user defined message or native Exception to wrap.

XPException

public XPException(java.lang.String message)

Constructs an XPException with a user defined error message.

Parameters:

message - User defined error message

XPException

public XPException(java.lang.Throwable innerException)

Constructs an XPException that wraps a native exception. CAUTION: The XPException.GetInstance() method is preferred in most cases, because it maps native exceptions to more specific subtypes of XPException which can be tested for in a cross-platform way.

Parameters:

innerException - The native exception to be wrapped.

XPException

public XPException(java.lang.String message,
                   java.lang.Throwable innerException)

This constructor creates an XPException that wraps the native exception with custom message CAUTION: The XPException.GetInstance() method is preferred in most cases, because it maps native exceptions to more specific subtypes of XPException which can be tested for in a cross-platform way.

Parameters:

message - Custom message

innerException - The native exception to be wrapped

Method Detail

GetMessage

public java.lang.String GetMessage()

Produces a detailed message string describing the XPException. It is never null.

Returns:

The custom error message of this XPException or the (custom or default) error message of the wrapped native Exception or the default error message of this XPException

getMessage

public java.lang.String getMessage()

Deprecated. Use GetMessage() instead.

Overrides the Java Throwable.getMessage() method, returning a detailed message string. It is never null. GetMessage() is preferred for translatable code.

Overrides:

getMessage in class java.lang.Throwable

Returns:

same as GetMessage(). Use GetMessage() instead.

GetInnerException

public java.lang.Throwable GetInnerException()

Return a reference to the inner native exception instance wrapped by this exception.

Returns:

The inner exception or null if there is not one.

PrintStackTrace

public void PrintStackTrace()

This method prints the stack trace of this exception on the standard error output stream.

See Also:

for comments on the format used.

printStackTrace

public void printStackTrace()

This method prints the stack trace of this exception on the standard error output stream.

Overrides:

printStackTrace in class java.lang.Throwable

See Also:

for comments on the format used.

GetStackTrace

public java.lang.String GetStackTrace()

Gets a string representation of this exception's stack trace, including rethrow stack traces from XPException.GetInstance() and stack trace from an inner exception if present. Additional rethrow and inner stack traces are marked off with a line starting with "Caused by". Redundant stack frames in "inner exception" traces which repeat the outer exception trace are edited out in the style of JDK 1.4, for example "... 18 more" would replace 18 matching frames in the enclosing exception.

Returns:

string representation of the stack trace

printStackTrace

public void printStackTrace(java.io.PrintWriter pw)

Deprecated. PrintStackTrace() is preferred for translatable code.

Overrides Throwable.printStackTrace(PrintWriter), prints instance and its backtrace to the specified print writer. This method is implemented because it is called by the Eclipse test runner.

Overrides:

printStackTrace in class java.lang.Throwable

Parameters:

pw - PrintWriter to use for output

Since:

JDK1.1

See Also:

for the format used.

GetInstance

public static XPException GetInstance(java.lang.Throwable e)

Creates an instance of a more specific subtype of XPException corresponding to the platform type passed as an argument and wrapping the argument as an inner exception, or returns an XPException unchanged.
Please note that it is not generally good practice to catch and wrap Throwable, but to use Exception as a general catch-all if needed.

Parameters:

e - The native exception to be wrapped, or an XPException to be returned unchanged.

Returns:

The specific type of XPException that this wraps

GetInstance

public static XPException GetInstance(java.lang.String strErrorMsg,
                                      java.lang.Throwable e)

Wraps a native exception instance as a corresponding subtype of XPException, supplying a context message, and is generally preferred to the XPException constructor for this purpose; XPException instances are augmented with a new "rethrow" stack trace and the new message, but the same instance is returned.
Please note that it is not generally good practice to catch and wrap Throwable, but to use Exception as a general catch-all if needed.

Parameters:

strErrorMsg - custom error message

e - The native exception to be wrapped, or an XPException which will have its message re-set and its stack trace augmented.

Returns:

The specific type of XPException that this wraps

ExceptionToString

public static java.lang.String ExceptionToString(java.lang.Throwable exception)

Returns string representation of an exception, with type, message, and stack trace.

Parameters:

exception - Exception to render

Returns:

Stack trace of exception as string

See Also:

for comments on the format used for XPException instances.

ToString

public java.lang.String ToString()

Exception message formated as String or the String with which Exception is created.

Returns:

The String value of Exception

exceptionToString

public static java.lang.String exceptionToString(java.lang.Throwable exception)

Deprecated. Use XPException.ExceptionToString() by preference in translatable code to match the preferred DotNet uppercase method style.

Returns string representation of an exception.

Parameters:

exception - A Throwable Object.

Returns:

Returns string representation of an exception.