Package org.apache.sis.storage

## Class ProbeResult

- Object
- - ProbeResult

- All Implemented Interfaces:
    `Serializable`

      public class ProbeResult
      extends Object
      implements Serializable

  Tells whether a storage (file, database) appears to be supported by a `DataStore`. `ProbeResult` may also provide additional information, like file MIME type and the format version.
  Usage
  When a `DataStores​.open(…)` method is invoked, SIS will iterate over the list of known providers and invoke the `DataStoreProvider​.probeContent(StorageConnector)` method for each of them. The `ProbeResult` value returned by `probeContent(…)` tells to SIS whether a particular `DataStoreProvider` instance has reasonable chances to be able to handle the given storage.

  Whether a storage appears to be supported or not is given by the `isSupported()` property. Other properties like `getVersion()` are sometime available for both supported and unsupported storages. For example a file may be encoded in a known format, but may be using an unsupported version of that format.

  Special values
  In addition to the supported/unsupported information, `ProbeResult` defines two constants having a special meaning: `INSUFFICIENT_BYTES` and `UNDETERMINED`, which indicate that the provider does not have enough information for telling whether the storage can be opened. In such cases, SIS will revisit those providers only if no better suited provider is found.
  Since:
    0.4
  See Also:
    `DataStoreProvider​.probeContent(StorageConnector)`, Serialized Form

  Defined in the `sis-storage` module

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static ProbeResult` | `INSUFFICIENT_BYTES` | The open capability can not be determined because the `ByteBuffer` contains an insufficient amount of bytes.
    `static ProbeResult` | `SUPPORTED` | The `DataStoreProvider` recognizes the given storage, but has no additional information.
    `static ProbeResult` | `UNDETERMINED` | The open capability can not be determined.
    `static ProbeResult` | `UNSUPPORTED_STORAGE` | The `DataStoreProvider` does not recognize the given storage object, file format or database schema.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ProbeResult​(boolean isSupported, String mimeType, Version version)` | Creates a new `ProbeResult` with the given support status, MIME type and version number.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `equals​(Object object)` | Compares this `ProbeResult` with the given object for equality.
    `String` | `getMimeType()` | Returns the MIME type of the storage file format, or `null` if unknown or not applicable.
    `Version` | `getVersion()` | Returns the version of file format or database schema used by the storage, or `null` if unknown or not applicable.
    `int` | `hashCode()` | Returns a hash code value for this instance.
    `boolean` | `isSupported()` | Returns `true` if the storage is supported by the `DataStoreProvider`.
    `String` | `toString()` | Returns a string representation of this `ProbeResult` for debugging purpose.

    - ### Methods inherited from class Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### SUPPORTED

          public static final ProbeResult SUPPORTED

      The `DataStoreProvider` recognizes the given storage, but has no additional information. The `isSupported()` method returns `true`, but the MIME type and version properties are `null`.

      `DataStoreProvider​.probeContent(StorageConnector)` implementations should consider returning a new instance instead than this constant if they can provide the file MIME type or the format version number.

    - #### UNSUPPORTED_STORAGE

          public static final ProbeResult UNSUPPORTED_STORAGE

      The `DataStoreProvider` does not recognize the given storage object, file format or database schema. No other information is available: the `isSupported()` method returns `false`, and the MIME type and version properties are `null`.

      Examples:

      - The storage is a file while the provider expected a database connection (or conversely).
      - The file does not contains the expected magic number.
      - The database schema does not contain the expected tables.
      `DataStoreProvider​.probeContent(StorageConnector)` implementations should consider returning a new instance instead than this constant if the `DataStoreProvider` recognizes the given storage, but the data are structured according a file or schema version not yet supported by the current implementation.

    - #### INSUFFICIENT_BYTES

          public static final ProbeResult INSUFFICIENT_BYTES

      The open capability can not be determined because the `ByteBuffer` contains an insufficient amount of bytes. This value can be returned by `DataStoreProvider​.probeContent(StorageConnector)` implementations as below:

      >     public ProbeResult probeContent(StorageConnector storage) throws DataStoreException {
      >         final ByteBuffer buffer = storage.getStorageAs(ByteBuffer.class);
      >         if (buffer == null) {
      >             return ProbeResult.UNSUPPORTED_STORAGE;
      >         }
      >         if (buffer.remaining() < Integer.BYTES) {
      >             return ProbeResult.INSUFFICIENT_BYTES;
      >         }
      >         // Other verifications here.
      >     }

      When searching for a provider capable to read a given file, if at least one `DataStoreProvider` returns `INSUFFICIENT_BYTES`, then:
      1. SIS will continue to search for an other provider for which `probeContent(…)` declares to support the storage, using only the available bytes.
      2. Only if no such provider can be found, then SIS will fetch more bytes and query again the providers that returned `INSUFFICIENT_BYTES` in the previous iteration.
      SIS tries to work with available bytes before to ask more in order to reduce latencies on network connections.

    - #### UNDETERMINED

          public static final ProbeResult UNDETERMINED

      The open capability can not be determined. This value may be returned by `DataStore` implementations that could potentially open anything, for example the RAW image format.

      This is a last resort value! `probeContent(…)` implementations are strongly encouraged to return a more accurate enumeration value for allowing `DataStores​.open(Object)` to perform a better choice. Generally, this value should be returned only by the RAW image format.

  - ### Constructor Detail

    - #### ProbeResult

          public ProbeResult​(boolean isSupported,
                             String mimeType,
                             Version version)

      Creates a new `ProbeResult` with the given support status, MIME type and version number.
      Parameters:
        `isSupported` - `true` if the storage is supported by the `DataStoreProvider`.
        `mimeType` - the storage MIME type, or `null` if unknown or not applicable.
        `version` - the version of file format or database schema used by the storage, or `null` if unknown or not applicable.

  - ### Method Detail

    - #### isSupported

          public boolean isSupported()

      Returns `true` if the storage is supported by the `DataStoreProvider`. `DataStore` instances created by that provider are likely (but not guaranteed) to be able to read from - and eventually write to - the given storage.
      Returns:
        `true` if the storage is supported by the `DataStoreProvider`.

    - #### getMimeType

          public String getMimeType()

      Returns the MIME type of the storage file format, or `null` if unknown or not applicable. The `DataStoreProvider` may (at implementation choice) inspect the storage content for determining a more accurate MIME type.
      XML types
      A generic MIME type for XML documents is `"application/xml"`. However many other MIME types exist for XML documents compliant to some particular shema. Those types can be determined by inspecting the namespace of XML root element. The following table gives some example:

      MIME type examples
      MIME type | Description | Namespace
      --- | --- | ---
      `"application/gml+xml"` | Official mime type for OGC GML | "http://www.opengis.net/gml/3.2"
      `"application/vnd.eu.europa.ec.inspire.resource+xml"` | Official mime type for INSPIRE Resources |
      `"application/vnd.iso.19139+xml"` | Unofficial mime type for ISO 19139 metadata | "http://www.isotc211.org/2005/gmd"
      `"application/vnd.ogc.wms_xml"` | Unofficial mime type for OGC WMS |
      `"application/vnd.ogc.wfs_xml"` | Unofficial mime type for OGC WFS |
      `"application/vnd.ogc.csw_xml"` | Unofficial mime type for OGC CSW | "http://www.opengis.net/cat/csw/3.0"
      `"application/vnd.google-earth.kml+xml"` |  |
      `"application/rdf+xml"` |  |
      `"application/soap+xml"` |  |

      Returns:
        the storage MIME type, or `null` if unknown or not applicable.

    - #### getVersion

          public Version getVersion()

      Returns the version of file format or database schema used by the storage, or `null` if unknown or not applicable.
      Returns:
        the version of file format or database schema used by the storage, or `null` if unknown or not applicable.

    - #### hashCode

          public int hashCode()

      Returns a hash code value for this instance.
      Overrides:
        `hashCode` in class `Object`

    - #### equals

          public boolean equals​(Object object)

      Compares this `ProbeResult` with the given object for equality. Two `ProbeResult`s are equal if they are instances of the same class and all their properties are equal.
      Overrides:
        `equals` in class `Object`
      Parameters:
        `object` - the object to compare with this `ProbeResult`.
      Returns:
        `true` if the two objects are equal.

    - #### toString

          public String toString()

      Returns a string representation of this `ProbeResult` for debugging purpose.
      Overrides:
        `toString` in class `Object`