mazz.i18n
Class Msg

java.lang.Object
  mazz.i18n.Msg

All Implemented Interfaces:

java.io.Serializable

public class Msg
extends java.lang.Object
implements java.io.Serializable

Retrieves messages from a message ResourceBundle and formats them as appropriate using MessageFormat. Instances of this object are mostly read-only - the only thing you can change is the locale. Changing the locale will attempt to convert the message to that new locale's format.

I18N Msg objects are serializable and will be re-translated once it is deserialized. This means that a message could be localized in the English language, serialized and sent over the wire to another JVM with a German locale and when the deserialized message is retrieved again, it will be in German. This feature assumes a resource bundle with the same base bundle name exists in the JVM that deserialized the Msg. If it does not, then the original message will be used (in the previous example, it would mean the English message would be retrieved in the JVM, even though its locale is German).

There is a method to the madness to some of the methods' parameter ordering. Anytime you want to specify a localized message, you always specify the base bundle name first, followed by the locale, the bundle key and the variable list of arguments that go with the keyed message (all in that order). Bundle name and locale are both optional. This is consistent with the way localized messages are specified in constructors for LocalizedException and LocalizedRuntimeException. When you need to specify a Throwable with your localized message, it is specified before those parameters. Again, this is consistent both in this class and the localized exception classes (see createMsg(mazz.i18n.Msg.BundleBaseName, Locale, String, Object[]) and LocalizedException.LocalizedException(Throwable, mazz.i18n.Msg.BundleBaseName, Locale, String, Object[]) as examples).

Version:

$Revision: 1.3 $

Author:

John Mazzitelli

See Also:

LocalizedException, LocalizedRuntimeException, Serialized Form

Nested Class Summary

static class

Msg.BundleBaseName The purpose of this class is to offer a strongly typed object (more strongly than String) so we can pass bundle base names to our vararg methods and not have this be confused with a key or arg parameter.

Constructor Summary

Msg()
Initializes the message repository using the default, localized resource bundle.

Msg(java.util.Locale locale)
Initializes the message repository using the default resource bundle and given locale.

Msg(Msg.BundleBaseName basename)
Initializes the message repository using the default locale and given resource bundle base name.

Msg(Msg.BundleBaseName basename, java.util.Locale locale)
Initializes the message repository with the appropriate resource bundle.

Method Summary

static Msg	createMsg(java.util.Locale locale, java.lang.String key, java.lang.Object... varargs) Creates a message object and automatically looks up the given resource bundle message.
static Msg	createMsg(Msg.BundleBaseName basename, java.util.Locale locale, java.lang.String key, java.lang.Object... varargs) Creates a message object and automatically looks up the given resource bundle message.
static Msg	createMsg(Msg.BundleBaseName basename, java.lang.String key, java.lang.Object... varargs) Creates a message object and automatically looks up the given resource bundle message.
static Msg	createMsg(java.lang.String key, java.lang.Object... varargs) Creates a message object and automatically looks up the given resource bundle message.
protected static java.lang.Object	deserialize(byte[] serializedData) Deserializes the given serialization data and returns the object.
Msg.BundleBaseName	getBundleBaseName() Returns the base name of the resource bundles to be used when looking for messages.
static Msg.BundleBaseName	getBundleBaseNameDefault() Returns the default bundle base name that all instances of this class will use when no basename is provided.
java.lang.String	getLastMessage() Returns the last message that this instance read from a resource bundle.
java.util.Locale	getLocale() Sets a new locale.
java.lang.String	getMsg(java.lang.String key, java.lang.Object... varargs) Returns the message string identified with the given key.
protected java.util.ResourceBundle	getResourceBundle() Gets the resource bundle to use, based on the current values of the base name and the locale.
protected static byte[]	serialize(java.io.Serializable object) Given a serializable object, this will return the object's serialized byte array representation.
static void	setBundleBaseNameDefault(Msg.BundleBaseName newDefault) Sets the default bundle base name that all instances of this class will use when no basename is provided.
void	setLocale(java.util.Locale locale) Sets a new locale.
java.lang.String	toString() Same as getLastMessage().

Methods inherited from class java.lang.Object

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

Constructor Detail

Msg

public Msg(Msg.BundleBaseName basename,
           java.util.Locale locale)

Initializes the message repository with the appropriate resource bundle.

Parameters:

basename - resource bundle to use, if null uses the default

locale - locale used to determine proper resource bundle to use, if null uses the default locale of the JVM

Msg

public Msg(java.util.Locale locale)

Initializes the message repository using the default resource bundle and given locale.

Parameters:

locale - locale used to determine proper resource bundle to use

See Also:

Msg(mazz.i18n.Msg.BundleBaseName, Locale)

Msg

public Msg(Msg.BundleBaseName basename)

Initializes the message repository using the default locale and given resource bundle base name.

Parameters:

basename - resource bundle to use

See Also:

Msg(mazz.i18n.Msg.BundleBaseName, Locale)

Msg

public Msg()

Initializes the message repository using the default, localized resource bundle.

Method Detail

createMsg

public static Msg createMsg(Msg.BundleBaseName basename,
                            java.util.Locale locale,
                            java.lang.String key,
                            java.lang.Object... varargs)

Creates a message object and automatically looks up the given resource bundle message. The caller need only call toString() to get the resource bundle message after this method returns.

Parameters:

basename - the base name of the resource bundle

locale - the locale to determine what bundle to use

key - the resource bundle key name

varargs - arguments to help fill in the resource bundle message

Returns:

if the message was logged, a non-null Msg object is returned

createMsg

public static Msg createMsg(java.util.Locale locale,
                            java.lang.String key,
                            java.lang.Object... varargs)

Creates a message object and automatically looks up the given resource bundle message. The caller need only call toString() to get the resource bundle message after this method returns. A default basename is used along with the given locale.

Parameters:

locale - the locale to determine what bundle to use

key - the resource bundle key name

varargs - arguments to help fill in the resource bundle message

Returns:

if the message was logged, a non-null Msg object is returned

createMsg

public static Msg createMsg(Msg.BundleBaseName basename,
                            java.lang.String key,
                            java.lang.Object... varargs)

Creates a message object and automatically looks up the given resource bundle message. The caller need only call toString() to get the resource bundle message after this method returns.

Parameters:

basename - the base name of the resource bundle

key - the resource bundle key name

varargs - arguments to help fill in the resource bundle message

Returns:

if the message was logged, a non-null Msg object is returned

createMsg

public static Msg createMsg(java.lang.String key,
                            java.lang.Object... varargs)

Creates a message object and automatically looks up the given resource bundle message. The caller need only call toString() to get the resource bundle message after this method returns. A default basename and the default locale is used to determine what resource bundle to use.

Parameters:

key - the resource bundle key name

varargs - arguments to help fill in the resource bundle message

Returns:

if the message was logged, a non-null Msg object is returned

getBundleBaseNameDefault

public static Msg.BundleBaseName getBundleBaseNameDefault()

Returns the default bundle base name that all instances of this class will use when no basename is provided.

Returns:

the bundle base name default (e.g. "com.abc.messages")

setBundleBaseNameDefault

public static void setBundleBaseNameDefault(Msg.BundleBaseName newDefault)

Sets the default bundle base name that all instances of this class will use when no basename is provided.

Parameters:

newDefault - the new bundle base name default (e.g. "com.abc.messages")

getLocale

public java.util.Locale getLocale()

Sets a new locale. This allows this class to change the message it returns after this instance has already been constructed.

Returns:

the current locale used by this class to determine which bundle to find the message in

setLocale

public void setLocale(java.util.Locale locale)

Sets a new locale. This allows this class to change the message it returns after this instance has already been constructed. The side effect of calling this method is that the next time getLastMessage() is called, it may return a different string if the locale was set to a different locale than what it was before.

Parameters:

locale - the new locale to set, if null, the default locale will be set

getBundleBaseName

public Msg.BundleBaseName getBundleBaseName()

Returns the base name of the resource bundles to be used when looking for messages.

Returns:

the resource bundles' base name

getLastMessage

public java.lang.String getLastMessage()

Returns the last message that this instance read from a resource bundle.

This object can change the messages it finds by simply setting the locale. When you change the local, the message is retrieved again when this method is called and is stored as the last message.

Returns:

the last retrieved resource bundle message

getMsg

public java.lang.String getMsg(java.lang.String key,
                               java.lang.Object... varargs)

Returns the message string identified with the given key. The additional arguments replace any placeholders found in the message. This sets the getLastMessage() when it returns.

Parameters:

key - identifies the message to be retrieved

varargs - arguments to replace placeholders in message

Returns:

localized and formatted message

See Also:

MessageFormat

toString

public java.lang.String toString()

Same as getLastMessage().

Overrides:

toString in class java.lang.Object

See Also:

Object.toString()

getResourceBundle

protected java.util.ResourceBundle getResourceBundle()

Gets the resource bundle to use, based on the current values of the base name and the locale.

Returns:

the resource bundle to be used by this object when looking up messages

serialize

protected static byte[] serialize(java.io.Serializable object)
                           throws java.lang.Exception

Given a serializable object, this will return the object's serialized byte array representation.

Parameters:

object - the object to serialize

Returns:

the serialized bytes

Throws:

java.lang.Exception - if failed to serialize the object

deserialize

protected static java.lang.Object deserialize(byte[] serializedData)
                                       throws java.lang.Exception

Deserializes the given serialization data and returns the object.

Parameters:

serializedData - the serialized data as a byte array

Returns:

the deserialized object

Throws:

java.lang.Exception - if failed to deserialize the object