com.github.fge.msgsimple.bundle
Class MessageBundle

java.lang.Object
  com.github.fge.msgsimple.bundle.MessageBundle

All Implemented Interfaces:

Frozen<MessageBundleBuilder>

@ThreadSafe
public final class MessageBundle
extends Object
implements Frozen<MessageBundleBuilder>

A message bundle

A bundle is a list of MessageSourceProviders. When a message is looked up, providers are queried in order for a MessageSource for that locale; if a source is found, it is queried for the message.

When a method is used which does not take a Locale as an argument, the default locale is used (obtained via Locale.getDefault()). If no match is found for the locale, the next, more general locale is tried.

Finally, if no match was found for any provider/source, the key itself is returned.

You can generate a bundle from a single source using the withSingleSource(MessageSource) convenience static factory method; for more elaborate bundles, use newBuilder() to obtain a builder, then that builder's MessageBundleBuilder.freeze() method to obtain the bundle; alternatively, you can reuse an existing bundle and thaw() it, modify it and freeze it again.

See Also:

LocaleUtils.getApplicable(Locale), MessageSourceProvider

Method Summary

void	checkArgument(boolean condition, Locale locale, String key) Check for a condition
void	checkArgument(boolean condition, String key) Check for a condition
void	checkArgumentFormat(boolean condition, Locale locale, String key, Object... params) Check for a condition
void	checkArgumentFormat(boolean condition, String key, Object... params) Check for a condition
void	checkArgumentPrintf(boolean condition, Locale locale, String key, Object... params) Check for a condition
void	checkArgumentPrintf(boolean condition, String key, Object... params) Check for a condition
<T> T	checkNotNull(T reference, Locale locale, String key) Check an object reference for null and return it
<T> T	checkNotNull(T reference, String key) Check a reference for null and return it
<T> T	checkNotNullFormat(T reference, Locale locale, String key, Object... params) Check a reference for null and return it
<T> T	checkNotNullFormat(T reference, String key, Object... params) Check a reference for null and return it
<T> T	checkNotNullPrintf(T reference, Locale locale, String key, Object... params) Check a reference for null and return it
<T> T	checkNotNullPrintf(T reference, String key, Object... params) Check a reference for null and return it
String	format(Locale locale, String key, Object... params) Get a locale-dependent message formatted using MessageFormat
String	format(String key, Object... params) Get a MessageFormat formatted message with the current default locale
String	getMessage(Locale locale, String key) Get a message for the given key and locale
String	getMessage(String key) Return a message for a given key, using the JVM's current locale
static MessageBundleBuilder	newBuilder() Create a new, empty builder for a bundle
String	printf(Locale locale, String key, Object... params) Get a locale-dependent printf()-like formatted message
String	printf(String key, Object... params) Get a printf()-like message with the default locale
MessageBundleBuilder	thaw()
static MessageBundle	withSingleSource(MessageSource source) Convenience static factory method to create a bundle with a single message source

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

newBuilder

public static MessageBundleBuilder newBuilder()

Create a new, empty builder for a bundle

Returns:

a builder

withSingleSource

public static MessageBundle withSingleSource(MessageSource source)

Convenience static factory method to create a bundle with a single message source

Parameters:

source - the message source

Returns:

a new bundle

Since:

0.7

See Also:

StaticMessageSourceProvider.withSingleSource(MessageSource)

getMessage

public String getMessage(Locale locale,
                         String key)

Get a message for the given key and locale

Parameters:

locale - the locale

key - the key

Returns:

a matching message if found; the key itself if no message is found

Throws:

NullPointerException - either the key or the locale is null

getMessage

public String getMessage(String key)

Return a message for a given key, using the JVM's current locale

Parameters:

key - the key

Returns:

a matching message if found; the key itself if no message is found

Throws:

NullPointerException - key is null

See Also:

Locale.getDefault(), Locale.setDefault(Locale)

printf

public String printf(Locale locale,
                     String key,
                     Object... params)

Get a locale-dependent printf()-like formatted message

This is essentially a call to String.format(Locale, String, Object...).

There is however one important difference: while String.format() will throw an IllegalFormatException if an argument is missing or a format specifier is incorrect, this method returns the format itself (or the key, like getMessage(Locale, String), if no match was found for that locale/key pair).

Parameters:

locale - the locale

key - the key

params - the format parameters

Returns:

the formatted message

See Also:

Formatter

printf

public String printf(String key,
                     Object... params)

Get a printf()-like message with the default locale

This calls printf(Locale, String, Object...) with Locale.getDefault() as the first argument.

Parameters:

key - the key

params - the format parameters

Returns:

the formatted message

format

public String format(Locale locale,
                     String key,
                     Object... params)

Get a locale-dependent message formatted using MessageFormat

You should really consider using printf(Locale, String, Object...) instead.

Parameters:

locale - the locale

key - the key

params - the format parameters

Returns:

the formatted message

format

public String format(String key,
                     Object... params)

Get a MessageFormat formatted message with the current default locale

You should really consider using printf(String, Object...) instead.

Parameters:

key - the key

params - the format parameters

Returns:

the formatted message

checkNotNull

public <T> T checkNotNull(T reference,
                          Locale locale,
                          String key)

Check an object reference for null and return it

If the reference is null, a NullPointerException is thrown, with its message set according to the given locale and key.

Type Parameters:

T - type of the reference

Parameters:

reference - the reference to check

locale - the locale to use

key - the key to use

Returns:

the reference

Throws:

NullPointerException - see description

See Also:

getMessage(Locale, String)

checkNotNull

public <T> T checkNotNull(T reference,
                          String key)

Check a reference for null and return it

This calls checkNotNull(Object, Locale, String) with the JVM's current locale.

Type Parameters:

T - type of the reference

Parameters:

reference - the reference to check

key - the key

Returns:

the reference

Throws:

NullPointerException - see description

checkArgument

public void checkArgument(boolean condition,
                          Locale locale,
                          String key)

Check for a condition

When the condition is false, an IllegalArgumentException is thrown with its message set using the given locale and key.

Parameters:

condition - the condition to check

locale - the locale to use

key - the key

Throws:

IllegalArgumentException - see description

See Also:

getMessage(Locale, String)

checkArgument

public void checkArgument(boolean condition,
                          String key)

Check for a condition

This calls checkArgument(boolean, Locale, String) using the JVM's current locale.

Parameters:

condition - the condition to check

key - the key

Throws:

IllegalArgumentException - see description

checkNotNullPrintf

public <T> T checkNotNullPrintf(T reference,
                                Locale locale,
                                String key,
                                Object... params)

Check a reference for null and return it

Like checkNotNull(Object, Locale, String), except that this will use printf(Locale, String, Object...)

Type Parameters:

T - type of the reference

Parameters:

reference - the reference to check

locale - the locale to use

key - the key

params - arguments for the format string

Returns:

the reference

Throws:

NullPointerException - see description

See Also:

printf(Locale, String, Object...)

checkNotNullPrintf

public <T> T checkNotNullPrintf(T reference,
                                String key,
                                Object... params)

Check a reference for null and return it

This calls checkNotNullPrintf(Object, Locale, String, Object...) with the JVM's current locale.

Type Parameters:

T - type of the reference

Parameters:

reference - the reference

key - the key

params - arguments for the format string

Returns:

the reference

Throws:

NullPointerException - see description

checkArgumentPrintf

public void checkArgumentPrintf(boolean condition,
                                Locale locale,
                                String key,
                                Object... params)

Check for a condition

Like checkArgument(boolean, Locale, String), except that printf(Locale, String, Object...) is used to fill the message.

Parameters:

condition - the condition to check

locale - the locale

key - the key

params - arguments for the format string

Throws:

IllegalArgumentException - see description

See Also:

printf(Locale, String, Object...)

checkArgumentPrintf

public void checkArgumentPrintf(boolean condition,
                                String key,
                                Object... params)

Check for a condition

This calls checkArgumentPrintf(boolean, Locale, String, Object...) with the JVM's current locale.

Parameters:

condition - the condition to check

key - the key

params - arguments for the format string

Throws:

IllegalArgumentException - see description

checkNotNullFormat

public <T> T checkNotNullFormat(T reference,
                                Locale locale,
                                String key,
                                Object... params)

Check a reference for null and return it

Like checkNotNull(Object, Locale, String), except that this will use format(Locale, String, Object...)}

Type Parameters:

T - type of the reference

Parameters:

reference - the reference to check

locale - the locale to use

key - the key

params - arguments for the format string

Returns:

the reference

Throws:

NullPointerException - see description

See Also:

format(Locale, String, Object...)

checkNotNullFormat

public <T> T checkNotNullFormat(T reference,
                                String key,
                                Object... params)

Check a reference for null and return it

This calls checkNotNullFormat(Object, Locale, String, Object...) with the JVM's current locale.

Type Parameters:

T - type of the reference

Parameters:

reference - the reference

key - the key

params - arguments for the format string

Returns:

the reference

Throws:

NullPointerException - see description

checkArgumentFormat

public void checkArgumentFormat(boolean condition,
                                Locale locale,
                                String key,
                                Object... params)

Check for a condition

Like checkArgument(boolean, Locale, String), except that format(Locale, String, Object...) is used to fill the message.

Parameters:

condition - the condition to check

locale - the locale

key - the key

params - arguments for the format string

Throws:

IllegalArgumentException - see description

See Also:

format(Locale, String, Object...)

checkArgumentFormat

public void checkArgumentFormat(boolean condition,
                                String key,
                                Object... params)

Check for a condition

This calls checkArgumentFormat(boolean, Locale, String, Object...) with the JVM's current locale.

Parameters:

condition - the condition to check

key - the key

params - arguments for the format string

Throws:

IllegalArgumentException - see description

thaw

public MessageBundleBuilder thaw()

Specified by:

thaw in interface Frozen<MessageBundleBuilder>