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).
+ *
+ *
+ * Generally, a format's parseObject method must be able to parse
+ * any string formatted by its format method. However, there may
+ * be exceptional cases where this is not possible. For example, a
+ * format method might create two adjacent integer numbers with
+ * no separator in between, and in this case the parseObject could
+ * not tell which digits belong to which number.
+ *
+ *
+ * The Java Platform provides three specialized subclasses of Format--
+ * DateFormat, MessageFormat, and
+ * NumberFormat--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 additional format methods for
+ * specific input types as well as parse methods for specific
+ * result types. Any parse method that does not take a
+ * ParsePosition argument should throw ParseException
+ * when no text in the required format is at the beginning of the input text.
+ *
+ * + * Most subclasses will also implement the following factory methods: + *
getInstance for getting a useful format object appropriate
+ * for the current locale
+ * getInstance(Locale) for getting a useful format
+ * object appropriate for the specified locale
+ * 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 {@link DateFormat}.
+ *
+ *
+ * Formats 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. + * + * @see java.text.ParsePosition + * @see java.text.FieldPosition + * @see java.text.NumberFormat + * @see java.text.DateFormat + * @see java.text.MessageFormat + * @author Mark Davis + */ +public abstract class Format implements Serializable, Cloneable { + + private static final long serialVersionUID = -299282585814624189L; + + /** + * Sole constructor. (For invocation by subclass constructors, typically + * implicit.) + */ + protected Format() { + } + + /** + * Formats an object to produce a string. This is equivalent to + *
+ * {@link #format(Object, StringBuffer, FieldPosition) format}(obj,
+ * new StringBuffer(), new FieldPosition(0)).toString();
+ *
+ *
+ * @param obj The object to format
+ * @return Formatted string.
+ * @exception IllegalArgumentException if the Format cannot format the given
+ * object
+ */
+ public final String format (Object obj) {
+ return format(obj, new StringBuffer(), new FieldPosition(0)).toString();
+ }
+
+ /**
+ * Formats an object and appends the resulting text to a given string
+ * buffer.
+ * If the pos argument identifies a field used by the format,
+ * then its indices are set to the beginning and end of the first such
+ * field encountered.
+ *
+ * @param obj The object to format
+ * @param toAppendTo where the text is to be appended
+ * @param pos A FieldPosition identifying a field
+ * in the formatted text
+ * @return the string buffer passed in as toAppendTo,
+ * with formatted text appended
+ * @exception NullPointerException if toAppendTo or
+ * pos is null
+ * @exception IllegalArgumentException if the Format cannot format the given
+ * object
+ */
+ public abstract StringBuffer format(Object obj,
+ StringBuffer toAppendTo,
+ FieldPosition pos);
+
+ /**
+ * Formats an Object producing an AttributedCharacterIterator.
+ * You can use the returned AttributedCharacterIterator
+ * to 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 each Format implementation
+ * to define what the legal values are for each attribute in the
+ * AttributedCharacterIterator, but typically the attribute
+ * key is also used as the attribute value.
+ *
The default implementation creates an
+ * AttributedCharacterIterator with no attributes. Subclasses
+ * that support fields should override this and create an
+ * AttributedCharacterIterator with meaningful attributes.
+ *
+ * @exception NullPointerException if obj is null.
+ * @exception IllegalArgumentException when the Format cannot format the
+ * given object.
+ * @param obj The object to format
+ * @return AttributedCharacterIterator describing the formatted value.
+ * @since 1.4
+ */
+ public AttributedCharacterIterator formatToCharacterIterator(Object obj) {
+ return createAttributedCharacterIterator(format(obj));
+ }
+
+ /**
+ * 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 of pos is 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 updated pos can be used to
+ * indicate the starting point for the next call to this method.
+ * If an error occurs, then the index of pos is not
+ * changed, the error index of pos is set to the index of
+ * the character where the error occurred, and null is returned.
+ *
+ * @param source A String, part of which should be parsed.
+ * @param pos A ParsePosition object with index and error
+ * index information as described above.
+ * @return An Object parsed from the string. In case of
+ * error, returns null.
+ * @exception NullPointerException if pos is null.
+ */
+ public abstract Object parseObject (String source, ParsePosition pos);
+
+ /**
+ * 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.
+ *
+ * @param source A String whose beginning should be parsed.
+ * @return An Object parsed from the string.
+ * @exception ParseException if the beginning of the specified string
+ * cannot be parsed.
+ */
+ public Object parseObject(String source) throws ParseException {
+ ParsePosition pos = new ParsePosition(0);
+ Object result = parseObject(source, pos);
+ if (pos.index == 0) {
+ throw new ParseException("Format.parseObject(String) failed",
+ pos.errorIndex);
+ }
+ return result;
+ }
+
+ /**
+ * Creates and returns a copy of this object.
+ *
+ * @return a clone of this instance.
+ */
+ public Object clone() {
+ try {
+ return super.clone();
+ } catch (CloneNotSupportedException e) {
+ // will never happen
+ return null;
+ }
+ }
+
+ //
+ // Convenience methods for creating AttributedCharacterIterators from
+ // different parameters.
+ //
+
+ /**
+ * Creates an AttributedCharacterIterator for the String
+ * s.
+ *
+ * @param s String to create AttributedCharacterIterator from
+ * @return AttributedCharacterIterator wrapping s
+ */
+ AttributedCharacterIterator createAttributedCharacterIterator(String s) {
+ AttributedString as = new AttributedString(s);
+
+ return as.getIterator();
+ }
+
+ /**
+ * Creates an AttributedCharacterIterator containg the
+ * concatenated contents of the passed in
+ * AttributedCharacterIterators.
+ *
+ * @param iterators AttributedCharacterIterators used to create resulting
+ * AttributedCharacterIterators
+ * @return AttributedCharacterIterator wrapping passed in
+ * AttributedCharacterIterators
+ */
+ AttributedCharacterIterator createAttributedCharacterIterator(
+ AttributedCharacterIterator[] iterators) {
+ AttributedString as = new AttributedString(iterators);
+
+ return as.getIterator();
+ }
+
+ /**
+ * Returns an AttributedCharacterIterator with the String
+ * string and additional key/value pair key,
+ * value.
+ *
+ * @param string String to create AttributedCharacterIterator from
+ * @param key Key for AttributedCharacterIterator
+ * @param value Value associated with key in AttributedCharacterIterator
+ * @return AttributedCharacterIterator wrapping args
+ */
+ AttributedCharacterIterator createAttributedCharacterIterator(
+ String string, AttributedCharacterIterator.Attribute key,
+ Object value) {
+ AttributedString as = new AttributedString(string);
+
+ as.addAttribute(key, value);
+ return as.getIterator();
+ }
+
+ /**
+ * Creates an AttributedCharacterIterator with the contents of
+ * iterator and the additional attribute key
+ * value.
+ *
+ * @param iterator Initial AttributedCharacterIterator to add arg to
+ * @param key Key for AttributedCharacterIterator
+ * @param value Value associated with key in AttributedCharacterIterator
+ * @return AttributedCharacterIterator wrapping args
+ */
+ AttributedCharacterIterator createAttributedCharacterIterator(
+ AttributedCharacterIterator iterator,
+ AttributedCharacterIterator.Attribute key, Object value) {
+ AttributedString as = new AttributedString(iterator);
+
+ as.addAttribute(key, value);
+ return as.getIterator();
+ }
+
+
+ /**
+ * Defines constants that are used as attribute keys in the
+ * AttributedCharacterIterator returned
+ * from Format.formatToCharacterIterator and as
+ * field identifiers in FieldPosition.
+ *
+ * @since 1.4
+ */
+ public static class Field extends AttributedCharacterIterator.Attribute {
+
+ // Proclaim serial compatibility with 1.4 FCS
+ private static final long serialVersionUID = 276966692217360283L;
+
+ /**
+ * Creates a Field with the specified name.
+ *
+ * @param name Name of the attribute
+ */
+ protected Field(String name) {
+ super(name);
+ }
+ }
+
+
+ /**
+ * FieldDelegate is notified by the various Format
+ * implementations as they are formatting the Objects. This allows for
+ * storage of the individual sections of the formatted String for
+ * later use, such as in a FieldPosition or for an
+ * AttributedCharacterIterator.
+ *
+ * Delegates should NOT assume that the Format will notify
+ * the delegate of fields in any particular order.
+ *
+ * @see FieldPosition.Delegate
+ * @see CharacterIteratorFieldDelegate
+ */
+ interface FieldDelegate {
+ /**
+ * Notified when a particular region of the String is formatted. This
+ * method will be invoked if there is no corresponding integer field id
+ * matching attr.
+ *
+ * @param attr Identifies the field matched
+ * @param value Value associated with the field
+ * @param start Beginning location of the field, will be >= 0
+ * @param end End of the field, will be >= start and <= buffer.length()
+ * @param buffer Contains current formatted value, receiver should
+ * NOT modify it.
+ */
+ public void formatted(Format.Field attr, Object value, int start,
+ int end, StringBuffer buffer);
+
+ /**
+ * Notified when a particular region of the String is formatted.
+ *
+ * @param fieldID Identifies the field by integer
+ * @param attr Identifies the field matched
+ * @param value Value associated with the field
+ * @param start Beginning location of the field, will be >= 0
+ * @param end End of the field, will be >= start and <= buffer.length()
+ * @param buffer Contains current formatted value, receiver should
+ * NOT modify it.
+ */
+ public void formatted(int fieldID, Format.Field attr, Object value,
+ int start, int end, StringBuffer buffer);
+ }
+}