Package org.apache.sis.setup

## Class OptionKey<T>

- Object
- - OptionKey<T>

- Type Parameters:
    `T` - the type of option values.
  All Implemented Interfaces:
    `Serializable`
  Direct Known Subclasses:
    `DataOptionKey`

      public class OptionKey<T>
      extends Object
      implements Serializable

  Keys in a map of options for configuring various services (`DataStore`, etc). `OptionKey`s are used for aspects that usually do not need to be configured, except in a few specialized cases. For example most data file formats read by SIS do not require the user to specify the character encoding, since the encoding it is often given in the file header or in the format specification. However if SIS needs to read plain text files and the default platform encoding is not suitable, then the user can specify the desired encoding explicitly using the `ENCODING` option.

  All options are hints and may be silently ignored. For example most `DataStore`s will ignore the `ENCODING` option if irrelevant to their format, or if the encoding is specified in the data file header.

  Options are transitive: if a service uses others services for its internal working, the given options may also be given to those dependencies, at implementation choice.

  Defining new options
  Developers who wish to define their own options can define static constants in a subclass, as in the following example:

  >     public final class MyOptionKey<T> extends OptionKey<T> {
  >         public static final OptionKey<String> MY_OPTION = new MyOptionKey<>("MY_OPTION", String.class);

  >         private MyOptionKey(final String name, final Class<T> type) {
  >             super(name, type);
  >         }
  >     }

  Since:
    0.3
  See Also:
    Serialized Form

  Defined in the `sis-utility` module

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static OptionKey<ByteBuffer>` | `BYTE_BUFFER` | The byte buffer to use for input/output operations.
    `static OptionKey<Charset>` | `ENCODING` | The character encoding of document content.
    `static OptionKey<GeometryLibrary>` | `GEOMETRY_LIBRARY` | The library to use for creating geometric objects at reading time.
    `static OptionKey<Integer>` | `INDENTATION` | The number of spaces to use for indentation when formatting text files in WKT or XML formats.
    `static OptionKey<Locale>` | `LOCALE` | The locale to use for locale-sensitive data.
    `static OptionKey<OpenOption[]>` | `OPEN_OPTIONS` | Whether a storage object (e.g. a `DataStore`) shall be opened in read, write, append or other modes.
    `static OptionKey<TimeZone>` | `TIMEZONE` | The timezone to use when parsing or formatting dates and times without explicit timezone.
    `static OptionKey<String>` | `URL_ENCODING` | The encoding of a URL (not the encoding of the document content).

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `OptionKey​(String name, Class<T> type)` | Creates a new key of the given name for values of the given type.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `equals​(Object object)` | Returns `true` if the given object is an instance of the same class having the same name and type.
    `Class<T>` | `getElementType()` | Returns the type of values associated to this option key.
    `String` | `getName()` | Returns the name of this option key.
    `T` | `getValueFrom​(Map<OptionKey<?>,​?> options)` | Returns the option value in the given map for this key, or `null` if none.
    `int` | `hashCode()` | Returns a hash code value for this object.
    `Map<OptionKey<?>,​Object>` | `setValueInto​(Map<OptionKey<?>,​Object> options, T value)` | Sets a value for this option key in the given map, or in a new map if the given map is `null`.
    `String` | `toString()` | Returns a string representation of this option key.

    - ### Methods inherited from class Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### LOCALE

          public static final OptionKey<Locale> LOCALE

      The locale to use for locale-sensitive data. This option determines the language to use for writing `international strings` when the target storage support only one language. It may also control number and date patterns in some file formats like Comma Separated Values (CSV). However most data formats will ignore this locale.

      This option is not for the locale of logging or warning messages. Messages locale is rather controlled by `DataStore​.setLocale(Locale)`.

      Since:
        0.8
      See Also:
        `XML​.LOCALE`

    - #### TIMEZONE

          public static final OptionKey<TimeZone> TIMEZONE

      The timezone to use when parsing or formatting dates and times without explicit timezone. If this option is not provided, then the default value is format specific. That default is often, but not necessarily, the platform default.
      Upcoming API change — Java time API
      The type may be changed to `ZoneId` when Apache SIS will target Java 8. This change may be applied in synchronization with GeoAPI 4.0.
      Since:
        0.8
      See Also:
        `XML​.TIMEZONE`

    - #### ENCODING

          public static final OptionKey<Charset> ENCODING

      The character encoding of document content. This option can be used when the file to read does not describe itself its encoding. For example this option can be used when reading plain text files, but is ignored when reading XML files having a `<?xml version="1.0" encoding="…"?>` declaration.

      If this option is not provided, then the default value is format specific. That default is often, but not necessarily, the platform default.

      Since:
        0.4
      See Also:
        `Marshaller​.JAXB_ENCODING`

    - #### URL_ENCODING

          public static final OptionKey<String> URL_ENCODING

      The encoding of a URL (not the encoding of the document content). This option may be used when converting a `String` or a `URL` to a `URI` or a `File`. The following rules apply:
      - URI are always encoded in UTF-8. Consequently this option is ignored for URI.
      - URL are often encoded in UTF-8, but not necessarily. Other encodings are possible (while not recommended), or some URL may not be encoded at all.
      If this option is not provided, then the URL is assumed not encoded.

      Example: Given the `"file:Map%20with%20spaces​.png"` URL, then:

      - If the URL encoding option is set to `"UTF-8"` or `"ISO-8859-1"`, then:
        - the encoded URI will be `"file:Map%20with%20spaces​.png"`;
        - the decoded URI or the file will be `"file:Map with spaces​.png"`.
      - If the URL encoding option is set to `null` or is not provided, then:
        - the encoded URI will be `"file:Map%2520with%2520spaces​.png"`, i.e. the percent sign will be encoded as `"%25"`;
        - the decoded URI or the file will be `"file:Map%20with%20spaces​.png"`.
      This option has not effect on URI encoding, which is always UTF-8.
      See Also:
        `URLDecoder`

    - #### OPEN_OPTIONS

          public static final OptionKey<OpenOption[]> OPEN_OPTIONS

      Whether a storage object (e.g. a `DataStore`) shall be opened in read, write, append or other modes. The main options that can be provided are:

      Supported open options
      Value | Meaning
      --- | ---
      `StandardOpenOption.READ` | Open for reading data from the storage object.
      `StandardOpenOption.WRITE` | Open for modifying existing data in the storage object.
      `StandardOpenOption.APPEND` | Open for appending new data in the storage object.
      `StandardOpenOption.CREATE` | Creates a new storage object (file or database) if it does not exist.

    - #### BYTE_BUFFER

          public static final OptionKey<ByteBuffer> BYTE_BUFFER

      The byte buffer to use for input/output operations. Some `DataStore` implementations allow a byte buffer to be specified, thus allowing users to choose the buffer capacity, whether the buffer is direct, or to recycle existing buffers.

      It is user's responsibility to ensure that:

      - The buffer does not contains any valuable data, as it will be cleared.
      - The same buffer is not used concurrently by two different `DataStore` instances.

    - #### GEOMETRY_LIBRARY

          public static final OptionKey<GeometryLibrary> GEOMETRY_LIBRARY

      The library to use for creating geometric objects at reading time. Some libraries are the Java Topology Suite (JTS), ESRI geometry API and Java2D. If this option is not specified, then a default library will be selected among the libraries available in the runtime environment.
      Since:
        0.8

    - #### INDENTATION

          public static final OptionKey<Integer> INDENTATION

      The number of spaces to use for indentation when formatting text files in WKT or XML formats. A value of -1 means to format the whole WKT or XML document on a single line without line feeds or indentation.

      If this option is not provided, then the most typical default value used in Apache SIS is 2. Such small indentation value is used because XML documents defined by OGC standards tend to be verbose.

      Since:
        0.8
      See Also:
        `WKTFormat​.SINGLE_LINE`, `Marshaller​.JAXB_FORMATTED_OUTPUT`

  - ### Constructor Detail

    - #### OptionKey

          protected OptionKey​(String name,
                              Class<T> type)

      Creates a new key of the given name for values of the given type.
      Parameters:
        `name` - the key name.
        `type` - the type of values.

  - ### Method Detail

    - #### getName

          public String getName()

      Returns the name of this option key.
      Returns:
        the name of this option key.

    - #### getElementType

          public final Class<T> getElementType()

      Returns the type of values associated to this option key.
      Returns:
        the type of values.

    - #### getValueFrom

          public T getValueFrom​(Map<OptionKey<?>,​?> options)

      Returns the option value in the given map for this key, or `null` if none. This is a convenience method for implementers, which can be used as below:

      >     public <T> T getOption(final OptionKey<T> key) {
      >         ArgumentChecks.ensureNonNull("key", key);
      >         return key.getValueFrom(options);
      >     }

      Parameters:
        `options` - the map where to search for the value, or `null` if not yet created.
      Returns:
        the current value in the map for the this option, or `null` if none.

    - #### setValueInto

          public Map<OptionKey<?>,​Object> setValueInto​(Map<OptionKey<?>,​Object> options,
                                                             T value)

      Sets a value for this option key in the given map, or in a new map if the given map is `null`. This is a convenience method for implementers, which can be used as below:

      >     public <T> void setOption(final OptionKey<T> key, final T value) {
      >         ArgumentChecks.ensureNonNull("key", key);
      >         options = key.setValueInto(options, value);
      >     }

      Parameters:
        `options` - the map where to set the value, or `null` if not yet created.
        `value` - the new value for the given option, or `null` for removing the value.
      Returns:
        the given map of options, or a new map if the given map was null. The returned value may be null if the given map and the given value are both null.

    - #### equals

          public boolean equals​(Object object)

      Returns `true` if the given object is an instance of the same class having the same name and type.
      Overrides:
        `equals` in class `Object`
      Parameters:
        `object` - the object to compare with this `OptionKey` for equality.

    - #### hashCode

          public int hashCode()

      Returns a hash code value for this object.
      Overrides:
        `hashCode` in class `Object`

    - #### toString

          public String toString()

      Returns a string representation of this option key. The default implementation returns the value of `getName()`.
      Overrides:
        `toString` in class `Object`