MessageFormat

MessageFormat

java.text

---

Java 1.1

cloneable serializable

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  ( );   }