msg-simple 1.1 API

What is it


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.source Message sources


What is it

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

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
    // 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.checkNotNull(ref, "err.nullMyClass");
    // Checks whether the condition is true; throws IllegalArgumentException
    // otherwise
    bundle.checkArgumentPrintf(something.isOk(), "err.something.notOk", arg1,

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);