# Class DataStores

Object
DataStores

public final class DataStores extends Object
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`
  `open(Object storage, String preferredFormat)`
  Creates a `DataStore` capable to read the given storage, with a preference for the specified reader.
  `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.
  `static Optional<GridCoverage>`
  `readGridCoverage(Object storage, Envelope aoi)`
  Reads immediately the first grid coverage found in the given storage.

  ### 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.
    The file format is detected automatically by inspection of the file header. The file suffix may also be used in case of ambiguity.
    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.

  - ### open

    public static DataStore open(Object storage, String preferredFormat) throws UnsupportedStorageException, DataStoreException
    Creates a `DataStore` capable to read the given storage, with a preference for the specified reader. The `storage` argument can be of the same types as documented in `open(Object)`. The `preferredFormat` argument can be one of the following (non-exhaustive list). Note that which formats are available depend on which modules are on the module-path.

    Common formats
    Format | Description
    --- | ---
    `"ASCII Grid"` | ESRI ASCII Grid raster format
    `"BIL/BIP/BSQ"` | ESRI RAW binary encoding
    `"CSV"` | Comma-Separated Values, optionally with Moving Features
    `"folder"` | Directory of more files
    `"GDAL"` | Binding to the GDAL C/C++ library
    `"GeoTIFF"` | GeoTIFF, including big and COG variants
    `"GPX"` | GPS Exchange Format
    `"Landsat"` | Landsat 8 level 1-2 data
    `"NetCDF"` | NetCDF 3 (or 4 if UCAR dependency is included)
    `"SQL"` | Connection to a SQL database
    `"WKT"` | CRS definition in Well-Known Text format
    `"World file"` | World File image read through Java Image I/O
    `"XML"` | Metadata in GML format

    The preferred format is only a hint. If the `DataStore` identified by `preferredFormat` cannot open the given storage, another data store will be searched as with `open(Object)`. The actual format which has been selected is given by `DataStore​.getProvider()​.getShortName()`.

    #### Example

    If both the `org​.apache​.sis​.storage​.geotiff` and `org​.apache​.sis​.storage​.gdal` modules are present on the module-path, then the Apache SIS implementation is used by default for opening GeoTIFF files. For using GDAL instead, use this method with `"GDAL"` argument value.
    Parameters:
      `storage` - the input object as a URL, file, image input stream, etc..
      `preferredFormat` - identification of the preferred `DataStore` implementation, or `null`.
    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.
    Since:
      1.5
    See Also:
      - `DataStore​.getProvider()`
      - `DataStoreProvider​.getShortName()`

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

  - ### readGridCoverage

    public static Optional<GridCoverage> readGridCoverage(Object storage, Envelope aoi) throws UnsupportedStorageException, DataStoreException
    Reads immediately the first grid coverage found in the given storage. This is a convenience method searching for the first instance of `GridCoverageResource`. If the given storage contains two or more such instances, all resources after the first one are ignored.

    The Area Of Interest (AOI) is an optional argument for reducing the amount of data to load. It can be expressed using an arbitrary Coordinate Reference System (CRS), as transformations will be applied as needed. If the AOI does not specify a CRS, then the AOI is assumed to be in the CRS of the grid coverage to read. The returned grid coverage will not necessarily cover exactly the specified AOI. It may be smaller if the coverage does not cover the full AOI, or it may be larger for loading an integer number of tiles.

    On return, the grid coverage (possibly intersected with the AOI) has been fully loaded in memory. If lower memory consumption is desired, for example because the coverage is very large, then deferred tile loading should be used. The latter approach requires that the caller use `DataStore` directly, because the store needs to be open as long as the `GridCoverage` is used. See `RasterLoadingStrategy` for more details.

    Parameters:
      `storage` - the input object as a URL, file, image input stream, etc..
      `aoi` - spatiotemporal region of interest, or `null` for reading the whole coverage.
    Returns:
      the first grid coverage found in the given storage, or an empty value if none was found.
    Throws:
      `UnsupportedStorageException` - if no `DataStoreProvider` is found for the given storage object.
      `DataStoreException` - if an error occurred while opening the storage or reading the grid coverage.
      `DisjointExtentException` - if the given envelope does not intersect any resource extent.
    Since:
      1.5