Class CompoundFormat<T>

    • 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:
        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 implementers 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 is found for a concrete class, search again for all implemented interfaces.
        5. If no format can be created, return 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.