net.sf.mmm.util.nls.api

Interface NlsMessage

All Superinterfaces:

NlsObject, Serializable

All Known Implementing Classes:

AbstractNlsMessage, BasicNlsMessage, ComposedNlsMessage, GenericSerializableException, NlsMessageImpl, NlsMessagePlain

public interface NlsMessage
extends NlsObject, Serializable

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. For an introduction first read here
The format of the internationalized-message is (almost) 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. See NlsArgument for the specification of the argument syntax.
To specify NlsMessages you create an NlsBundle per module. For the term internationalization usually the shortcut i18n is used.

Since:

1.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

NlsArgument, NlsBundle, NlsMessageFactory, net.sf.mmm.util.nls.api

Field Summary

Fields

Modifier and Type	Field and Description
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_CONTAINER, KEY_DEFAULT, KEY_DIRECTORY, KEY_ERROR, KEY_EXISTING, KEY_EXPECTED, 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_USER, KEY_VALUE

Method Summary

Modifier and Type	Method and Description
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 value for the given key.
int	getArgumentCount() Deprecated. this method does NOT make sense anymore.
String	getInternationalizedMessage() This method gets the internationalized message what is the actual message template for the root locale without resolving its NlsArguments.
String	getLocalizedMessage() This method tries to get the localized message as String using the default Locale.
String	getLocalizedMessage(Locale locale) This method gets the resolved and localized message. First it will translate the internationalized message to the given Locale.
void	getLocalizedMessage(Locale locale, Appendable buffer) This method writes the localized message to the given buffer.
String	getLocalizedMessage(Locale locale, NlsTemplateResolver resolver) Deprecated. providing external NlsTemplateResolver has been discouraged.
void	getLocalizedMessage(Locale locale, NlsTemplateResolver resolver, Appendable buffer) Deprecated. providing external NlsTemplateResolver has been discouraged.
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 what is the actual message template for the root locale without resolving its NlsArguments.

Returns:

the message for internationalization (e.g. "Welcome {name}!").

See Also:

NlsMessage, 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 value for the given key.

Parameters:

key - is the name of the requested argument.

Returns:

the argument value for the given key or null if NOT defined.

See Also:

NlsArgument

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.
ATTENTION:
In most cases you wand to use getLocalizedMessage(Locale) instead of this method.

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 using the default Locale. In the simplest case Locale.getDefault() is used but if available LocaleContextHolder from spring is used.
ATTENTION:
If possible try to avoid using this method and use getLocalizedMessage(Locale) instead.

Returns:

the localized message.

getLocalizedMessage

String getLocalizedMessage(Locale locale)

This method gets the resolved and localized message.
First it will translate the internationalized message to the given Locale. If this fails for whatever reason, the internationalized message is used as fallback.
Then this message gets resolved by replacing the arguments with their according values.
Example:
We assume the internationalized message is "Welcome {name}!" and the argument with the key @c"name" has the value "Joelle". After translation to Locale.GERMAN the message may be "Willkommen {name}!". This results in the resolved message "Willkommen Joelle!". If the German localization was not present or has a syntax error, the root locale is used as fallback result in "Welcome Joelle!".

Parameters:

locale - is the locale to translate to.

Returns:

the localized message.

See Also:

net.sf.mmm.util.nls.api

getLocalizedMessage

void getLocalizedMessage(Locale locale,
                         Appendable buffer)

This method writes the localized message to the given buffer.

Parameters:

locale - is the locale to translate to.

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

Since:

5.0.0

See Also:

getLocalizedMessage(Locale)

getLocalizedMessage

@Deprecated
String getLocalizedMessage(Locale locale,
                                        NlsTemplateResolver resolver)

Deprecated. providing external NlsTemplateResolver has been discouraged.

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

@Deprecated
void getLocalizedMessage(Locale locale,
                                      NlsTemplateResolver resolver,
                                      Appendable buffer)

Deprecated. providing external NlsTemplateResolver has been discouraged.

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.