Class java.text.Format

  • Article

Class Members | This Package | All Packages

java.lang.Object
   |
   +----java.text.Format

public abstract class Format** extends Object
implements Serializable, Cloneable

Format is an abstract base class for formatting locale-sensitive information such as dates, messages, and numbers.

Format defines the programming interface for formatting locale-sensitive objects into Strings (the format method) and for parsing Strings back into objects (the parseObject method). Any String formatted by format is guaranteed to be parseable by parseObject.

If formatting is unsuccessful because the Format object cannot format the type of object specified, format throws an IllegalArgumentException. Otherwise, if there is something illformed about the object, format returns the Unicode replacement character \\uFFFD.

If there is no match when parsing, parseObject(String) throws a ParseException, and parseObject(String, ParsePosition) leaves the ParsePositionindex member unchanged and returns null.

Subclassing: The JDK provides three concrete subclasses of Format-- DateFormat, MessageFormat, and NumberFormat--for formatting dates, messages, and numbers, respectively.

Concrete subclasses must implement these two methods:

  1. format(Object obj, StringBuffer toAppendTo, FieldPosition pos)
  2. parseObject (String source, ParsePosition pos)

Most subclasses will also implement the following two methods:

  1. getInstance for getting a useful format object appropriate for the current locale
  2. getInstance(Locale) for getting a useful format object appropriate for the specified locale

In addition, some subclasses may also choose to implement other getXxxxInstance methods for more specialized control. For example, the NumberFormat class provides getPercentInstance and getCurrencyInstance methods for getting specialized number formatters.

Subclasses of Format that allow programmers to create objects for locales (with getInstance(Locale) for example) must also implement the following class method:

 public static Locale[] getAvailableLocales()

And finally subclasses may define a set of constants to identify the various fields in the formatted output. These constants are used to create a FieldPosition object which identifies what information is contained in the field and its position in the formatted result. These constants should be named item_FIELD where item identifies the field. For examples of these constants, see ERA_FIELD and its friends in DateFormat.