Package org.apache.sis.io
Class CompoundFormat<T>
-
- Type Parameters:
T
- the base type of objects parsed and formatted by this class.
- All Implemented Interfaces:
Serializable
,Cloneable
,Localized
- Direct Known Subclasses:
CoordinateFormat
,TabularFormat
,WKTFormat
public abstract class CompoundFormat<T> extends Format implements Localized
Base class ofFormat
implementations which delegate part of their work to otherFormat
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 toNumberFormat
andDateFormat
respectively. Subclasses can obtain instances of those formats by call togetFormat(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:Supported value 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) Sources and destinationsSinceCompoundFormat
may work on larger texts than the usualFormat
classes, it definesparse
andformat
methods working with arbitraryCharSequence
andAppendable
instances. The standardFormat
methods redirect to the above-cited methods.Sub-classingThe abstract methods to be defined by subclasses are:API 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.- Since:
- 0.3
- See Also:
- Serialized Form
Defined in the
sis-utility
module
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from class Format
Format.Field
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
CompoundFormat(Locale locale, TimeZone timezone)
Creates a new format for the given locale.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method 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 thisFormat
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 returnsnull
if an error occurred while parsing.-
Methods inherited from class Format
format, formatToCharacterIterator
-
-
-
-
Constructor Detail
-
CompoundFormat
protected CompoundFormat(Locale locale, TimeZone timezone)
Creates a new format for the given locale. The given locale can benull
orLocale.ROOT
if this format shall parse and format "unlocalized" strings. SeegetLocale()
for more information about theROOT
locale.- Parameters:
locale
- the locale for the newFormat
, ornull
forLocale.ROOT
.timezone
- the timezone, ornull
for UTC.
-
-
Method Detail
-
getLocale
public Locale getLocale()
Returns the locale used by this format. The returned value may beLocale.ROOT
if this format does not apply any localization. The definition of "unlocalized string" is implementation-dependent, but some typical examples are:- Specified by:
getLocale
in interfaceLocalized
- Returns:
- the locale of this
Format
, orLocale.ROOT
for unlocalized format.
-
getLocale
public Locale getLocale(Locale.Category category)
Returns the locale for the given category. Subclasses may override this method in order to assign different roles to the different locale categories. A typical (but not mandatory) mapping is:Locale.Category.FORMAT
specifies the locale to use for numbers, dates and angles formatting.Locale.Category.DISPLAY
specifies the locale to use forCodeList
labels andInternationalString
contents.
Example: The ISO 19162 (Well Known Text) standard requires a number format similar to the one defined byFor subclasses that do not override this method, the default implementation returnsLocale.ROOT
while it allows informative texts (remarks, etc.) to be formatted according the user's locale. ConsequentlyWKTFormat
fixes (usually) the locale forCategory.FORMAT
toLocale.ROOT
and letCategory.DISPLAY
be any locale.getLocale()
.- Parameters:
category
- the category for which a locale is desired.- Returns:
- the locale for the given category (never
null
). - Since:
- 0.4
-
getTimeZone
public TimeZone getTimeZone()
Returns the timezone used by this format.- Returns:
- the timezone used for this format, or UTC for unlocalized format.
-
getValueType
public abstract Class<? extends T> getValueType()
Returns the base type of values parsed and formatted by thisFormat
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.Example:StatisticsFormat
unconditionally returnsStatistics.class
.TreeTableFormat
unconditionally returnsTreeTable.class
.
- Returns:
- the base type of values parsed and formatted by this
Format
instance.
-
parse
public abstract T parse(CharSequence text, ParsePosition pos) throws ParseException
Creates an object from the given character sequence. The parsing begins at the index given by thepos
argument. If parsing succeeds, then:- The
pos
index is updated to the index after the last successfully parsed character. - The parsed object is returned.
- The
pos
index is left unchanged - The
pos
error index is set to the beginning of the unparsable character sequence. - One of the following actions is taken (at implementation choice):
- this method returns
null
, or - a
ParseException
is thrown with an error offset set to the index of the first unparsable character.
- this method returns
Note: if aMost implementations never returnParseException
is thrown, its error offset is usually the same than theParsePosition
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 thepos
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 returnnull
if they can determine that the given text is not a supported format and reserveParseException
for the cases where the text seems to be the expected format but contains a malformed element.- Parameters:
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.- Returns:
- the parsed object, or
null
if the text is not recognized. - Throws:
ParseException
- if an error occurred while parsing the object.
- The
-
parseObject
public T parseObject(String text, ParsePosition pos)
Creates an object from the given string representation, or returnsnull
if an error occurred while parsing. The parsing begins at the index given by thepos
argument. If parsing succeeds, then:- The
pos
index is updated to the index after the last successfully parsed character. - The parsed object is returned.
- The
pos
index is left unchanged - The
pos
error index is set to the index of the character where the error occurred. null
is returned.
parse(CharSequence, ParsePosition)
.- Specified by:
parseObject
in classFormat
- Parameters:
text
- the string representation of the object to parse.pos
- the position where to start the parsing.- Returns:
- the parsed object, or
null
if the given string can not be parsed.
- The
-
parseObject
public T parseObject(String text) throws ParseException
Creates an object from the given string representation. The default implementation delegates toparse(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 theCharacter.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.- Overrides:
parseObject
in classFormat
- Parameters:
text
- the string representation of the object to parse.- Returns:
- the parsed object.
- Throws:
ParseException
- if an error occurred while parsing the object.
-
format
public abstract void format(T object, Appendable toAppendTo) throws IOException
Writes a textual representation of the given object in the given stream or buffer.- Parameters:
object
- the object to format.toAppendTo
- where to format the object.- Throws:
IOException
- if an error occurred while writing to the given appendable.
-
format
public StringBuffer format(Object object, StringBuffer toAppendTo, FieldPosition pos)
Writes a textual representation of the specified object in the given buffer. This method delegates its work toformat(Object, Appendable)
, but without propagatingIOException
. The I/O exception should never occur since we are writing in aStringBuffer
.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 implementers should avoid such unexpected I/O operation.
-
getFormat
protected Format getFormat(Class<?> valueType)
Returns the format to use for parsing and formatting values of the given type. This method applies the following algorithm:- If a format is cached for the given type, return that format.
- Otherwise if a format can be created for the given type, cache the newly created format and return it.
- Otherwise do again the same checks for the super class.
- If no format is found for a concrete class, search again for all implemented interfaces.
- If no format can be created, return
null
.
createFormat(Class)
for the list of value types recognized by the defaultCompoundFormat
implementation.- Parameters:
valueType
- the base type of values to parse or format, ornull
if unknown.- Returns:
- the format to use for parsing and formatting values of the given type or any parent type,
or
null
if none.
-
createFormat
protected Format createFormat(Class<?> valueType)
Creates a new format to use for parsing and formatting values of the given type. This method is invoked bygetFormat(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:Supported value types 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 theexpected == type
comparator, notexpected.isAssignableFrom(type)
, because the check for parent types is done by thegetFormat(Class)
method. This approach allows subclasses to create specialized formats for different value sub-types. For example a subclass may choose to formatDouble
values differently than other types of number.- Parameters:
valueType
- the base type of values to parse or format.- Returns:
- the format to use for parsing of formatting values of the given type, or
null
if none.
-
clone
public CompoundFormat<T> clone()
Returns a clone of this format.
-
-