com.ccg.util
Class FormatException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          com.ccg.util.FormatException

All Implemented Interfaces:

Serializable

public abstract class FormatException
extends Exception

A base class to simplify the creation of localized exceptions.

This class is intended to make it easier for developers to design and implement localized exception messages on a package basis.

To get a good idea of how this works, refer to the simple working example FException.java, its messages in their default language in the file msgs/FormatException.properties, and a "pig latin" version of the strings in msgs/FormatException_en_PL.properties.

Here are the basics in using this class:

• For your package, create one base exception class which extends this class. See the com.ccg.messages.MessageException class for a working example.
• Next, for you package create the sub-directory "msgs" and the resource file "FormatExceptions.properties". Define all of the exceptions which your package might generate in here. Some messages might look like:

 E1000=Failed to connect to host {0}.
 E1001=Port {0} in use at {1}.
 E1002=You can not leave the user ID field blank.
 

• When you construct your new exception types, make sure that the string you use at construction is either a key name from your resource file, OR starts with a key name. For example: "E1002" and "E1002:Missing ID" would both find the "E1002" definition in the sample resource file shown above.

NOTE: By default, this class will ALWAYS attempt to return a localized message. By ALWAYS attempting to localize, one can simply pass the exception ID's to the constructor (like: "E0002") thus removing the need for long strings in the source code. If you don't want your error strings always localized, you should override the isAlwaysLocalized method and have it return false instead of true in your derived class.

Since:

1.0

Version:

$Revision: 1.2 $

Author:

$Author: pkb $

See Also:

Serialized Form

Constructor Summary

FormatException()
Construct the exception without a message/tag.

FormatException(String s, Object[] args, Throwable t)
Associate a tag/message and optional format arguments with the exception.

Method Summary

String	getLocalizedMessage() Get a localized representation of the exception.
String	getMessage() Get string representation of the exception.
protected abstract ResourceBundle	getResourceBundle() This method is used when a localized message is being used.
Throwable	getUnderlying() Get the underlying Throwable which triggered this exception
boolean	hasUnderlying() Is there an underlying problem associated with this exception?
boolean	isAlwaysLocalized() Should all messages be localized?
protected ResourceBundle	loadResourceBundle(Package p) Helper method to load stock error messages for a package.
void	setUnderlying(Throwable val) Set the underlying Throwable which triggered this exception

Methods inherited from class java.lang.Throwable

fillInStackTrace, getCause, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

FormatException

public FormatException()

Construct the exception without a message/tag.

Typically one doesn't use this method - as it pretty much defeats the translation capabilities of this class.

Since:

1.0

See Also:

FormatException(String,Object[],Throwable)

FormatException

public FormatException(String s,
                       Object[] args,
                       Throwable t)

Associate a tag/message and optional format arguments with the exception.

This is the typical way in which one constructs these objects. It allows one to specify a default message (like: "E1000:config file {0} not found"), and optional set of arguments which can be subsituted into the message.

Parameters:

s - The ID of the message in the resource file to use with the exception (can be null - but it isn't recommended)

args - The set of arguments to subsitute into the string as defined by the MessageFormat class. If you don't require variable subsitution, then pass null.

t - The underlying problem which caused us to throw this exception (or null if there wasn't one).

Since:

1.0

See Also:

setUnderlying(java.lang.Throwable)

Method Detail

hasUnderlying

public boolean hasUnderlying()

Is there an underlying problem associated with this exception?

Sometimes one will want to create custom exceptions which have an associated underlying exception. For example, if you

Returns:

true if there is another underlying exception associated

Since:

1.0

See Also:

getUnderlying()

setUnderlying

public void setUnderlying(Throwable val)

Set the underlying Throwable which triggered this exception

Parameters:

val - New Throwable value to assign.

See Also:

getUnderlying()

getUnderlying

public Throwable getUnderlying()

Get the underlying Throwable which triggered this exception

Returns:

Current underlying Throwable which triggered this one (or null if there wasn't one).

See Also:

setUnderlying(java.lang.Throwable)

getMessage

public String getMessage()

Get string representation of the exception.

This method returns the default string representation of the exception. This has several different possibilities:

• If this object was constructed without a string representation, and does not have a associated Exception, then null is returned.
• If this object was constructed without a string representation, but has an associated Exception, then message from the underlying exception is returned.
• If this item was created with a string representation and arguments and the string has a '{', then an attempt will be made to format the string (subsituting arguments following the standard MessageFormat protocol).
• If created with a string representation, but no argument subsitution is required, then the string itself will be returned.

Note, if the class localizes ALL messages, then any invocation of this method will just be handed off to the getLocalizedMessage method.

Overrides:

getMessage in class Throwable

Since:

1.0

See Also:

getLocalizedMessage()

isAlwaysLocalized

public boolean isAlwaysLocalized()

Should all messages be localized?

This method will return "true" if all error messages should be localized. By default, this method returns "false" indicating the that string the error is constructed with can be used as the normal text for the error message. If this method returns true, then the getLocalizedMessage method will be used (even when you call getMessage()).

If you prefer to keep all of your error descriptions in your resource bundles (which is probably wise), you don't need to override this method (as the default behavior is to always use the associated resource bundle). Using this implementation, you only need to specify the "key name" of your error messages (it reduces the size of the strings in your actual code as you can use strings like: "E0001" instead of "E0001:{0} is not a valid name".

If however, you prefer that the default text be exactly what you entered in your code, then you should override this method (make it return false), and then make sure that you use the "KEY:TEXT" form for all of your error messages in your program.

Returns:

true in this default implementation

See Also:

getLocalizedMessage(), getMessage()

getLocalizedMessage

public String getLocalizedMessage()

Get a localized representation of the exception.

This method attempts to translate the error message into its "localized" form. In order for a message to be translated, ALL of the following must be true:

• The non-localized string associated with the object must not be null or zero length.
• The non-localized string associated with the object must either be a key into a resource bundle, or the first portion of the string (up to the first ':') must be a key into the resource bundle. For example, "E1000" and "E1000:Missing config file" would both result in a key value of "E1000" used for looking up the localized message.
• A non-null resource bundle must be associated with the object.

If we are unable to translate the message to its localized form, then the non-localized form will be returned.

NOTE: This method should NEVER invoke the getMessage method directly (it can use: super.getMessage()).

Overrides:

getLocalizedMessage in class Throwable

Since:

1.0

See Also:

getMessage(), getResourceBundle()

getResourceBundle

protected abstract ResourceBundle getResourceBundle()

This method is used when a localized message is being used.

This method is used if a request for a localized exception message has been requested. It method returns the resource bundle if its possible to lookup a localized message. This method will return null if not possible - but it should NEVER throw an exception.

You MUST override this method! The easy way to do this looks something like the following:

 private static ResourceBundle _Resources;

 protected ResourceBundle getResourceBundle() {
   if (_Resources == null) {
     _Resources = loadResourceBundle(this.class.getPackage());
   }
   return _Resources;
 }
 

To use the above, you then create a "msgs/FormatExcection.properties" file (and its language derivatives) for your package.

Returns:

Resource bundle to lookup localized message from, or null if no localized information is available.

Since:

1.0

See Also:

getLocalizedMessage()

loadResourceBundle

protected ResourceBundle loadResourceBundle(Package p)

Helper method to load stock error messages for a package.

This helper method is used to load stock error messages for a package. You pass it the package which you want to get the error message resources for, it will then try and return the appropriate resource bundle.

This method is intended as a helper method for derived classes which implement the getResourceBundle() method.

Take a look at the "com.ccg.messages.MessageException" class, its source files and the "com/ccg/messages/msgs/FormatException.properties" file for a example of how this works.

Parameters:

p - The package to get the error messages for - if you pass null, we will assume no package and look for "msgs/FormatException.properties".

Returns:

The ResourceBundle with the error message translations for the package. If not found, we will return a custom resource bundle that just returns the "key" value as the associated data for each lookup.

Since:

1.0

See Also:

getResourceBundle()