va-json-tools.msg-simple.1.2.source-code.overview.html Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of msg-simple Show documentation
A lightweight, UTF-8 capable, printf() capable alternative to Java's ResourceBundle
The newest version!




    msg-simple: a better ResourceBundle




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