Package org.apache.sis.storage

# Class StorageConnector

Object
StorageConnector

All Implemented Interfaces:
  `Serializable`

public class StorageConnector extends Object implements Serializable
Information for creating a connection to a `DataStore` in read and/or write mode. `StorageConnector` wraps an input `Object`, which can be any of the following types:

- A `Path` or a `File` for a file or a directory.
- A `URI` or a `URL` to a distant resource.
- A `CharSequence` interpreted as a filename or a URL.
- A `Channel`, `DataInput`, `InputStream` or `Reader`.
- A `DataSource` or a `Connection` to a JDBC database.
- Any other `DataStore`-specific object, for example `NetcdfFile`.

The `getStorageAs(Class)` method provides the storage as an object of the given type, opening the input stream if necessary. This class tries to open the stream only once - subsequent invocation of `getStorageAs(…)` may return the same input stream.

This class is used only for discovery of a `DataStore` implementation capable to handle the input. Once a suitable `DataStore` has been found, the `StorageConnector` instance is typically discarded since each data store implementation will use their own input/output objects.

Instances of this class are serializable if the `storage` object given at construction time is serializable.

Since:
  0.3
See Also:
  - Serialized Form

Defined in the `sis-storage` module

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `StorageConnector(Object storage)`
  Creates a new data store connection wrapping the given input/output object.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `closeAllExcept(Object view)`
  Closes all streams and connections created by this `StorageConnector` except the given view.
  `String`
  `getFileExtension()`
  Returns the filename extension of the input/output object.
  `<T> T`
  `getOption(OptionKey<T> key)`
  Returns the option value for the given key, or `null` if none.
  `Object`
  `getStorage()`
  Returns the input/output object given at construction time.
  `<T> T`
  `getStorageAs(Class<T> type)`
  Returns the storage as a view of the given type if possible, or `null` otherwise.
  `String`
  `getStorageName()`
  Returns a short name of the input/output object.
  `<T> void`
  `setOption(OptionKey<T> key, T value)`
  Sets the option value for the given key.
  `String`
  `toString()`
  Returns a string representation of this `StorageConnector` for debugging purpose.

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### StorageConnector

    public StorageConnector(Object storage)
    Creates a new data store connection wrapping the given input/output object. The object can be of any type, but the class javadoc lists the most typical ones.
    Parameters:
      `storage` - the input/output object as a URL, file, image input stream, etc..

- ## Method Details

  - ### getOption

    public <T> T getOption(OptionKey<T> key)
    Returns the option value for the given key, or `null` if none.
    Type Parameters:
      `T` - the type of option value.
    Parameters:
      `key` - the option for which to get the value.
    Returns:
      the current value for the given option, or `null` if none.

  - ### setOption

    public <T> void setOption(OptionKey<T> key, T value)
    Sets the option value for the given key. The default implementation recognizes the following options:
    - `OptionKey​.ENCODING` for decoding characters in an input stream, if needed.
    - `OptionKey​.URL_ENCODING` for converting URL to URI or filename, if needed.
    - `OptionKey​.OPEN_OPTIONS` for specifying whether the data store shall be read only or read/write.
    - `OptionKey​.BYTE_BUFFER` for allowing users to control the byte buffer to be created.
    Type Parameters:
      `T` - the type of option value.
    Parameters:
      `key` - the option for which to set the value.
      `value` - the new value for the given option, or `null` for removing the value.

  - ### getStorage

    public Object getStorage() throws DataStoreException
    Returns the input/output object given at construction time. The object can be of any type, but the class javadoc lists the most typical ones.
    Returns:
      the input/output object as a URL, file, image input stream, etc..
    Throws:
      `DataStoreException` - if the storage object has already been used and can not be reused.
    See Also:
      - `getStorageAs(Class)`

  - ### getStorageName

    public String getStorageName()
    Returns a short name of the input/output object. For example if the storage is a file, this method returns the filename without the path (but including the file extension). The default implementation performs the following choices based on the type of the storage object:
    - For `Path`, `File`, `URI` or `URL` instances, this method uses dedicated API like `Path​.getFileName()`.
    - For `CharSequence` instances, this method gets a string representation of the storage object and returns the part after the last `'/'` character or platform-dependent name separator.
    - For instances of unknown type, this method builds a string representation using the class name. Note that the string representation of unknown types may change in any future SIS version.
    Returns:
      a short name of the storage object.

  - ### getFileExtension

    public String getFileExtension()
    Returns the filename extension of the input/output object. The default implementation performs the following choices based on the type of the storage object:
    - For `Path`, `File`, `URI`, `URL` or `CharSequence` instances, this method returns the string after the last `'.'` character in the filename, provided that the `'.'` is not the first filename character. This may be an empty string if the filename has no extension, but never `null`.
    - For instances of unknown type, this method returns `null`.
    Returns:
      the filename extension, or an empty string if none, or `null` if the storage is an object of unknown type.

  - ### getStorageAs

    public <T> T getStorageAs(Class<T> type) throws IllegalArgumentException, DataStoreException
    Returns the storage as a view of the given type if possible, or `null` otherwise. The default implementation accepts the following types:
    - `String`:
      - If the storage object is an instance of the `Path`, `File`, `URL`, `URI` or `CharSequence` types, returns the string representation of their path.
      - Otherwise this method returns `null`.
    - `Path`, `URI`, `URL`, `File`:
      - If the storage object is an instance of the `Path`, `File`, `URL`, `URI` or `CharSequence` types and that type can be converted to the requested type, returned the conversion result.
      - Otherwise this method returns `null`.
    - `ByteBuffer`:
      - If the storage object can be obtained as described in bullet 2 of the `DataInput` section below, then this method returns the associated byte buffer.
      - Otherwise this method returns `null`.
    - `DataInput`:
      - If the storage object is already an instance of `DataInput` (including the `ImageInputStream` and `ImageOutputStream` types), then it is returned unchanged.
      - Otherwise if the input is an instance of `Path`, `File`, `URI`, `URL`, `CharSequence`, `InputStream` or `ReadableByteChannel`, then an `ImageInputStream` backed by a `ByteBuffer` is created when first needed and returned.
      - Otherwise if `ImageIO​.createImageInputStream(Object)` returns a non-null value, then this value is cached and returned.
      - Otherwise this method returns `null`.
    - `ImageInputStream`:
      - If the above `DataInput` can be created and casted to `ImageInputStream`, returns it.
      - Otherwise this method returns `null`.
    - `InputStream`:
      - If the storage object is already an instance of `InputStream`, then it is returned unchanged.
      - Otherwise if the above `ImageInputStream` can be created, returns a wrapper around that stream.
      - Otherwise this method returns `null`.
    - `Reader`:
      - If the storage object is already an instance of `Reader`, then it is returned unchanged.
      - Otherwise if the above `InputStream` can be created, returns an `InputStreamReader` using the encoding specified by `OptionKey​.ENCODING` if any, or using the system default encoding otherwise.
      - Otherwise this method returns `null`.
    - `Connection`:
      - If the storage object is already an instance of `Connection`, then it is returned unchanged.
      - Otherwise if the storage is an instance of `DataSource`, then a connection is obtained when first needed and returned.
      - Otherwise this method returns `null`.
    - Any other types:
      - If the storage given at construction time is already an instance of the requested type, returns it as-is.
      - Otherwise this method throws `IllegalArgumentException`.
    Multiple invocations of this method on the same `StorageConnector` instance will try to return the same instance on a best effort basis. Consequently, implementations of `DataStoreProvider​.probeContent(StorageConnector)` methods shall not close the stream or database connection returned by this method. In addition, those `probeContent(StorageConnector)` methods are responsible for restoring the stream or byte buffer to its original position on return.
    Type Parameters:
      `T` - the compile-time type of the `type` argument.
    Parameters:
      `type` - the desired type as one of `ByteBuffer`, `DataInput`, `Connection` class or other type supported by `StorageConnector` subclasses.
    Returns:
      the storage as a view of the given type, or `null` if the given type is one of the supported types listed in javadoc but no view can be created for the source given at construction time.
    Throws:
      `IllegalArgumentException` - if the given `type` argument is not one of the supported types listed in this javadoc or in subclass javadoc.
      `IllegalStateException` - if this `StorageConnector` has been closed.
      `DataStoreException` - if an error occurred while opening a stream or database connection.
    See Also:
      - `getStorage()`
      - `closeAllExcept(Object)`

  - ### closeAllExcept

    public void closeAllExcept(Object view) throws DataStoreException
    Closes all streams and connections created by this `StorageConnector` except the given view. This method closes all objects created by the `getStorageAs(Class)` method except the given `view`. If `view` is `null`, then this method closes everything including the storage if it is closeable.

    This method is invoked when a suitable `DataStore` has been found - in which case the view used by the data store is given in argument to this method - or when no suitable `DataStore` has been found - in which case the `view` argument is null.

    This `StorageConnector` instance shall not be used anymore after invocation of this method.

    Parameters:
      `view` - the view to leave open, or `null` if none.
    Throws:
      `DataStoreException` - if an error occurred while closing the stream or database connection.
    See Also:
      - `getStorageAs(Class)`
      - `DataStoreProvider​.open(StorageConnector)`

  - ### toString

    public String toString()
    Returns a string representation of this `StorageConnector` for debugging purpose. This string representation is for debugging purpose only and may change in any future version.
    Overrides:
      `toString` in class `Object`
    Returns:
      a string representation of this `StorageConnector` for debugging purpose.