core/java12/com/vladium/util/exception/ExceptionCommon.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: ExceptionCommon.java,v 1.1.1.1.2.2 2004/07/10 03:34:52 vlad_r Exp $
  */
 package com.vladium.util.exception;

 import java.io.PrintStream;
 import java.io.PrintWriter;
 import java.text.MessageFormat;
 import java.util.Collections;
 import java.util.Enumeration;
 import java.util.HashMap;
 import java.util.Locale;
 import java.util.Map;
 import java.util.ResourceBundle;

 import com.vladium.util.IJREVersion;

 // TODO: embed build # in error codes

 // ----------------------------------------------------------------------------
 /**
  * TODO: javadoc
  *
  * Based on code <a href="http://www.fawcette.com/javapro/2002_12/online/exception_vroubtsov_12_16_02/default_pf.asp">published</a>
  * by me in JavaPro, 2002.<P>
  *
  * This non-instantiable class provides static support functions common to
  * {@link AbstractException} and {@link AbstractRuntimeException}.<P>
  *
  * @author Vlad Roubtsov, (C) 2002
  */
 abstract class ExceptionCommon implements IJREVersion
 {
     // public: ................................................................

     /**
      * This method can be called by static initializers of {@link AbstractException}
      * and {@link AbstractRuntimeException} subclasses in order to add another
      * resource bundle to the set that is used to look up error codes. This makes
      * it possible to extend the set of exception error codes across independently
      * maintained and built projects.<P>
      *
      * <BLOCKQUOTE>
      * Note that this introduces a possibility of error code name clashes. This
      * is resolved in the following way:
      * <UL>
      *     <LI> when <CODE>getMessage(namespace, code)</CODE> is called, 'code'
      *     is attempted to be looked up in the resource bundle previously keyed
      *     under 'namespace';
      *
      *     <LI> if no such bundle it found or if it does not contain a value for
      *     key 'code', the same step is repeated for the superclass of 'namespace';
      *
      *     <LI> finally, if all of the above steps fail, the root resource bundle
      *     specified by {@link #ROOT_RESOURCE_BUNDLE_NAME} is searched.
      * </UL>
      *
      * This strategy ensures that error codes follow inheritance and hiding rules
      * similar to Java static methods.<P>
      * </BLOCKQUOTE>
      *
      * <B>IMPORTANT:</B> this method must be called from static class initializers
      * <I>only</I>.<P>
      *
      * There is no visible state change if the indicated resource is not found
      * or if it has been added already under the same key.<P>
      *
      * @param namespace the Class object acting as the namespace key for the
      * resource bundle identified by 'messageResourceBundleName'. <I>This should
      * be the calling class.</I> [the method is a no-op if this is null]
      *
      * @param messageResourceBundleName name of a bundle (path relative to 'namespace'
      * package) to add to the set from which error code mappings are retrieved
      * [the method is a no-op if this is null or an empty string]
      *
      * @return ResourceBundle that corresponds to 'namespace' key or null if
      * no such bundle could be loaded
      *
      * @throws Error if 'namespace' does not correspond to an exception class derived
      * from {@link AbstractException} or {@link AbstractRuntimeException}.
      *
      * @see #lookup
      */
     public static ResourceBundle addExceptionResource (final Class namespace,
                                                        final String messageResourceBundleName)
     {
         if ((namespace != null) && (messageResourceBundleName != null)
             && (messageResourceBundleName.length () > 0))
         {
             // bail out if the some other exception hierarchy attempts
             // to use this functionality:
             if (! ABSTRACT_EXCEPTION.isAssignableFrom (namespace)
                 && ! ABSTACT_RUNTIME_EXCEPTION.isAssignableFrom (namespace))
             {
                 throw new Error ("addExceptionResource(): class [" + namespace +
                     "] is not a subclass of " + ABSTRACT_EXCEPTION.getName () +
                     " or " + ABSTACT_RUNTIME_EXCEPTION.getName ());
             }

             // try to load resource bundle

             ResourceBundle temprb = null;
             String nameInNamespace = null;
             try
             {
                 nameInNamespace = getNameInNamespace (namespace, messageResourceBundleName);

                 //temprb = ResourceBundle.getBundle (nameInNamespace);

                 ClassLoader loader = namespace.getClassLoader ();
                 if (loader == null) loader = ClassLoader.getSystemClassLoader ();

                 temprb = ResourceBundle.getBundle (nameInNamespace, Locale.getDefault (), loader);
             }
             catch (Throwable ignore)
             {
                // ignored intentionally: if the exception codes rb is absent,
                // we are still in a supported configuration
                temprb = null;
             }

             if (temprb != null)
             {
                 synchronized (s_exceptionCodeMap)
                 {
                     final ResourceBundle currentrb =
                         (ResourceBundle) s_exceptionCodeMap.get (namespace);
                     if (currentrb != null)
                         return currentrb;
                     else
                     {
                         s_exceptionCodeMap.put (namespace, temprb);
                         return temprb;
                     }
                 }
             }
         }

         return null;
     }

     // protected: .............................................................

     // package: ...............................................................


     static void printStackTrace (Throwable t, final PrintWriter out)
     {
         if (JRE_1_4_PLUS)
         {
             if (t instanceof IThrowableWrapper)
             {
                 final IThrowableWrapper tw = (IThrowableWrapper) t;

                 tw.__printStackTrace (out);
             }
             else
             {
                 t.printStackTrace (out);
             }
         }
         else
         {
             for (boolean first = true; t != null; )
             {
                 if (first)
                     first = false;
                 else
                 {
                     out.println ();
                     out.println (NESTED_THROWABLE_HEADER);
                 }

                 if (t instanceof IThrowableWrapper)
                 {
                     final IThrowableWrapper tw = (IThrowableWrapper) t;

                     tw.__printStackTrace (out);
                     t = tw.getCause ();
                 }
                 else
                 {
                     t.printStackTrace (out);
                     break;
                 }
             }
         }
     }


     static void printStackTrace (Throwable t, final PrintStream out)
     {
         if (JRE_1_4_PLUS)
         {
             if (t instanceof IThrowableWrapper)
             {
                 final IThrowableWrapper tw = (IThrowableWrapper) t;

                 tw.__printStackTrace (out);
             }
             else
             {
                 t.printStackTrace (out);
             }
         }
         else
         {
             for (boolean first = true; t != null; )
             {
                 if (first)
                     first = false;
                 else
                 {
                     out.println ();
                     out.println (NESTED_THROWABLE_HEADER);
                 }

                 if (t instanceof IThrowableWrapper)
                 {
                     final IThrowableWrapper tw = (IThrowableWrapper) t;

                     tw.__printStackTrace (out);
                     t = tw.getCause ();
                 }
                 else
                 {
                     t.printStackTrace (out);
                     break;
                 }
             }
         }
     }


     /**
      * Provides support for lookup of exception error codes from {@link AbstractException}
      * and {@link AbstractRuntimeException} and their subclasses.
      *
      * @param namespace the Class object acting as the key to the namespace from
      * which to retrieve the description for 'code' [can be null, in which case
      * only the root namespace is used for lookup]
      *
      * @param code the message string value that was passed into exception
      * constructor [can be null, in which case null is returned].
      *
      * @return looked-up error message or the error code if it could not be
      * looked up [null is returned on null 'code' input only].
      *
      * This method does not throw.
      *
      * @see AbstractException#getMessage
      * @see AbstractRuntimeException#getMessage
      */
     static String getMessage (final Class namespace, final String code)
     {
         if (code == null) return null;

         try
         {
             if (code.length () > 0)
             {
                 // look the code up in the resource bundle:
                 final String msg = lookup (namespace, code);
                 if (msg == null)
                 {
                     // if code lookup failed, return 'code' as is:
                     return code;
                 }
                 else
                 {
                     return EMBED_ERROR_CODE ? "[" + code + "] " + msg : msg;
                 }
            }
            else
            {
                return "";
            }
         }
         catch (Throwable t)
         {
             // this method must never fail: default to returning the input
             // verbatim on all unexpected problems
             return code;
         }
     }

     /**
      * Provides support for lookup of exception error codes from {@link AbstractException}
      * and {@link AbstractRuntimeException} and their subclasses.
      *
      * @param namespace the Class object acting as the key to the namespace from
      * which to retrieve the description for 'code' [can be null, in which case
      * only the root namespace is used for lookup]
      *
      * @param code the message string value that was passed into exception
      * constructor [can be null, in which case null is returned].
      *
      * @param arguments java.text.MessageFormat-style parameters to be substituted
      * into the error message once it is looked up.
      *
      * @return looked-up error message or the error code if it could not be
      * looked up [null is returned on null 'code' input only].
      *
      * This method does not throw.
      *
      * @see AbstractException#getMessage
      * @see AbstractRuntimeException#getMessage
      */
     static String getMessage (final Class namespace, final String code, final Object [] arguments)
     {
         if (code == null) return null;
         final String pattern = getMessage (namespace, code);

         // assertion: pattern != null

         if ((arguments == null) || (arguments.length == 0))
         {
             return pattern;
         }
         else
         {
             try
             {
                 return MessageFormat.format (pattern, arguments);
             }
             catch (Throwable t)
             {
                 // this method cannot fail: default to returning the input
                 // verbatim on all unexpected problems:

                 final StringBuffer msg = new StringBuffer (code + EOL);

                 for (int a = 0; a < arguments.length; a ++)
                 {
                     msg.append ("\t{" + a + "} = [");
                     final Object arg = arguments [a];
                     try
                     {
                         msg.append (arg.toString ());
                     }
                     catch (Throwable e) // guard against bad toString() overrides
                     {
                         if (arg != null)
                             msg.append (arg.getClass ().getName ());
                         else
                             msg.append ("null");
                     }
                     msg.append ("]");
                     msg.append (EOL);
                 }

                 return msg.toString ();
             }
         }
     }

     // private: ...............................................................


     private ExceptionCommon () {} // prevent subclassing

     /**
      * Internal property lookup method. It implements the lookup scheme described
      * in {@link #addExceptionResource}.
      *
      * @return property value corresponding to 'propertyName' [null if lookup fails]
      */
     private static String lookup (Class namespace, final String propertyName)
     {
         if (propertyName == null) return null;

         // note: the following does not guard against exceptions that do not subclass
         // our base classes [done elsewhere], however it will not crash either

         // check extension bundles:
         if (namespace != null)
         {
             ResourceBundle rb;
             while (namespace != ABSTRACT_EXCEPTION && namespace != ABSTACT_RUNTIME_EXCEPTION
                    && namespace != THROWABLE && namespace != null)
             {
                 synchronized (s_exceptionCodeMap)
                 {
                     rb = (ResourceBundle) s_exceptionCodeMap.get (namespace);
                     if (rb == null)
                     {
                         // check if there is a default bundle to be loaded for this namespace:
                         if ((rb = addExceptionResource (namespace, "exceptions")) == null)
                         {
                             // add an immutable empty bundle to avoid this check in the future:
                             s_exceptionCodeMap.put (namespace, EMPTY_RESOURCE_BUNDLE);
                         }
                     }
                 }

                 if (rb != null)
                 {
                     String propertyValue = null;
                     try
                     {
                         propertyValue = rb.getString (propertyName);
                     }
                     catch (Throwable ignore) {}
                     if (propertyValue != null) return propertyValue;
                 }

                 // walk the inheritance chain for 'namespace':
                 namespace = namespace.getSuperclass ();
             }
         }

         // if everything fails, check the root bundle:
         if (ROOT_RESOURCE_BUNDLE != null)
         {
             String propertyValue = null;
             try
             {
                 propertyValue = ROOT_RESOURCE_BUNDLE.getString (propertyName);
             }
             catch (Throwable ignore) {}
             if (propertyValue != null) return propertyValue;
         }

         return null;
     }

     private static String getNameInNamespace (final Class namespace, final String name)
     {
         if (namespace == null) return name;

         final String namespaceName = namespace.getName ();
         final int lastDot = namespaceName.lastIndexOf ('.');

         if (lastDot <= 0)
             return name;
         else
             return namespaceName.substring (0, lastDot + 1)  + name;
     }


     // changes this to 'false' to eliminate repetition of error codes in
     // the output of getMessage():
     private static final boolean EMBED_ERROR_CODE = true;

     // the name of the 'root' message resource bundle, derived as
     // [this package name + ".exceptions"]:
     private static final String ROOT_RESOURCE_BUNDLE_NAME;      // set in <clinit>

     // the root resource bundle; always checked if all other lookups fail:
     private static final ResourceBundle ROOT_RESOURCE_BUNDLE;   // set in <clinit>

     // static cache of all loaded resource bundles, populated via addExceptionResource():
     private static final Map /* Class -> ResourceBundle */ s_exceptionCodeMap = new HashMap ();

     // misc constants:

     private static final String NESTED_THROWABLE_HEADER = "[NESTED EXCEPTION]:";
     private static final Class THROWABLE                    = Throwable.class;
     private static final Class ABSTRACT_EXCEPTION           = AbstractException.class;
     private static final Class ABSTACT_RUNTIME_EXCEPTION    = AbstractRuntimeException.class;
     /*private*/ static final Enumeration EMPTY_ENUMERATION  = Collections.enumeration (Collections.EMPTY_SET);
     private static final ResourceBundle EMPTY_RESOURCE_BUNDLE = new ResourceBundle ()
     {
         public Object handleGetObject (final String key)
         {
             return null;
         }

         public Enumeration getKeys ()
         {
             return EMPTY_ENUMERATION;
         }
     };

     // end-of-line terminator for the current platform:
     private static final String EOL = System.getProperty ("line.separator", "\n");


     static
     {
         // set the name of ROOT_RESOURCE_BUNDLE_NAME:
         ROOT_RESOURCE_BUNDLE_NAME = getNameInNamespace (ExceptionCommon.class, "exceptions");

         // set the root resource bundle:
         ResourceBundle temprb = null;
         try
         {
             temprb = ResourceBundle.getBundle (ROOT_RESOURCE_BUNDLE_NAME);
         }
         catch (Throwable ignore)
         {
             // if the exception codes rb is absent, we are still in a supported configuration
         }
         ROOT_RESOURCE_BUNDLE = temprb;
     }

 } // 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: ExceptionCommon.java,v 1.1.1.1.2.2 2004/07/10 03:34:52 vlad_r Exp $
	*/
	package com.vladium.util.exception;

	import java.io.PrintStream;
	import java.io.PrintWriter;
	import java.text.MessageFormat;
	import java.util.Collections;
	import java.util.Enumeration;
	import java.util.HashMap;
	import java.util.Locale;
	import java.util.Map;
	import java.util.ResourceBundle;

	import com.vladium.util.IJREVersion;

	// TODO: embed build # in error codes

	// ----------------------------------------------------------------------------
	/**
	* TODO: javadoc
	*
	* Based on code <a href="http://www.fawcette.com/javapro/2002_12/online/exception_vroubtsov_12_16_02/default_pf.asp">published</a>
	* by me in JavaPro, 2002.<P>
	*
	* This non-instantiable class provides static support functions common to
	* {@link AbstractException} and {@link AbstractRuntimeException}.<P>
	*
	* @author Vlad Roubtsov, (C) 2002
	*/
	abstract class ExceptionCommon implements IJREVersion
	{
	// public: ................................................................

	/**
	* This method can be called by static initializers of {@link AbstractException}
	* and {@link AbstractRuntimeException} subclasses in order to add another
	* resource bundle to the set that is used to look up error codes. This makes
	* it possible to extend the set of exception error codes across independently
	* maintained and built projects.<P>
	*
	* <BLOCKQUOTE>
	* Note that this introduces a possibility of error code name clashes. This
	* is resolved in the following way:
	* <UL>
	* <LI> when <CODE>getMessage(namespace, code)</CODE> is called, 'code'
	* is attempted to be looked up in the resource bundle previously keyed
	* under 'namespace';
	*
	* <LI> if no such bundle it found or if it does not contain a value for
	* key 'code', the same step is repeated for the superclass of 'namespace';
	*
	* <LI> finally, if all of the above steps fail, the root resource bundle
	* specified by {@link #ROOT_RESOURCE_BUNDLE_NAME} is searched.
	* </UL>
	*
	* This strategy ensures that error codes follow inheritance and hiding rules
	* similar to Java static methods.<P>
	* </BLOCKQUOTE>
	*
	* <B>IMPORTANT:</B> this method must be called from static class initializers
	* <I>only</I>.<P>
	*
	* There is no visible state change if the indicated resource is not found
	* or if it has been added already under the same key.<P>
	*
	* @param namespace the Class object acting as the namespace key for the
	* resource bundle identified by 'messageResourceBundleName'. <I>This should
	* be the calling class.</I> [the method is a no-op if this is null]
	*
	* @param messageResourceBundleName name of a bundle (path relative to 'namespace'
	* package) to add to the set from which error code mappings are retrieved
	* [the method is a no-op if this is null or an empty string]
	*
	* @return ResourceBundle that corresponds to 'namespace' key or null if
	* no such bundle could be loaded
	*
	* @throws Error if 'namespace' does not correspond to an exception class derived
	* from {@link AbstractException} or {@link AbstractRuntimeException}.
	*
	* @see #lookup
	*/
	public static ResourceBundle addExceptionResource (final Class namespace,
	final String messageResourceBundleName)
	{
	if ((namespace != null) && (messageResourceBundleName != null)
	&& (messageResourceBundleName.length () > 0))
	{
	// bail out if the some other exception hierarchy attempts
	// to use this functionality:
	if (! ABSTRACT_EXCEPTION.isAssignableFrom (namespace)
	&& ! ABSTACT_RUNTIME_EXCEPTION.isAssignableFrom (namespace))
	{
	throw new Error ("addExceptionResource(): class [" + namespace +
	"] is not a subclass of " + ABSTRACT_EXCEPTION.getName () +
	" or " + ABSTACT_RUNTIME_EXCEPTION.getName ());
	}

	// try to load resource bundle

	ResourceBundle temprb = null;
	String nameInNamespace = null;
	try
	{
	nameInNamespace = getNameInNamespace (namespace, messageResourceBundleName);

	//temprb = ResourceBundle.getBundle (nameInNamespace);

	ClassLoader loader = namespace.getClassLoader ();
	if (loader == null) loader = ClassLoader.getSystemClassLoader ();

	temprb = ResourceBundle.getBundle (nameInNamespace, Locale.getDefault (), loader);
	}
	catch (Throwable ignore)
	{
	// ignored intentionally: if the exception codes rb is absent,
	// we are still in a supported configuration
	temprb = null;
	}

	if (temprb != null)
	{
	synchronized (s_exceptionCodeMap)
	{
	final ResourceBundle currentrb =
	(ResourceBundle) s_exceptionCodeMap.get (namespace);
	if (currentrb != null)
	return currentrb;
	else
	{
	s_exceptionCodeMap.put (namespace, temprb);
	return temprb;
	}
	}
	}
	}

	return null;
	}

	// protected: .............................................................

	// package: ...............................................................


	static void printStackTrace (Throwable t, final PrintWriter out)
	{
	if (JRE_1_4_PLUS)
	{
	if (t instanceof IThrowableWrapper)
	{
	final IThrowableWrapper tw = (IThrowableWrapper) t;

	tw.__printStackTrace (out);
	}
	else
	{
	t.printStackTrace (out);
	}
	}
	else
	{
	for (boolean first = true; t != null; )
	{
	if (first)
	first = false;
	else
	{
	out.println ();
	out.println (NESTED_THROWABLE_HEADER);
	}

	if (t instanceof IThrowableWrapper)
	{
	final IThrowableWrapper tw = (IThrowableWrapper) t;

	tw.__printStackTrace (out);
	t = tw.getCause ();
	}
	else
	{
	t.printStackTrace (out);
	break;
	}
	}
	}
	}


	static void printStackTrace (Throwable t, final PrintStream out)
	{
	if (JRE_1_4_PLUS)
	{
	if (t instanceof IThrowableWrapper)
	{
	final IThrowableWrapper tw = (IThrowableWrapper) t;

	tw.__printStackTrace (out);
	}
	else
	{
	t.printStackTrace (out);
	}
	}
	else
	{
	for (boolean first = true; t != null; )
	{
	if (first)
	first = false;
	else
	{
	out.println ();
	out.println (NESTED_THROWABLE_HEADER);
	}

	if (t instanceof IThrowableWrapper)
	{
	final IThrowableWrapper tw = (IThrowableWrapper) t;

	tw.__printStackTrace (out);
	t = tw.getCause ();
	}
	else
	{
	t.printStackTrace (out);
	break;
	}
	}
	}
	}


	/**
	* Provides support for lookup of exception error codes from {@link AbstractException}
	* and {@link AbstractRuntimeException} and their subclasses.
	*
	* @param namespace the Class object acting as the key to the namespace from
	* which to retrieve the description for 'code' [can be null, in which case
	* only the root namespace is used for lookup]
	*
	* @param code the message string value that was passed into exception
	* constructor [can be null, in which case null is returned].
	*
	* @return looked-up error message or the error code if it could not be
	* looked up [null is returned on null 'code' input only].
	*
	* This method does not throw.
	*
	* @see AbstractException#getMessage
	* @see AbstractRuntimeException#getMessage
	*/
	static String getMessage (final Class namespace, final String code)
	{
	if (code == null) return null;

	try
	{
	if (code.length () > 0)
	{
	// look the code up in the resource bundle:
	final String msg = lookup (namespace, code);
	if (msg == null)
	{
	// if code lookup failed, return 'code' as is:
	return code;
	}
	else
	{
	return EMBED_ERROR_CODE ? "[" + code + "] " + msg : msg;
	}
	}
	else
	{
	return "";
	}
	}
	catch (Throwable t)
	{
	// this method must never fail: default to returning the input
	// verbatim on all unexpected problems
	return code;
	}
	}

	/**
	* Provides support for lookup of exception error codes from {@link AbstractException}
	* and {@link AbstractRuntimeException} and their subclasses.
	*
	* @param namespace the Class object acting as the key to the namespace from
	* which to retrieve the description for 'code' [can be null, in which case
	* only the root namespace is used for lookup]
	*
	* @param code the message string value that was passed into exception
	* constructor [can be null, in which case null is returned].
	*
	* @param arguments java.text.MessageFormat-style parameters to be substituted
	* into the error message once it is looked up.
	*
	* @return looked-up error message or the error code if it could not be
	* looked up [null is returned on null 'code' input only].
	*
	* This method does not throw.
	*
	* @see AbstractException#getMessage
	* @see AbstractRuntimeException#getMessage
	*/
	static String getMessage (final Class namespace, final String code, final Object [] arguments)
	{
	if (code == null) return null;
	final String pattern = getMessage (namespace, code);

	// assertion: pattern != null

	if ((arguments == null) \|\| (arguments.length == 0))
	{
	return pattern;
	}
	else
	{
	try
	{
	return MessageFormat.format (pattern, arguments);
	}
	catch (Throwable t)
	{
	// this method cannot fail: default to returning the input
	// verbatim on all unexpected problems:

	final StringBuffer msg = new StringBuffer (code + EOL);

	for (int a = 0; a < arguments.length; a ++)
	{
	msg.append ("\t{" + a + "} = [");
	final Object arg = arguments [a];
	try
	{
	msg.append (arg.toString ());
	}
	catch (Throwable e) // guard against bad toString() overrides
	{
	if (arg != null)
	msg.append (arg.getClass ().getName ());
	else
	msg.append ("null");
	}
	msg.append ("]");
	msg.append (EOL);
	}

	return msg.toString ();
	}
	}
	}

	// private: ...............................................................


	private ExceptionCommon () {} // prevent subclassing

	/**
	* Internal property lookup method. It implements the lookup scheme described
	* in {@link #addExceptionResource}.
	*
	* @return property value corresponding to 'propertyName' [null if lookup fails]
	*/
	private static String lookup (Class namespace, final String propertyName)
	{
	if (propertyName == null) return null;

	// note: the following does not guard against exceptions that do not subclass
	// our base classes [done elsewhere], however it will not crash either

	// check extension bundles:
	if (namespace != null)
	{
	ResourceBundle rb;
	while (namespace != ABSTRACT_EXCEPTION && namespace != ABSTACT_RUNTIME_EXCEPTION
	&& namespace != THROWABLE && namespace != null)
	{
	synchronized (s_exceptionCodeMap)
	{
	rb = (ResourceBundle) s_exceptionCodeMap.get (namespace);
	if (rb == null)
	{
	// check if there is a default bundle to be loaded for this namespace:
	if ((rb = addExceptionResource (namespace, "exceptions")) == null)
	{
	// add an immutable empty bundle to avoid this check in the future:
	s_exceptionCodeMap.put (namespace, EMPTY_RESOURCE_BUNDLE);
	}
	}
	}

	if (rb != null)
	{
	String propertyValue = null;
	try
	{
	propertyValue = rb.getString (propertyName);
	}
	catch (Throwable ignore) {}
	if (propertyValue != null) return propertyValue;
	}

	// walk the inheritance chain for 'namespace':
	namespace = namespace.getSuperclass ();
	}
	}

	// if everything fails, check the root bundle:
	if (ROOT_RESOURCE_BUNDLE != null)
	{
	String propertyValue = null;
	try
	{
	propertyValue = ROOT_RESOURCE_BUNDLE.getString (propertyName);
	}
	catch (Throwable ignore) {}
	if (propertyValue != null) return propertyValue;
	}

	return null;
	}

	private static String getNameInNamespace (final Class namespace, final String name)
	{
	if (namespace == null) return name;

	final String namespaceName = namespace.getName ();
	final int lastDot = namespaceName.lastIndexOf ('.');

	if (lastDot <= 0)
	return name;
	else
	return namespaceName.substring (0, lastDot + 1) + name;
	}


	// changes this to 'false' to eliminate repetition of error codes in
	// the output of getMessage():
	private static final boolean EMBED_ERROR_CODE = true;

	// the name of the 'root' message resource bundle, derived as
	// [this package name + ".exceptions"]:
	private static final String ROOT_RESOURCE_BUNDLE_NAME; // set in <clinit>

	// the root resource bundle; always checked if all other lookups fail:
	private static final ResourceBundle ROOT_RESOURCE_BUNDLE; // set in <clinit>

	// static cache of all loaded resource bundles, populated via addExceptionResource():
	private static final Map /* Class -> ResourceBundle */ s_exceptionCodeMap = new HashMap ();

	// misc constants:

	private static final String NESTED_THROWABLE_HEADER = "[NESTED EXCEPTION]:";
	private static final Class THROWABLE = Throwable.class;
	private static final Class ABSTRACT_EXCEPTION = AbstractException.class;
	private static final Class ABSTACT_RUNTIME_EXCEPTION = AbstractRuntimeException.class;
	/private/ static final Enumeration EMPTY_ENUMERATION = Collections.enumeration (Collections.EMPTY_SET);
	private static final ResourceBundle EMPTY_RESOURCE_BUNDLE = new ResourceBundle ()
	{
	public Object handleGetObject (final String key)
	{
	return null;
	}

	public Enumeration getKeys ()
	{
	return EMPTY_ENUMERATION;
	}
	};

	// end-of-line terminator for the current platform:
	private static final String EOL = System.getProperty ("line.separator", "\n");


	static
	{
	// set the name of ROOT_RESOURCE_BUNDLE_NAME:
	ROOT_RESOURCE_BUNDLE_NAME = getNameInNamespace (ExceptionCommon.class, "exceptions");

	// set the root resource bundle:
	ResourceBundle temprb = null;
	try
	{
	temprb = ResourceBundle.getBundle (ROOT_RESOURCE_BUNDLE_NAME);
	}
	catch (Throwable ignore)
	{
	// if the exception codes rb is absent, we are still in a supported configuration
	}
	ROOT_RESOURCE_BUNDLE = temprb;
	}

	} // end of class
	// ----------------------------------------------------------------------------