echopoint.util.throwable
Class ThrowableKit

java.lang.Object
  echopoint.util.throwable.ThrowableKit

public class ThrowableKit
extends Object

ThrowableKit provides helper methods for handling Exceptions in Echo web applications. It is expecially useful for allowing JDK 1.4 exception chaining while still retaining a JDK 1.3 compliant code base.

Method Summary

static Throwable	attachCause(Throwable throwable, Throwable cause) This method attempts to attach the cause Throwable to the provided Throwable.
static ThrowableDescriptor	describeThrowable(Throwable throwable) This method will examine a Throwable and return a ThrowableDescriptor that can then be used to output error details.
static Throwable	initCause(Throwable throwable, Throwable cause) Short hand method for ThrowableKit.attachCause(throwable, cause);
static RuntimeException	makeRuntimeException(String message, Throwable cause) This method creates a RuntimeException that will attach the root cause if you are running under JDK 1.4 or later.
static RuntimeException	makeRuntimeException(Throwable cause) A short cut method for ThrowableKit.makeRuntimeException(null,cause);
static Throwable	makeThrowable(Class throwableClass, String message, Throwable cause) This method creates a Throwable derived object that will attach the root cause if you are running under JDK 1.4 or later.
static Throwable	makeThrowable(Class throwableClass, Throwable cause) Short hand method for ThrowableKit.makeThrowable(throwableClass, null,cause);
static void	printThrowableDescription(Throwable throwable, PrintStream out) Shorthand method for ThrowableKit.printThrowableDescription(throwable,out,true);
static void	printThrowableDescription(Throwable throwable, PrintStream out, boolean indent) Prints a textual description of a Throwable and its properties, causes and stack traces.

Methods inherited from class java.lang.Object

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

Method Detail

makeThrowable

public static Throwable makeThrowable(Class throwableClass,
                                      String message,
                                      Throwable cause)

This method creates a Throwable derived object that will attach the root cause if you are running under JDK 1.4 or later.

This method makes it easier in dumps that find the root cause of a problem.

If the contructor(String,Throwable) is not available (JDK 1.3 or below) then the message + " : " + cause.toString() will be used and the root cause Throwable stack trace will not be avalable.

This method allows you to use the new 1.4 exception chaining if possible.

Parameters:

throwableClass - - must be a class derived from Throwable.class

message - - a custom error message, can be null.

cause - - the root cause Throwable

Returns:

a new RuntimeException

makeThrowable

public static Throwable makeThrowable(Class throwableClass,
                                      Throwable cause)

Short hand method for ThrowableKit.makeThrowable(throwableClass, null,cause);

Parameters:

throwableClass - - must be a class derived from Throwable.class

cause - - the root cause Throwable

Returns:

a new RuntimeException

See Also:

makeThrowable(Class, String, Throwable)

makeRuntimeException

public static RuntimeException makeRuntimeException(String message,
                                                    Throwable cause)

This method creates a RuntimeException that will attach the root cause if you are running under JDK 1.4 or later. This makes it easier in Exception dumps that find the root cause of a problem. If the RuntimeException(String,Throwable) contructor is not available (JDK 1.3 or below) then the message + " : " + cause.toString() will be used and the root cause Throwable stack trace will not be avalable.

This method allows you to use the new 1.4 exception chaining if possible.

Parameters:

message - - a custom error message, can be null.

cause - - the root cause Throwable

Returns:

a new RuntimeException

makeRuntimeException

public static RuntimeException makeRuntimeException(Throwable cause)

A short cut method for ThrowableKit.makeRuntimeException(null,cause);

Parameters:

cause - the root cause Throwablew to attach

Returns:

the target Throwable t

See Also:

makeRuntimeException(String, Throwable)

attachCause

public static Throwable attachCause(Throwable throwable,
                                    Throwable cause)

This method attempts to attach the cause Throwable to the provided Throwable. It emuluates the Throwable.initCause(Throwable) method found in JDK 1.4.

If this cant be done then nothing is attached, such as when you are running under JDK 1.3

This method can be called at most once on an Throwable. It is generally called from within the constructor, or immediately after creating the throwable. If this throwable was created with Throwable.Throwable(Throwable) or Throwable.Throwable(String,Throwable), this method has no effect since the cause has already been set.

Parameters:

throwable - the target Throwable

cause - the root cause Throwablew to attach

Returns:

the target Throwable t

initCause

public static Throwable initCause(Throwable throwable,
                                  Throwable cause)

Short hand method for ThrowableKit.attachCause(throwable, cause);

Parameters:

throwable - the target Throwable

cause - the root cause Throwablew to attach

Returns:

the target Throwable t

See Also:

attachCause(Throwable, Throwable), Throwable.initCause(java.lang.Throwable)

describeThrowable

public static ThrowableDescriptor describeThrowable(Throwable throwable)

This method will examine a Throwable and return a ThrowableDescriptor that can then be used to output error details.

This works equally well on JDK 1.3 as it does on JDK 1.4.

Any circular references in the Exception chaining will be removed.

Parameters:

throwable - - the Throwable to examine

Returns:

a ThrowableDescriptor that describes the Throwable

printThrowableDescription

public static void printThrowableDescription(Throwable throwable,
                                             PrintStream out,
                                             boolean indent)

Prints a textual description of a Throwable and its properties, causes and stack traces.

Parameters:

throwable - - the Throwable in question

out - - the PrintStream to write to

indent - - control whether tab indents will be used

printThrowableDescription

public static void printThrowableDescription(Throwable throwable,
                                             PrintStream out)

Shorthand method for ThrowableKit.printThrowableDescription(throwable,out,true);

See Also:

printThrowableDescription(Throwable, PrintStream, boolean)