29.13 java.text.MessageFormat (JDK 1.1)

This class formats and substitutes objects into specified positions in a message string (also known as the "pattern" string). It provides the closest Java equivalent to the printf() function of the C programming language.

If a message is to be displayed only a single time, the simplest way to use the MessageFormat class is through the static format() method which is passed a message or pattern string and an array of argument objects to be formatted and substituted into the string. If the message is to be displayed several times, it makes more sense to create a MessageFormat object, supplying the pattern string, and then to call the format() instance method of this object, supplying the array of objects to be formatted into the message.

The message or pattern string used by the MessageFormat should contain digits enclosed in curly braces to indicate where each argument should be substituted. The sequence "{0}" indicates that the first object should be converted to a string (if necessary) and inserted at that point, while the sequence "{3}" indicates that the fourth object should be inserted, for example. If the object to be inserted is not a string, MessageFormat checks to see if it is a Date or a subclass of Number. If so, it uses a default DateFormat or NumberFormat object to convert the value to a string. If not, it simply invokes the object's toString() method to convert it.

A digit within curly braces in a pattern string may be optionally followed by a comma, and one of the words "date", "time", "number", or "choice", to indicate that the corresponding argument should be formatted as a date, time, number, or choice before being substituted into the pattern string. Any of these keywords may additionally be followed by a comma and additional pattern information to be used in formatting the date, time, number, or choice. (See SimpleDateFormat, DecimalFormat, and ChoiceFormat for more information.)

You can use the setLocale() method to specify a non-default Locale that the MessageFormat should use when obtaining DateFormat and NumberFormat objects to format dates, time, and numbers inserted into the pattern.

You can change the Format object used at a particular position in the pattern with the setFormat() method. You can set a new pattern for the MessageFormat object by calling applyPattern(), and you can obtain a string that represents the current formatting pattern by calling toPattern().

MessageFormat also supports a parse() method that can parse an array of objects out of a specified string, according to the specified pattern.

public class MessageFormat extends Format {
    // Public Constructor
            public MessageFormat(String pattern);
    // Class Methods
            public static String format(String pattern, Object[] arguments);
    // Public Instance Methods
            public void applyPattern(String newPattern);
            public Object clone();  // Overrides Format
            public boolean equals(Object obj);  // Overrides Object
            public final StringBuffer format(Object[] source, StringBuffer result, FieldPosition ignore);
            public final StringBuffer format(Object source, StringBuffer result, FieldPosition ignore);  // Defines Format
            public Format[] getFormats();
            public Locale getLocale();
            public int hashCode();  // Overrides Object
            public Object[] parse(String source, ParsePosition status);
            public Object[] parse(String source) throws ParseException;
            public Object parseObject(String text, ParsePosition status);  // Defines Format
            public void setFormat(int variable, Format newFormat);
            public void setFormats(Format[] newFormats);
            public void setLocale(Locale theLocale);
            public String toPattern();
}

Hierarchy:

Object->Format(Serializable, Cloneable)->MessageFormat