- java.lang.Object
- 
- java.text.Format
 
- 
- All Implemented Interfaces:
- Serializable,- Cloneable
 - Direct Known Subclasses:
- DateFormat,- MessageFormat,- NumberFormat
 
 public abstract class Format extends Object implements Serializable, Cloneable Formatis an abstract base class for formatting locale-sensitive information such as dates, messages, and numbers.Formatdefines the programming interface for formatting locale-sensitive objects intoStrings (theformatmethod) and for parsingStrings back into objects (theparseObjectmethod).Generally, a format's parseObjectmethod must be able to parse any string formatted by itsformatmethod. However, there may be exceptional cases where this is not possible. For example, aformatmethod might create two adjacent integer numbers with no separator in between, and in this case theparseObjectcould not tell which digits belong to which number.SubclassingThe Java Platform provides three specialized subclasses of Format--DateFormat,MessageFormat, andNumberFormat--for formatting dates, messages, and numbers, respectively.Concrete subclasses must implement three methods: -  format(Object obj, StringBuffer toAppendTo, FieldPosition pos)
-  formatToCharacterIterator(Object obj)
-  parseObject(String source, ParsePosition pos)
 MessageFormat. Subclasses often also provide additionalformatmethods for specific input types as well asparsemethods for specific result types. Anyparsemethod that does not take aParsePositionargument should throwParseExceptionwhen no text in the required format is at the beginning of the input text.Most subclasses will also implement the following factory methods: - 
 getInstancefor getting a useful format object appropriate for the current locale
- 
 getInstance(Locale)for getting a useful format object appropriate for the specified locale
 getXxxxInstancemethods for more specialized control. For example, theNumberFormatclass providesgetPercentInstanceandgetCurrencyInstancemethods for getting specialized number formatters.Subclasses of Formatthat allow programmers to create objects for locales (withgetInstance(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_FIELDwhereitemidentifies the field. For examples of these constants, seeERA_FIELDand its friends inDateFormat.SynchronizationFormats are generally not synchronized. It is recommended to create separate format instances for each thread. If multiple threads access a format concurrently, it must be synchronized externally. - Since:
- 1.1
- See Also:
- ParsePosition,- FieldPosition,- NumberFormat,- DateFormat,- MessageFormat, Serialized Form
 
- 
- 
Nested Class SummaryNested Classes Modifier and Type Class Description static classFormat.FieldDefines constants that are used as attribute keys in theAttributedCharacterIteratorreturned fromFormat.formatToCharacterIteratorand as field identifiers inFieldPosition.
 - 
Constructor SummaryConstructors Modifier Constructor Description protectedFormat()Sole constructor.
 - 
Method SummaryAll Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description Objectclone()Creates and returns a copy of this object.Stringformat(Object obj)Formats an object to produce a string.abstract StringBufferformat(Object obj, StringBuffer toAppendTo, FieldPosition pos)Formats an object and appends the resulting text to a given string buffer.AttributedCharacterIteratorformatToCharacterIterator(Object obj)Formats an Object producing anAttributedCharacterIterator.ObjectparseObject(String source)Parses text from the beginning of the given string to produce an object.abstract ObjectparseObject(String source, ParsePosition pos)Parses text from a string to produce an object.
 
- 
- 
- 
Method Detail- 
formatpublic final String format(Object obj) Formats an object to produce a string. This is equivalent toformat(obj, new StringBuffer(), new FieldPosition(0)).toString();- Parameters:
- obj- The object to format
- Returns:
- Formatted string.
- Throws:
- IllegalArgumentException- if the Format cannot format the given object
 
 - 
formatpublic abstract StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos) Formats an object and appends the resulting text to a given string buffer. If theposargument identifies a field used by the format, then its indices are set to the beginning and end of the first such field encountered.- Parameters:
- obj- The object to format
- toAppendTo- where the text is to be appended
- pos- A- FieldPositionidentifying a field in the formatted text
- Returns:
- the string buffer passed in as toAppendTo, with formatted text appended
- Throws:
- NullPointerException- if- toAppendToor- posis null
- IllegalArgumentException- if the Format cannot format the given object
 
 - 
formatToCharacterIteratorpublic AttributedCharacterIterator formatToCharacterIterator(Object obj) Formats an Object producing anAttributedCharacterIterator. You can use the returnedAttributedCharacterIteratorto build the resulting String, as well as to determine information about the resulting String.Each attribute key of the AttributedCharacterIterator will be of type Field. It is up to eachFormatimplementation to define what the legal values are for each attribute in theAttributedCharacterIterator, but typically the attribute key is also used as the attribute value.The default implementation creates an AttributedCharacterIteratorwith no attributes. Subclasses that support fields should override this and create anAttributedCharacterIteratorwith meaningful attributes.- Parameters:
- obj- The object to format
- Returns:
- AttributedCharacterIterator describing the formatted value.
- Throws:
- NullPointerException- if obj is null.
- IllegalArgumentException- when the Format cannot format the given object.
- Since:
- 1.4
 
 - 
parseObjectpublic abstract Object parseObject(String source, ParsePosition pos) Parses text from a string to produce an object.The method attempts to parse text starting at the index given by pos. If parsing succeeds, then the index ofposis updated to the index after the last character used (parsing does not necessarily use all characters up to the end of the string), and the parsed object is returned. The updatedposcan be used to indicate the starting point for the next call to this method. If an error occurs, then the index ofposis not changed, the error index ofposis set to the index of the character where the error occurred, and null is returned.- Parameters:
- source- A- String, part of which should be parsed.
- pos- A- ParsePositionobject with index and error index information as described above.
- Returns:
- An Objectparsed from the string. In case of error, returns null.
- Throws:
- NullPointerException- if- sourceor- posis null.
 
 - 
parseObjectpublic Object parseObject(String source) throws ParseException Parses text from the beginning of the given string to produce an object. The method may not use the entire text of the given string.- Parameters:
- source- A- Stringwhose beginning should be parsed.
- Returns:
- An Objectparsed from the string.
- Throws:
- ParseException- if the beginning of the specified string cannot be parsed.
- NullPointerException- if- sourceis null.
 
 
- 
 
-