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.
Subclasses can obtain instances of those formats by call to getFormat(Class)
where
the argument is the type of the value to parse or format.
CompoundFormat
supports at least the following value types, but subclasses may add more types:
Value type | Format type | Remarks |
---|---|---|
DirectPosition | CoordinateFormat | Requires sis-referencing module. |
Angle | AngleFormat | |
Date | DateFormat | Timezone specified by getTimeZone() . |
Number | NumberFormat | |
Unit | UnitFormat | |
Range | RangeFormat | |
Class | (internal) |
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.
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.
|
Locale |
getLocale(Locale.Category category)
Returns the locale for the given category.
|
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.public Locale getLocale(Locale.Category category)
Locale.Category.FORMAT
specifies the locale to use for numbers, dates and angles formatting.Locale.Category.DISPLAY
specifies the locale to use for CodeList
labels
and InternationalString
contents.Locale.ROOT
while it allows informative texts (remarks, etc.) to be formatted according the
user's locale. Consequently WKTFormat
fixes (usually) the locale for Category.FORMAT
to
Locale.ROOT
and let Category.DISPLAY
be any locale.getLocale()
.category
- the category for which a locale is desired.null
).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.null
, orParseException
is thrown with an error offset
set to the index of the first unparsable character.ParseException
is thrown, its error offset is usually the same than the ParsePosition
error index, but implementations are free to adopt a slightly different policy. For example
if parsing of the "30.0 40,0"
coordinate fails on the coma in the last number, then the pos
error index may be set to 5 (the beginning of the "40.0"
character sequence) or to 7 (the coma position), depending on the implementation.null
. However some implementations may choose to return null
if they can determine that the given text is not a supported format and reserve ParseException
for the
cases where the text seems to be the expected format but contains a malformed element.text
- the character sequence for the object to parse.pos
- the position where to start the parsing.
On return, the position where the parsing stopped or where an error occurred.null
if the text is not recognized.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)
.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 class given in argument can be any of the classes listed in the "Value type" column below:
Value type | Format type |
---|---|
DirectPosition | CoordinateFormat |
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–2017 The Apache Software Foundation. All rights reserved.