Module org.apache.sis.storage
Package org.apache.sis.storage

# Class DataStores

Object
Static
DataStores

public final class DataStores extends Static
Static convenience methods creating `DataStore` instances from a given storage object. Storage objects are typically `File` or `DataSource` instances, but can also be any other objects documented in the `StorageConnector` class.

Since:
  0.4

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static DataStore`
  `open(Object storage)`
  Creates a `DataStore` capable to read the given storage.
  `static DataStore`
  `openWritable(Object storage, String preferredFormat)`
  Creates a `DataStore` capable to write or update the given storage.
  `static String`
  `probeContentType(Object storage)`
  Returns the MIME type of the storage file format, or `null` if unknown or not applicable.
  `static Collection<DataStoreProvider>`
  `providers()`
  Returns the set of available data store providers.

  ### Methods inherited from class Object

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

- ## Method Details

  - ### providers

    public static Collection<DataStoreProvider> providers()
    Returns the set of available data store providers. The returned collection is live: its content may change if new modules are added on the module path at run-time.
    Returns:
      descriptions of available data stores.
    Since:
      0.8

  - ### probeContentType

    public static String probeContentType(Object storage) throws DataStoreException
    Returns the MIME type of the storage file format, or `null` if unknown or not applicable.
    Parameters:
      `storage` - the input/output object as a URL, file, image input stream, etc..
    Returns:
      the storage MIME type, or `null` if unknown or not applicable.
    Throws:
      `DataStoreException` - if an error occurred while opening the storage.

  - ### open

    public static DataStore open(Object storage) throws UnsupportedStorageException, DataStoreException
    Creates a `DataStore` capable to read the given storage. The `storage` argument 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`.
    - An existing `StorageConnector` instance.
    Parameters:
      `storage` - the input object as a URL, file, image input stream, etc..
    Returns:
      the object to use for reading geospatial data from the given storage.
    Throws:
      `UnsupportedStorageException` - if no `DataStoreProvider` is found for the given storage object.
      `DataStoreException` - if an error occurred while opening the storage in read mode.

  - ### openWritable

    public static DataStore openWritable(Object storage, String preferredFormat) throws UnsupportedStorageException, DataStoreException
    Creates a `DataStore` capable to write or update the given storage. The `storage` argument can be any of the types documented in `open(Object)`. If the storage is a file and that file does not exist, then a new file will be created. If the storage exists, then it will be opened in read/write mode for updates. The returned data store should implement the `WritableGridCoverageResource`, `WritableFeatureSet` or `WritableAggregate` interface.

    #### Format selection

    The `preferredFormat` argument can be a data store name (examples: `"CSV"`, `"GPX"`) or an Image I/O name (examples: `"TIFF"`, `"PNG"`). In the latter case, the WorldFile convention is used.

    If the given storage exists (for example, an existing file), then the `DataStoreProvider` is determined by probing the existing content and the `preferredFormat` argument may be ignored (it can be `null`). Otherwise the `DataStoreProvider` is selected by a combination of `preferredFormat` (if non-null) and file suffix (if the storage is a file path or URI).

    Parameters:
      `storage` - the input/output object as a URL, file, image input stream, etc..
      `preferredFormat` - the format to use if not determined by the existing content, or `null`.
    Returns:
      the object to use for writing geospatial data in the given storage.
    Throws:
      `UnsupportedStorageException` - if no `DataStoreProvider` is found for the given storage object.
      `DataStoreException` - if an error occurred while opening the storage in write mode.
    Since:
      1.4