Class OptionKey<T>

Object
OptionKey<T>
OptionKey<T>
Type Parameters:
T - the type of option values.
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
Data­Option­Key
public class OptionKey<T> extends OptionKey<T>
Keys in a map of options for configuring data stores. Option­Keys 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, because the encoding 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 Data­Stores 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 data store uses others data stores 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:
1.7
See Also:

  • Field Details

    • 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 supports only one language. It may also control number and date patterns in some file formats such as 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 Data­Store​.set­Locale(Locale).

      See Also:

    • TIMEZONE

      public static final OptionKey<ZoneId> 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.
      See Also:

    • INDENTATION

      public static final OptionKey<Integer> INDENTATION
      The number of spaces to use for indentation when formatting texts in WKT or XML. 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.

      See Also:

    • ENCODING

      public static final OptionKey<Charset> ENCODING
      The character encoding of document content. This option can be used when the file to read or write 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.

      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. Therefore, this option is ignored for URI.
      • URL are often encoded in UTF-8, but not necessarily. Other encoding 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".
      See Also:

    • OPEN_OPTIONS

      public static final OptionKey<OpenOption[]> OPEN_OPTIONS
      Whether a storage object 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<Supplier<ByteBuffer>> BYTE_BUFFER
      Provider of the byte buffer to use for input/output operations. Some Data­Store implementations allow a 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 Data­Store instances.

    • XML_INPUT_FACTORY

      public static final OptionKey<Supplier<XMLInputFactory>> XML_INPUT_FACTORY
      Provider of a factory for creating XML stream readers or event readers. If this option is not specified or if the supplier returns null, Apache SIS uses a default factory with the XMLConstants​.ACCESS_EXTERNAL_DTD property set to an empty string for security reasons. If a factory is supplied, the suppliers should set the factory properties itself for the desired security level.

    • METADATA_PATH

      public static final OptionKey<Path> METADATA_PATH
      Path to an auxiliary file containing metadata encoded in an ISO 19115-3 XML document. The given path, if not absolute, is relative to the path of the main storage file. If the file exists, it is parsed and its content is merged or appended after the metadata read by the storage. If the file does not exist, then it is ignored.

      Wildcard

      It the '*' character is present in the path, then it is replaced by the name of the main file without its extension. For example if the main file is "city-center​.tiff", then "*.xml" will become "city-center​.xml".

    • DEFAULT_CRS

      public static final OptionKey<CoordinateReferenceSystem> DEFAULT_CRS
      The coordinate reference system (CRS) of data to use if not explicitly defined. This option can be used when the file to read does not describe itself the data CRS. For example, this option can be used when reading ASCII Grid without CRS information, but is ignored if the ASCII Grid file is accompanied by a *.prj file giving the CRS.

    • FOLIATION_REPRESENTATION

      public static final OptionKey<FoliationRepresentation> FOLIATION_REPRESENTATION
      Whether to assemble trajectory fragments (distinct CSV lines) into a single Feature instance forming a foliation. This is ignored if the file does not seem to contain moving features.

    • GEOMETRY_LIBRARY

      public static final OptionKey<GeometryLibrary> GEOMETRY_LIBRARY
      The library to use for creating geometric objects at reading time. Some available 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.

    • COVERAGE_MODIFIER

      public static final OptionKey<CoverageModifier> COVERAGE_MODIFIER
      Callback methods invoked for modifying some aspects of the grid coverages created by resources.

    • PARENT_LISTENERS

      public static final OptionKey<StoreListeners> PARENT_LISTENERS
      The listeners to declare as the parent of the data store listeners. This option can be used when the Data­Store to open is itself a child of an Aggregate.

  • Constructor Details

    • 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 Details

    • asOpenParameter

      public Optional<ParameterDescriptor<T>> asOpenParameter()
      Returns this option as a parameter descriptor. Storing option values as Parameter­Value instances is sometime convenient when the options need to be serialized, for example, in a text file or a database. While values are stored as Java objects of type <T>, the Parameter­Value​.set­Value(Object) method is capable to convert text representations to the expected object type.

      Parameter descriptors are available only for a subset of the options. This method may return a non-empty value only if the values of this option have a text representation.

      Returns:
      a parameter descriptor for this option.
      See Also: