Class DataStores

Object
Static
DataStores
public final class DataStores extends Static
Static convenience methods creating Data­Store instances from a given storage object. Storage objects are typically File or Data­Source instances, but can also be any other objects documented in the Storage­Connector class.
Since:
0.4

  • 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:
      Data­Store­Exception - if an error occurred while opening the storage.

    • open

      public static DataStore open(Object storage) throws UnsupportedStorageException, DataStoreException
      Creates a Data­Store capable to read the given storage. The storage argument can be any of the following types: 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:
      Unsupported­Storage­Exception - if no Data­Store­Provider is found for the given storage object.
      Data­Store­Exception - 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 Data­Store 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 preferred­Format 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 Data­Store identified by preferred­Format 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 Data­Store​.get­Provider()​.get­Short­Name().

      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..
      preferred­Format - identification of the preferred Data­Store implementation, or null.
      Returns:
      the object to use for reading geospatial data from the given storage.
      Throws:
      Unsupported­Storage­Exception - if no Data­Store­Provider is found for the given storage object.
      Data­Store­Exception - if an error occurred while opening the storage in read mode.
      Since:
      1.5
      See Also:

    • openWritable

      public static DataStore openWritable(Object storage, String preferredFormat) throws UnsupportedStorageException, DataStoreException
      Creates a Data­Store 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 Writable­Grid­Coverage­Resource, Writable­Feature­Set or Writable­Aggregate interface.

      Format selection

      The preferred­Format 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 Data­Store­Provider is determined by probing the existing content and the preferred­Format argument may be ignored (it can be null). Otherwise the Data­Store­Provider is selected by a combination of preferred­Format (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..
      preferred­Format - 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:
      Unsupported­Storage­Exception - if no Data­Store­Provider is found for the given storage object.
      Data­Store­Exception - 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 Grid­Coverage­Resource. 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 Data­Store directly, because the store needs to be open as long as the Grid­Coverage is used. See Raster­Loading­Strategy 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:
      Unsupported­Storage­Exception - if no Data­Store­Provider is found for the given storage object.
      Data­Store­Exception - if an error occurred while opening the storage or reading the grid coverage.
      Disjoint­Extent­Exception - if the given envelope does not intersect any resource extent.
      Since:
      1.5