Java Doc for MessageFormat.java in  » Internationalization-Localization » icu4j » com » ibm » icu » text » Java Source Code / Java DocumentationJava Source Code and Java Documentation

MessageFormat takes a set of objects, formats them, 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.

Patterns and Their Interpretation

 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:
 StringPartopt
 String StringPart
 StringPart:
 ''
 ' QuotedString '
 UnquotedString
 SubformatPattern:
 SubformatPatternPartopt
 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 pound-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.

Warning:

The rules for using quotes within message format patterns unfortunately have shown to be somewhat confusing. In particular, it isn't always obvious to localizers whether single quotes need to be doubled or not. Make sure to inform localizers about the rules, and tell them (for example, by using comments in resource bundle source files) which strings will be processed by MessageFormat. Note that localizers may need to use single quotes in translated strings where the original version doesn't have them.
Note also that the simplest way to avoid the problem is to use the real apostrophe (single quote) character \u2019 (') for human-readable text, and to use the ASCII apostrophe (\u0027 ' ) only in program syntax, like quoting in 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)

Usage Information

Here are some examples of usage:

 Object[] arguments = {
 new Integer(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.
 

Example 2:

 Object[] testArgs = {new Long(3), "MyDisk"};
 MessageFormat form = new MessageFormat(
 "The disk \"{1}\" contains {0} file(s).");
 System.out.println(form.format(testArgs));
 // output, with different testArgs
 output: The disk "MyDisk" contains 0 file(s).
 output: The disk "MyDisk" contains 1 file(s).
 output: The disk "MyDisk" contains 1,273 file(s).
 

For more sophisticated patterns, you can use a ChoiceFormat to get output such as:

 MessageFormat 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 = {new Long(12373), "MyDisk"};
 System.out.println(form.format(testArgs));
 // output, with different testArgs
 output: The disk "MyDisk" contains no files.
 output: The disk "MyDisk" contains one file.
 output: The disk "MyDisk" contains 1,273 files.
 

 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 occurances 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")}
 

Synchronization

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.
See Also:   java.util.Locale
See Also:   Format
See Also:   NumberFormat
See Also:   DecimalFormat
See Also:   ChoiceFormat
author:
   Mark Davis

The text substituted for the individual format elements is derived from the current subformat of the format element and the arguments element at the format element's argument index as indicated by the first matching line of the following table.

Caveats: The parse may fail in a number of circumstances. For example:

• If one of the arguments does not occur in the pattern.
• If the format of an argument loses information, such as with a choice format where a large number formats to "many".
• Does not yet handle recursion (where the substituted strings contain {n} references.)
• Will not always find a match (or the correct match) if some part of the parse is ambiguous. For example, if the pattern "{1},{2}" is used with the string arguments {"a,b", "c"}, it will format as "a,b,c". When the result is parsed, it will return {"a", "b,c"}.
• If a single argument is parsed more than once in the string, then the later parse wins.

See the MessageFormat.parse(String,ParsePosition) method for more information on message parsing.
Parameters:
  source - A String whose beginning should be parsed.

The method attempts to parse text starting at the index given by pos. If parsing succeeds, then the index of pos is updated to the index after the last character used (parsing does not necessarily use all characters up to the end of the string), and the parsed object array is returned.

If the argument index is used for more than one format element in the pattern string, then the new format is used for all such format elements.

If more formats are provided than needed by the pattern string, the remaining ones are ignored.

Note it is not guaranteed that the returned pattern is indeed a valid pattern. The only effect is to convert between patterns having different quoting semantics.
Parameters:
  pattern - the 'apostrophe-friendly' patttern to convert the standard equivalent of the original pattern

The text substituted for the individual format elements is derived from the current subformat of the format element and the arguments element at the format element's argument index as indicated by the first matching line of the following table. An argument is unavailable if arguments is null or has fewer than argumentIndex+1 elements.

Subformat	Argument	Formatted Text
any	unavailable	"{" + argumentIndex + "}"
any	null	"null"
instanceof ChoiceFormat	any	subformat.format(argument).indexOf('{') >= 0 ? (new MessageFormat(subformat.format(argument), getLocale())).format(argument) : subformat.format(argument)
!= null	any	subformat.format(argument)
null	instanceof Number	NumberFormat.getInstance(getLocale()).format(argument)
null	instanceof Date	DateFormat.getDateTimeInstance(DateFormat.SHORT, DateFormat.SHORT, getLocale()).format(argument)
null	instanceof String	argument
null	any	argument.toString()

If pos is non-null, and refers to Field.ARGUMENT, the location of the first formatted string will be returned.
Parameters:
  arguments - an array of objects to be formatted and substituted.
Parameters:
  result - where text is appended.
Parameters:
  pos - On input: an alignment field, if desired.On output: the offsets of the alignment field.
exception:
  IllegalArgumentException - if an argument in thearguments array is not of the typeexpected by the format element(s) that use it.

(new MessageFormat.MessageFormat(String) MessageFormat (pattern)). MessageFormat.format(java.lang.Object[],java.lang.StringBuffer,java.text.FieldPosition) format (arguments, new StringBuffer(), null).toString()

MessageFormat.format(java.lang.Object[],java.lang.StringBuffer,java.text.FieldPosition) format ((Object[]) arguments, result, pos)

Since the order of format elements in a pattern string often changes during localization, it's generally better to use the MessageFormat.getFormatsByArgumentIndex getFormatsByArgumentIndex method, which assumes an order of formats corresponding to the order of elements in the arguments array passed to the format methods or the result array returned by the parse methods. the formats used for the format elements in the pattern

If an argument index is used for more than one format element in the pattern string, then the format used for the last such format element is returned in the array. If an argument index is not used for any format element in the pattern string, then null is returned in the array. the formats used for the arguments within the pattern

Caveats: The parse may fail in a number of circumstances. For example:

• If one of the arguments does not occur in the pattern.
• If the format of an argument loses information, such as with a choice format where a large number formats to "many".
• Does not yet handle recursion (where the substituted strings contain {n} references.)
• Will not always find a match (or the correct match) if some part of the parse is ambiguous. For example, if the pattern "{1},{2}" is used with the string arguments {"a,b", "c"}, it will format as "a,b,c". When the result is parsed, it will return {"a", "b,c"}.
• If a single argument is parsed more than once in the string, then the later parse wins.

See the MessageFormat.parse(String,ParsePosition) method for more information on message parsing.
Parameters:
  source - A String whose beginning should be parsed. An Object array parsed from the string.
exception:
  ParseException - if the beginning of the specified stringcannot be parsed.

The method attempts to parse text starting at the index given by pos. If parsing succeeds, then the index of pos is updated to the index after the last character used (parsing does not necessarily use all characters up to the end of the string), and the parsed object array is returned. The updated pos can be used to indicate the starting point for the next call to this method. If an error occurs, then the index of pos is not changed, the error index of pos is set to the index of the character where the error occurred, and null is returned.

See the MessageFormat.parse(String,ParsePosition) method for more information on message parsing.
Parameters:
  source - A String, part of which should be parsed.
Parameters:
  pos - A ParsePosition object with index and errorindex information as described above. An Object array parsed from the string. In case oferror, returns null.
exception:
  NullPointerException - if pos is null.

Since the order of format elements in a pattern string often changes during localization, it is generally better to use the MessageFormat.setFormatByArgumentIndex setFormatByArgumentIndex method, which accesses format elements based on the argument index they specify.
Parameters:
  formatElementIndex - the index of a format element within the pattern
Parameters:
  newFormat - the format to use for the specified format element
exception:
  ArrayIndexOutOfBoundsException - if formatElementIndex is equal to orlarger than the number of format elements in the pattern string

If the argument index is used for more than one format element in the pattern string, then the new format is used for all such format elements. If the argument index is not used for any format element in the pattern string, then the new format is ignored.
Parameters:
  argumentIndex - the argument index for which to use the new format
Parameters:
  newFormat - the new format to use

If more formats are provided than needed by the pattern string, the remaining ones are ignored. If fewer formats are provided than needed, then only the first newFormats.length formats are replaced.

Since the order of format elements in a pattern string often changes during localization, it is generally better to use the MessageFormat.setFormatsByArgumentIndex setFormatsByArgumentIndex method, which assumes an order of formats corresponding to the order of elements in the arguments array passed to the format methods or the result array returned by the parse methods.
Parameters:
  newFormats - the new formats to use
exception:
  NullPointerException - if newFormats is null

If an argument index is used for more than one format element in the pattern string, then the corresponding new format is used for all such format elements. If an argument index is not used for any format element in the pattern string, then the corresponding new format is ignored. If fewer formats are provided than needed, then only the formats for argument indices less than newFormats.length are replaced.
Parameters:
  newFormats - the new formats to use
exception:
  NullPointerException - if newFormats is null