Previous | Next | Trail Map | Writing Global Programs | Locale-Sensitive Data


The Format Classes

The Format class is an abstract base class that defines the API for formatting and parsing locale-sensitive data. Format declares two important methods: format whichs formats locale-sensitive objects into Strings, and parseObject which parses Strings back into objects. Anything that was formatted by format is guaranteed to be parseable by parseObject.

JDK 1.1 provides several subclasses of Format including intermediate abstract classes that define the programming interface for formatting and parsing specific types of data, and concrete classes that implement those APIs. Here's a class hierarchy diagram of Format and its descendents:

NumberFormat and DateFormat are both abstract subclasses of Format. NumberFormat defines the interface for formatting and parsing numerical data such as 9.23458, .34, 54%, and 23. DateFormat defines the interface for formatting and parsing date and time such as 25 May 96, 12:56 PM, and so on.

The JDK provides concrete subclasses of both NumberFormat and DateFormat because both are abstract and don't implement any formatting scheme themselves.

The JDK implements two concrete subclasses of NumberFormat: DecimalFormat that formats decimal numbers, and ChoiceFormat that formats a number by choosing the resulting format from a range-specified list of options. These two concrete classes implement locale-sensitive formatting and parsing for a comprehensive set of locales. To find out the list of supported Locales call the getAvailableLocales method.

SimpleDateFormat is the JDK's 1.1 concrete implementation of a DateFormat. SimpleDateFormat formats dates and times based on the Gregorian calendar. As with the number format classes, SimpleDateFormat supports a comprehensive set of locales. To find out the list of supported Locales call the getAvailableLocales method.

The final descendent of Format is MessageFormat. MessageFormat is a concrete class and provides a means to produce concatenated messages in language-neutral way. Use this to construct messages displayed for end users.

Getting a Formatter

The JDK formatters provide the locale-sensitive formatting for dates, times, numbers, and messages that is designed to be useful to most programmers, their data, and their formatting needs. Thus most programmers will use one of the formatters provided by the JDK (rather than writing their own).

The most convenient way of getting a generally useful formatter is to call one of the factory methods provided by the abstract parent class for the data type you want to format. For example, to get a formatter for formatting a date, call one of the getXxxxxInstance factory methods provided by DateFormat. Similarly, to get a formatter for formatting a number, call one of the getXxxxxInstance factory methods provided by NumberFormat.

So why not instantiate a formatter directly using a concrete class's constructor method? Well, the formatters are customizable and require a fair amount of initialization. Most programmers just want to format a date or number in the "normal" way and get on with writing the rest of their program. So, to make programmers' lives easier, the abstract format classes provide factory methods that you can use to create already-initialized formatters. The formatters provided by these factory methods format the data in a way that most programmers want.

The abstract format classes often provide several factory methods so that you can choose from among a group of already-initialized formatters. For example, to get a already-initialized formatter to format a date use DateFormat.getDateInstance, to get a time formatter use DateFormat.getTimeInstance. Similarly, to get a formatter to format a money value use NumberFormat.getCurrencyInstance and to get a formatter to format a percentage value use NumberFormat.getPercentInstance. Additionally, some factory methods take arguments that let you further control some formatter options. For instance, the DateFormat factory methods lets you specify the time or date style from a short list. The formatters also let you set the Locale for which the data should be formatted.

If the factory methods don't provide a formatter that suits your needs, you can

The MessageFormat class is an exception to this rule. Messages are all different so there is no notion of "the message that most programmers want". So to format messages, you either instantiate a MessageFormat using its constructors or you use the class method MessageFormat.format.

Using a Formatter

Once you've got a formatter, you can use it to format your data. Call its format method and pass in an object to be formatted:
myFormatter.format(objectToFormat);
The format method returns a String that contains the result of formatting the object. This String can be used as a GUI label, error message, or other item displayed to the user.

You can also use a formatter to parse a String that was generated by the formatter:

myFormatter.parse(formattedString);
parse returns an Object of the appropriate type. The Object contains the data value represented by the String contents. If the string was formatted by the formatter, it is guaranteed to be parseable.


Previous | Next | Trail Map | Writing Global Programs | Locale-Sensitive Data