sji18n
Class I18n

java.lang.Object
  sji18n.I18n

public final class I18n
extends Object

I18n instances provide easy access to locale-specific objects and the class's static methods allow an application to manage its locale configuration.
Support is provided to set a different locale for logging messages and application objects. To use this feature, use the getLogString or getLogMessage methods when generating log messages.

I18nListeners can be registered to listen for locale change events. This allows applications to implement dynamic locale switching.

In a more advanced (and perhaps more exotic) application, multiple locales can be set in separate parts of an application runtime by introducing named contexts.
Every context can have its own locale. The default context is the nameless context, i.e. its name is null. A second predefined context is the default logging context already mentioned above. The name of this context is "logging".
If required, applications can introduce and manage more contexts.
Libraries that support multiple context management must have some classes (where applicable) having a method to set an instance's context. These classes could implement I18nable to provide a uniform interface for setting an instance's context and/or logging context, but this is not a hard requirement.

Implementation notes:
This class uses a L10nResourceFactory implementation to find and load actual localization resources. The actual L10nResourceFactory implementation used is set at this class's initialization. System property sji18n.L10nResourceFactory, if set, must contain the fully qualified class name of the implementation to load. Failing to load the class specified in this system property will cause this class's initialization to fail.
If system property sji18n.L10nResourceFactory is not set, I18n will look for a L10nResourceFactory service provider (see ServiceLoader for more info on configuring a service provider).

Setting system property sji18n.resource.name.map (since version 1.1) allows to refer to a file in which resource names are mapped to other resource names. This allows to change the actual (and often hard-coded) resource names used to construct I18n instances at deploy time. It is even possible to map some or all resource names to the same name.
The contents of this resource name map file must be formatted as follows:

• one mapping rule per line
• a mapping rule is formatted <original resource name>=<new resource name>
• or <original resource name prefix>*=<new resource name>

Specifying a rule '*=common', for example, will map all resource names (except the ones that match preceding rules) to the name 'common'.

The value in system property sji18n.resource.name.map must start with a forward slash to refer to a file relative to the working directory or to refer to a resource in the classpath. If the value does not start with a forward slash character, it must be a valid URL.

Requires at least java 1.6, no other external libraries are required.

Field Summary

static String

LOGGING_CONTEXT Context name of the default logging context.

Constructor Summary

I18n(String resourceName)
Creates a new instance obtaining its objects from a resource identified by the specified name.

Method Summary

static void	addI18nListener(I18nListener listener) Registers a I18nListener.
Image	getImage(String key) Fetches an application object for the locale currently set for the default, nameless context and casts it to an Image.
Image	getImage(String context, String key) Fetches an application object for the locale currently set for the specified context and casts it to an Image.
static Locale	getLocale() Returns the locale currently set for application objects in the default, nameless context.
static Locale	getLocale(String context) Returns the locale currently set for application objects in the specified context.
static Locale	getLogLocale() Returns the locale currently set for logging messages.
String	getLogMessage(String messageID, Object... args) Fetches a logging message string for the locale currently set for the default logging context and formats a message using the specified object arguments.
String	getLogString(String key) Fetches a logging message string for the locale currently set for the default logging context.
static String	getMappedResourceName(String resourceName) Returns the name the specified resource name is mapped to.
String	getMessage(String messageID, Object... args) Fetches an application string for the locale currently set for the default, nameless context and formats a message using the specified object arguments.
String	getMessage(String context, String messageID, Object... args) Fetches an application string for the locale currently set for the specified context and formats a message using the specified object arguments.
Object	getObject(String key) Fetches an application object for the locale currently set for the default, nameless context.
Object	getObject(String context, String key) Fetches an application object for the locale currently set for the specified context.
String	getString(String key) Fetches an application string for the locale currently set for the default, nameless context.
String	getString(String context, String key) Fetches an application string for the locale currently set for the specified context.
static void	removeI18nListener(I18nListener listener) Removed a I18nListener from the list of registered listeners.
static void	setAllLocales(Locale locale) Sets the locale in all contexts (including the default, nameless context and the logging context).
static void	setLocale(Locale locale) Sets the locale for application objects in the default, nameless context.
static void	setLocale(String context, Locale locale) Sets the locale for application objects in the specified context.
static void	setLogLocale(Locale locale) Sets the locale for logging messages.

Methods inherited from class java.lang.Object

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

Field Detail

LOGGING_CONTEXT

public static final String LOGGING_CONTEXT

Context name of the default logging context. Calling getLocale(LOGGING_CONTEXT), setLocale(LOGGING_CONTEXT, locale) or getString(LOGGING_CONTEXT, key) all yield the same result or effect as calling getLogLocale(), setLogLocale(locale) or getLogString(key). The latter calls should return a little bit faster, however.

See Also:

Constant Field Values

Constructor Detail

I18n

public I18n(String resourceName)

Creates a new instance obtaining its objects from a resource identified by the specified name.

Parameters:

resourceName - the name of the resource, should not be null.

Method Detail

getLocale

public static Locale getLocale()

Returns the locale currently set for application objects in the default, nameless context.

Returns:

a valid Locale instance, never null.

getLogLocale

public static Locale getLogLocale()

Returns the locale currently set for logging messages.

Returns:

a valid Locale instance, never null.

getLocale

public static Locale getLocale(String context)

Returns the locale currently set for application objects in the specified context.

Parameters:

context - name of the context to check the locale for, may be null to indicate the default, nameless context.

Returns:

a valid Locale instance, never null.

setLocale

public static void setLocale(Locale locale)

Sets the locale for application objects in the default, nameless context.

Parameters:

locale - the locale to set, may be null to indicate Locale.getDefault().

setLogLocale

public static void setLogLocale(Locale locale)

Sets the locale for logging messages.

Parameters:

locale - the locale to set, may be null to indicate Locale.getDefault().

setLocale

public static void setLocale(String context,
                             Locale locale)

Sets the locale for application objects in the specified context.

Parameters:

context - name of the context to set the locale for, null to indicate the default, nameless context.

locale - the locale to set, may be null to indicate Locale.getDefault().

setAllLocales

public static void setAllLocales(Locale locale)

Sets the locale in all contexts (including the default, nameless context and the logging context).

Parameters:

locale - the locale to set, may be null to indicate Locale.getDefault().

addI18nListener

public static void addI18nListener(I18nListener listener)

Registers a I18nListener. Registered listeners receive events when the locale was changed in a particular context.
Do not forget to remove a registered listener once it is no longer used by the application. This class keeps a hard reference to all registered listeners and thus prevents any listener still registered from being garbage collected.

Parameters:

listener - the listener to register, may be null if none, in which case this method does nothing.

removeI18nListener

public static void removeI18nListener(I18nListener listener)

Removed a I18nListener from the list of registered listeners.

Parameters:

listener - the listener to remove, may be null if none, in which case this method does nothing.

getMappedResourceName

public static String getMappedResourceName(String resourceName)

Returns the name the specified resource name is mapped to.

Parameters:

resourceName - the resource name to lookup the mapped name for.

Returns:

the new name mapped to the specified resource name, if none the specified resource name is returned.

getString

public String getString(String key)

Fetches an application string for the locale currently set for the default, nameless context. Calling getString(null, key) would yield the same result but is less optimal as it requires to look up the locale for the specified context. This method's implementation uses a direct reference to the default context's locale to have a slightly improved performance.

Parameters:

key - the key identifying the string to fetch, must not be null.

Returns:

a valid string, never null.

Throws:

MissingResourceException - when the specified key is not found.

getMessage

public String getMessage(String messageID,
                         Object... args)

Fetches an application string for the locale currently set for the default, nameless context and formats a message using the specified object arguments.

Parameters:

messageID - the key identifying the message string to fetch, must not be null.

args - the objects to include in the formatted message.

Returns:

a valid string, never null.

Throws:

MissingResourceException - when the specified key is not found.

getObject

public Object getObject(String key)

Fetches an application object for the locale currently set for the default, nameless context. Calling getObject(null, key) would yield the same result but is less optimal as it requires to look up the locale for the specified context. This method's implementation uses a direct reference to the default context's locale to have a slightly improved performance.

Parameters:

key - the key identifying the object to fetch, must not be null.

Returns:

the object requested, may be null if none.

getImage

public Image getImage(String key)

Fetches an application object for the locale currently set for the default, nameless context and casts it to an Image. Calling getImage(null, key) would yield the same result but is less optimal as it requires to look up the locale for the specified context. This method's implementation uses a direct reference to the default context's locale to have a slightly improved performance.

Parameters:

key - the key identifying the image to fetch, must not be null.

Returns:

the image requested, may be null if none.

Throws:

ClassCastException - when the found object cannot be cast to an Image.

getString

public String getString(String context,
                        String key)

Fetches an application string for the locale currently set for the specified context.

Parameters:

context - the context in which the string is required, may be null to indicate the default, nameless context.

key - the key identifying the string to fetch, must not be null.

Returns:

a valid string, never null.

Throws:

MissingResourceException - when the specified key is not found.

getMessage

public String getMessage(String context,
                         String messageID,
                         Object... args)

Fetches an application string for the locale currently set for the specified context and formats a message using the specified object arguments.

Parameters:

context - the context in which the string is required, may be null to indicate the default, nameless context.

messageID - the key identifying the message string to fetch, must not be null.

args - the objects to include in the formatted message.

Returns:

a valid string, never null.

Throws:

MissingResourceException - when the specified key is not found.

getObject

public Object getObject(String context,
                        String key)

Fetches an application object for the locale currently set for the specified context.

Parameters:

context - the context in which the object is required, may be null to indicate the default, nameless context.

key - the key identifying the object to fetch, must not be null.

Returns:

the object requested, may be null if none.

getImage

public Image getImage(String context,
                      String key)

Fetches an application object for the locale currently set for the specified context and casts it to an Image.

Parameters:

context - the context in which the image is required, may be null to indicate the default, nameless context.

key - the key identifying the image to fetch, must not be null.

Returns:

the image requested, may be null if none.

Throws:

ClassCastException - when the found object cannot be cast to an Image.

getLogString

public String getLogString(String key)

Fetches a logging message string for the locale currently set for the default logging context. Calling getString(LOGGING_CONTEXT, key) would yield the same result but is less optimal as it requires to look up the locale for the specified context. This method's implementation uses a direct reference to the default logging context's locale to have a slightly improved performance.

Parameters:

key - the key identifying the string to fetch, must not be null.

Returns:

a valid string, never null.

Throws:

MissingResourceException - when the specified key is not found.

getLogMessage

public String getLogMessage(String messageID,
                            Object... args)

Fetches a logging message string for the locale currently set for the default logging context and formats a message using the specified object arguments.

Parameters:

messageID - the key identifying the message string to fetch, must not be null.

args - the objects to include in the formatted message.

Returns:

a valid string, never null.

Throws:

MissingResourceException - when the specified key is not found.