public final class LocalizableMessage extends Object implements CharSequence, Formattable, Comparable<LocalizableMessage>, Serializable
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.
LocalizableMessageBuilder
,
Serialized FormModifier and Type | Field and Description |
---|---|
static LocalizableMessage |
EMPTY
Represents an empty message string.
|
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 . |
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
chars, codePoints
public static final LocalizableMessage EMPTY
public static LocalizableMessage raw(CharSequence string)
String
representation is
always the same regardless of the requested locale.string
- The raw message string.String
representation is
always the same regardless of the requested locale.NullPointerException
- If string
was null
.public static LocalizableMessage raw(CharSequence formatString, Object... args)
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);
formatString
- The raw message format string.args
- The raw message parameters.String
representation is
always the same regardless of the requested locale.NullPointerException
- If formatString
was null
.public static LocalizableMessage valueOf(Object object)
String
representation
of the provided Object
.object
- The object to be converted to a message, may be null
.public char charAt(int index)
char
value at the specified index of the
String
representation of this message in the default locale.charAt
in interface CharSequence
index
- The index of the char
value to be returned.char
value.IndexOutOfBoundsException
- If the index
argument is negative or not less than
length()
.public char charAt(Locale locale, int index)
char
value at the specified index of the
String
representation of this message in the specified locale.locale
- The locale.index
- The index of the char
value to be returned.char
value.IndexOutOfBoundsException
- If the index
argument is negative or not less than
length()
.NullPointerException
- If locale
was null
.public int compareTo(LocalizableMessage message)
compareTo
in interface Comparable<LocalizableMessage>
message
- The message to be compared.public boolean equals(Object o)
true
if the provided object is a message whose
String
representation is equal to the String
representation of this message in the default locale.public void formatTo(Formatter formatter, int flags, int width, int precision)
Formatter
.formatTo
in interface Formattable
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.IllegalFormatException
- If any of the parameters are invalid. For specification of
all possible formatting errors, see the Details section of
the formatter class specification.public int hashCode()
String
representation of this message in the default
locale.public int length()
String
representation of this message
in the default locale.length
in interface CharSequence
String
representation of this message
in the default locale.public int length(Locale locale)
String
representation of this message
in the specified locale.locale
- The locale.String
representation of this message
in the specified locale.NullPointerException
- If locale
was null
.public int ordinal()
-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.
-1
if
undefined.resourceName()
public String resourceName()
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)
.
null
if this message is a raw message and its source is
undefined.ordinal()
public CharSequence subSequence(int start, int end)
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 char
s) of the returned sequence is end - start
, so if
start == end
then an empty sequence is returned.subSequence
in interface CharSequence
start
- The start index, inclusive.end
- The end index, exclusive.IndexOutOfBoundsException
- If start
or end
are negative, if end
is greater than length()
, or if start
is
greater than end
.public CharSequence subSequence(Locale locale, int start, int end)
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 char
s) of the returned sequence is end - start
, so if start == end
then an empty sequence is returned.locale
- The locale.start
- The start index, inclusive.end
- The end index, exclusive.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
.public String toString()
String
representation of this message in the default
locale.toString
in interface CharSequence
toString
in class Object
String
representation of this message.public String toString(Locale locale)
String
representation of this message in the
specified locale.locale
- The locale.String
representation of this message.NullPointerException
- If locale
was null
.Copyright 2010-2022 ForgeRock AS.