net.sourceforge.groboutils.util.throwable.v1
Class ChainableExceptionHelper

java.lang.Object
  net.sourceforge.groboutils.util.throwable.v1.ChainableExceptionHelper

All Implemented Interfaces:

java.io.Serializable

public class ChainableExceptionHelper

extends java.lang.Object

implements java.io.Serializable

Helper class to support easy-to-implement chainable exceptions. In most situations, it is close to impossible to create a generic chainable exception due to inheritance restrictions on the Java exception hierarchy (this shows a Java weakness - exception categories should be interfaces, not specific classes).

This will attempt to use the owning source's initCause() and getCause() methods, provided the owning source provides those methods. Only the superclass's implementation that provides these methods yet does not implement IChainableException will be used (to prevent a possible recursion nightmare).

In order to prevent endless recursion, this class will not look at the JDK 1.4 implementation of the source exception. This used to work with JDK 1.4.0, but JDK 1.4.2 seems to have broken the original implementation.

Since:

July 7, 2002

Version:

$Date: 2003/05/06 05:35:01 $

Author:

Matt Albrecht groboclown@users.sourceforge.net

See Also:

Serialized Form

Constructor Summary

ChainableExceptionHelper(java.lang.Throwable source)
Sets the owning throwable.

ChainableExceptionHelper(java.lang.Throwable source, java.lang.Throwable cause)

Method Summary

java.lang.Throwable	getCause() JDK 1.4 compatible method.
protected java.lang.String	getUnderlyingExceptionSeparator()
protected java.lang.String	getUnknownExceptionString()
java.lang.Throwable	initCause(java.lang.Throwable cause) JDK 1.4 compatible method.
void	printStackTrace(java.io.PrintStream ps) For non-JDK 1.4 compatible VMs, this overrides the original behavior to describe the underlying cause.
void	printStackTrace(java.io.PrintWriter pw) For non-JDK 1.4 compatible VMs, this overrides the original behavior to describe the underlying cause.
protected boolean	shouldDisplayCause()

Methods inherited from class java.lang.Object

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

Constructor Detail

ChainableExceptionHelper

public ChainableExceptionHelper(java.lang.Throwable source)

Sets the owning throwable. The initCause() method can still be called after this constructor is used.

ChainableExceptionHelper

public ChainableExceptionHelper(java.lang.Throwable source,
                                java.lang.Throwable cause)

Method Detail

getCause

public java.lang.Throwable getCause()

JDK 1.4 compatible method.

from the JDK 1.4 documentation:

Returns the cause of this throwable or null if the cause is nonexistent or unknown. (The cause is the throwable that caused this throwable to get thrown.)

This implementation returns the cause that was supplied via one of the constructors requiring a Throwable, or that was set after creation with the initCause( Throwable ) method. While it is typically unnecessary to override this method, a subclass can override it to return a cause set by some other means. This is appropriate for a "legacy chained throwable" that predates the addition of chained exceptions to Throwable. Note that it is not necessary to override any of the PrintStackTrace methods, all of which invoke the getCause method to determine the cause of a throwable.

Returns:

the cause of this throwable or null if the cause is nonexistent or unknown.

initCause

public java.lang.Throwable initCause(java.lang.Throwable cause)

JDK 1.4 compatible method.

from the JDK 1.4 documentation:

Initializes the cause of this throwable to the specified value. (The cause is the throwable that caused this throwable to get thrown.)

This method can be called at most once. It is generally called from within the constructor, or immediately after creating the throwable. If this throwable was created with Throwable(Throwable) or Throwable(String,Throwable), this method cannot be called even once.

Parameters:

cause - the cause (which is saved for later retrieval by the getCause() method). (A null value is permitted, and indicates that the cause is nonexistent or unknown.)

Returns:

a reference to this Throwable instance.

Throws:

java.lang.IllegalArgumentException - if cause is this throwable. (A throwable cannot be its own cause.)

java.lang.IllegalStateException - if this throwable was created with Throwable(Throwable) or Throwable(String,Throwable), or this method has already been called on this throwable.

printStackTrace

public void printStackTrace(java.io.PrintStream ps)

For non-JDK 1.4 compatible VMs, this overrides the original behavior to describe the underlying cause. Special logic is performed to ensure that no JDK 1.4 VM is being used when the inner exception is displayed (in order to prevent double printing).

printStackTrace

public void printStackTrace(java.io.PrintWriter pw)

For non-JDK 1.4 compatible VMs, this overrides the original behavior to describe the underlying cause. Special logic is performed to ensure that no JDK 1.4 VM is being used when the inner exception is displayed (in order to prevent double printing).

getUnderlyingExceptionSeparator

protected java.lang.String getUnderlyingExceptionSeparator()

getUnknownExceptionString

protected java.lang.String getUnknownExceptionString()

shouldDisplayCause

protected boolean shouldDisplayCause()