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

  • Field Summary

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

  • Method Summary

    Modifier and Type
    Method
    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.
    boolean
    isEmpty()
    Returns whether the String representation of this message is empty.
    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 Details

    • EMPTY

      public static final LocalizableMessage EMPTY
      Represents an empty message string.

  • Method Details

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

    • isEmpty

      public boolean isEmpty()
      Returns whether the String representation of this message is empty.
      Specified by:
      isEmpty in interface CharSequence
      Returns:
      whether the String representation of this message is empty.

    • 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

      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:

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