Package 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    │ Multiplicity │ 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 | 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 | 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 | 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.