core/java12/com/vladium/util/exception/AbstractException.java - platform/external/emma - Git at Google

 /* 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
 // ----------------------------------------------------------------------------
	/* 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
	// ----------------------------------------------------------------------------