FileDocCategorySizeDatePackage
AbstractRuntimeException.javaAPI DocAndroid 1.5 API11293Wed May 06 22:41:16 BST 2009com.vladium.util.exception

AbstractRuntimeException

public abstract class AbstractRuntimeException extends RuntimeException implements IThrowableWrapper, ICodedException
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:

  • ability to take in compact error codes that map to full text messages in a resource bundle loaded at this class' instantiation time. This avoids hardcoding the error messages in product code and allows for easy localization of such text if required. Additionally, these messages can be parametrized in the java.text.MessageFormat style;
  • exception chaining in J2SE versions prior to 1.4
See {@link 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 {@link #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 {@link ExceptionCommon#addExceptionResource} for further details.
author
Vlad Roubtsov, (C) 2002

Fields Summary
private String
m_message
private final transient Object[]
m_arguments
private final Throwable
m_cause
Constructors Summary
public AbstractRuntimeException()
Constructs an exception with null message and null cause.

        m_cause = null;
        m_arguments = null;
public AbstractRuntimeException(String message)
Constructs an exception with given error message/code and null cause.

param
message the detail message [can be null]

        super (message);
        m_cause = null;
        m_arguments = null;
public AbstractRuntimeException(String message, Object[] arguments)
Constructs an exception with given error message/code and null cause.

param
message the detail message [can be null]
param
arguments message format parameters [can be null or empty]
see
java.text.MessageFormat

        super (message);
        m_cause = null;
        m_arguments = arguments == null ? null : (Object []) arguments.clone ();
public AbstractRuntimeException(Throwable cause)
Constructs an exception with null error message/code and given cause.

param
cause the cause [nested exception] [can be null]

        super ();
        m_cause = cause;
        m_arguments = null;
public AbstractRuntimeException(String message, Throwable cause)
Constructs an exception with given error message/code and given cause.

param
message the detail message [can be null]
param
cause the cause [nested exception] [can be null]

        super (message);
        m_cause = cause;
        m_arguments = null;
public AbstractRuntimeException(String message, Object[] arguments, Throwable cause)
Constructs an exception with given error message/code and given cause.

param
message the detail message [can be null]
param
arguments message format parameters [can be null or empty]
param
cause the cause [nested exception] [can be null]
see
java.text.MessageFormat

        super (message);
        m_cause = cause;
        m_arguments = arguments == null ? null : (Object []) arguments.clone ();
Methods Summary
public void__printStackTrace(java.io.PrintStream ps)

        super.printStackTrace (ps);
public void__printStackTrace(java.io.PrintWriter pw)

        super.printStackTrace (pw);
public static voidaddExceptionResource(java.lang.Class namespace, java.lang.String messageResourceBundleName)
Equivalent to {@link ExceptionCommon#addExceptionResource}, repeated here for convenience. Subclasses should invoke from static initializers only. 'namespace' should be YourException.class.

        // note: 'namespace' will be the most derived class; it is possible to
        // auto-detect that in a static method but that requires some security
        // permissions
        ExceptionCommon.addExceptionResource (namespace, messageResourceBundleName);
public final java.lang.ThrowablegetCause()
This implements {@link IThrowableWrapper} and also overrides the base method in JDK 1.4+.

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

return
message code string [can be null]

        return super.getMessage ();
public final java.lang.StringgetLocalizedMessage()
Overrides base method for the sole purpose of making it final.

Equivalent to {@link #getMessage}.

        // this is the same as what's done in Throwable
        // [copied here to be independent of future JDK changes]
        return getMessage ();
public final java.lang.StringgetMessage()
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 {@link #getLocalizedMessage}.

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

        if (m_message == null) // not synchronized by design
        {
            String msg;
            final String supermsg = super.getMessage ();
            final Class _class = getClass ();
            
            if (m_arguments == null)
            {
                msg = ExceptionCommon.getMessage (_class, supermsg);
            }
            else
            {
                msg = ExceptionCommon.getMessage (_class, supermsg, m_arguments);
            }
            
            if (msg == null)
            {
                // this is the same as what's done in Throwable.toString() [copied here to be independent of future JDK changes]
                final String className = _class.getName ();
                
                msg = (supermsg != null) ? (className + ": " + supermsg) : className;
            }
            
            m_message = msg;
        }
        
        return m_message;
public final voidprintStackTrace(java.io.PrintStream s)
Overrides Exception.printStackTrace() to handle nested exceptions in JDKs prior to 1.4.

Subclasses cannot override.

        ExceptionCommon.printStackTrace (this, s);
public final voidprintStackTrace(java.io.PrintWriter s)
Overrides Exception.printStackTrace() to handle nested exceptions in JDKs prior to 1.4.

Subclasses cannot override.

        ExceptionCommon.printStackTrace (this, s);
public final voidprintStackTrace()
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.

        // NOTE: unlike the JDK implementation, force the output to go to System.out:
        ExceptionCommon.printStackTrace (this, System.out);
private voidwriteObject(java.io.ObjectOutputStream out)

        getMessage (); // transform this instance to serializable form
        out.defaultWriteObject ();