org.apache.sis.feature

## Class FeatureFormat

- Object
- - Format
  - - CompoundFormat<T>
    - - TabularFormat<Object>
      - - FeatureFormat

- All Implemented Interfaces:
    Serializable, Cloneable, Localized

      public class FeatureFormat
      extends TabularFormat<Object>

  Formats features or feature types in a tabular format. This format assumes a monospaced font and an encoding supporting drawing box characters (e.g. UTF-8).
  Example: a feature named “City” and containing 3 properties (“name”, “population” and “twin town”) may be formatted like below. The two first properties are attributes while the last property is an association to an other feature.

      City
      ┌────────────┬─────────┬─────────────┬───────────┐
      │ Name       │ Type    │ Cardinality │ Value     │
      ├────────────┼─────────┼─────────────┼───────────┤
      │ name       │ String  │ [1 … 1]     │ Paderborn │
      │ population │ Integer │ [1 … 1]     │ 143,174   │
      │ twin town  │ City    │ [0 … ∞]     │ Le Mans   │
      └────────────┴─────────┴─────────────┴───────────┘

  Limitations:

  - The current implementation can only format features — parsing is not yet implemented.
  - `FeatureFormat`, like most `java​.text​.Format` subclasses, is not thread-safe.
  Since:
    0.5
  See Also:
    Serialized Form

  Defined in the `sis-feature` module

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `FeatureFormat.Column` Identifies the columns to include in the table formatted by `FeatureFormat`.

    - ### Nested classes/interfaces inherited from class Format

      `Format​.Field`

  - ### Field Summary

    - ### Fields inherited from class TabularFormat

      `beforeFill, columnSeparator, fillCharacter, lineSeparator, omitTrailingNulls`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FeatureFormat()` Creates a new formatter for the default locale and timezone.
    `FeatureFormat(Locale locale, TimeZone timezone)` Creates a new formatter for the given locale and timezone.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `FeatureFormat` | `clone()` Returns a clone of this format.
    `void` | `format(Object object, Appendable toAppendTo)` Formats the given object to the given stream of buffer.
    `Set<FeatureFormat.Column>` | `getAllowedColumns()` Returns all columns that may be shown in the tables to format.
    `Locale` | `getLocale(Locale.Category category)` Returns the locale for the given category.
    `Class<Object>` | `getValueType()` Returns the type of objects formatted by this class.
    `Object` | `parse(CharSequence text, ParsePosition pos)` Not yet supported.
    `void` | `setAllowedColumns(Set<FeatureFormat.Column> inclusion)` Sets all columns that may be shown in the tables to format.

    - ### Methods inherited from class TabularFormat

      `getColumnSeparatorMatcher, getColumnSeparatorPattern, getLineSeparator, setColumnSeparatorPattern, setLineSeparator`

    - ### Methods inherited from class CompoundFormat

      `createFormat, format, getFormat, getLocale, getTimeZone, parseObject, parseObject`

    - ### Methods inherited from class Format

      `format, formatToCharacterIterator`

    - ### Methods inherited from class Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### FeatureFormat

          public FeatureFormat()

      Creates a new formatter for the default locale and timezone.

    - #### FeatureFormat

          public FeatureFormat(Locale locale,
                               TimeZone timezone)

      Creates a new formatter for the given locale and timezone.
      Parameters:
        `locale` - the locale, or `null` for `Locale​.ROOT`.
        `timezone` - the timezone, or `null` for UTC.

  - ### Method Detail

    - #### getValueType

          public final Class<Object> getValueType()

      Returns the type of objects formatted by this class. This method has to return `Object​.class` since it is the only common parent to `Feature` and `FeatureType`.
      Specified by:
        `getValueType` in class `CompoundFormat<Object>`
      Returns:
        `Object​.class`

    - #### getLocale

          public Locale getLocale(Locale.Category category)

      Returns the locale for the given category.
      - `Locale​.Category​.FORMAT` specifies the locale to use for values.
      - `Locale​.Category​.DISPLAY` specifies the locale to use for labels.
      Overrides:
        `getLocale` in class `CompoundFormat<Object>`
      Parameters:
        `category` - the category for which a locale is desired.
      Returns:
        the locale for the given category (never `null`).

    - #### getAllowedColumns

          public Set<FeatureFormat.Column> getAllowedColumns()

      Returns all columns that may be shown in the tables to format. The columns included in the set may be shown, but not necessarily; some columns will still be omitted if they are completely empty. However columns not included in the set are guaranteed to be omitted.
      Returns:
        all columns that may be shown in the tables to format.
      Since:
        0.8

    - #### setAllowedColumns

          public void setAllowedColumns(Set<FeatureFormat.Column> inclusion)

      Sets all columns that may be shown in the tables to format. Note that the columns specified to this method are not guaranteed to be shown; some columns will still be omitted if they are completely empty.
      Parameters:
        `inclusion` - all columns that may be shown in the tables to format.
      Since:
        0.8

    - #### format

          public void format(Object object,
                             Appendable toAppendTo)
                      throws IOException

      Formats the given object to the given stream of buffer. The object may be an instance of any of the following types:
      - `Feature`
      - `FeatureType`
      Specified by:
        `format` in class `CompoundFormat<Object>`
      Parameters:
        `object` - the object to format.
        `toAppendTo` - where to format the object.
      Throws:
        `IOException` - if an error occurred while writing to the given appendable.

    - #### parse

          public Object parse(CharSequence text,
                              ParsePosition pos)
                       throws ParseException

      Not yet supported.
      Specified by:
        `parse` in class `CompoundFormat<Object>`
      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:
        currently never return.
      Throws:
        `ParseException` - currently always thrown.

    - #### clone

          public FeatureFormat clone()

      Returns a clone of this format.
      Overrides:
        `clone` in class `TabularFormat<Object>`
      Returns:
        a clone of this format.

Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.