What is it

This package is an alternative to the JDK's {@link java.util.ResourceBundle} with the following characteristics:

• extensible API;
• can read property files using any character set;
• full backwards-compatibility with {@link java.util.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;
• {@link java.util.Formatter} support, in addition to {@link java.text.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 {@link java.util.ResourceBundle}, the class you will use is {@link com.github.fge.msgsimple.bundle.PropertiesBundle}. It contains static factory methods to provide a ready-to-use {@link com.github.fge.msgsimple.bundle.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.checkNotNull(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:

• {@link com.github.fge.msgsimple.source.MessageSource} represents a message source;
• {@link com.github.fge.msgsimple.provider.MessageSourceProvider} represents a related set of message sources;
• {@link com.github.fge.msgsimple.provider.MessageSourceLoader} represents an on-demand loader for dynamic message sources.

This library provides two message source implementations: {@link com.github.fge.msgsimple.source.MapMessageSource} is a "quickpatch" source backed by a {@link java.util.Map}, and {@link com.github.fge.msgsimple.source.PropertiesMessageSource}, which reads a property file using the encoding of your choice.

It also provides two implementations of message source providers: {@link com.github.fge.msgsimple.provider.StaticMessageSourceProvider} (static, unchanging message sources) and {@link com.github.fge.msgsimple.provider.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 {@link com.github.fge.msgsimple.load.MessageBundleLoader}. When you need to access this bundle, from anywhere in your code, you can then use the {@link com.github.fge.msgsimple.load.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);