com.vladium.util.exception
Class AbstractRuntimeException

java.lang.Object
  extended byjava.lang.Throwable
      extended byjava.lang.Exception
          extended byjava.lang.RuntimeException
              extended bycom.vladium.util.exception.AbstractRuntimeException
All Implemented Interfaces:
ICodedException, IThrowableWrapper, java.io.Serializable
Direct Known Subclasses:
EMMARuntimeException

public abstract class AbstractRuntimeException
extends java.lang.RuntimeException
implements ICodedException, IThrowableWrapper

Based on code published by me in JavaPro, 2002.

This unchecked exception class is designed as a base/expansion point for the entire hierarchy of unchecked exceptions in a project.

It provides the following features:

See AbstractException for a checked version of the same class.

TODO: javadoc Each constructor that accepts a String 'message' parameter accepts an error code as well. You are then responsible for ensuring that either the root com.vladium.exception.exceptions resource bundle or your project/exception class-specific resource bundle [see below for details] contains a mapping for this error code. When this lookup fails the passed String value itself will be used as the error message.

All constructors taking an 'arguments' parameter supply parameters to the error message used as a java.text.MessageFormat pattern.

Example:


  File file = ...
  try
  ...
  catch (Exception e)
  {
      throw new AbstractRuntimeException ("FILE_NOT_FOUND", new Object[] {file, e}, e);
  }
 
where com.vladium.util.exception.exceptions contains:

 FILE_NOT_FOUND: file {0} could not be opened: {1}
 
To log exception data use getMessage() or printStackTrace family of methods. You should never have to use toString().

It is also possible to use project- or exception subhierarchy-specific message resource bundles without maintaining all error codes in com.vladium.exception.exceptions. To do so, create a custom resource bundle and add the following static initializer code to your base exception class:


  static
  {
      addExceptionResource (MyException.class, "my_custom_resource_bundle");
  }
 
The bundle name is relative to MyException package. This step can omitted if the bundle name is "exceptions". Note that the implementation correctly resolves error code name collisions across independently developed exception families, as long as resource bundles use unique names. Specifically, error codes follow inheritance and hiding rules similar to Java class static methods. See ExceptionCommon.addExceptionResource(java.lang.Class, java.lang.String) for further details.

Author:
Vlad Roubtsov, (C) 2002
See Also:
Serialized Form

Field Summary
private  java.lang.Object[] m_arguments
           
private  java.lang.Throwable m_cause
           
private  java.lang.String m_message
           
 
Fields inherited from class java.lang.RuntimeException
 
Fields inherited from class java.lang.Throwable
 
Constructor Summary
AbstractRuntimeException()
          Constructs an exception with null message and null cause.
AbstractRuntimeException(java.lang.String message)
          Constructs an exception with given error message/code and null cause.
AbstractRuntimeException(java.lang.String message, java.lang.Object[] arguments)
          Constructs an exception with given error message/code and null cause.
AbstractRuntimeException(java.lang.String message, java.lang.Object[] arguments, java.lang.Throwable cause)
          Constructs an exception with given error message/code and given cause.
AbstractRuntimeException(java.lang.String message, java.lang.Throwable cause)
          Constructs an exception with given error message/code and given cause.
AbstractRuntimeException(java.lang.Throwable cause)
          Constructs an exception with null error message/code and given cause.
 
Method Summary
 void __printStackTrace(java.io.PrintStream ps)
          Every exception hierarchy implementing this interface must ensure that this method delegates to super.printStackTrace(ps) where 'super' is the first superclass not implementing IThrowableWrapper.
 void __printStackTrace(java.io.PrintWriter pw)
          Every exception hierarchy implementing this interface must ensure that this method delegates to super.printStackTrace(pw) where 'super' is the first superclass not implementing IThrowableWrapper.
static void addExceptionResource(java.lang.Class namespace, java.lang.String messageResourceBundleName)
          Equivalent to ExceptionCommon.addExceptionResource(java.lang.Class, java.lang.String), repeated here for convenience.
 java.lang.Throwable getCause()
          This implements IThrowableWrapper and also overrides the base method in JDK 1.4+.
 java.lang.String getErrorCode()
          Returns the String that was passed as 'message' constructor argument.
 java.lang.String getLocalizedMessage()
          Overrides base method for the sole purpose of making it final.
 java.lang.String getMessage()
          Overrides base method to support error code lookup and avoid returning nulls.
 void printStackTrace()
          Overrides Exception.printStackTrace() to (a) force the output to go to System.out and (b) handle nested exceptions in JDKs prior to 1.4.
 void printStackTrace(java.io.PrintStream s)
          Overrides Exception.printStackTrace() to handle nested exceptions in JDKs prior to 1.4.
 void printStackTrace(java.io.PrintWriter s)
          Overrides Exception.printStackTrace() to handle nested exceptions in JDKs prior to 1.4.
private  void writeObject(java.io.ObjectOutputStream out)
           
 
Methods inherited from class java.lang.Throwable
fillInStackTrace, getStackTrace, initCause, setStackTrace, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

m_message

private java.lang.String m_message

m_arguments

private final transient java.lang.Object[] m_arguments

m_cause

private final java.lang.Throwable m_cause
Constructor Detail

AbstractRuntimeException

public AbstractRuntimeException()
Constructs an exception with null message and null cause.


AbstractRuntimeException

public AbstractRuntimeException(java.lang.String message)
Constructs an exception with given error message/code and null cause.

Parameters:
message - the detail message [can be null]

AbstractRuntimeException

public AbstractRuntimeException(java.lang.String message,
                                java.lang.Object[] arguments)
Constructs an exception with given error message/code and null cause.

Parameters:
message - the detail message [can be null]
arguments - message format parameters [can be null or empty]
See Also:
MessageFormat

AbstractRuntimeException

public AbstractRuntimeException(java.lang.Throwable cause)
Constructs an exception with null error message/code and given cause.

Parameters:
cause - the cause [nested exception] [can be null]

AbstractRuntimeException

public AbstractRuntimeException(java.lang.String message,
                                java.lang.Throwable cause)
Constructs an exception with given error message/code and given cause.

Parameters:
message - the detail message [can be null]
cause - the cause [nested exception] [can be null]

AbstractRuntimeException

public AbstractRuntimeException(java.lang.String message,
                                java.lang.Object[] arguments,
                                java.lang.Throwable cause)
Constructs an exception with given error message/code and given cause.

Parameters:
message - the detail message [can be null]
arguments - message format parameters [can be null or empty]
cause - the cause [nested exception] [can be null]
See Also:
MessageFormat
Method Detail

getMessage

public final java.lang.String getMessage()
Overrides base method to support error code lookup and avoid returning nulls. Note that this does not recurse into any 'cause' for message lookup, it only uses the data passed into the constructor. Subclasses cannot override.

Equivalent to getLocalizedMessage().

Returns:
String error message provided at construction time or the result of toString() if no/null message was provided [never null].

getLocalizedMessage

public final java.lang.String getLocalizedMessage()
Overrides base method for the sole purpose of making it final.

Equivalent to getMessage().


printStackTrace

public final void printStackTrace()
Overrides Exception.printStackTrace() to (a) force the output to go to System.out and (b) handle nested exceptions in JDKs prior to 1.4.

Subclasses cannot override.


printStackTrace

public final void printStackTrace(java.io.PrintStream s)
Overrides Exception.printStackTrace() to handle nested exceptions in JDKs prior to 1.4.

Subclasses cannot override.


printStackTrace

public final void printStackTrace(java.io.PrintWriter s)
Overrides Exception.printStackTrace() to handle nested exceptions in JDKs prior to 1.4.

Subclasses cannot override.


getErrorCode

public final java.lang.String getErrorCode()
Returns the String that was passed as 'message' constructor argument. Can be null.

Specified by:
getErrorCode in interface ICodedException
Returns:
message code string [can be null]

getCause

public final java.lang.Throwable getCause()
This implements IThrowableWrapper and also overrides the base method in JDK 1.4+.

Specified by:
getCause in interface IThrowableWrapper

__printStackTrace

public void __printStackTrace(java.io.PrintStream ps)
Description copied from interface: IThrowableWrapper
Every exception hierarchy implementing this interface must ensure that this method delegates to super.printStackTrace(ps) where 'super' is the first superclass not implementing IThrowableWrapper. This is used by ExceptionCommon to avoid infinite recursion and is not meant to be called by other classes.

Specified by:
__printStackTrace in interface IThrowableWrapper

__printStackTrace

public void __printStackTrace(java.io.PrintWriter pw)
Description copied from interface: IThrowableWrapper
Every exception hierarchy implementing this interface must ensure that this method delegates to super.printStackTrace(pw) where 'super' is the first superclass not implementing IThrowableWrapper. This is used by ExceptionCommon to avoid infinite recursion and is not meant to be called by other classes.

Specified by:
__printStackTrace in interface IThrowableWrapper

addExceptionResource

public static void addExceptionResource(java.lang.Class namespace,
                                        java.lang.String messageResourceBundleName)
Equivalent to ExceptionCommon.addExceptionResource(java.lang.Class, java.lang.String), repeated here for convenience. Subclasses should invoke from static initializers only. 'namespace' should be YourException.class.


writeObject

private void writeObject(java.io.ObjectOutputStream out)
                  throws java.io.IOException
Throws:
java.io.IOException