java.lang.Object | ||
↳ | java.text.Format | |
↳ | java.text.MessageFormat |
Produces concatenated messages in language-neutral way. New code
should probably use Formatter
instead.
MessageFormat
takes a set of objects, formats them and then
inserts the formatted strings into the pattern at the appropriate places.
Note: MessageFormat
differs from the other
Format
classes in that you create a MessageFormat
object with one of its constructors (not with a getInstance
style factory method). The factory methods aren't necessary because
MessageFormat
itself doesn't implement locale-specific
behavior. Any locale-specific behavior is defined by the pattern that you
provide as well as the subformats used for inserted arguments.
MessageFormat
uses patterns of the following form:
MessageFormatPattern: String MessageFormatPattern FormatElement String FormatElement: { ArgumentIndex } { ArgumentIndex , FormatType } { ArgumentIndex , FormatType , FormatStyle } FormatType: one of number date time choice FormatStyle: short medium long full integer currency percent SubformatPattern String: StringPart<sub>opt</sub> String StringPart StringPart: '' ' QuotedString ' UnquotedString SubformatPattern: SubformatPatternPart<sub>opt</sub> SubformatPattern SubformatPatternPart SubFormatPatternPart: ' QuotedPattern ' UnquotedPattern
Within a String, "''"
represents a single quote. A
QuotedString can contain arbitrary characters except single quotes;
the surrounding single quotes are removed. An UnquotedString can
contain arbitrary characters except single quotes and left curly brackets.
Thus, a string that should result in the formatted message "'{0}'" can be
written as "'''{'0
''"} or "'''{0
'''"}.
Within a SubformatPattern, different rules apply. A QuotedPattern
can contain arbitrary characters except single quotes, but the surrounding
single quotes are not removed, so they may be interpreted
by the subformat. For example, "{1,number,$'#',##
"} will
produce a number format with the hash-sign quoted, with a result such as:
"$#31,45". An UnquotedPattern can contain arbitrary characters except
single quotes, but curly braces within it must be balanced. For example,
"ab {0
de"} and "ab '
' de"} are valid subformat
patterns, but "ab {0'
' de"} and "ab
de"} are
not.
MessageFormat
. Note that localizers may need to use single quotes in
translated strings where the original version doesn't have them. MessageFormat
. See the annotations for U+0027 Apostrophe in The Unicode
Standard.
The ArgumentIndex value is a non-negative integer written using the
digits '0' through '9', and represents an index into the
arguments
array passed to the format
methods or
the result array returned by the parse
methods.
The FormatType and FormatStyle values are used to create a
Format
instance for the format element. The following table
shows how the values map to Format
instances. Combinations not shown in the
table are illegal. A SubformatPattern must be a valid pattern string
for the Format
subclass used.
Format Type | Format Style | Subformat Created |
---|---|---|
(none) | null |
|
number |
(none) | NumberFormat.getInstance(getLocale()) |
integer |
NumberFormat.getIntegerInstance(getLocale()) |
|
currency |
NumberFormat.getCurrencyInstance(getLocale()) |
|
percent |
NumberFormat.getPercentInstance(getLocale()) |
|
SubformatPattern | new DecimalFormat(subformatPattern, new DecimalFormatSymbols(getLocale())) |
|
date |
(none) | DateFormat.getDateInstance(DateFormat.DEFAULT, getLocale()) |
short |
DateFormat.getDateInstance(DateFormat.SHORT, getLocale()) |
|
medium |
DateFormat.getDateInstance(DateFormat.DEFAULT, getLocale()) |
|
long |
DateFormat.getDateInstance(DateFormat.LONG, getLocale()) |
|
full |
DateFormat.getDateInstance(DateFormat.FULL, getLocale()) |
|
SubformatPattern | new SimpleDateFormat(subformatPattern, getLocale()) |
|
time |
(none) | DateFormat.getTimeInstance(DateFormat.DEFAULT, getLocale()) |
short |
DateFormat.getTimeInstance(DateFormat.SHORT, getLocale()) |
|
medium |
DateFormat.getTimeInstance(DateFormat.DEFAULT, getLocale()) |
|
long |
DateFormat.getTimeInstance(DateFormat.LONG, getLocale()) |
|
full |
DateFormat.getTimeInstance(DateFormat.FULL, getLocale()) |
|
SubformatPattern | new SimpleDateFormat(subformatPattern, getLocale()) |
|
choice |
SubformatPattern | new ChoiceFormat(subformatPattern) |
Here are some examples of usage:
Object[] arguments = { Integer.valueOf(7), new Date(System.currentTimeMillis()), "a disturbance in the Force"}; String result = MessageFormat.format( "At {1,time} on {1,date}, there was {2} on planet {0,number,integer}.", arguments); Output: At 12:30 PM on Jul 3, 2053, there was a disturbance in the Force on planet 7.
Typically, the message format will come from resources, and the arguments will be dynamically set at runtime.
Example 2:
Object[] testArgs = {Long.valueOf(3), "MyDisk"}; MessageFormat form = new MessageFormat("The disk \"{1}\" contains {0} file(s)."); System.out.println(form.format(testArgs)); Output with different testArgs: The disk "MyDisk" contains 0 file(s). The disk "MyDisk" contains 1 file(s). The disk "MyDisk" contains 1,273 file(s).
For more sophisticated patterns, you can use a ChoiceFormat
to
get output such as:
You can either do this programmatically, as in the above example, or by using a pattern (seeMessageFormat form = new MessageFormat("The disk \"{1}\" contains {0}."); double[] filelimits = {0,1,2}; String[] filepart = {"no files","one file","{0,number} files"}; ChoiceFormat fileform = new ChoiceFormat(filelimits, filepart); form.setFormatByArgumentIndex(0, fileform); Object[] testArgs = {Long.valueOf(12373), "MyDisk"}; System.out.println(form.format(testArgs)); Output (with different testArgs): The disk "MyDisk" contains no files. The disk "MyDisk" contains one file. The disk "MyDisk" contains 1,273 files.
ChoiceFormat
for more
information) as in: form.applyPattern("There {0,choice,0#are no files|1#is one file|1<are {0,number,integer} files}.");
Note: As we see above, the string produced by a
ChoiceFormat
in MessageFormat
is treated
specially; occurances of '{' are used to indicated subformats, and cause
recursion. If you create both a MessageFormat
and
ChoiceFormat
programmatically (instead of using the string
patterns), then be careful not to produce a format that recurses on itself,
which will cause an infinite loop.
When a single argument is parsed more than once in the string, the last match will be the final result of the parsing. For example:
MessageFormat mf = new MessageFormat("{0,number,#.##}, {0,number,#.#}"); Object[] objs = {new Double(3.1415)}; String result = mf.format(objs); // result now equals "3.14, 3.1" objs = null; objs = mf.parse(result, new ParsePosition(0)); // objs now equals {new Double(3.1)}
Likewise, parsing with a MessageFormat
object using patterns
containing multiple occurrences of the same argument would return the last
match. For example:
MessageFormat mf = new MessageFormat("{0}, {0}, {0}"); String forParsing = "x, y, z"; Object[] objs = mf.parse(forParsing, new ParsePosition(0)); // result now equals {new String("z")}
Message formats are not synchronized. It is recommended to create separate format instances for each thread. If multiple threads access a format concurrently, it must be synchronized externally.
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
MessageFormat.Field | The instances of this inner class are used as attribute keys in
AttributedCharacterIterator that the
formatToCharacterIterator(Object) method returns. |
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Constructs a new
MessageFormat using the specified pattern and locale . | |||||||||||
Constructs a new
MessageFormat using the specified pattern and
the user's default locale. |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Changes this
MessageFormat to use the specified pattern. | |||||||||||
Returns a new instance of
MessageFormat with the same pattern and
formats as this MessageFormat . | |||||||||||
Compares the specified object to this
MessageFormat and indicates
if they are equal. | |||||||||||
Converts the specified objects into a string which it appends to the
specified string buffer using the pattern of this message format.
| |||||||||||
Formats the supplied objects using the specified message format pattern.
| |||||||||||
Converts the specified objects into a string which it appends to the
specified string buffer using the pattern of this message format.
| |||||||||||
Formats the specified object using the rules of this message format and
returns an
AttributedCharacterIterator with the formatted message and
attributes. | |||||||||||
Returns the
Format instances used by this message format. | |||||||||||
Returns the formats used for each argument index.
| |||||||||||
Returns the locale used when creating formats.
| |||||||||||
Returns an integer hash code for this object.
| |||||||||||
Parses the message arguments from the specified string using the rules of
this message format.
| |||||||||||
Parses the message argument from the specified string starting at the
index specified by
position . | |||||||||||
Parses the message argument from the specified string starting at the
index specified by
position . | |||||||||||
Sets the specified format used by this message format.
| |||||||||||
Sets the format used for the argument at index
argIndex to
format . | |||||||||||
Sets the formats used by this message format.
| |||||||||||
Sets the formats used for each argument.
| |||||||||||
Sets the locale to use when creating
Format instances. | |||||||||||
Returns the pattern of this message format.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.text.Format
| |||||||||||
From class
java.lang.Object
|
Constructs a new MessageFormat
using the specified pattern and locale
.
template | the pattern. |
---|---|
locale | the locale. |
IllegalArgumentException | if the pattern cannot be parsed. |
---|
Constructs a new MessageFormat
using the specified pattern and
the user's default locale.
See "Be wary of the default locale".
template | the pattern. |
---|
IllegalArgumentException | if the pattern cannot be parsed. |
---|
Changes this MessageFormat
to use the specified pattern.
template | the new pattern. |
---|
IllegalArgumentException | if the pattern cannot be parsed. |
---|
Returns a new instance of MessageFormat
with the same pattern and
formats as this MessageFormat
.
MessageFormat
.Compares the specified object to this MessageFormat
and indicates
if they are equal. In order to be equal, object
must be an
instance of MessageFormat
and have the same pattern.
object | the object to compare with this object. |
---|
true
if the specified object is equal to this
MessageFormat
; false
otherwise.Converts the specified objects into a string which it appends to the specified string buffer using the pattern of this message format.
If the field
member of the specified FieldPosition
is
MessageFormat.Field.ARGUMENT
, then the begin and end index of
this field position is set to the location of the first occurrence of a
message format argument. Otherwise, the FieldPosition
is ignored.
objects | the array of objects to format. |
---|---|
buffer | the target string buffer to append the formatted message to. |
field | on input: an optional alignment field; on output: the offsets of the alignment field in the formatted text. |
Formats the supplied objects using the specified message format pattern.
format | the format string (see format(String, Object...) ) |
---|---|
args | the list of arguments passed to the formatter. If there are
more arguments than required by format ,
additional arguments are ignored. |
IllegalArgumentException | if the pattern cannot be parsed. |
---|
Converts the specified objects into a string which it appends to the specified string buffer using the pattern of this message format.
If the field
member of the specified FieldPosition
is
MessageFormat.Field.ARGUMENT
, then the begin and end index of
this field position is set to the location of the first occurrence of a
message format argument. Otherwise, the FieldPosition
is ignored.
Calling this method is equivalent to calling
format((Object[])object, buffer, field)
object | the object to format, must be an array of Object . |
---|---|
buffer | the target string buffer to append the formatted message to. |
field | on input: an optional alignment field; on output: the offsets of the alignment field in the formatted text. |
ClassCastException | if object is not an array of Object .
|
---|
Formats the specified object using the rules of this message format and
returns an AttributedCharacterIterator
with the formatted message and
attributes. The AttributedCharacterIterator
returned also includes the
attributes from the formats of this message format.
object | the object to format. |
---|
AttributedCharacterIterator
with the formatted message and
attributes.IllegalArgumentException | if the arguments in the object array cannot be formatted by this message format. |
---|
Returns the Format
instances used by this message format.
Format
instances.
Returns the formats used for each argument index. If an argument is placed more than once in the pattern string, then this returns the format of the last one.
Returns the locale used when creating formats.
Returns an integer hash code for this object. By contract, any two
objects for which equals(Object)
returns true
must return
the same hash code value. This means that subclasses of Object
usually override both methods or neither method.
Note that hash values must not change over time unless information used in equals comparisons also changes.
See Writing a correct
hashCode
method
if you intend implementing your own hashCode
method.
Parses the message arguments from the specified string using the rules of this message format.
string | the string to parse. |
---|
Object
arguments resulting from the parse.ParseException | if an error occurs during parsing. |
---|
Parses the message argument from the specified string starting at the
index specified by position
. If the string is successfully
parsed then the index of the ParsePosition
is updated to the
index following the parsed text. On error, the index is unchanged and the
error index of ParsePosition
is set to the index where the error
occurred.
string | the string to parse. |
---|---|
position | input/output parameter, specifies the start index in
string from where to start parsing. If parsing is
successful, it is updated with the index following the parsed
text; on error, the index is unchanged and the error index is
set to the index where the error occurred. |
null
if
there is an error.
Parses the message argument from the specified string starting at the
index specified by position
. If the string is successfully
parsed then the index of the ParsePosition
is updated to the
index following the parsed text. On error, the index is unchanged and the
error index of ParsePosition
is set to the index where the error
occurred.
string | the string to parse. |
---|---|
position | input/output parameter, specifies the start index in
string from where to start parsing. If parsing is
successful, it is updated with the index following the parsed
text; on error, the index is unchanged and the error index is
set to the index where the error occurred. |
null
if
there is an error.
Sets the specified format used by this message format.
offset | the index of the format to change. |
---|---|
format | the Format that replaces the old format.
|
Sets the format used for the argument at index argIndex
to
format
.
argIndex | the index of the format to set. |
---|---|
format | the format that will be set at index argIndex .
|
Sets the formats used by this message format.
formats | an array of Format .
|
---|
Sets the formats used for each argument. The formats
array
elements should be in the order of the argument indices.
formats | the formats in an array. |
---|
Sets the locale to use when creating Format
instances. Changing
the locale may change the behavior of applyPattern
,
toPattern
, format
and formatToCharacterIterator
.
locale | the new locale. |
---|
Returns the pattern of this message format.