Strings. It is guaranteed that any
* String produced by a concrete subclass of Format
* will be parseable by that same subclass.
*
* In addition to implementing the abstract methods in this class, subclasses
* should provide static factory methods of the form
* getInstance() and getInstance(Locale) if the
* subclass loads different formatting/parsing schemes based on locale.
* These subclasses should also implement a static method called
* getAvailableLocales() which returns an array of
* available locales in the current runtime environment.
*
* @author Aaron M. Renn (arenn@urbanophile.com)
* @author Per Bothner (bothner@cygnus.com)
*/
public abstract class Format implements Serializable, Cloneable
{
/**
* For compatability with Sun's JDK 1.4.2 rev. 5
*/
static final long serialVersionUID = -299282585814624189L;
public static class Field extends AttributedCharacterIterator.Attribute
{
static final long serialVersionUID = 276966692217360283L;
protected Field(String name)
{
super(name);
}
}
/**
* This method initializes a new instance of Format.
* It performs no actions, but acts as a default constructor for
* subclasses.
*/
protected Format ()
{
}
/**
* This method formats an Object into a String.
*
* @param obj The Object to format.
*
* @return The formatted String.
*
* @exception IllegalArgumentException If the Object
* cannot be formatted.
*/
public final String format(Object obj) throws IllegalArgumentException
{
StringBuffer sb = new StringBuffer ();
format (obj, sb, new FieldPosition (0));
return sb.toString ();
}
/**
* This method formats an Object into a String and
* appends the String to a StringBuffer.
*
* @param obj The Object to format.
* @param sb The StringBuffer to append to.
* @param pos The desired FieldPosition, which is also
* updated by this call.
*
* @return The updated StringBuffer.
*
* @exception IllegalArgumentException If the Object
* cannot be formatted.
*/
public abstract StringBuffer format (Object obj, StringBuffer sb,
FieldPosition pos)
throws IllegalArgumentException;
/**
* This method parses a String and converts the parsed
* contents into an Object.
*
* @param str The String to parse.
*
* @return The resulting Object.
*
* @exception ParseException If the String cannot be parsed.
*/
public Object parseObject (String str) throws ParseException
{
ParsePosition pos = new ParsePosition(0);
Object result = parseObject (str, pos);
if (result == null)
{
int index = pos.getErrorIndex();
if (index < 0)
index = pos.getIndex();
throw new ParseException("parseObject failed", index);
}
return result;
}
/**
* This method parses a String and converts the parsed
* contents into an Object.
*
* @param str The String to parse.
* @param pos The starting parse index on input, the ending parse
* index on output.
*
* @return The parsed Object, or null in
* case of error.
*/
public abstract Object parseObject (String str, ParsePosition pos);
public AttributedCharacterIterator formatToCharacterIterator(Object obj)
{
return new FormatCharacterIterator(format(obj), null, null);
}
/**
* Creates a copy of this object.
*
* @return The copied Object.
*/
public Object clone ()
{
try
{
return super.clone ();
}
catch (CloneNotSupportedException e)
{
return null;
}
}
}