msg-simple 1.1 API

What is it

See:
Description

Packages

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.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.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:

• MessageSource represents a message source;
• MessageSourceProvider represents a related set of message sources;
• MessageSourceLoader represents an on-demand loader for dynamic message sources.

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