Class OptionKey<T>

Object

OptionKey<T>

Type Parameters:

T - the type of option values.

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

Option­Key

@Deprecated(since="1.7",
            forRemoval=true)
public class OptionKey<T>
extends Object
implements Serializable

Deprecated, for removal: This API element is subject to removal in a future version.

Moved to the org.apache.sis.storage because these options appear to be used only by data stores.

Keys in a map of options for configuring various services (Data­Store, etc). 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 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

Field Summary

Fields

Modifier and Type	Field	Description
static Option­Key<Coordinate­Reference­System>	DEFAULT_CRS	Deprecated, for removal: This API element is subject to removal in a future version. The coordinate reference system (CRS) of data to use if not explicitly defined.
static Option­Key<Charset>	ENCODING	Deprecated, for removal: This API element is subject to removal in a future version. The character encoding of document content.
static Option­Key<Geometry­Library>	GEOMETRY_LIBRARY	Deprecated, for removal: This API element is subject to removal in a future version. The library to use for creating geometric objects at reading time.
static Option­Key<Integer>	INDENTATION	Deprecated, for removal: This API element is subject to removal in a future version. The number of spaces to use for indentation when formatting text files in WKT or XML formats.
static Option­Key<Locale>	LOCALE	Deprecated, for removal: This API element is subject to removal in a future version. The locale to use for locale-sensitive data.
static Option­Key<Open­Option[]>	OPEN_OPTIONS	Deprecated, for removal: This API element is subject to removal in a future version. Whether a storage object shall be opened in read, write, append or other modes.
static Option­Key<Zone­Id>	TIMEZONE	Deprecated, for removal: This API element is subject to removal in a future version. The timezone to use when parsing or formatting dates and times without explicit timezone.
static Option­Key<String>	URL_ENCODING	Deprecated, for removal: This API element is subject to removal in a future version. The encoding of a URL (not the encoding of the document content).

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Option­Key(String name, Class<T> type)	Deprecated, for removal: This API element is subject to removal in a future version. Creates a new key of the given name for values of the given type.

Method Summary

Modifier and Type	Method	Description
boolean	equals(Object object)	Deprecated, for removal: This API element is subject to removal in a future version. Returns true if the given object is an instance of the same class having the same name and type.
final Class<T>	get­Element­Type()	Deprecated, for removal: This API element is subject to removal in a future version. Returns the type of values associated with this option key.
String	get­Name()	Deprecated, for removal: This API element is subject to removal in a future version. Returns the name of this option key.
T	get­Value­From(Map<? extends Option­Key<?>, ?> options)	Deprecated, for removal: This API element is subject to removal in a future version. Returns the option value in the given map for this key, or null if none.
int	hash­Code()	Deprecated, for removal: This API element is subject to removal in a future version. Returns a hash code value for this object.
Map<Option­Key<?>, Object>	set­Value­Into(Map<Option­Key<?>, Object> options, T value)	Deprecated, for removal: This API element is subject to removal in a future version. Sets a value for this option key in the given map, or in a new map if the given map is null.
String	to­String()	Deprecated, for removal: This API element is subject to removal in a future version. Returns a string representation of this option key.

Methods inherited from class Object

clone, finalize, get­Class, notify, notify­All, wait, wait, wait

Field Details

LOCALE

public static OptionKey<Locale> LOCALE

Deprecated, for removal: This API element is subject to removal in a future version.

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 Data­Store.set­Locale(Locale).

Since:

0.8

See Also:

• XML.LOCALE

TIMEZONE

public static OptionKey<ZoneId> TIMEZONE

Deprecated, for removal: This API element is subject to removal in a future version.

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.

Since:

0.8

See Also:

• XML.TIMEZONE

ENCODING

public static OptionKey<Charset> ENCODING

Deprecated, for removal: This API element is subject to removal in a future version.

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.

Since:

0.4

See Also:

• Marshaller.JAXB_ENCODING

URL_ENCODING

public static OptionKey<String> URL_ENCODING

Deprecated, for removal: This API element is subject to removal in a future version.

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 OptionKey<OpenOption[]> OPEN_OPTIONS

Deprecated, for removal: This API element is subject to removal in a future version.

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.

DEFAULT_CRS

public static OptionKey<CoordinateReferenceSystem> DEFAULT_CRS

Deprecated, for removal: This API element is subject to removal in a future version.

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.

Since:

1.5

GEOMETRY_LIBRARY

public static OptionKey<GeometryLibrary> GEOMETRY_LIBRARY

Deprecated, for removal: This API element is subject to removal in a future version.

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 OptionKey<Integer> INDENTATION

Deprecated, for removal: This API element is subject to removal in a future version.

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 Details

OptionKey

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

Deprecated, for removal: This API element is subject to removal in a future version.

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

getName

public String getName()

Deprecated, for removal: This API element is subject to removal in a future version.

Returns the name of this option key.

Returns:

the name of this option key.

getElementType

public final Class<T> getElementType()

Deprecated, for removal: This API element is subject to removal in a future version.

Returns the type of values associated with this option key.

Returns:

the type of values.

getValueFrom

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

Deprecated, for removal: This API element is subject to removal in a future version.

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) {
    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)

Deprecated, for removal: This API element is subject to removal in a future version.

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) {
    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)

Deprecated, for removal: This API element is subject to removal in a future version.

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 Option­Key for equality.

hashCode

public int hashCode()

Deprecated, for removal: This API element is subject to removal in a future version.

Returns a hash code value for this object.

Overrides:

hash­Code in class Object

toString

public String toString()

Deprecated, for removal: This API element is subject to removal in a future version.

Returns a string representation of this option key. The default implementation returns the value of get­Name().

Overrides:

to­String in class Object