com.xerceo.text
Class Messages

java.lang.Object
  java.util.ResourceBundle
      com.xerceo.text.Messages

public class Messages
extends java.util.ResourceBundle

Supports the localization of Java programs by providing convenience methods to format and log text messages derived from an XML message bundle. This class supports three common ways to store localized messages in an XML file: one XML file per project, one XML file per package, and one XML file per class. However, the code to retrieve a Messages for a given class insulates the calling program from knowing how the underlying XML documents are arranged in the project. This allows you to migrate from a one per project approach to a one per package or class approach as the project grows in the number of messages. See the XML DTD xmsg_1_0.dtd for more details. The primary design goals were to provide an interface that behaves like a standard ResourceBundle, but adds the following features:

• Ability to markup the messages (resources) using XML to provide additional metadata about a message than a standard name=value pair allows.
• Integrated logging support; logging and localization are intimately tied together in server-side applications; ResourceBundles don't provide a convenient way to log an exception with a message from the bundle.
• Simplify the process of formatting messages with replaceable (runtime) parameters.
• Most importantly, allow the messages to live inside the source code to make developer's lives easier, but still provide an external form for translators.

Version:

#xerceo-1.0#

Author:

tim.potter@xerceo.com

Field Summary

Fields inherited from class java.util.ResourceBundle

parent

Method Summary

void	debug(java.lang.String message) Writes a debug message to the log if Level.FINEST is enabled on the Log4J Logger.
void	debug(java.lang.String template, java.lang.Object param1) Writes a debug message to the log if Level.FINEST is enabled on the Log4J Logger.
void	debug(java.lang.String template, java.lang.Object[] params) Writes a debug message to the log if Level.DEBUG is enabled on the Log4J Logger.
void	debug(java.lang.String template, java.lang.Object[] params, java.lang.Throwable thrown) Writes a debug message to the log if Level.DEBUG is enabled on the Log4J Logger.
boolean	equals(java.lang.Object obj) Determines if obj is equivalent to this.
static Messages	forClass(java.lang.Class cls) Find or create a Messages for the specified class for the current default Locale.
static Messages	forClass(java.lang.Class cls, java.util.Locale locale) Find or create a Messages for the specified class for the specified Locale.
java.lang.String	format(java.lang.String id) Returns a formatted, localized message.
java.lang.String	format(java.lang.String id, java.lang.Object param1) Returns a formatted, localized message.
java.lang.String	format(java.lang.String id, java.lang.Object[] params) Returns a formatted, localized message.
java.util.Enumeration	getKeys() Returns an enumeration of the keys in this message bundle.
java.util.Locale	getLocale() Returns the actual locale the messages in this message bundle are translated to.
org.apache.log4j.Logger	getLogger() Provides access to the Log4J Logger instance this message bundle uses to log messages to.
java.lang.String	getName() Returns the name of this message bundle.
protected java.lang.Object	handleGetObject(java.lang.String objKey) Gets an object for the given key from this resource bundle.
int	hashCode() Returns a code based on the key of the message bundle.
boolean	isDebugEnabled() Quick check to see if debugging is enabled for this logger.
boolean	isLoggable(java.lang.String id) Determines if a message identified by id would be sent to the underlying logger based on its configured severity level.
java.lang.String	log(java.lang.String id) Formats, logs, and returns a localized message to the underlying Log4J Logger.
java.lang.String	log(java.lang.String id, java.lang.Object param1) Formats, logs, and returns a localized message to the underlying Log4J Logger.
java.lang.String	log(java.lang.String id, java.lang.Object[] params) Formats, logs, and returns a localized message to the underlying Log4J Logger.
java.lang.String	log(java.lang.String id, java.lang.Object[] params, java.lang.Throwable thrown) Formats, logs, and returns a localized message to the underlying Log4J Logger with an exception.
java.lang.String	log(java.lang.String id, java.lang.Object param1, java.lang.Throwable thrown) Formats, logs, and returns a localized message to the underlying Log4J Logger.
java.lang.String	log(java.lang.String id, java.lang.Throwable thrown) Formats, logs, and returns a localized message to the underlying Log4J Logger with an exception.
java.lang.String	toString() Provides a String representation of the underlying state of this object suitable for debugging purposes.

Methods inherited from class java.util.ResourceBundle

getBundle, getBundle, getBundle, getObject, getString, getStringArray, setParent

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

forClass

public static final Messages forClass(java.lang.Class cls)

Find or create a Messages for the specified class for the current default Locale. If a bundle has already been created for this class for the current default locale, it is returned directly. Otherwise, a new Messages is created by locating the underlying XML document containing the localized messages for cls. The search algorithm behaves like the standard Java ResourceBundle.getBundle(...) search algorithm. Specifically, the search algorithm search for an appropriate XML message bundle document in the following order:

 Messages mb =
     Messages.forClass(jmx.User.class, Locale.US);
 

 class-level bundles
 
jmx/User_xmsg_en_US.xml
 
jmx/User_xmsg_en.xml
 
jmx/User_xmsg.xml
 package-level bundles
 
jmx/xmsg_en_US.xml
 
jmx/xmsg_en.xml
 
jmx/xmsg.xml
 project-level bundles
 
xmsg_en_US.xml
 
xmsg_en.xml
 
xmsg.xml
 
 

Parameters:

cls - The class that needs localized messages.

Returns:

Messages a suitable Messages; similar to the behavior of a java.util.ResourceBundle, the provided Messages may be for a fallback locale.

forClass

public static final Messages forClass(java.lang.Class cls,
                                      java.util.Locale locale)

Find or create a Messages for the specified class for the specified Locale. If a bundle has already been created for this class for the specified locale, it is returned directly. Otherwise, a new Messages is created by locating the underlying XML document containing the localized messages for cls.

Parameters:

cls - The class that needs localized messages.

locale - The desired locale.

Returns:

Messages a suitable Messages; similar to the behavior of a java.util.ResourceBundle, the provided Messages may be for a fallback locale.

getKeys

public java.util.Enumeration getKeys()

Returns an enumeration of the keys in this message bundle.

Specified by:

getKeys in class java.util.ResourceBundle

Returns:

Enumeration enumeration of the message keys in this bundle.

handleGetObject

protected java.lang.Object handleGetObject(java.lang.String objKey)

Gets an object for the given key from this resource bundle. Returns null if this resource bundle does not contain an object for the given key.

Specified by:

handleGetObject in class java.util.ResourceBundle

Parameters:

objKey - The identifier of the message to retrieve.

Returns:

Object The message retrieved from the bundle.

getLogger

public org.apache.log4j.Logger getLogger()

Provides access to the Log4J Logger instance this message bundle uses to log messages to.

Returns:

Logger The Log4J Logger based on the message bundle name.

getName

public java.lang.String getName()

Returns the name of this message bundle.

Returns:

String The name of this message bundle.

getLocale

public java.util.Locale getLocale()

Returns the actual locale the messages in this message bundle are translated to. This method can be used to determine whether the bundle returned really corresponds to the requested locale or is a fallback.

Overrides:

getLocale in class java.util.ResourceBundle

Returns:

Locale The actual locale for this Messages, derived from the XML document element.

format

public java.lang.String format(java.lang.String id)

Returns a formatted, localized message.

Parameters:

id - The identifier of the message in the message bundle.

Returns:

String The formatted message.

format

public java.lang.String format(java.lang.String id,
                               java.lang.Object param1)

Returns a formatted, localized message.

Parameters:

id - The identifier of the message in the message bundle.

param1 - A parameter to be applied to the message during formatting.

Returns:

String The formatted message.

format

public java.lang.String format(java.lang.String id,
                               java.lang.Object[] params)

Returns a formatted, localized message.

Parameters:

id - The identifier of the message in the message bundle.

params - An array of parameters to be applied to the message during formatting.

Returns:

String The formatted message.

isLoggable

public boolean isLoggable(java.lang.String id)

Determines if a message identified by id would be sent to the underlying logger based on its configured severity level. This method is useful if constructing the parameters for formatting the message requires expensive work that should only be undertaken if it will actually be logged and the message is not needed after it is logged.

Parameters:

id - The identifier of the message.

Returns:

true if the message identified by id would be logged; false otherwise.

log

public java.lang.String log(java.lang.String id)
                     throws MessagesRuntimeException

Formats, logs, and returns a localized message to the underlying Log4J Logger.

Parameters:

id - The message id, used to look up a localized message from the underlying message bundle.

Returns:

String the generated localized message, regardless of whether it makes it to a log handler.

Throws:

MessagesRuntimeException - if no message is mapped to the specified id.

log

public java.lang.String log(java.lang.String id,
                            java.lang.Throwable thrown)
                     throws MessagesRuntimeException

Formats, logs, and returns a localized message to the underlying Log4J Logger with an exception.

Parameters:

id - The message id, used to look up a localized message from the underlying message bundle.

thrown - An exception that needs to be logged.

Returns:

String the generated localized message, regardless of whether it makes it to a log handler.

Throws:

MessagesRuntimeException - if no message is mapped to the specified id.

log

public java.lang.String log(java.lang.String id,
                            java.lang.Object param1)
                     throws MessagesRuntimeException

Formats, logs, and returns a localized message to the underlying Log4J Logger.

Parameters:

id - The message id, used to look up a message template from the underlying message bundle and then apply the replace-able parameter to generate the localized message.

param1 - A replace-able parameter to be applied to the MessageFormat for the given message.

Returns:

String the generated localized message, regardless of whether it makes it to a log handler.

Throws:

MessagesRuntimeException - if no message is mapped to the specified id.

log

public java.lang.String log(java.lang.String id,
                            java.lang.Object param1,
                            java.lang.Throwable thrown)
                     throws MessagesRuntimeException

Formats, logs, and returns a localized message to the underlying Log4J Logger.

Parameters:

id - The message id, used to look up a message template from the underlying message bundle and then apply the replace-able parameter to generate the localized message.

param1 - A replace-able parameter to be applied to the MessageFormat for the given message.

thrown - An exception that needs to be logged.

Returns:

String the generated localized message, regardless of whether it makes it to a log handler.

Throws:

MessagesRuntimeException - if no message is mapped to the specified id.

log

public java.lang.String log(java.lang.String id,
                            java.lang.Object[] params)
                     throws MessagesRuntimeException

Formats, logs, and returns a localized message to the underlying Log4J Logger.

Parameters:

id - The message id, used to look up a message template from the underlying message bundle and then apply the replace-able parameters to generate the localized message.

params - An array of replace-able parameters to be applied to the MessageFormat for the given message.

Returns:

String the generated localized message, regardless of whether it makes it to a log handler.

Throws:

MessagesRuntimeException - if no message is mapped to the specified id.

log

public java.lang.String log(java.lang.String id,
                            java.lang.Object[] params,
                            java.lang.Throwable thrown)
                     throws MessagesRuntimeException

Formats, logs, and returns a localized message to the underlying Log4J Logger with an exception.

Parameters:

id - The message id, used to look up a message template from the underlying message bundle and then apply the replace-able parameters to generate the localized message.

params - An array of replace-able parameters to be applied to the MessageFormat for the given message.

thrown - An exception that needs to be logged.

Returns:

String the generated localized message, regardless of whether it makes it to a log handler.

Throws:

MessagesRuntimeException - if no message is mapped to the specified id.

isDebugEnabled

public boolean isDebugEnabled()

Quick check to see if debugging is enabled for this logger.

Returns:

true if debug messages will be rendered by this logger.

debug

public void debug(java.lang.String message)

Writes a debug message to the log if Level.FINEST is enabled on the Log4J Logger.

Parameters:

message - A debug message that does not require any runtime formatting.

debug

public void debug(java.lang.String template,
                  java.lang.Object param1)

Writes a debug message to the log if Level.FINEST is enabled on the Log4J Logger.

Parameters:

template - A java.text.MessageFormat style message template to format param1 into a debug message.

param1 - A parameter to be applied to the message as a replaceable parameter during runtime formatting.

debug

public void debug(java.lang.String template,
                  java.lang.Object[] params)

Writes a debug message to the log if Level.DEBUG is enabled on the Log4J Logger.

Parameters:

template - A java.text.MessageFormat style message template to format params into a debug message.

params - An array of parameters to be applied to the message as replaceable parameters; should not be null but if it is, this method just logs template as the message.

debug

public void debug(java.lang.String template,
                  java.lang.Object[] params,
                  java.lang.Throwable thrown)

Writes a debug message to the log if Level.DEBUG is enabled on the Log4J Logger.

Parameters:

template - A java.text.MessageFormat style message template to format params into a debug message.

params - An array of parameters to be applied to the message as replaceable parameters; should not be null but if it is, this method just logs template as the message.

thrown - An exception related to this debug message.

hashCode

public int hashCode()

Returns a code based on the key of the message bundle.

Overrides:

hashCode in class java.lang.Object

Returns:

int a hash code based on the key.

equals

public boolean equals(java.lang.Object obj)

Determines if obj is equivalent to this.

Overrides:

equals in class java.lang.Object

Parameters:

obj - The object to compare this to; must be an instance of Messages.

Returns:

true if obj is a Messages and its key is equivalent to this'; false otherwise

toString

public java.lang.String toString()

Provides a String representation of the underlying state of this object suitable for debugging purposes.

Overrides:

toString in class java.lang.Object

Returns:

A String representation of the state of this instance.