net.sf.mmm.util.nls.api

Interface NlsBundle

All Known Subinterfaces:

NlsBundleClientUiRoot, NlsBundleSearchRoot, NlsBundleUtilCliRoot, NlsBundleUtilComponentRoot, NlsBundleUtilCoreRoot, NlsBundleUtilExceptionRoot, NlsBundleUtilFileRoot, NlsBundleUtilIoRoot, NlsBundleUtilPojoRoot, NlsBundleUtilReflectRoot, NlsBundleUtilResourceRoot, NlsBundleUtilSearchRoot, NlsBundleUtilValidationRoot, NlsBundleWithLookup

public interface NlsBundle

This is the marker interface for all "resource-bundles" for this native language support. Instead of a ResourceBundle you create a custom interface extending this one in order to define the messages. This is done by defining methods with NlsMessage as return type and the NLS argument values as parameter.
NOTE:
You should NOT create an implementation of that interface as this is created for you automatically via NlsBundleFactory.createBundle(Class). This is the recommended approach for defining and binding NlsMessages. In order to make your NlsBundle work even in limited environments such as GWT (google web toolkit) clients, we had to define the following convention:

• For your bundle you define a Package and a base name (e.g. my.package.NlsBundleExample). This namespace must not be occupied by an existing type.
• The interface you create and extend from NlsBundle has to be named using the base name followed by the suffix Root (e.g. my.package.NlsBundleExampleRoot). This interface defines the NlsMessagees for the root locale what is the reason for the suffix.
• Your localized *.properties files have to be named using the base name followed by the according locale suffix as for a regular ResourceBundle (e.g. my/package/NlsBundleExample_de.properties or my/package/NlsBundleExample_zh_HK.properties). To override the message texts for the root locale (e.g. as customization of a NlsBundle provided by a third-party library) you could also create a properties file without the locale suffix (e.g. my/package/NlsBundleExample.properties)

Here is an example:

 public interface NlsBundleMynameRoot extends NlsBundle {
    @NlsBundleMessage("The value {value} has to be in the range from {min} to {max}!")
   NlsMessage errorValueOutOfRange( @Named("value") int value,
             @Named("min") int min,  @Named("max") int max);
 }
 

For localization you create *.properties files (see net.sf.mmm.util.nls.base.ResourceBundleSynchronizer) in the same package for each supported Locale. In the example above e.g. NlsBundleMyname_de.properties with this content:

 errorValueOutOfRange = Der Wert {value} muss innerhalb des Wertebereichs von {min} bis {max} liegen!
 

For a real example see NlsBundleUtilCoreRoot.
IMPORTANT:
Unless annotated with NlsBundleKey the key is derived from the name of the method. You have to ensure that the keys are unique as otherwise the localization is NOT possible. Please strictly avoid having methods with the same name.

For maintenance and better support of localizers it is strongly recommended to use named arguments instead of indexed arguments. Unfortunately Java does not include names of parameters in abstract methods (including methods of interfaces). Java8 introduced this feature that we might support in the future. Currently the only way to work around this is to add an annotation to each parameter. The NlsBundleFactory therefore supports the Named annotation for this purpose. As it is nasty to add these annotations manually here is a script for automation. This is just an example - please add more types as needed.

 sed -i -r 's/([(]|, )((Object|Type|int|Number|String|boolean)([.]{3})?) ([a-z][a-zA-Z0-9]*)/\1@Named("\5") \2 \5/g' NlsBundleExampleRoot.java
 

ATTENTION:
It is strongly recommended NOT to use inheritance for NlsBundle interfaces. Instead create an interface that directly extends NlsBundle (and nothing else). However, for purpose of abstraction feel free to add an empty custom extension of NlsBundle as intermediate interface for your project to decouple dependencies.

Since:

3.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

NlsBundleMessage, NlsBundleKey

Field Summary

Fields

Modifier and Type	Field and Description
static String	INTERFACE_NAME_SUFFIX The suffix for the interfaces derived from NlsBundle.

Field Detail

INTERFACE_NAME_SUFFIX

static final String INTERFACE_NAME_SUFFIX

The suffix for the interfaces derived from NlsBundle. This suffix will not change in the future.

See Also:

Constant Field Values