msg-simple 0.9 API

What is it

See: Description

Packages 
Package Description
com.github.fge.msgsimple  
com.github.fge.msgsimple.bundle
Main class; property-based bundle provider
com.github.fge.msgsimple.load
Automatic message bundle loading support
com.github.fge.msgsimple.locale
Locale utilities
com.github.fge.msgsimple.provider
Message source provider interface and implementations
com.github.fge.msgsimple.serviceloader
ServiceLoader support - DEPRECATED
com.github.fge.msgsimple.source
Message sources

What is it

This package is an alternative to the JDK's ResourceBundle with the following characteristics:

  • extensible API;
  • can read property files using any character set;
  • full backwards-compatibility with ResourceBundle;
  • i18n/locale support;
  • stackable message sources; can prepend as well as append;
  • static message sources or on-demand loading message sources, with configurable timeout and expiry;
  • Formatter support, in addition to MessageFormat support;
  • error-proof: missing messages or bad format arguments won't throw exceptions (only null arguments will, with appropriate error messages);
  • builtin assertions into message bundles (null checks, condition checks);
  • on-demand loading and caching of message bundles.

Quick start

If you wish to reuse an existing ResourceBundle, the class you will use is PropertiesBundle. It contains static factory methods to provide a ready-to-use MessageBundle:

    // Load a properties bundle using UTF-8 and no expiry
    final MessageBundle bundle = PropertiesBundle.forPath("path/to/messages");
    // Load a properties bundle using UTF-8 and an expiry of 15 minutes
    final MessageBundle bundle = PropertiesBundle.forPath("path/to/messages",
        15L, TimeUnit.MINUTES);
    // Load a legacy resource bundle (ISO-8859-1 charset, no expiry)
    final MessageBundle bundle
        = PropertiesBundle.legacyResourceBundle("path/to/messages");

You are now ready to print out messages:

    // Message using the default locale
    bundle.getMessage("message.key");
    // Message using an alternative locale
    bundle.getMessage(Locale.CANADA, "message.key");
    bundle.getMessage(LocaleUtils.parseLocale("it_IT_sicily", "message.key");
    // message using a Formatter
    bundle.printf("message.key", arg1, arg2);
    // message using MessageFormat
    bundle.format("message.key", arg1, arg2);
    // etc etc

You can also use preconditions:

    // Checks the reference for null; throws NullPointerException if it is;
    final MyClass obj = bundle.checkForNull(ref, "err.nullMyClass");
    // Checks whether the condition is true; throws IllegalArgumentException
    // otherwise
    bundle.checkArgumentPrintf(something.isOk(), "err.something.notOk", arg1,
        arg2);

Extending the API

The API is very simple to extend. There are two interfaces:

This library provides two message source implementations: MapMessageSource is a "quickpatch" source backed by a Map, and PropertiesMessageSource, which reads a property file using the encoding of your choice.

It also provides two implementations of message source providers: StaticMessageSourceProvider (static, unchanging message sources) and LoadingMessageSourceProvider (on-demand loading). Using the latter, you can specify an expiry time and a loading timeout.

Automatic loading

If you have several message bundles and don't want to create a singleton just to distribute them across several classes, you can instead provide an implementation of MessageBundleLoader. When you need to access this bundle, from anywhere in your code, you can then use the MessageBundles class, which will take care of instantiating the loader and provide you with the bundle:

    private static final MessageBundle BUNDLE
        = MessageBundles.getBundle(MyBundleLoader.class);

Migrating from ServiceLoader

ServiceLoader support is now deprecated and discouraged. Fortunately, migrating from ServiceLoader is an easy three-step process:

Make your MessageBundleProvider implementations also implement MessageBundleLoader

That is, turn:

    public final class MyBundle
        implements MessageBundleProvider

into:

    public final class MyBundle
        implements MessageBundleLoader, MessageBundleProvider

Those two interfaces are ultimately the same.

Turn all your calls to MessageBundleFactory into calls to MessageBundles

That is, turn:

    private static final MessageBundle BUNDLE
        = MessageBundleFactory.getBundle(MyBundle.class);

into:

    private static final MessageBundle BUNDLE
        = MessageBundles.getBundle(MyBundle.class);

Unimplement MessageBundleProvider on all your message bundle loaders

That is, turn:

    public final class MyBundle
        implements MessageBundleLoader, MessageBundleProvider

into:

    public final class MyBundle
        implements MessageBundleLoader

And you're done!

Using ServiceLoader (OBSOLETE!)

In order to use the service loader capability of the JDK, you need two elements:

  • one or more implementation(s) of MessageBundleProvider;
  • a file in your classpath, named META-INF/services/com.github.fge.msgsimple.serviceloader.MessageBundleProvider listing your implementations (one per line).

Once this is done, you can get a bundle using:

    final MessageBundle bundle = MessageBundleFactory.getBundle(MyBundle.class);

More information

See here for more complete usage examples.