msg-simple 0.5 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.locale
Locale utilities
com.github.fge.msgsimple.provider
Message source provider interface and implementations
com.github.fge.msgsimple.serviceloader
ServiceLoader support
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);
  • registration of message bundles using the ServiceLoader API.

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

Using ServiceLoader

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.

Copyright © 2013. All Rights Reserved.