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 kind 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 and 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 and 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 and 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.

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