org.forgerock.i18n

Class LocalizableMessage

java.lang.Object

org.forgerock.i18n.LocalizableMessage

All Implemented Interfaces:

Serializable, CharSequence, Comparable<LocalizableMessage>, Formattable

public final class LocalizableMessage
extends Object
implements CharSequence, Formattable, Comparable<LocalizableMessage>, Serializable

A localizable message whose String representation can be retrieved in one or more locales. A message is localized each time it is converted to a String using one of its toString() methods.

Localizable messages are particularly useful in situations where a message a destined for multiple recipients, potentially in different locales. For example, a server application may record a message in its log file using its default locale, but also send the same message to the client using the client's locale (if known).

In most cases messages are intended for use in a locale-sensitive manner although this class defines convenience methods for creating non-localizable messages whose String representation is always the same regardless of the requested locale.

This class implements CharSequence so that messages can be supplied as arguments to other messages. This way messages can be composed of fragments of other messages if necessary.

See Also:

LocalizableMessageBuilder, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static LocalizableMessage	EMPTY Represents an empty message string.

Method Summary

Modifier and Type	Method and Description
char	charAt(int index) Returns the char value at the specified index of the String representation of this message in the default locale.
char	charAt(Locale locale, int index) Returns the char value at the specified index of the String representation of this message in the specified locale.
int	compareTo(LocalizableMessage message) Compares this message with the specified message for order in the default locale.
boolean	equals(Object o) Returns true if the provided object is a message whose String representation is equal to the String representation of this message in the default locale.
void	formatTo(Formatter formatter, int flags, int width, int precision) Formats this message using the provided Formatter.
int	hashCode() Returns the hash code value for this message calculated using the hash code of the String representation of this message in the default locale.
int	length() Returns the length of the String representation of this message in the default locale.
int	length(Locale locale) Returns the length of the String representation of this message in the specified locale.
int	ordinal() Returns the ordinal associated with this message, or -1 if undefined.
static LocalizableMessage	raw(CharSequence string) Creates an non-localizable message whose String representation is always the same regardless of the requested locale.
static LocalizableMessage	raw(CharSequence formatString, Object... args) Creates an non-localizable message whose String representation is always the same regardless of the requested locale.
String	resourceName() Returns the name of the resource in which this message is defined.
CharSequence	subSequence(int start, int end) Returns a new CharSequence which is a subsequence of the String representation of this message in the default locale.
CharSequence	subSequence(Locale locale, int start, int end) Returns a new CharSequence which is a subsequence of the String representation of this message in the specified locale.
String	toString() Returns the String representation of this message in the default locale.
String	toString(Locale locale) Returns the String representation of this message in the specified locale.
static LocalizableMessage	valueOf(Object object) Creates a new message whose content is the String representation of the provided Object.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.CharSequence

chars, codePoints

Field Detail

EMPTY

public static final LocalizableMessage EMPTY

Represents an empty message string.

Method Detail

raw

public static LocalizableMessage raw(CharSequence string)

Creates an non-localizable message whose String representation is always the same regardless of the requested locale.

Parameters:

string - The raw message string.

Returns:

A non-localizable messages whose String representation is always the same regardless of the requested locale.

Throws:

NullPointerException - If string was null.

raw

public static LocalizableMessage raw(CharSequence formatString,
                                     Object... args)

Creates an non-localizable message whose String representation is always the same regardless of the requested locale.

Note that the types for args must be consistent with any argument specifiers appearing in formatString according to the rules of Formatter. A mismatch in type information will cause this message to render without argument substitution. Before using this method you should be sure that the message you are creating is not locale sensitive. If it is locale sensitive consider defining an appropriate LocalizableMessageDescriptor.

This method handles the special case where a CharSequence needs to be converted directly to LocalizableMessage as follows:

 String s = ...;

 // Both of these are equivalent:
 LocalizableMessage m = LocalizableMessage.raw(s);
 LocalizableMessage m = LocalizableMessage.raw("%s", s);
 

Parameters:

formatString - The raw message format string.

args - The raw message parameters.

Returns:

A non-localizable messages whose String representation is always the same regardless of the requested locale.

Throws:

NullPointerException - If formatString was null.

valueOf

public static LocalizableMessage valueOf(Object object)

Creates a new message whose content is the String representation of the provided Object.

Parameters:

object - The object to be converted to a message, may be null.

Returns:

The new message.

charAt

public char charAt(int index)

Returns the char value at the specified index of the String representation of this message in the default locale.

Specified by:

charAt in interface CharSequence

Parameters:

index - The index of the char value to be returned.

Returns:

The specified char value.

Throws:

IndexOutOfBoundsException - If the index argument is negative or not less than length().

charAt

public char charAt(Locale locale,
                   int index)

Returns the char value at the specified index of the String representation of this message in the specified locale.

Parameters:

locale - The locale.

index - The index of the char value to be returned.

Returns:

The specified char value.

Throws:

IndexOutOfBoundsException - If the index argument is negative or not less than length().

NullPointerException - If locale was null.

compareTo

public int compareTo(LocalizableMessage message)

Compares this message with the specified message for order in the default locale. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Specified by:

compareTo in interface Comparable<LocalizableMessage>

Parameters:

message - The message to be compared.

Returns:

A negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

equals

public boolean equals(Object o)

Returns true if the provided object is a message whose String representation is equal to the String representation of this message in the default locale.

Overrides:

equals in class Object

Parameters:

o - The object to be compared for equality with this message.

Returns:

true if this message is the equal to o, otherwise false.

formatTo

public void formatTo(Formatter formatter,
                     int flags,
                     int width,
                     int precision)

Formats this message using the provided Formatter.

Specified by:

formatTo in interface Formattable

Parameters:

formatter - The Formatter.

flags - The flags modify the output format. The value is interpreted as a bitmask. Any combination of the following flags may be set: FormattableFlags.LEFT_JUSTIFY, FormattableFlags.UPPERCASE, and FormattableFlags.ALTERNATE. If no flags are set, the default formatting of the implementing class will apply.

width - The minimum number of characters to be written to the output. If the length of the converted value is less than the width then the output will be padded by white space until the total number of characters equals width. The padding is at the beginning by default. If the FormattableFlags.LEFT_JUSTIFY flag is set then the padding will be at the end. If width is -1 then there is no minimum.

precision - The maximum number of characters to be written to the output. The precision is applied before the width, thus the output will be truncated to precision characters even if the width is greater than the precision. If precision is -1 then there is no explicit limit on the number of characters.

Throws:

IllegalFormatException - If any of the parameters are invalid. For specification of all possible formatting errors, see the Details section of the formatter class specification.

hashCode

public int hashCode()

Returns the hash code value for this message calculated using the hash code of the String representation of this message in the default locale.

Overrides:

hashCode in class Object

Returns:

The hash code value for this message.

length

public int length()

Returns the length of the String representation of this message in the default locale.

Specified by:

length in interface CharSequence

Returns:

The length of the String representation of this message in the default locale.

length

public int length(Locale locale)

Returns the length of the String representation of this message in the specified locale.

Parameters:

locale - The locale.

Returns:

The length of the String representation of this message in the specified locale.

Throws:

NullPointerException - If locale was null.

ordinal

public int ordinal()

Returns the ordinal associated with this message, or -1 if undefined. A message can be uniquely identified by its resource name and ordinal.

This may be useful when an application wishes to identify the source of a message. For example, a logging implementation could log the resource name in addition to the ordinal in order to unambiguously identify a message in a locale independent way.

Returns:

The ordinal associated with this descriptor, or -1 if undefined.

See Also:

resourceName()

resourceName

public String resourceName()

Returns the name of the resource in which this message is defined. A message can be uniquely identified by its resource name and ordinal.

This may be useful when an application wishes to identify the source of a message. For example, a logging implementation could log the resource name in addition to the ordinal in order to unambiguously identify a message in a locale independent way.

The resource name may be used for obtaining named loggers, e.g. using SLF4J's org.slf4j.LoggerFactory#getLogger(String name).

Returns:

The name of the resource in which this message is defined, or null if this message is a raw message and its source is undefined.

See Also:

ordinal()

subSequence

public CharSequence subSequence(int start,
                                int end)

Returns a new CharSequence which is a subsequence of the String representation of this message in the default locale. The subsequence starts with the char value at the specified index and ends with the char value at index end - 1 . The length (in chars) of the returned sequence is end - start, so if start == end then an empty sequence is returned.

Specified by:

subSequence in interface CharSequence

Parameters:

start - The start index, inclusive.

end - The end index, exclusive.

Returns:

The specified subsequence.

Throws:

IndexOutOfBoundsException - If start or end are negative, if end is greater than length(), or if start is greater than end.

subSequence

public CharSequence subSequence(Locale locale,
                                int start,
                                int end)

Returns a new CharSequence which is a subsequence of the String representation of this message in the specified locale. The subsequence starts with the char value at the specified index and ends with the char value at index end - 1 . The length (in chars) of the returned sequence is end - start , so if start == end then an empty sequence is returned.

Parameters:

locale - The locale.

start - The start index, inclusive.

end - The end index, exclusive.

Returns:

The specified subsequence.

Throws:

IndexOutOfBoundsException - If start or end are negative, if end is greater than length(), or if start is greater than end.

NullPointerException - If locale was null.

toString

public String toString()

Returns the String representation of this message in the default locale.

Specified by:

toString in interface CharSequence

Overrides:

toString in class Object

Returns:

The String representation of this message.

toString

public String toString(Locale locale)

Returns the String representation of this message in the specified locale.

Parameters:

locale - The locale.

Returns:

The String representation of this message.

Throws:

NullPointerException - If locale was null.