Package org.apache.sis.parameter

## Class ParameterFormat

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

- All Implemented Interfaces:
    `Serializable`, `Cloneable`, `Localized`

      public class ParameterFormat
      extends TabularFormat<Object>

  Formats parameter descriptors or parameter values in a tabular format. This format assumes a monospaced font and an encoding supporting drawing box characters (e.g. UTF-8).

  This class can format parameters with different levels of verbosity, specified by the `ParameterFormat​.ContentLevel` property. The content level controls whether the formatter should write all names and aliases (at the cost of multi-line rows), or to pickup one name per parameter for a more compact table. See `ParameterFormat​.ContentLevel` javadoc for output examples.

  Example: The Mercator (variant A) example given in `DefaultParameterDescriptorGroup` javadoc will be formatted by default as below:

  >     EPSG: Mercator (variant A)
  >     ┌────────────────────────────────┬────────┬────────────┬───────────────┬───────────────┐
  >     │ Name (EPSG)                    │ Type   │ Obligation │ Value domain  │ Default value │
  >     ├────────────────────────────────┼────────┼────────────┼───────────────┼───────────────┤
  >     │ Latitude of natural origin     │ Double │ Mandatory  │  [-80 … 84]°  │         0.0°  │
  >     │ Longitude of natural origin    │ Double │ Mandatory  │ [-180 … 180]° │         0.0°  │
  >     │ Scale factor at natural origin │ Double │ Mandatory  │    (0 … ∞)    │         1.0   │
  >     │ False easting                  │ Double │ Mandatory  │   (−∞ … ∞) m  │         0.0 m │
  >     │ False northing                 │ Double │ Mandatory  │   (−∞ … ∞) m  │         0.0 m │
  >     └────────────────────────────────┴────────┴────────────┴───────────────┴───────────────┘

  The kinds of objects accepted by this formatter are:

  Formattable object types
  Class | Remarks
  --- | ---
  `ParameterValueGroup` | Default values column is replaced by a column of the actual values.
  `ParameterDescriptorGroup` | Table caption is the parameter group name.
  `OperationMethod` | Table caption is the method name (not necessarily the same than parameter group name).
  `IdentifiedObject[]` | Accepted only for `ParameterFormat​.ContentLevel​.NAME_SUMMARY`.

  Limitations:

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

  Defined in the `sis-referencing` module

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `ParameterFormat.ContentLevel` | The amount of information to include in the table formatted by `ParameterFormat`.

    - ### 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
    --- | ---
    `ParameterFormat()` | Creates a new formatter for the default locale and timezone.
    `ParameterFormat​(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
    --- | --- | ---
    `ParameterFormat` | `clone()` | Returns a clone of this format.
    `void` | `format​(Object object, Appendable toAppendTo)` | Formats the given object to the given stream of buffer.
    `Colors` | `getColors()` | Returns the colors for an output on X3.64 compatible terminal, or `null` if none.
    `ParameterFormat.ContentLevel` | `getContentLevel()` | Returns the amount of information to put in the table.
    `Locale` | `getLocale​(Locale.Category category)` | Returns the locale for the given category.
    `String[]` | `getPreferredCodespaces()` | Returns the code spaces of names, aliases and identifiers to show, or `null` if there is no restriction.
    `Class<Object>` | `getValueType()` | Returns the type of objects formatted by this class.
    `Object` | `parse​(CharSequence text, ParsePosition pos)` | Not yet supported.
    `void` | `setColors​(Colors colors)` | Sets the colors for an output on X3.64 compatible terminal.
    `void` | `setContentLevel​(ParameterFormat.ContentLevel level)` | Sets the amount of information to put in the table.
    `void` | `setPreferredCodespaces​(String... codespaces)` | Filters names, aliases and identifiers by their code spaces.

    - ### 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

    - #### ParameterFormat

          public ParameterFormat()

      Creates a new formatter for the default locale and timezone.

    - #### ParameterFormat

          public ParameterFormat​(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 all object types accepted by this formatter.
      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`).

    - #### getContentLevel

          public ParameterFormat.ContentLevel getContentLevel()

      Returns the amount of information to put in the table. The default value is `ParameterFormat​.ContentLevel​.BRIEF`.
      Returns:
        the table content.

    - #### setContentLevel

          public void setContentLevel​(ParameterFormat.ContentLevel level)

      Sets the amount of information to put in the table.
      Parameters:
        `level` - the amount of information to put in the table.

    - #### getPreferredCodespaces

          public String[] getPreferredCodespaces()

      Returns the code spaces of names, aliases and identifiers to show, or `null` if there is no restriction. This method returns the sequence specified by the last call to `setPreferredCodespaces(String[])`, without duplicated values.

      The default value is `null`.

      Returns:
        the code spaces of names and identifiers to show, or `null` if no restriction.

    - #### setPreferredCodespaces

          public void setPreferredCodespaces​(String... codespaces)

      Filters names, aliases and identifiers by their code spaces. If the given array is non-null, then the only names, aliases and identifiers to be formatted are those having a `ReferenceIdentifier​.getCodeSpace()`, `ScopedName​.head()` or `GenericName​.scope()` value in the given list, unless no name or alias matches this criterion.
      Parameters:
        `codespaces` - the preferred code spaces of names, aliases and identifiers to format, or `null` for accepting all of them. Some typical values are `"EPSG"`, `"OGC"` or `"GeoTIFF"`.

    - #### getColors

          public Colors getColors()

      Returns the colors for an output on X3.64 compatible terminal, or `null` if none. The default value is `null`.
      Returns:
        the colors for an output on X3.64 compatible terminal, or `null` if none.

    - #### setColors

          public void setColors​(Colors colors)

      Sets the colors for an output on X3.64 compatible terminal.
      Parameters:
        `colors` - the colors for an output on X3.64 compatible terminal, or `null` if none.

    - #### 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:
      - `ParameterValueGroup`
      - `ParameterDescriptorGroup`
      - `OperationMethod`
      - `IdentifiedObject[]` — accepted only for `ParameterFormat​.ContentLevel​.NAME_SUMMARY`.
      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 ParameterFormat clone()

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