T
- The base type of objects parsed and formatted by this class.public abstract class CompoundFormat<T> extends Format implements Localized
Format
implementations which delegate part of their work to other
Format
instances. CompoundFormat
subclasses typically work on relatively
large blocks of data, for example a metadata tree or a Well Known Text (WKT).
Those blocks of data usually contain smaller elements like numbers and dates, whose parsing
and formatting can be delegated to NumberFormat
and DateFormat
respectively.
Since CompoundFormat
may work on larger texts than the usual Format
classes,
it defines parse
and format
methods working with arbitrary CharSequence
and Appendable
instances. The standard Format
methods redirect to the above-cited
methods.
The abstract methods to be defined by subclasses are:
getValueType()
returns the <T>
class or a subclass.parse(CharSequence, ParsePosition)
may throws ParseException
.format(Object, Appendable)
may throws IOException
.Format
class, the parse
methods either accept a ParsePosition
argument
and returns null
on error, or does not take position argument and throws a ParseException
on error.
In this CompoundFormat
class, the parse
method both takes a ParsePosition
argument and
throws a ParseException
on error. This allows both substring parsing and more accurate exception message
in case of error.Defined in the sis-utility
module
Format.Field
Modifier | Constructor and Description |
---|---|
protected |
CompoundFormat(Locale locale,
TimeZone timezone)
Creates a new format for the given locale.
|
Modifier and Type | Method and Description |
---|---|
CompoundFormat<T> |
clone()
Returns a clone of this format.
|
protected Format |
createFormat(Class<?> valueType)
Creates a new format to use for parsing and formatting values of the given type.
|
StringBuffer |
format(Object object,
StringBuffer toAppendTo,
FieldPosition pos)
Writes a textual representation of the specified object in the given buffer.
|
abstract void |
format(T object,
Appendable toAppendTo)
Writes a textual representation of the given object in the given stream or buffer.
|
protected Format |
getFormat(Class<?> valueType)
Returns the format to use for parsing and formatting values of the given type.
|
Locale |
getLocale()
Returns the locale used by this format.
|
TimeZone |
getTimeZone()
Returns the timezone used by this format.
|
abstract Class<? extends T> |
getValueType()
Returns the base type of values parsed and formatted by this
Format instance. |
abstract T |
parse(CharSequence text,
ParsePosition pos)
Creates an object from the given character sequence.
|
T |
parseObject(String text)
Creates an object from the given string representation.
|
T |
parseObject(String text,
ParsePosition pos)
Creates an object from the given string representation, or returns
null if an error
occurred while parsing. |
format, formatToCharacterIterator
protected CompoundFormat(Locale locale, TimeZone timezone)
null
or
Locale.ROOT
if this format shall parse and format "unlocalized" strings.
See getLocale()
for more information about the ROOT
locale.locale
- The locale for the new Format
, or null
for Locale.ROOT
.timezone
- The timezone, or null
for UTC.public Locale getLocale()
Locale.ROOT
if this format does not apply any localization. The definition of "unlocalized string"
is implementation-dependent, but some typical examples are:
getLocale
in interface Localized
Format
, or Locale.ROOT
for unlocalized format.getLocale()
public TimeZone getTimeZone()
public abstract Class<? extends T> getValueType()
Format
instance.
The returned type may be a subclass of <T>
if the format is configured in a way
that restrict the kind value to be parsed.
StatisticsFormat
unconditionally returns Statistics.class
.TreeTableFormat
unconditionally returns TreeTable.class
.Format
instance.public abstract T parse(CharSequence text, ParsePosition pos) throws ParseException
pos
argument.
If parsing succeeds, then:
pos
index is updated to the index
after the last successfully parsed character.pos
index is left unchangedpos
error index
is set to the beginning of the unparsable character sequence.ParseException
is thrown with an
error offset relative to the above-cited
pos
error index. Consequently the exact error location is pos
error index + ParseException
error offset."30.0 40,0"
coordinate fails on the coma in the last number, then the pos
error index will be set to 5 (the beginning of the "40.0"
character sequence) while the
ParseException
error offset will be set to 2 (the coma position relative the beginning
of the "40.0"
character sequence).CompoundFormat
,
since the exception may have been produced by a call to Format.parseObject(String)
.text
- The character sequence for the object to parse.pos
- The position where to start the parsing.ParseException
- If an error occurred while parsing the object.public T parseObject(String text, ParsePosition pos)
null
if an error
occurred while parsing. The parsing begins at the index given by the pos
argument.
If parsing succeeds, then:
pos
index is updated to the index
after the last successfully parsed character.pos
index is left unchangedpos
error index
is set to the index of the character where the error occurred.null
is returned.parse(CharSequence, ParsePosition)
.
In case of failure, the exception error offset is added
to the pos
error index.parseObject
in class Format
text
- The string representation of the object to parse.pos
- The position where to start the parsing.null
if the given string can not be parsed.public T parseObject(String text) throws ParseException
parse(CharSequence, ParsePosition)
and ensures that the given string has been fully used, ignoring trailing
spaces and
ISO control characters.
CharSequences
class, is to test for
whitespaces using the Character.isWhitespace(…)
method. The combination of isSpaceChar(…)
and isISOControl(…)
done in this parseObject(…)
method is more permissive since it encompasses
all whitespace characters, plus non-breaking spaces and non-white ISO controls.parseObject
in class Format
text
- The string representation of the object to parse.ParseException
- If an error occurred while parsing the object.public abstract void format(T object, Appendable toAppendTo) throws IOException
object
- The object to format.toAppendTo
- Where to format the object.IOException
- If an error occurred while writing to the given appendable.public StringBuffer format(Object object, StringBuffer toAppendTo, FieldPosition pos)
format(Object, Appendable)
, but
without propagating IOException
. The I/O exception should never
occur since we are writing in a StringBuffer
.
IOException
could still occur if a subclass overrides the above format
method and performs some I/O operation outside the given StringBuffer
. However this is not the intended
usage of this class and implementors should avoid such unexpected I/O operation.protected Format getFormat(Class<?> valueType)
null
.createFormat(Class)
for the list of value types recognized by the default
CompoundFormat
implementation.valueType
- The base type of values to parse or format, or null
if unknown.null
if none.protected Format createFormat(Class<?> valueType)
getFormat(Class)
the first time that a format
is needed for the given type.
The default implementation creates the following formats:
Value type | Format |
---|---|
Angle | AngleFormat |
Date | DateFormat |
Number | NumberFormat |
Unit | UnitFormat |
Range | RangeFormat |
Class | (internal) |
Format
instances. Note that implementations shall check the
type using the expected == type
comparator, not
expected.isAssignableFrom(type)
,
because the check for parent types is done by the getFormat(Class)
method.
This approach allows subclasses to create specialized formats for different value
sub-types. For example a subclass may choose to format Double
values differently
than other types of number.valueType
- The base type of values to parse or format.null
if none.public CompoundFormat<T> clone()
Copyright © 2010–2015 The Apache Software Foundation. All rights reserved.