org.clapper.util.misc
Class NestedException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          org.clapper.util.misc.NestedException

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

ClassUtilException, CommandLineException, ConfigurationException, EmailException, IOExceptionExt, ObjectExistsException, RegexException, SemaphoreException, UnifiedScriptException, VariableSubstitutionException, VersionMismatchException

public class NestedException
extends java.lang.Exception

NestedException defines a special Exception class that permits exceptions to wrap other exceptions. Much of the functionality of this class has been subsumed by the "chained exception" handling introduced in JDK 1.4. However, this class is retained for two reasons:

• backward compatibility
• it has constructors that support internationalization and localization of exception messages

While NestedException can be used directly, it is most useful as a base class for other exceptions classes.

Version:

$Revision: 6778 $

Author:

Copyright © 2004-2007 Brian M. Clapper

See Also:

Serialized Form

Constructor Summary

NestedException()
Default constructor, for an exception with no nested exception and no message.

NestedException(java.lang.String message)
Constructs an exception containing an error message, but no nested exception.

NestedException(java.lang.String bundleName, java.lang.String messageKey, java.lang.String defaultMsg)
Constructs an exception containing a resource bundle name, a message key, and a default message (in case the resource bundle can't be found).

NestedException(java.lang.String bundleName, java.lang.String messageKey, java.lang.String defaultMsg, java.lang.Object[] msgParams)
Constructs an exception containing a resource bundle name, a message key, a default message format (in case the resource bundle can't be found), and arguments to be incorporated in the message via java.text.MessageFormat.

NestedException(java.lang.String bundleName, java.lang.String messageKey, java.lang.String defaultMsg, java.lang.Object[] msgParams, java.lang.Throwable exception)
Constructs an exception containing a resource bundle name, a message key, a default message format (in case the resource bundle can't be found), arguments to be incorporated in the message via java.text.MessageFormat, and another exception.

NestedException(java.lang.String bundleName, java.lang.String messageKey, java.lang.String defaultMsg, java.lang.Throwable exception)
Constructs an exception containing a resource bundle name, a message key, a default message (in case the resource bundle can't be found), and another exception.

NestedException(java.lang.String message, java.lang.Throwable exception)
Constructs an exception containing another exception and a message.

NestedException(java.lang.Throwable exception)
Constructs an exception containing another exception, but no message of its own.

Method Summary

java.lang.String	getMessage() Returns the error message string for this exception.
java.lang.String	getMessage(java.util.Locale locale) Returns the error message string for this exception.
java.lang.String	getMessages() Get all the messages of all the nested exceptions, as one string, with each message on a separate line.
java.lang.String	getMessages(boolean elideNewlines) Get all the messages of all the nested exceptions, as one string.
java.lang.String	getMessages(boolean elideNewlines, java.util.Locale locale) Get all the messages of all the nested exceptions, as one string.
java.lang.Throwable	getNestedException() Deprecated. Use java.lang.Throwable.getCause() instead
void	printStackTrace() Print a stack trace to standard error.
void	printStackTrace(java.util.Locale locale) Print a stack trace to standard error, using the specified locale.
void	printStackTrace(java.io.PrintStream out) Print a stack trace.
void	printStackTrace(java.io.PrintStream out, java.util.Locale locale) Print a stack trace, using a specific locale for the output.
void	printStackTrace(java.io.PrintWriter out) Print a stack trace.
void	printStackTrace(java.io.PrintWriter out, java.util.Locale locale) Print a stack trace, using a specific locale for the output.
java.lang.String	toString() Returns a short description of this exception.

Methods inherited from class java.lang.Throwable

fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, initCause, setStackTrace

Methods inherited from class java.lang.Object

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

Constructor Detail

NestedException

public NestedException()

Default constructor, for an exception with no nested exception and no message.

NestedException

public NestedException(java.lang.Throwable exception)

Constructs an exception containing another exception, but no message of its own.

Parameters:

exception - the exception to contain

NestedException

public NestedException(java.lang.String message)

Constructs an exception containing an error message, but no nested exception.

Parameters:

message - the message to associate with this exception

NestedException

public NestedException(java.lang.String message,
                       java.lang.Throwable exception)

Constructs an exception containing another exception and a message.

Parameters:

message - the message to associate with this exception

exception - the exception to contain

NestedException

public NestedException(java.lang.String bundleName,
                       java.lang.String messageKey,
                       java.lang.String defaultMsg)

Constructs an exception containing a resource bundle name, a message key, and a default message (in case the resource bundle can't be found). Using this constructor is equivalent to calling the NestedException(String,String,String,Object[]) constructor, with a null pointer for the Object[] parameter. Calls to getMessage(Locale) will attempt to retrieve the top-most message (i.e., the message from this exception, not from nested exceptions) by querying the named resource bundle. Calls to printStackTrace(PrintWriter,Locale) will do the same, where applicable. The message is not retrieved until one of those methods is called, because the desired locale is passed into getMessage() and printStackTrace(), not this constructor.

Parameters:

bundleName - resource bundle name

messageKey - the key to the message to find in the bundle

defaultMsg - the default message

See Also:

NestedException(String,String,String,Object[]), getMessage(Locale)

NestedException

public NestedException(java.lang.String bundleName,
                       java.lang.String messageKey,
                       java.lang.String defaultMsg,
                       java.lang.Object[] msgParams)

Constructs an exception containing a resource bundle name, a message key, a default message format (in case the resource bundle can't be found), and arguments to be incorporated in the message via java.text.MessageFormat. Using this constructor is equivalent to calling the NestedException(String,String,String,Object[],Throwable) with a null Throwable parameter. Calls to getMessage(Locale) will attempt to retrieve the top-most message (i.e., the message from this exception, not from nested exceptions) by querying the named resource bundle. Calls to printStackTrace(PrintWriter,Locale) will do the same, where applicable. The message is not retrieved until one of those methods is called, because the desired locale is passed into getMessage() and printStackTrace(), not this constructor.

Parameters:

bundleName - resource bundle name

messageKey - the key to the message to find in the bundle

defaultMsg - the default message

msgParams - parameters to the message, if any, or null

See Also:

NestedException(String,String,String,Object[]), getMessage(Locale)

NestedException

public NestedException(java.lang.String bundleName,
                       java.lang.String messageKey,
                       java.lang.String defaultMsg,
                       java.lang.Throwable exception)

Constructs an exception containing a resource bundle name, a message key, a default message (in case the resource bundle can't be found), and another exception. Using this constructor is equivalent to calling the NestedException(String,String,String,Object[],Throwable) constructor, with a null pointer for the Object[] parameter. Calls to getMessage(Locale) will attempt to retrieve the top-most message (i.e., the message from this exception, not from nested exceptions) by querying the named resource bundle. Calls to printStackTrace(PrintWriter,Locale) will do the same, where applicable. The message is not retrieved until one of those methods is called, because the desired locale is passed into getMessage() and printStackTrace(), not this constructor.

Parameters:

bundleName - resource bundle name

messageKey - the key to the message to find in the bundle

defaultMsg - the default message

exception - the exception to nest

See Also:

NestedException(String,String,String,Object[]), getMessage(Locale)

NestedException

public NestedException(java.lang.String bundleName,
                       java.lang.String messageKey,
                       java.lang.String defaultMsg,
                       java.lang.Object[] msgParams,
                       java.lang.Throwable exception)

Constructs an exception containing a resource bundle name, a message key, a default message format (in case the resource bundle can't be found), arguments to be incorporated in the message via java.text.MessageFormat, and another exception. Calls to getMessage(Locale) will attempt to retrieve the top-most message (i.e., the message from this exception, not from nested exceptions) by querying the named resource bundle. Calls to printStackTrace(PrintWriter,Locale) will do the same, where applicable. The message is not retrieved until one of those methods is called, because the desired locale is passed into getMessage() and printStackTrace(), not this constructor.

Parameters:

bundleName - resource bundle name

messageKey - the key to the message to find in the bundle

defaultMsg - the default message

msgParams - parameters to the message, if any, or null

exception - exception to be nested

See Also:

NestedException(String,String,String,Object[]), getMessage(Locale)

Method Detail

getMessage

public java.lang.String getMessage()

Returns the error message string for this exception. If the exception was instantiated with a message of its own, then that message is returned. Otherwise, this method returns the class name, along with the class name of the first nested exception, if any. Unlike the parent Exception class, this method will never return null.

Overrides:

getMessage in class java.lang.Throwable

Returns:

the error message string for this exception

getMessage

public java.lang.String getMessage(java.util.Locale locale)

Returns the error message string for this exception. If the exception was instantiated with a message of its own, then that message is returned. Otherwise, this method returns the class name, along with the class name of the first nested exception, if any. Unlike the parent Exception class, this method will never return null. If a localized version of the message is available, it will be returned.

Parameters:

locale - the locale to use, or null for the default

Returns:

the error message string for this exception

getMessages

public java.lang.String getMessages()

Get all the messages of all the nested exceptions, as one string, with each message on a separate line. To run all the messages together into one line, use getMessages(boolean), with a parameter of true.

Returns:

the aggregated messages

See Also:

getMessages(boolean)

getMessages

public java.lang.String getMessages(boolean elideNewlines)

Get all the messages of all the nested exceptions, as one string. If the elideNewlines parameter is true, then the messages are joined so that there are no newlines in the resulting string. Otherwise, (a) any existing newlines in the messages are preserved, and (b) each nested message occupies its own line.

Parameters:

elideNewlines - whether to elide newlines or not

Returns:

the aggregated messages

getMessages

public java.lang.String getMessages(boolean elideNewlines,
                                    java.util.Locale locale)

Get all the messages of all the nested exceptions, as one string. If the elideNewlines parameter is true, then the messages are joined so that there are no newlines in the resulting string. Otherwise, (a) any existing newlines in the messages are preserved, and (b) each nested message occupies its own line.

Parameters:

elideNewlines - whether to elide newlines or not

locale - the locale to use, or null for the default

Returns:

the aggregated messages

getNestedException

public java.lang.Throwable getNestedException()

Deprecated. Use java.lang.Throwable.getCause() instead

Gets the exception that's nested within this NestedException, if any.

Returns:

the nested exception, or null

toString

public java.lang.String toString()

Returns a short description of this exception. If this object was created with an error message string, then the result is the concatenation of three strings:

• The name of the actual class of this object
• ": " (a colon and a space)
• The result of the getMessage() method for this object

If this object was created with no error message string, then the name of the actual class of this object is returned.

Overrides:

toString in class java.lang.Throwable

Returns:

a string representation of this object

printStackTrace

public void printStackTrace()

Print a stack trace to standard error.

Overrides:

printStackTrace in class java.lang.Throwable

See Also:

printStackTrace(Locale), printStackTrace(PrintWriter), printStackTrace(PrintStream)

printStackTrace

public void printStackTrace(java.util.Locale locale)

Print a stack trace to standard error, using the specified locale.

Parameters:

locale - the locale to use, or null for the default

See Also:

printStackTrace(Locale), printStackTrace(PrintWriter), printStackTrace(PrintStream)

printStackTrace

public void printStackTrace(java.io.PrintWriter out)

Print a stack trace.

Overrides:

printStackTrace in class java.lang.Throwable

Parameters:

out - where to dump the stack trace

See Also:

printStackTrace(), printStackTrace(PrintWriter,Locale), printStackTrace(PrintStream)

printStackTrace

public void printStackTrace(java.io.PrintWriter out,
                            java.util.Locale locale)

Print a stack trace, using a specific locale for the output.

Parameters:

out - where to dump the stack trace

locale - the locale to use, or null for the default

See Also:

printStackTrace(), printStackTrace(PrintWriter), printStackTrace(PrintStream,Locale)

printStackTrace

public void printStackTrace(java.io.PrintStream out)

Print a stack trace.

Overrides:

printStackTrace in class java.lang.Throwable

Parameters:

out - where to dump the stack trace

See Also:

printStackTrace(), printStackTrace(PrintStream,Locale), printStackTrace(PrintWriter)

printStackTrace

public void printStackTrace(java.io.PrintStream out,
                            java.util.Locale locale)

Print a stack trace, using a specific locale for the output.

Parameters:

out - where to dump the stack trace

locale - the locale to use, or null for the default

See Also:

printStackTrace(), printStackTrace(PrintStream), printStackTrace(PrintWriter,Locale)