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

    All Methods Instance Methods Concrete Methods
    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 Detail

    - #### 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 Detail

    - #### 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.