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.
Figure 15-12. java.text.MessageFormat
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 ( );
}