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
.Note: In the standardFormat
class, theparse
methods either accept aParsePosition
argument and returnsnull
on error, or does not take position argument and throws aParseException
on error. In thisCompoundFormat
class, theparse
method both takes aParsePosition
argument and throws aParseException
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 on ROOT
locale.locale
- The locale to use for numbers, dates and angles formatting,
or null
for the root locale.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
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.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.Example: If parsing of theThis error offset policy is a consequence of the compound nature of"30.0 40,0"
coordinate fails on the coma in the last number, then thepos
error index will be set to 5 (the beginning of the"40.0"
character sequence) while theParseException
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.
Note: The usual SIS policy, as documented in theCharSequences
class, is to test for whitespaces using theCharacters.isWhitespace(…)
method. The combination ofisSpaceChar(…)
andisISOControl(…)
done in thisparseObject(…)
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 in the given appender.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
.
Note: Strictly speaking, anIOException
could still occur if a subclass overrides the aboveformat
method and performs some I/O operation outside the givenStringBuffer
. 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.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 |
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–2013 The Apache Software Foundation. All rights reserved.