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
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 sis-referencingmodule. | 
| 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:API note:
 in the standard 
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.- Since:
- 0.3
- See Also:
Defined in the sis-utility module
- 
Nested Class SummaryNested classes/interfaces inherited from class FormatFormat.Field
- 
Constructor SummaryConstructorsModifierConstructorDescriptionprotectedCompoundFormat(Locale locale, TimeZone timezone) Creates a new format for the given locale.
- 
Method SummaryModifier 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 Formatformat, formatToCharacterIterator
- 
Constructor Details- 
CompoundFormatCreates 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 new- Format, or- nullfor- Locale.ROOT.
- timezone- the timezone, or- nullfor UTC.
 
 
- 
- 
Method Details- 
getLocaleReturns 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 interface- Localized
- Returns:
- the locale of this Format, orLocale.ROOTfor unlocalized format.
 
- 
getLocaleReturns 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 for- CodeListlabels and- InternationalStringcontents.
 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.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.getLocale().- Parameters:
- category- the category for which a locale is desired.
- Returns:
- the locale for the given category (never null).
- Since:
- 0.4
 
- 
getTimeZoneReturns the timezone used by this format.- Returns:
- the timezone used for this format, or UTC for unlocalized format.
 
- 
getValueTypeReturns 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.Example:- StatisticsFormatunconditionally returns- Statistics.class.
- TreeTableFormatunconditionally returns- TreeTable.class.
 - Returns:
- the base type of values parsed and formatted by this Formatinstance.
 
- 
parseCreates 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 
- 
parseObjectCreates 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 class- Format
- 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 
- 
parseObjectCreates 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 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 class- Format
- Parameters:
- text- the string representation of the object to parse.
- Returns:
- the parsed object.
- Throws:
- ParseException- if an error occurred while parsing the object.
 
- 
formatWrites 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.
 
- 
formatWrites 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.
- 
getFormatReturns 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, or- nullif unknown.
- Returns:
- the format to use for parsing and formatting values of the given type or any parent type,
         or nullif none.
 
- 
createFormatCreates 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.
 
- 
cloneReturns a clone of this format.
 
-