com.vladium.util.exception
Class ExceptionCommon

java.lang.Object
  extended by com.vladium.util.exception.ExceptionCommon
All Implemented Interfaces:
com.vladium.util.IJREVersion

abstract class ExceptionCommon
extends java.lang.Object
implements com.vladium.util.IJREVersion

TODO: javadoc Based on code published by me in JavaPro, 2002.

This non-instantiable class provides static support functions common to AbstractException and AbstractRuntimeException.

Author:
Vlad Roubtsov, (C) 2002

Nested Class Summary
 
Nested classes/interfaces inherited from interface com.vladium.util.IJREVersion
com.vladium.util.IJREVersion._JREVersion
 
Field Summary
private static java.lang.Class ABSTACT_RUNTIME_EXCEPTION
           
private static java.lang.Class ABSTRACT_EXCEPTION
           
private static boolean EMBED_ERROR_CODE
           
(package private) static java.util.Enumeration EMPTY_ENUMERATION
           
private static java.util.ResourceBundle EMPTY_RESOURCE_BUNDLE
           
private static java.lang.String EOL
           
private static java.lang.String NESTED_THROWABLE_HEADER
           
private static java.util.ResourceBundle ROOT_RESOURCE_BUNDLE
           
private static java.lang.String ROOT_RESOURCE_BUNDLE_NAME
           
private static java.util.Map s_exceptionCodeMap
           
private static java.lang.Class THROWABLE
           
 
Fields inherited from interface com.vladium.util.IJREVersion
JRE_1_2_PLUS, JRE_1_3_PLUS, JRE_1_4_PLUS, JRE_SUN_SIGNAL_COMPATIBLE
 
Constructor Summary
private ExceptionCommon()
           
 
Method Summary
static java.util.ResourceBundle addExceptionResource(java.lang.Class namespace, java.lang.String messageResourceBundleName)
          This method can be called by static initializers of AbstractException and AbstractRuntimeException subclasses in order to add another resource bundle to the set that is used to look up error codes.
(package private) static java.lang.String getMessage(java.lang.Class namespace, java.lang.String code)
          Provides support for lookup of exception error codes from AbstractException and AbstractRuntimeException and their subclasses.
(package private) static java.lang.String getMessage(java.lang.Class namespace, java.lang.String code, java.lang.Object[] arguments)
          Provides support for lookup of exception error codes from AbstractException and AbstractRuntimeException and their subclasses.
private static java.lang.String getNameInNamespace(java.lang.Class namespace, java.lang.String name)
           
private static java.lang.String lookup(java.lang.Class namespace, java.lang.String propertyName)
          Internal property lookup method.
(package private) static void printStackTrace(java.lang.Throwable t, java.io.PrintStream out)
           
(package private) static void printStackTrace(java.lang.Throwable t, java.io.PrintWriter out)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EMBED_ERROR_CODE

private static final boolean EMBED_ERROR_CODE
See Also:
Constant Field Values

ROOT_RESOURCE_BUNDLE_NAME

private static final java.lang.String ROOT_RESOURCE_BUNDLE_NAME

ROOT_RESOURCE_BUNDLE

private static final java.util.ResourceBundle ROOT_RESOURCE_BUNDLE

s_exceptionCodeMap

private static final java.util.Map s_exceptionCodeMap

NESTED_THROWABLE_HEADER

private static final java.lang.String NESTED_THROWABLE_HEADER
See Also:
Constant Field Values

THROWABLE

private static final java.lang.Class THROWABLE

ABSTRACT_EXCEPTION

private static final java.lang.Class ABSTRACT_EXCEPTION

ABSTACT_RUNTIME_EXCEPTION

private static final java.lang.Class ABSTACT_RUNTIME_EXCEPTION

EMPTY_ENUMERATION

static final java.util.Enumeration EMPTY_ENUMERATION

EMPTY_RESOURCE_BUNDLE

private static final java.util.ResourceBundle EMPTY_RESOURCE_BUNDLE

EOL

private static final java.lang.String EOL
Constructor Detail

ExceptionCommon

private ExceptionCommon()
Method Detail

addExceptionResource

public static java.util.ResourceBundle addExceptionResource(java.lang.Class namespace,
                                                            java.lang.String messageResourceBundleName)
This method can be called by static initializers of AbstractException and 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.

Note that this introduces a possibility of error code name clashes. This is resolved in the following way:
  • when getMessage(namespace, code) is called, 'code' is attempted to be looked up in the resource bundle previously keyed under 'namespace';
  • 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';
  • finally, if all of the above steps fail, the root resource bundle specified by ROOT_RESOURCE_BUNDLE_NAME is searched.
This strategy ensures that error codes follow inheritance and hiding rules similar to Java static methods.

IMPORTANT: this method must be called from static class initializers only.

There is no visible state change if the indicated resource is not found or if it has been added already under the same key.

Parameters:
namespace - the Class object acting as the namespace key for the resource bundle identified by 'messageResourceBundleName'. This should be the calling class. [the method is a no-op if this is null]
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]
Returns:
ResourceBundle that corresponds to 'namespace' key or null if no such bundle could be loaded
Throws:
java.lang.Error - if 'namespace' does not correspond to an exception class derived from AbstractException or AbstractRuntimeException.
See Also:
lookup(java.lang.Class, java.lang.String)

printStackTrace

static void printStackTrace(java.lang.Throwable t,
                            java.io.PrintWriter out)

printStackTrace

static void printStackTrace(java.lang.Throwable t,
                            java.io.PrintStream out)

getMessage

static java.lang.String getMessage(java.lang.Class namespace,
                                   java.lang.String code)
Provides support for lookup of exception error codes from AbstractException and AbstractRuntimeException and their subclasses.

Parameters:
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]
code - the message string value that was passed into exception constructor [can be null, in which case null is returned].
Returns:
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 Also:
AbstractException.getMessage(), AbstractRuntimeException.getMessage()

getMessage

static java.lang.String getMessage(java.lang.Class namespace,
                                   java.lang.String code,
                                   java.lang.Object[] arguments)
Provides support for lookup of exception error codes from AbstractException and AbstractRuntimeException and their subclasses.

Parameters:
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]
code - the message string value that was passed into exception constructor [can be null, in which case null is returned].
arguments - java.text.MessageFormat-style parameters to be substituted into the error message once it is looked up.
Returns:
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 Also:
AbstractException.getMessage(), AbstractRuntimeException.getMessage()

lookup

private static java.lang.String lookup(java.lang.Class namespace,
                                       java.lang.String propertyName)
Internal property lookup method. It implements the lookup scheme described in addExceptionResource(java.lang.Class, java.lang.String).

Returns:
property value corresponding to 'propertyName' [null if lookup fails]

getNameInNamespace

private static java.lang.String getNameInNamespace(java.lang.Class namespace,
                                                   java.lang.String name)