Chapter 16
The java.text Package

MessageFormat

Name

MessageFormat

Synopsis

Class Name:

java.text.MessageFormat

Superclass:

java.text.Format

Immediate Subclasses:

None

Interfaces Implemented:

None

Availability:

New as of JDK 1.1

The MessageFormat class constructs textual messages using a formatting pattern string. Conceptually, the class functions much like printf() in C. Syntactically, however, it is quite different. A MessageFormat object uses a pattern string; formatted arguments are placed into the pattern string to produce a resulting string. Arguments are delimited by matching sets of curly braces and may include additional information about how that data should be formatted. For example, consider the following code:

String message = 
  "Boot of server {0}began at {1, time}on {1, date, full}.";
MessageFormat boot = new MessageFormat(message);
Date now = new Date();
Object[] arguments = {"luna3", now};
System.out.println(boot.format(arguments));

This code produces the following output:

Boot of server luna3 began at 11:13:22 AM on Monday, March 03, 1997.

Each of the arguments is numbered and includes an optional type and an optional style. In the example above, {1, date, full} indicates that the argument at index 1 in the argument array should be formatted using a DateFormat object with the FULL style. The allowed types and styles are:

Type	Object	Styles
`choice`	`ChoiceFormat`	pattern
`date`	`DateFormat`	`short`, `medium`, `long`, `full`, pattern
`number`	`NumberFormat`	`integer`, `percent`, `currency`, pattern
`time`	`DateFormat`	`short`, `medium`, `long`, `full`, pattern

For the date and time types, the styles correspond to the styles, or lengths, of the resulting date and time strings. You can also specify a date or time pattern string as you would for creating a SimpleDateFormat object. For the number type, the styles correspond to formatting normal numbers, percentage values, and currency values. You can also specify a number pattern string as you would for creating a DecimalFormat object. For the choice type, you can specify a choice pattern as you would for creating a ChoiceFormat object. If no type is specified, the argument should be a string.

The following example shows how to use a choice format pattern with a MessageFormat:

Object[] arguments = {new Integer(1)};
String grammar = "At last count, {0}server{0, choice, 0#s|1#|1<s}
 {0, choice, 0#were|1#was|1<were}booted.";
MessageFormat booted = new MessageFormat(grammar);
System.out.println(booted.format(arguments));
arguments[0] = new Integer(2);
System.out.println(booted.format(arguments));

This example produces the following output:

At last count, 1 server was booted.
At last count, 2 servers were booted.

As an alternative to specifying all of the formatting in the pattern string, you can use an array of Format objects to format the arguments. You can specify this array using setFormats().

Note that you create MessageFormat objects directly, rather than through factory methods. This is because MessageFormat does not implement any locale-specific behavior. To produce properly internationalized output, the pattern string that is used to construct a MessageFormat should come from a ResourceBundle instead of being embedded in the code.

Class Summary

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

Constructors

MessageFormat

public MessageFormat(String pattern)

Parameters

pattern: The pattern string.

Description

This constructor creates a MessageFormat with the given formatting pattern string.

Class Methods

format

public static String format(String pattern, Object[] arguments)

Parameters

pattern

The pattern string.

arguments

An array of arguments.

Description

Calling this static method is equivalent to constructing a MessageFormat using the given formatting pattern string and asking it to format the given arguments with the format() method.

Instance Methods

applyPattern

public void applyPattern(String pattern)

Parameters

pattern: The pattern string.

Description

This method tells this MessageFormat to use the given formatting pattern to format and parse arguments.

clone

public Object clone()

Returns

A copy of this MessageFormat.

Overrides

Format.clone()

Description

This method creates a copy of this MessageFormat and then returns it.

equals

public boolean equals(Object obj)

Parameters

obj: The object to be compared with this object.

Returns

true if the objects are equal; false if they are not.

Overrides

Format.equals()

Description

This method returns true if obj is an instance of MessageFormat and is equivalent to this MessageFormat.

format

 public StringBuffer format(Object source, StringBuffer result, FieldPosition ignore)

Parameters

source

The object to be formatted.

result

A StringBuffer on which to append the formatted information.

ignore

Ignored.

Returns

The given buffer result with the formatted representation of the object appended to it.

Overrides

Format.format(Object, StringBuffer, FieldPosition)

Description

This method formats the given object and appends the result to the given StringBuffer. The method assumes that the given object is an array of arguments.

 public StringBuffer format(Object[] source, StringBuffer result, FieldPosition ignore)

Parameters

source

The object array to be formatted.

result

A StringBuffer on which to append the formatted information.

ignore

Ignored.

Returns

The given buffer result with the formatted representation of the object array appended to it.

Description

This method formats the given arguments in the object array and appends the result to the given StringBuffer.

getFormats

public Format[] getFormats()

Returns

An array of the formats used by this MessageFormat.

Description

This method returns the format objects that this MessageFormat uses. Note that formats are numbered according to the order in which they appear in the formatting pattern string, not according to their specified argument numbers.

getLocale

public Locale getLocale()

Returns

The Locale of this MessageFormat.

Description

This method returns the locate for this MessageFormat. This locale is used to get default date, time, and number formatters.

hashCode

public int hashCode()

Returns

A hashcode for this object.

Overrides

Object.hashCode()

Description

This method returns a hashcode for this MessageFormat.

parse

public Object[] parse(String source) throws ParseException

Parameters

source: The string to be parsed.

Returns

An array of objects represented by the given string.

Throws

ParseException: If the text cannot be parsed.

Description

This method parses arguments from the given string, which should be in the format given by the formatting pattern string of this MessageFormat. If the string is not correctly formatted, an exception is thrown.

public Object[] parse(String source, ParsePosition status)

Parameters

source

The string to be parsed.

status

A ParsePosition object that specifies a position in the string.

Returns

An array of objects represented by the test starting at the given position.

Description

This method parses arguments from the given string, starting at the specified position. The string should be in the format given by the formatting pattern string of this MessageFormat.

parseObject

public Object parseObject(String text, ParsePosition status)

Parameters

text

The string to be parsed.

status

A ParsePosition object that specifies a position in the string.

Returns

The object represented by the test starting at the given position.

Overrides

Format.parseObject(String, ParsePosition)

Description

This method parses arguments from the given string, starting at the specified position. The string should be in the format given by the formatting pattern string of this MessageFormat.

setFormat

public void setFormat(int variable, Format newFormat)

Parameters

variable

The index of an argument in the pattern string.

newFormat

The format object to use.

Description

This method sets the Format object that is used for the given argument in the formatting pattern string.

setFormats

public void setFormats(Format[] newFormats)

Parameters

newFormats: The format objects to use.

Description

This method sets the Format objects that format the arguments of this MessageFormat. Note that formats are numbered according to the order in which they appear in the formatting pattern string, not according to their specified argument numbers.

setLocale

public void setLocale(Locale theLocale)

Parameters

theLocale: The new locale.

Description

This method sets the Locale object that generates the default date, time, and number format objects.

toPattern

public String toPattern()

Returns

The pattern string of this MessageFormat.

Description

This method returns the pattern string of this MessageFormat.

Inherited Methods

Method	Inherited From	Method	Inherited From
`finalize()`	`Object`	`format(Object)`	`Format`
`getClass()`	`Object`	`notify()`	`Object`
`notifyAll()`	`Object`	`parseObject(String)`	`Format`
`toString()`	`Object`	`wait()`	`Object`
`wait(long)`	`Object`	`wait(long, int)`	`Object`