/* Copyright (C) 2003 Vladimir Roubtsov. All rights reserved.
*
* This program and the accompanying materials are made available under
* the terms of the Common Public License v1.0 which accompanies this distribution,
* and is available at http://www.eclipse.org/legal/cpl-v10.html
*
* $Id: AbstractException.java,v 1.1.1.1 2004/05/09 16:57:57 vlad_r Exp $
*/
package com.vladium.util.exception;
import java.io.IOException;
import java.io.ObjectOutputStream;
import java.io.PrintStream;
import java.io.PrintWriter;
// ----------------------------------------------------------------------------
/**
* Based on code published by me in <a href="http://www.fawcette.com/javapro/2002_12/online/exception_vroubtsov_12_16_02/default_pf.asp">JavaPro, 2002</a>.<P>
*
* This checked exception class is designed as a base/expansion point for the
* entire hierarchy of checked exceptions in a project.<P>
*
* It provides the following features:
* <UL>
* <LI> 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;
* <LI> exception chaining in J2SE versions prior to 1.4
* </UL>
*
* See {@link AbstractRuntimeException} for an unchecked version of the same class.<P>
*
* 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
* <CODE>com.vladium.exception.exceptions</CODE> resource bundle
* or your project/exception class-specific resource bundle [see
* <A HREF="#details">below</A> 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.<P>
*
* All constructors taking an 'arguments' parameter supply parameters to the error
* message used as a java.text.MessageFormat pattern.<P>
*
* Example:
* <PRE><CODE>
* File file = ...
* try
* ...
* catch (Exception e)
* {
* throw new AbstractException ("FILE_NOT_FOUND", new Object[] {file, e}, e);
* }
* </CODE></PRE>
* where <CODE>com.vladium.util.exception.exceptions</CODE> contains:
* <PRE><CODE>
* FILE_NOT_FOUND: file {0} could not be opened: {1}
* </CODE></PRE>
*
* To log exception data use {@link #getMessage} or <CODE>printStackTrace</CODE>
* family of methods. You should never have to use toString().<P>
*
* <A NAME="details"> It is also possible to use project- or exception
* subhierarchy-specific message resource bundles without maintaining all error
* codes in <CODE>com.vladium.exception.exceptions</CODE>. To do so, create a
* custom resource bundle and add the following static initializer code to your
* base exception class:
* <PRE><CODE>
* static
* {
* addExceptionResource (MyException.class, "my_custom_resource_bundle");
* }
* </CODE></PRE>
* 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
*/
public
abstract class AbstractException extends Exception implements ICodedException, IThrowableWrapper
{
// public: ................................................................
/**
* Constructs an exception with null message and null cause.
*/
public AbstractException ()
{
m_cause = null;
m_arguments = null;
}
/**
* Constructs an exception with given error message/code and null cause.
*
* @param message the detail message [can be null]
*/
public AbstractException (final String message)
{
super (message);
m_cause = null;
m_arguments = null;
}
/**
* 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
*/
public AbstractException (final String message, final Object [] arguments)
{
super (message);
m_cause = null;
m_arguments = arguments == null ? null : (Object []) arguments.clone ();
}
/**
* Constructs an exception with null error message/code and given cause.
*
* @param cause the cause [nested exception] [can be null]
*/
public AbstractException (final Throwable cause)
{
super ();
m_cause = cause;
m_arguments = null;
}
/**
* 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]
*/
public AbstractException (final String message, final Throwable cause)
{
super (message);
m_cause = cause;
m_arguments = null;
}
/**
* 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
*/
public AbstractException (final String message, final Object [] arguments, final Throwable cause)
{
super (message);
m_cause = cause;
m_arguments = arguments == null ? null : (Object []) arguments.clone ();
}
/**
* 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.<P>
*
* 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].
*/
public final String getMessage ()
{
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;
}
/**
* Overrides base method for the sole purpose of making it final.<P>
*
* Equivalent to {@link #getMessage}.
*/
public final String getLocalizedMessage ()
{
// this is the same as what's done in Throwable
// [copied here to be independent of future JDK changes]
return getMessage ();
}
/**
* Overrides Exception.printStackTrace() to (a) force the output to go
* to System.out and (b) handle nested exceptions in JDKs prior to 1.4.<P>
*
* Subclasses cannot override.
*/
public final void printStackTrace ()
{
// NOTE: unlike the JDK implementation, force the output to go to System.out:
ExceptionCommon.printStackTrace (this, System.out);
}
/**
* Overrides Exception.printStackTrace() to handle nested exceptions in JDKs prior to 1.4.<P>
*
* Subclasses cannot override.
*/
public final void printStackTrace (final PrintStream s)
{
ExceptionCommon.printStackTrace (this, s);
}
/**
* Overrides Exception.printStackTrace() to handle nested exceptions in JDKs prior to 1.4.<P>
*
* Subclasses cannot override.
*/
public final void printStackTrace (final PrintWriter s)
{
ExceptionCommon.printStackTrace (this, s);
}
// ICodedException:
/**
* Returns the String that was passed as 'message' constructor argument.
* Can be null.
*
* @return message code string [can be null]
*/
public final String getErrorCode ()
{
return super.getMessage ();
}
// IThrowableWrapper:
/**
* This implements {@link IThrowableWrapper}
* and also overrides the base method in JDK 1.4+.
*/
public final Throwable getCause ()
{
return m_cause;
}
public void __printStackTrace (final PrintStream ps)
{
super.printStackTrace (ps);
}
public void __printStackTrace (final PrintWriter pw)
{
super.printStackTrace (pw);
}
/**
* Equivalent to {@link ExceptionCommon#addExceptionResource}, repeated here for
* convenience. Subclasses should invoke from static initializers <I>only</I>.
* 'namespace' should be YourException.class.
*/
public static void addExceptionResource (final Class namespace,
final String messageResourceBundleName)
{
// 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);
}
// protected: .............................................................
// package: ...............................................................
// private: ...............................................................
/*
* Ensures that this instance can be serialized even if some message parameters
* are not serializable objects.
*/
private void writeObject (final ObjectOutputStream out)
throws IOException
{
getMessage (); // transform this instance to serializable form
out.defaultWriteObject ();
}
private String m_message; // marshalled/cached result of getMessage()
private transient final Object [] m_arguments;
// note: this field duplicates functionality available in stock Throwable in JRE 1.4+
private final Throwable m_cause;
} // end of class
// ----------------------------------------------------------------------------
|
