Features

Preliminary note

This documents version 0.2.

Features

No external library dependency

This library relies only on the JDK (note: 6+).

Full i18n support

When you .getMessage() from a MessageBundle, the current JVM locale is tried first, then other, more generic locales are tried. For instance, if your locale is ja_JP_JP, the following locales are tried in order:

• ja_JP_JP;
• ja_JP;
• ja;
• the root locale (Locale.ROOT in Java parlance).

You can also specify the locale you want using dedicated methods.

Message source, message provider extensibility

A MessageBundle works as follows when trying to find a message for a given locale/key pair:

• it loops through all of its registered MessageSourceProviders in order (see below);
• for one provider, it tries and sees if it has a MessageSource for this locale;
• if one is found, it queries the source for the key.

Both MessageSourceProvider and MessageSource are simple interfaces:

public interface MessageSourceProvider
{
    MessageSource getMessageSource(final Locale locale);
}

public interface MessageSource
{
    String getKey(final String key);
}

You can implement these interfaces the way you want. The implementation provides two implementations of MessageSourceProvider (one including dynamic lookup with caching and configurable timeout) and two implementations of MessageSource, including one to read from property files.

And as to property files...

Property files are read in UTF-8

This is unlike the JDK's ResourceBundle, which reads property files in ISO-8859-1.

Message providers can be stacked

Using the builder class for a MessageBundle, you can append or prepend message providers:

MessageProvider p1, p2, p3;

MessageBundleBuilder builder = MessageBundle.newBuilder();

builder = builder.appendProvider(p1).appendProvider(p2); // Order is now: p1 -> p2
builder = builder.prependProvider(p3); // Order is now: p3 -> p1 -> p2

// Build the final bundle
final MessageBundle bundle = builder.build();

Note that MessageBundles are immutable. However, You can reuse an existing one and extend it:

MessageProvider p4;

// New bundle with order p3 -> p1 -> p2 -> p4
final MessageBundle newBundle = bundle.thaw().appendProvider(p4).freeze();

Unknown keys are returned as is

This is unlike a ResourceBundle, which, in this case, throws an (unchecked!!) exception. In the event when a key does not exist, the key itself is returned. This allows for more graceful failures, and an easy spotting of missing keys.

Example:

final Map<String, String> map = new HashMap<String, String>();
map.put("foo", "bar");

final MessageSource source = new MapMessageSource(map);
// .appendSource() is a convenience method to append a provider with a single source for all locales
final MessageBundle bundle = MessageBundle.newBuilder().appendSource(source).freeze();

bundle.getKey("foo"); // returns "bar"
bundle.getKey("baz"); // returns "baz"