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. This method 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 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 contains 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. 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 followed
optionally 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 can 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 pass a
Locale to the constructor or call
setLocale( ) to specify a nondefault 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, or change all Format objects
with setFormats( ). Both of these methods depend
on the order of in which arguments are displayed in the pattern
string. The pattern string is often subject to localization and the
arguments may appear in different orders in different localizations
of the pattern. Therefore, in Java 1.4 and later it is usually more
convenient to use the
"ByArgumentIndex" versions of the
setFormat( ), setFormats( )
methods, and getFormats( ) methods.
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 Constructors
public MessageFormat(String pattern);
1.4 public MessageFormat(String pattern, java.util.Locale locale);
// Nested Types
1.4 public static class Field extends Format.Field;
// Public Class Methods
public static String format(String pattern, Object... arguments);
// Public Instance Methods
public void applyPattern(String pattern);
public final StringBuffer format(Object[ ] arguments, StringBuffer result,
FieldPosition pos);
public Format[ ] getFormats( );
1.4 public Format[ ] getFormatsByArgumentIndex( );
public java.util.Locale getLocale( );
public Object[ ] parse(String source) throws ParseException;
public Object[ ] parse(String source, ParsePosition pos);
public void setFormat(int formatElementIndex, Format newFormat);
1.4 public void setFormatByArgumentIndex(int argumentIndex, Format newFormat);
public void setFormats(Format[ ] newFormats);
1.4 public void setFormatsByArgumentIndex(Format[ ] newFormats);
public void setLocale(java.util.Locale locale);
public String toPattern( );
// Public Methods Overriding Format
public Object clone( );
public final StringBuffer format(Object arguments, StringBuffer result,
FieldPosition pos);
1.4 public AttributedCharacterIterator
formatToCharacterIterator(Object arguments);
public Object parseObject(String source, ParsePosition pos);
// Public Methods Overriding Object
public boolean equals(Object obj);
public int hashCode( );
}
