- 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
Base class of
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 org.apache.sis.referencing module. |
Angle | AngleFormat | |
Date | DateFormat | Timezone specified by getTimeZone(). |
Number | NumberFormat | |
Unit | UnitFormat | |
Range | RangeFormat | |
Class | (internal) |
Sources and destinations
SinceCompoundFormat 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.
Sub-classing
The abstract methods to be defined by subclasses are:Comparison with other API
In the standardFormat 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.- Since:
- 0.3
- See Also:
-
Nested Class Summary
Nested classes/interfaces inherited from class Format
Format.Field -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotectedCompoundFormat(Locale locale, TimeZone timezone) Creates a new format for the given locale. -
Method Summary
Modifier and TypeMethodDescriptionclone()Returns a clone of this format.protected FormatcreateFormat(Class<?> valueType) Creates a new format to use for parsing and formatting values of the given type.format(Object object, StringBuffer toAppendTo, FieldPosition pos) Writes a textual representation of the specified object in the given buffer.abstract voidformat(T object, Appendable toAppendTo) Writes a textual representation of the given object in the given stream or buffer.protected FormatgetFormat(Class<?> valueType) Returns the format to use for parsing and formatting values of the given type.Returns the locale used by this format.getLocale(Locale.Category category) Returns the locale for the given category.Returns the timezone used by this format.Returns the base type of values parsed and formatted by thisFormatinstance.abstract Tparse(CharSequence text, ParsePosition pos) Creates an object from the given character sequence.parseObject(String text) Creates an object from the given string representation.parseObject(String text, ParsePosition pos) Creates an object from the given string representation, or returnsnullif an error occurred while parsing.Methods inherited from class Format
format, formatToCharacterIterator
-
Constructor Details
-
CompoundFormat
Creates a new format for the given locale. The given locale can benullorLocale.ROOTif this format shall parse and format "unlocalized" strings. SeegetLocale()for more information about theROOTlocale.- Parameters:
locale- the locale for the newFormat, ornullforLocale.ROOT.timezone- the timezone, ornullfor UTC.
-
-
Method Details
-
getLocale
Returns the locale used by this format. The returned value may beLocale.ROOTif this format does not apply any localization. The definition of "unlocalized string" is implementation-dependent, but some typical examples are:- Specified by:
getLocalein interfaceLocalized- Returns:
- the locale of this
Format, orLocale.ROOTfor unlocalized format.
-
getLocale
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.FORMATspecifies the locale to use for numbers, dates and angles formatting.Locale.Category.DISPLAYspecifies the locale to use forCodeListlabels andInternationalStringcontents.
getLocale().Example
The ISO 19162 (Well Known Text) standard requires a number format similar to the one defined byLocale.ROOTwhile it allows informative texts (remarks, etc.) to be formatted according the user's locale. Consequently,WKTFormatfixes (usually) the locale forCategory.FORMATtoLocale.ROOTand letCategory.DISPLAYbe any locale.- Parameters:
category- the category for which a locale is desired.- Returns:
- the locale for the given category (never
null). - Since:
- 0.4
-
getTimeZone
Returns the timezone used by this format.- Returns:
- the timezone used for this format, or UTC for unlocalized format.
-
getValueType
Returns the base type of values parsed and formatted by thisFormatinstance. 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.Examples
StatisticsFormatunconditionally returnsStatistics.class.TreeTableFormatunconditionally returnsTreeTable.class.
- Returns:
- the base type of values parsed and formatted by this
Formatinstance.
-
parse
Creates an object from the given character sequence. The parsing begins at the index given by theposargument. If parsing succeeds, then:- The
posindex is updated to the index after the last successfully parsed character. - The parsed object is returned.
- The
posindex is left unchanged - The
poserror 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
ParseExceptionis thrown with an error offset set to the index of the first unparsable character.
- this method returns
Note: if aMost implementations never returnParseExceptionis thrown, its error offset is usually the same than theParsePositionerror 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 theposerror 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 returnnullif they can determine that the given text is not a supported format and reserveParseExceptionfor 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
nullif the text is not recognized. - Throws:
ParseException- if an error occurred while parsing the object.
- The
-
parseObject
Creates an object from the given string representation, or returnsnullif an error occurred while parsing. The parsing begins at the index given by theposargument. If parsing succeeds, then:- The
posindex is updated to the index after the last successfully parsed character. - The parsed object is returned.
- The
posindex is left unchanged - The
poserror index is set to the index of the character where the error occurred. nullis returned.
parse(CharSequence, ParsePosition).- Specified by:
parseObjectin classFormat- Parameters:
text- the string representation of the object to parse.pos- the position where to start the parsing.- Returns:
- the parsed object, or
nullif the given string cannot be parsed.
- The
-
parseObject
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.Whitespaces
The usual SIS policy, as documented in theCharSequencesclass, 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:
parseObjectin 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
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
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, anIOExceptioncould still occur if a subclass overrides the aboveformatmethod 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
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 defaultCompoundFormatimplementation.- Parameters:
valueType- the base type of values to parse or format, ornullif unknown.- Returns:
- the format to use for parsing and formatting values of the given type or any parent type,
or
nullif none.
-
createFormat
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:
Subclasses can override this method for adding more types, or for configuring the newly createdSupported value types Value type Format type DirectPositionCoordinateFormatAngleAngleFormatDateDateFormatNumberNumberFormatUnitUnitFormatQuantityQuantityFormatRangeRangeFormatClass(internal) Formatinstances. Note that implementations shall check the type using theexpected == typecomparator, 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 formatDoublevalues 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
nullif none.
-
clone
Returns a clone of this format.
-