net.sf.mmm.util.nls.api
Interface NlsMessage

All Superinterfaces:

NlsObject

All Known Implementing Classes:

AbstractNlsMessage, BasicNlsMessage, ComposedNlsMessage, NlsMessageImpl

public interface NlsMessage
extends NlsObject

This is the interface for an internationalized message. It stores an internationalized-message separated from language independent arguments. This approach ensures that the message is always available in the internationalized language (should be English) while it still allows to translate the message to a native language.
The format of the internationalized-message is compatible to MessageFormat. This allows to migrate existing code from MessageFormat to NlsMessage easily. However there are some advanced features available. While using numbers to identify the argument is a maintenance-hell for large messages, it is also possible to use named arguments. Further there is also support for additional styles as well as Justification. The format specification for parameter-syntax is as following:

'{' ArgumentKey [ ',' FormatType [ ',' FormatStyle ] ] [ '{' Justification '}' ] '}'

The literals are explained in this table.

literal	explanation
ArgumentKey	is the key of the parameter (may be numeric for legacy support)
FormatType	a type specifying how to format the value (see below). Should fit to the type of the value.
FormatStyle	a style according to FormatType (see below).
Justification	a justification

The following table shows the supported variants of FormatType and FormatStyle:

FormatType	FormatStyle	Example	Comment
-	-	value as string	default string representation of the value
number	-	123,456.78	Numeric representation
number	percent	12,345,678%	Number in percent
number	currency	123,456.78 �	Number as currency
number	'#'##.##	#123456.78	Any other style is treated as pattern for DecimalFormat
date	-	31-Dec-1999	Date default representation
date	short	31/12/99	Date short representation
date	medium	31-Dec-1999	Date medium representation
date	long	31 December 1999	Date long representation
date	full	Friday, 31 December 1999	Date full representation
date	iso8601	1999-12-31	Date ISO-8601 representation
date	yyyy.MM.dd	2010.01.01	Any other style is treated as pattern for SimpleDateFormat
time	-	23:59:59	Time default representation
time	short	23:59	Time short representation
time	medium	23:59:59	Time medium representation
time	long	23:59:59 GMT+01:00	Time long representation
time	full	23:59:59 o'clock GMT+01:00	Time full representation
time	iso8601	23:59:59+01:00	Time ISO-8601 representation
time	HH:mm:ss	23:59:59	Any other style is treated as pattern for SimpleDateFormat
datetime	-	31-Dec-1999 23:59:59	Date+time default representation
datetime	short	31/12/99 23:59	Date+time short representation
datetime	medium	31-Dec-1999 23:59:59	Date+time medium representation
datetime	long	31 December 1999 23:59:59 GMT+01:00	Date+time long representation
datetime	full	Friday, 31 December 1999 23:59:59 o'clock GMT+01:00	Date+time full representation
datetime	iso8601	1999-12-31T23:59:59+01:00	Date+time ISO-8601 representation
date	yyyy.MM.dd-HH:mm:ss	2010.01.01-23:59:59	Any other style is treated as pattern for SimpleDateFormat
type	-	java.util.List	Type medium representation (omit java.lang)
type	short	List	Type short representation
type	medium	java.util.List	Type medium representation (omit java.lang)
type	long	java.util.List<String>	Type long representation
type	full	java.util.List<java.lang.String>	Type full representation
choice	(?==1)'error'(else)'errors'	error	A choice to distinguish singular/plural forms.
choice	(?>=5){key,choice,(?==true)'a'(else){key2}}(else)'c'	a	A choice that results to 'c' if the value is NOT greater or equal to 5. Otherwise it results to 'a' if the value of the argument "key" is Boolean.TRUE. Otherwise it results to the value of the argument "key2". - This is a wired example. It shows the power of the choice format as well as how things turn out unmaintainable if the power is missused.

For the term internationalization usually the shortcut i18n is used.

Since:

1.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Field Summary

static String

LOCALIZATION_FAILURE_PREFIX The prefix appended to the message if the localization (translation) failed.

Fields inherited from interface net.sf.mmm.util.nls.api.NlsObject

KEY_ANNOTATION, KEY_ARGUMENT, KEY_CAPACITY, KEY_DEFAULT, KEY_DIRECTORY, KEY_ERROR, KEY_FILE, KEY_FUNCTION, KEY_ID, KEY_KEY, KEY_LOCATION, KEY_MAX, KEY_MIN, KEY_MODE, KEY_NAME, KEY_OBJECT, KEY_OPERAND, KEY_OPERATION, KEY_OPTION, KEY_PATH, KEY_PROPERTY, KEY_QUERY, KEY_RESOURCE, KEY_SIZE, KEY_SOURCE, KEY_TARGET_TYPE, KEY_TITLE, KEY_TYPE, KEY_URI, KEY_VALUE

Method Summary

Object	getArgument(int index) Deprecated. use getArgument(String) instead (and use named keys instead of numbers where possible).
Object	getArgument(String key) This method gets the language independent argument for the given key.
int	getArgumentCount() Deprecated. this method does NOT make sense anymore.
String	getInternationalizedMessage() This method gets the internationalized message that can be translated to a native language.
String	getLocalizedMessage() This method tries to get the localized message as string.
String	getLocalizedMessage(Locale locale) This method tries to get the localized message as string.
String	getLocalizedMessage(Locale locale, NlsTemplateResolver resolver) This method gets the localized message as string.
void	getLocalizedMessage(Locale locale, NlsTemplateResolver resolver, Appendable buffer) This method writes the localized message to the given buffer.
String	getMessage() This method gets the untranslated message (default language should be English) with arguments filled in.

Methods inherited from interface net.sf.mmm.util.nls.api.NlsObject

toNlsMessage

Field Detail

LOCALIZATION_FAILURE_PREFIX

static final String LOCALIZATION_FAILURE_PREFIX

The prefix appended to the message if the localization (translation) failed.

See Also:

Constant Field Values

Method Detail

getInternationalizedMessage

String getInternationalizedMessage()

This method gets the internationalized message that can be translated to a native language. The language independent arguments are filled into the message after the translation process.
E.g. the i18n message may be "Welcome {name}!" and there is one argument that is the string "Joelle". The final result will then be "Welcome Joelle!". If the message is translated to German as "Willkommen {name}!" the final result will be "Willkommen Joelle!".

Returns:

the message for internationalization.

See Also:

getArgument(String), MessageFormat

getArgumentCount

@Deprecated
int getArgumentCount()

Deprecated. this method does NOT make sense anymore.

This method gets the number of language independent arguments of this exception.

Returns:

the argument count.

getArgument

Object getArgument(String key)

This method gets the language independent argument for the given key.

Parameters:

key - is the name of the requested argument.

Returns:

the argument for the given key.

getArgument

@Deprecated
Object getArgument(int index)

Deprecated. use getArgument(String) instead (and use named keys instead of numbers where possible).

This method gets the language independent argument at the given index.

Parameters:

index - is the index of the requested argument.

Returns:

the argument for the given key.

getMessage

String getMessage()

This method gets the untranslated message (default language should be English) with arguments filled in.

Returns:

the i18n message with arguments filled in.

See Also:

getLocalizedMessage(Locale, NlsTemplateResolver)

getLocalizedMessage

String getLocalizedMessage()

This method tries to get the localized message as string. Since no translator is specified, the implementation may try its best to do the translation on its own according to the callers locale. Therefore this method has to do some magic behind the scenes. This may only work if you follow specific rules of the implementation of this interface. If this fails or is NOT supported, the untranslated message should be used.
ATTENTION:
If possible try to avoid using this method and use getLocalizedMessage(Locale, NlsTemplateResolver) instead.

Returns:

the localized message.

getLocalizedMessage

String getLocalizedMessage(Locale locale)

This method tries to get the localized message as string. Since no translator is specified, the implementation may try its best to do the translation on its own according to the callers locale. Therefore this method has to do some magic behind the scenes. This may only work if you follow specific rules of the implementation of this interface. If this fails or is NOT supported, the untranslated message should be used.
ATTENTION:
If possible try to avoid using this method and use getLocalizedMessage(Locale, NlsTemplateResolver) instead.

Parameters:

locale - is the locale to translate to.

Returns:

the localized message.

getLocalizedMessage

String getLocalizedMessage(Locale locale,
                           NlsTemplateResolver resolver)

This method gets the localized message as string.

Parameters:

locale - is the locale to translate to.

resolver - is used to translate the message.

Returns:

the localized message.

See Also:

getLocalizedMessage(Locale, NlsTemplateResolver, Appendable)

getLocalizedMessage

void getLocalizedMessage(Locale locale,
                         NlsTemplateResolver resolver,
                         Appendable buffer)
                         throws RuntimeIoException

This method writes the localized message to the given buffer.
The actual localization is done by a template that is provided via the given resolver. If this fails, the original message will be used. After translation is done, the language independent arguments will be filled in the translated message string according to the given locale.

Parameters:

locale - is the locale to translate to.

resolver - is used to resolve the template required to translate the internationalized message.

buffer - is the buffer where to write the message to.

Throws:

RuntimeIoException - if the given buffer produced an IOException.