public class KeyedMessage extends Object implements Serializable
With a KeyedMessage a named constant message (format) can be statically defined which automatically translate themselves for a specific locale using an automatically derived ResourceBundle or even a specified one.
Because KeyedMessages are created with a default message (format), even if no ResourceBundle or its key is defined or can't be found, message translation is still possible.
A KeyedMessage automatically derives the ResourceBundle lookup key from its (statically defined) instance field name
using the following format:
<containingClass.name>.<staticInstanceField.name>
The containingClass is derived at construction time by analyzing the StackTraceElements of a thrown exception. This requires the instance to be defined as a public static field!
At first access, the key is resolved by inspecting the derived containingClass for the declared field defining this instance.
If the KeyedMessage instance wasn't defined as public static field, the key can't be resolved and
message translation using a ResourceBundle won't be possible. Translation using the default message will still work
though. Furthermore, this instance can't be used as comparable named constant as the equals(Object)method
will always return false in this case.
When the key of a KeyedMessage is resolved, the default ResourceBundle name for message translation is retrieved from
the defined public static String field named "KEYED_MESSAGE_BUNDLE"defined
in its containingClass or one of its superClasses or interfaces.
If this field cannot be found, the fully qualified name of the containingClass is used.
ResourceBundle names are cached in a Map for each containingClass and only derived for the first KeyedMessage defined in a containingClass.
Again: only resolved instances can use a ResourceBundle for message translation.
When a message is translated without a specified Locale, CurrentLocale.get()is used to determine the default
Locale for the current Thread.
In Jetspeed, the LocalizationValve initializes the CurrentLocale on each request.
KeyedMessages accessed within the context of an Jetspeed request therefore will always be translated using the
current user Locale with the getMessage()or toString()methods.
If a message translation is done using the default ResourceBundle name the ResourceBundle is retrieved using the ClassLoader of the containingClass. This means the bundle(s) must be provided in the same context as from where the containingClass is loaded. Usually (and preferably), this will be from the shared classpath of the webserver.
MessageFormat patterns can also be used for a KeyedMessage.
With the create(Object[])method a specialized copy of a KeyedMessage instance can be created containing the
arguments to be used during message translation.
This new copy remains equals(Object)to its source and can still be used for named constant comparison.
For simplified usage, three create(Object),create(Object, Object)and
create(Object, Object, Object)methods are provided which delegate to create(Object[])with their
argument(s) transformed into an Object array.
An statically defined KeyedMessage can be used as a "simple" named constant.
If additional metadata is required
like some kind of status, level or type indication, the KeyedMessage class can easily be extended by providing a
specialized version of the create(KeyedMessage, Object[])copy factory.
KeyedMessage has been used to replace the hardcoded SecurityException String constants.
The
ResourceBundle name used is defined by JetspeedException.KEYED_MESSAGE_BUNDLE which is the superClass of
SecurityException.
For a different ResourceBundle to be used for SecurityException messages a KEYED_MESSAGE_BUNDLE field can be defined
in SecurityException too, overriding the one in JetspeedException.
Example:
public class JetspeedException extends Exception {
public static final String KEYED_MESSAGE_BUNDLE = "org.apache.jetspeed.exception.JetspeedExceptionMessages";
...
public String getMessage() {
if ( keyedMessage != null ) {
return keyedMessage.getMessage(); // translated using current Locale and default ResourceBundle
}
return super.getMessage();
}
}
public class SecurityException extends JetspeedException {
public static final KeyedMessage USER_DOES_NOT_EXIST = new KeyedMessage("The user {0} does not exist.");
...
}
// resource file: org.apache.jetspeed.exception.JetspeedExceptionMessages_nl.properties
org.apache.jetspeed.security.SecurityException.USER_DOES_NOT_EXIST = De gebruiker {0} bestaat niet.
...
public class UserManagerImpl implements UserManager {
public User getUser(String username) throws SecurityException {
...
if (null == userPrincipal) {
throw new SecurityException(SecurityException.USER_DOES_NOT_EXIST.create(username));
}
...
}
...
}
// example get User
try {
User user = userManager.getUser(userName);
} catch (SecurityException sex) {
if ( SecurityException.USER_DOES_NOT_EXISTS.equals(sex.getKeyedMessage()) {
// handle USER_DOES_NOT_EXISTS error
}
}
| Modifier and Type | Field and Description |
|---|---|
static String |
KEYED_MESSAGE_BUNDLE_FIELD_NAME
Static String Field name searched for in the class defining a KeyedMessage containing the default resource bundle
to use for translation.
|
| Modifier | Constructor and Description |
|---|---|
protected |
KeyedMessage(KeyedMessage source,
String scope,
Object[] arguments)
Constructs a derived KeyedMessage from another KeyedMessage to provide additional message format arguments.
|
|
KeyedMessage(String message)
Constructs a new KeyedMessage which will dynamically derive its own
getKey(). |
| Modifier and Type | Method and Description |
|---|---|
protected KeyedMessage |
create(KeyedMessage source,
Object[] arguments)
Extendable KeyedMessage factory
|
KeyedMessage |
create(Object o)
Simplified version of
create(Object[])with only one message argument |
KeyedMessage |
create(Object[] arguments)
Creates a derived KeyedMessage from this instance to provide additional message format arguments.
|
KeyedMessage |
create(Object o1,
Object o2)
Simplified version of
create(Object[])with only two arguments |
KeyedMessage |
create(Object o1,
Object o2,
Object o3)
Simplified version of
create(Object[])with only three arguments |
protected KeyedMessage |
createScoped(KeyedMessage source,
String scope,
Object[] arguments)
Extendable scoped KeyedMessage factory
|
KeyedMessage |
createScoped(String scope)
Simplified version of
createScoped(String, Object[]) without message arguments |
KeyedMessage |
createScoped(String scope,
Object o)
Simplified version of
createScoped(String, Object[])with only one message argument |
KeyedMessage |
createScoped(String scope,
Object[] arguments)
Creates a derived scoped KeyedMessage from this instance to provide additional message format arguments.
|
KeyedMessage |
createScoped(String scope,
Object o1,
Object o2)
Simplified version of
createScoped(String, Object[])with only two arguments |
KeyedMessage |
createScoped(String scope,
Object o1,
Object o2,
Object o3)
Simplified version of
createScoped(String, Object[])with only three arguments |
boolean |
equals(Object otherObject) |
Object |
getArgument(int index) |
Object[] |
getArguments() |
ResourceBundle |
getBundle()
Loads and returns the default ResourceBundle for this instance using the
current Locale. |
ResourceBundle |
getBundle(Locale locale)
Loads and returns a Locale specific default ResourceBundle for this instance.
|
String |
getKey()
Dynamically derived key based on the definingClass name, postfixed with the static field name of this instance.
|
String |
getMessage() |
String |
getMessage(Locale locale) |
String |
getMessage(ResourceBundle bundle) |
String |
toString() |
public static final String KEYED_MESSAGE_BUNDLE_FIELD_NAME
protected KeyedMessage(KeyedMessage source, String scope, Object[] arguments)
source - the KeyedMessage to derive this instance fromarguments - this instance specific message format argumentscreate(Object[])protected KeyedMessage create(KeyedMessage source, Object[] arguments)
source - the source to copy fromarguments - the optional message format argumentsprotected KeyedMessage createScoped(KeyedMessage source, String scope, Object[] arguments)
source - the source to copy fromscope - the optional scope key infix between the containing class name and the field namearguments - the optional message format argumentspublic KeyedMessage create(Object[] arguments)
equals(Object)to this instance with only different arguments. arguments - The derived instance specific message format argumentsequalto this with its own message format argumentspublic KeyedMessage createScoped(String scope, Object[] arguments)
equals(Object)to this instance with only different arguments. scope - the optional scope key infix between the containing class name and the field namearguments - The derived instance specific message format argumentsequalto this with its own message format argumentspublic KeyedMessage create(Object o)
create(Object[])with only one message argumentsingle - message format argumentequalto this with its own message format argumentcreate(Object[])public KeyedMessage createScoped(String scope)
createScoped(String, Object[]) without message argumentsscope - the optional scope key infix between the containing class name and the field nameequalto this with its own message format argumentcreateScoped(String,Object[])public KeyedMessage createScoped(String scope, Object o)
createScoped(String, Object[])with only one message argumentscope - the optional scope key infix between the containing class name and the field namesingle - message format argumentequalto this with its own message format argumentcreateScoped(String,Object[])public KeyedMessage create(Object o1, Object o2)
create(Object[])with only two argumentssingle - message format argumentequalto this with its own message format argumentscreate(Object[])public KeyedMessage createScoped(String scope, Object o1, Object o2)
createScoped(String, Object[])with only two argumentsscope - the optional scope key infix between the containing class name and the field namesingle - message format argumentequalto this with its own message format argumentscreateScoped(String,Object[])public KeyedMessage create(Object o1, Object o2, Object o3)
create(Object[])with only three argumentssingle - message format argumentequalto this with its own message format argumentscreate(Object[])public KeyedMessage createScoped(String scope, Object o1, Object o2, Object o3)
createScoped(String, Object[])with only three argumentsscope - the optional scope key infix between the containing class name and the field namesingle - message format argumentequalto this with its own message format argumentscreateScoped(String,Object[])public final String getKey()
<containingClass.name>.<staticInstanceField.name>
public ResourceBundle getBundle(Locale locale)
resolvedor the bundle couldn't be loadednull will be returned. containingClassits ClassLoader.locale - the Locale to lookup the locale specific default ResourceBundlepublic ResourceBundle getBundle()
current Locale.getBundle(Locale),
CurrentLocalepublic String getMessage()
current Locale.getBundle()public String getMessage(ResourceBundle bundle)
bundle - a specific ResourceBundle defining this instance keypublic String getMessage(Locale locale)
locale - a specific Localepublic Object[] getArguments()
derivedinstancecreate(Object[])public Object getArgument(int index)
index - argument numberderivedinstancepublic String toString()
toString in class Objectcurrent Locale.getMessage()public boolean equals(Object otherObject)
Copyright © 1999–2016 The Apache Software Foundation. All rights reserved.