org.apache.sis.io

Class CompoundFormat<T>

Object

Format

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 of Format implementations which delegate part of their work to other Format instances. Compound­Format 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 Number­Format and Date­Format respectively. Subclasses can obtain instances of those formats by call to get­Format(Class) where the argument is the type of the value to parse or format. Compound­Format 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 get­Time­Zone().
Number	NumberFormat
Unit	UnitFormat
Range	RangeFormat
Class	(internal)

Sources and destinations

Since Compound­Format may work on larger texts than the usual Format classes, it defines parse and format methods working with arbitrary Char­Sequence and Appendable instances. The standard Format methods redirect to the above-cited methods.

Sub-classing

The abstract methods to be defined by subclasses are:

• get­Value­Type()
• format(Object, Appendable)
• parse(Char­Sequence, Parse­Position)

API note: in the standard Format class, the parse methods either accept a Parse­Position argument and returns null on error, or does not take position argument and throws a Parse­Exception on error. In this Compound­Format class, the parse method both takes a Parse­Position argument and throws a Parse­Exception 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 and Description
protected	CompoundFormat(Locale locale, TimeZone timezone) Creates a new format for the given locale.

Method Summary

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.

Methods inherited from class Format

format, format­To­Character­Iterator

Methods inherited from class Object

equals, finalize, get­Class, hash­Code, notify, notify­All, to­String, wait, wait, wait

Constructor Detail

CompoundFormat

protected CompoundFormat(Locale locale,
                         TimeZone timezone)

Creates a new format for the given locale. The given locale can be null or Locale.ROOT if this format shall parse and format "unlocalized" strings. See get­Locale() for more information about the ROOT locale.

Parameters:

locale - the locale for the new Format, or null for Locale.ROOT.

timezone - the timezone, or null for UTC.

Method Detail

getLocale

public Locale getLocale()

Returns the locale used by this format. The returned value may be Locale.ROOT if this format does not apply any localization. The definition of "unlocalized string" is implementation-dependent, but some typical examples are:

• Format Number instances using to­String() instead than Number­Format.
• Format Date instances using the ISO pattern instead than the English one.

Specified by:

get­Locale in interface Localized

Returns:

the locale of this Format, or Locale.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 for Code­List labels and International­String contents.

Example: The ISO 19162 (Well Known Text) standard requires a number format similar to the one defined by 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.

For subclasses that do not override this method, the default implementation returns get­Locale().

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 this 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.

Example:

• Statistics­Format unconditionally returns Statistics.class.
• Tree­Table­Format unconditionally returns Tree­Table.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 the pos argument. If parsing succeeds, then:

• The pos index is updated to the index after the last successfully parsed character.
• The parsed object is returned.

If parsing fails, then:

• 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 Parse­Exception is thrown with an error offset set to the index of the first unparsable character.

Note: if a Parse­Exception is thrown, its error offset is usually the same than the Parse­Position 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.

Most implementations never return null. However some implementations may choose to return null if they can determine that the given text is not a supported format and reserve Parse­Exception 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:

Parse­Exception - if an error occurred while parsing the object.

parseObject

public T parseObject(String text,
                     ParsePosition pos)

Creates an object from the given string representation, or returns null if an error occurred while parsing. The parsing begins at the index given by the pos argument. If parsing succeeds, then:

• The pos index is updated to the index after the last successfully parsed character.
• The parsed object is returned.

If parsing fails, then:

• 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.

The default implementation delegates to parse(Char­Sequence, Parse­Position).

Specified by:

parse­Object in 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 null if the given string can not be parsed.

parseObject

public T parseObject(String text)
              throws ParseException

Creates an object from the given string representation. The default implementation delegates to parse(Char­Sequence, Parse­Position) 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 the Char­Sequences class, is to test for whitespaces using the Character.is­Whitespace(…) method. The combination of is­Space­Char(…) and is­ISOControl(…) done in this parse­Object(…) method is more permissive since it encompasses all whitespace characters, plus non-breaking spaces and non-white ISO controls.

Overrides:

parse­Object in class Format

Parameters:

text - the string representation of the object to parse.

Returns:

the parsed object.

Throws:

Parse­Exception - 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.

to­Append­To - 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 to format(Object, Appendable), but without propagating IOException. The I/O exception should never occur since we are writing in a String­Buffer.

Note: Strictly speaking, an IOException could still occur if a subclass overrides the above format method and performs some I/O operation outside the given String­Buffer. However this is not the intended usage of this class and implementors should avoid such unexpected I/O operation.

Specified by:

format in class Format

Parameters:

object - the object to format.

to­Append­To - where to format the object.

pos - ignored in current implementation.

Returns:

the given buffer, returned for convenience.

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:

1. If a format is cached for the given type, return that format.
2. Otherwise if a format can be created for the given type, cache the newly created format and return it.
3. Otherwise do again the same checks for the super class.
4. If no format can be created, returns null.

See create­Format(Class) for the list of value types recognized by the default Compound­Format implementation.

Parameters:

value­Type - the base type of values to parse or format, or null 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 by get­Format(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)

Subclasses can override this method for adding more types, or for configuring the newly created Format instances. Note that implementations shall check the type using the expected == type comparator, not expected.is­Assignable­From(type), because the check for parent types is done by the get­Format(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.

Parameters:

value­Type - 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.

Overrides:

clone in class Format

Returns:

a clone of this format.