# Class GDALStoreProvider

Object
DataStoreProvider
GDALStoreProvider

public class GDALStoreProvider extends DataStoreProvider
The provider of `GDALStore` instances. Given a `StorageConnector` input, this class tries to instantiate a `GDALStore`. This data store uses the GDAL native library for loading data.

Each `GDALStoreProvider` instance is linked to a GDAL library specified at construction time, or to a JVM-wide shared GDAL library if the no-argument constructor is used. In the non-shared case, GDAL will be unloaded when this `GDALStoreProvider` instance is garbage collected.

Since:
  1.5

- ## Nested Class Summary

  ### Nested classes/interfaces inherited from class DataStoreProvider

  `DataStoreProvider​.Prober<S>`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final OptionKey<String[]>`
  `DRIVERS_OPTION_KEY`
  Key for declaring GDAL drivers that may be used for opening the file.

  ### Fields inherited from class DataStoreProvider

  `CREATE, LOCATION`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `GDALStoreProvider()`
  Creates a new provider which will load the GDAL library from the default library path.
  `GDALStoreProvider(Path library)`
  Creates a new provider which will load the GDAL library from the specified file.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `TreeTable`
  `configuration()`
  Returns the GDAL version number together with the list of drivers.
  `List<Driver>`
  `getDrivers()`
  Returns an unmodifiable list of all GDAL drivers currently available.
  `Logger`
  `getLogger()`
  Returns the logger used by GDAL stores.
  `ParameterDescriptorGroup`
  `getOpenParameters()`
  Returns a description of all parameters accepted by this provider for opening a file with GDAL.
  `Optional<LocalDate>`
  `getReleaseDate()`
  Returns the release date of the GDAL library.
  `String`
  `getShortName()`
  Returns a generic name for this data store, used mostly in warnings or error messages.
  `Optional<Version>`
  `getVersion()`
  Returns the version number of the GDAL library.
  `DataStore`
  `open(StorageConnector connector)`
  Creates a `GDALStore` instance associated with this provider.
  `DataStore`
  `open(ParameterValueGroup parameters)`
  Creates a `GDALStore` instance from the given parameters.
  `ProbeResult`
  `probeContent(StorageConnector connector)`
  Returns the MIME type if the given storage appears to be supported by this data store.

  ### Methods inherited from class DataStoreProvider

  `getFormat, getSupportedVersions, probeContent`

  ### Methods inherited from class Object

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

- ## Field Details

  - ### DRIVERS_OPTION_KEY

    public static final OptionKey<String[]> DRIVERS_OPTION_KEY
    Key for declaring GDAL drivers that may be used for opening the file. Drivers are identified by their short names. The drivers will be tested in the order they are specified.
    See Also:
      - `Driver​.getIdentifier()`

- ## Constructor Details

  - ### GDALStoreProvider

    public GDALStoreProvider()
    Creates a new provider which will load the GDAL library from the default library path.

  - ### GDALStoreProvider

    public GDALStoreProvider(Path library)
    Creates a new provider which will load the GDAL library from the specified file. The library will be unloaded when this provider will be garbage-collected.
    Parameters:
      `library` - path to the library to load.
    Throws:
      `IllegalArgumentException` - if the GDAL library has not been found.
      `NoSuchElementException` - if a GDAL function has not been found in the library.
      `IllegalCallerException` - if this Apache SIS module is not authorized to call native methods.

- ## Method Details

  - ### getShortName

    public String getShortName()
    Returns a generic name for this data store, used mostly in warnings or error messages.
    Specified by:
      `getShortName` in class `DataStoreProvider`
    Returns:
      a short name or abbreviation for the data store.
    See Also:
      - `DataStoreProvider​.getFormat()`

  - ### getVersion

    public Optional<Version> getVersion()
    Returns the version number of the GDAL library. The returned version contains 4 components. Example: 3.6.3.0.
    Returns:
      GDAL version, or empty if the GDAL library has not been found.

  - ### getReleaseDate

    public Optional<LocalDate> getReleaseDate()
    Returns the release date of the GDAL library.
    Returns:
      the release date, or empty if the GDAL library has not been found.

  - ### getDrivers

    public List<Driver> getDrivers()
    Returns an unmodifiable list of all GDAL drivers currently available.
    Returns:
      all GDAL drivers, or an empty list if the GDAL library has not been found.

  - ### configuration

    public TreeTable configuration() throws DataStoreException
    Returns the GDAL version number together with the list of drivers. The GDAL version is in the root node, and drivers are listed as children. The table contains the following columns:
    1. invalid reference

           TableColumn#NAME

       for the value returned by
       invalid reference

           #getName()

       .
    2. invalid reference

           TableColumn#IDENTIFIER

       for the value returned by
       invalid reference

           #getIdentifier()

       .
    The current version lists only the drivers having raster capability, because this is the only type of data supported by the current implementation of this module.
    Returns:
      a table of available GDAL drivers.
    Throws:
      `DataStoreException` - if an error occurred while querying GDAL metadata.

  - ### getOpenParameters

    public ParameterDescriptorGroup getOpenParameters()
    Returns a description of all parameters accepted by this provider for opening a file with GDAL.
    Specified by:
      `getOpenParameters` in class `DataStoreProvider`
    Returns:
      description of available parameters for opening a file with GDAL.
    See Also:
      - `DataStoreProvider​.LOCATION`
      - `DataStoreProvider​.CREATE`
      - `DataStoreProvider​.open(ParameterValueGroup)`
      - `DataStore​.getOpenParameters()`

  - ### probeContent

    public ProbeResult probeContent(StorageConnector connector) throws DataStoreException
    Returns the MIME type if the given storage appears to be supported by this data store. A supported status does not guarantee that reading or writing will succeed, only that there appears to be a reasonable chance according GDAL.
    Specified by:
      `probeContent` in class `DataStoreProvider`
    Parameters:
      `connector` - information about the storage (URL, stream, etc).
    Returns:
      a supported status with the MIME type if the given storage seems to be readable by `GDALStore` instances.
    Throws:
      `DataStoreException` - if an I/O error occurred.

  - ### open

    public DataStore open(StorageConnector connector) throws DataStoreException
    Creates a `GDALStore` instance associated with this provider.
    Specified by:
      `open` in class `DataStoreProvider`
    Parameters:
      `connector` - information about the storage (URL, stream, etc).
    Returns:
      a data store implementation associated with this provider for the given storage.
    Throws:
      `DataStoreException` - if an error occurred while creating the data store instance.
    See Also:
      - `DataStores​.open(Object)`

  - ### open

    public DataStore open(ParameterValueGroup parameters) throws DataStoreException
    Creates a `GDALStore` instance from the given parameters.
    Overrides:
      `open` in class `DataStoreProvider`
    Parameters:
      `parameters` - opening parameters as defined by `getOpenParameters()`.
    Returns:
      a data store instance associated with this provider for the given parameters.
    Throws:
      `DataStoreException` - if an error occurred while creating the data store instance.
    See Also:
      - `DataStoreProvider​.LOCATION`
      - `DataStoreProvider​.CREATE`
      - `DataStoreProvider​.getOpenParameters()`

  - ### getLogger

    public Logger getLogger()
    Returns the logger used by GDAL stores.
    Overrides:
      `getLogger` in class `DataStoreProvider`
    Returns:
      the logger to use as a fallback (when there are no listeners) for warning messages.
    See Also:
      - `StoreListeners​.getLogger()`