com.lf.commons.msg

Class MessageCodes

java.lang.Object

com.lf.commons.msg.MessageCodes

public class MessageCodes
extends java.lang.Object

Provides support for message codes and strings in certain natural language.

Message codes and associated strings in certain natural languages are used by the Leisenfels applications to give the user some status. This class is a fast cache for the classes to get the desired messages. Currently message codes in the range between 0..9999 can be defined and the identifiers have the form XXXX-nnnn where nnnn is the numeric code identifier unique for the application. The message LIMA-0000 for instance has the text "Unknown message identifier" for English language. Obviously the messages are binded to a certain natural language and must be translated. This cache supports multiple languages natively and it's only necessary to put some files into the expected directories to set new languages. For example if you like French to be supported by your application you must create the directory my/company/app/db/resource/fre and put the code files 0000.conf, 0100.conf, ... into this new directory. If the file format is OK (UTF-8 encoding, proper codes and line format) the MessageCodes class will detect the new messages if French is requested. The language files apply to the following format:

 ... LIMA-0000=Unknown message identifier

 LIMA-0001=Unknown argument %value%
LIMA-0002=Illegal log level %value%
LIMA-0003=Invalid
 configuration file %file%
... 

The variable name is always the application message code like LIMA-0000 which means "Unknown message identifier" (English). As you can see some of the message texts have extra parts like %value% which can be seen as variables to be replaced by the calling Java methods. For consistency reasons these variables should always be replaced by the corresponding values normally by using regular expressions.

The language files are organized as pages with 100 messages each. This allows for a fast caching algorithm since most of the messages are never used during a normal application execution. The pages are only loaded internally when needed so the memory footprint is small. As it turns out to become a bottleneck for applications this cache class can be easily extended to implement FIFO/LIFO/... paging strategies. At the moment the loaded pages are kept in memory for the lifetime of the JVM to keep it simple. The page files are named 0000.conf, 0100.conf, ... to allow the cache to find the messages automatically. If a requested message cannot be found for a specific language then the English defaults should be used as fallback solution.

Since:

1.5

Version:

$Revision: 1.15 $, $Date: 2016/01/01 15:43:03 $

Author:

Axel Schwolow

See Also:

MessageFactory

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	base The classpath with language specific sub-directories with page files.
protected java.util.Hashtable<Locale,MessageCache>	cacheMessagesByLocale Container for fast acquisition of language dependent messages.
protected java.io.File	directory The directory with language specific sub-directories with page files.
protected java.lang.String	id The desired domain identifier like "LIMA".
protected java.lang.Object	loader The instance to use as class loader for the resources.

Constructor Summary

Constructors

Constructor and Description
MessageCodes() Constructor method for i18n purposes only.
MessageCodes(java.lang.String id, java.io.File directory) Constructor method for direct access on the file system level (no classpath).
MessageCodes(java.lang.String id, java.lang.String base, java.lang.Object loader) Constructor method.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	finalize() Cares for proper cleanup when is not needed any longer (helps gc).
java.lang.String	getMessage(java.lang.String code, Locale locale, boolean prefix) Returns the message text associated with a certain message code and language.
java.lang.String	getMessageReplace(java.lang.String code, Locale locale, boolean prefix, java.lang.String[] regex, java.lang.String[] replacement) Returns the message text associated with a certain message code and language.
java.lang.String	getMessageReplace(java.lang.String code, Locale locale, boolean prefix, java.lang.String regex, java.lang.String replacement) Returns the message text associated with a certain message code and language.
boolean	isArmed(Locale locale) Have the underlying message codes been successfully loaded?
java.util.Vector<java.lang.String>	listCodes(Locale locale) Provides the list of available message codes "0001", "0002", ...

Methods inherited from class java.lang.Object

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

Field Detail

cacheMessagesByLocale

protected java.util.Hashtable<Locale,MessageCache> cacheMessagesByLocale

Container for fast acquisition of language dependent messages.

id

protected java.lang.String id

The desired domain identifier like "LIMA".

base

protected java.lang.String base

The classpath with language specific sub-directories with page files.

loader

protected java.lang.Object loader

The instance to use as class loader for the resources.

directory

protected java.io.File directory

The directory with language specific sub-directories with page files.

Constructor Detail

MessageCodes

public MessageCodes()
             throws java.lang.InstantiationException

Constructor method for i18n purposes only.

Can only be used if beans design time is set (e.g. by external tools like the I18NExtractor).

Throws:

java.lang.InstantiationException - Error indication

Since:

1.6

MessageCodes

public MessageCodes(java.lang.String id,
            java.lang.String base,
            java.lang.Object loader)

Constructor method.

Simply installs the initial cache, data loading is done if required.

Parameters:

id - The desired domain identifier like "LIMA"

base - The classpath with language specific sub-directories with page files

loader - The instance to use as class loader for the resources

Throws:

java.lang.NullPointerException - Error indication

Since:

1.5

MessageCodes

public MessageCodes(java.lang.String id,
            java.io.File directory)

Constructor method for direct access on the file system level (no classpath).

Simply installs the initial cache, data loading is done if required. All available message code files are loaded immediately.

Parameters:

id - The desired domain identifier like "LIMA"

directory - The directory with language specific sub-directories with page files

Throws:

java.lang.NullPointerException - Error indication

Since:

1.6

Method Detail

finalize

protected void finalize()
                 throws java.lang.Throwable

Cares for proper cleanup when is not needed any longer (helps gc).

The caches are cleared here to allow for a faster garbage collecting.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable - Error indication

Since:

1.5

getMessage

public java.lang.String getMessage(java.lang.String code,
                          Locale locale,
                          boolean prefix)

Returns the message text associated with a certain message code and language.

Throws NullPointerException if code or locale is null. If the message text cannot be found for the specified code and language then null is returned and it's up to the caller to react appropriately e.g. by acquiring the message text in a default language like English.

You can either pass code as numerical string like "0001" (four places), or as full code including the domain identifier prefix like "LIMA-0001" which is used for the configuration files as property name.

With the parameter prefix you can specify whether to have the domain identifier automatically prepended (like "LIMA-0000: Unknown message identifier", or to get the plain message text (like "Unknown message identifier").

Parameters:

code - The desired message code like "0001" (required)

locale - The locale representing the language (required)

prefix - Shall the domain identifier be automatically prepended to the message?

Returns:

The message text, null if code does not exist

Throws:

java.lang.IllegalArgumentException - If code=null

java.lang.NullPointerException - If locale=null

Since:

1.5

getMessageReplace

public java.lang.String getMessageReplace(java.lang.String code,
                                 Locale locale,
                                 boolean prefix,
                                 java.lang.String regex,
                                 java.lang.String replacement)

Returns the message text associated with a certain message code and language.

Throws NullPointerException if code or locale is null. If the message text cannot be found for the specified code and language then null is returned and it's up to the caller to react appropriately e.g. by acquiring the message text in a default language like English.

You can either pass code as numerical string like "0001" (four places), or as full code including the domain identifier prefix like "LIMA-0001" which is used for the configuration files as property name.

With the parameter prefix you can specify whether to have the domain identifier automatically prepended (like "LIMA-0000: Unknown message identifier", or to get the plain message text (like "Unknown message identifier").

This variant substitutes sub-strings according to a regular expression for convenience.

Parameters:

code - The desired message code like "0001" (required)

locale - The locale representing the language (required)

prefix - Shall the domain identifier be automatically prepended to the message?

regex - The regular expression to be replaced (all occurrences)

replacement - The replacement for the regular expression

Returns:

The message text, null if code does not exist

Throws:

java.lang.IllegalArgumentException - If code=null

java.lang.NullPointerException - If locale, regex, or replacement is null

java.util.regex.PatternSyntaxException - If regex is invalid

Since:

1.5

getMessageReplace

public java.lang.String getMessageReplace(java.lang.String code,
                                 Locale locale,
                                 boolean prefix,
                                 java.lang.String[] regex,
                                 java.lang.String[] replacement)

Returns the message text associated with a certain message code and language.

Throws NullPointerException if code or locale is null. If the message text cannot be found for the specified code and language then null is returned and it's up to the caller to react appropriately e.g. by acquiring the message text in a default language like English.

You can either pass code as numerical string like "0001" (four places), or as full code including the domain identifier prefix like "LIMA-0001" which is used for the configuration files as property name.

With the parameter prefix you can specify whether to have the domain identifier automatically prepended (like "LIMA-0000: Unknown message identifier", or to get the plain message text (like "Unknown message identifier").

This variant substitutes sub-strings according to a regular expression for convenience.

Parameters:

code - The desired message code like "0001" (required)

locale - The locale representing the language (required)

prefix - Shall the domain identifier be automatically prepended to the message?

regex - The regular expressions to be replaced (all occurrences)

replacement - The replacements for the regular expression

Returns:

The message text, null if code does not exist

Throws:

java.lang.IllegalArgumentException - If code=null

java.lang.NullPointerException - If locale, regex, or replacement is null

java.util.regex.PatternSyntaxException - If regex is invalid

Since:

1.5

isArmed

public boolean isArmed(Locale locale)

Have the underlying message codes been successfully loaded?

Parameters:

locale - The locale representing the language (required)

Returns:

Successful?

Since:

1.6

listCodes

public java.util.Vector<java.lang.String> listCodes(Locale locale)

Provides the list of available message codes "0001", "0002", ...

Parameters:

locale - The locale representing the language (required)

Returns:

The message codes, may be empty

Since:

1.6