Class ProbeResult

java.lang.Object
org.apache.sis.storage.ProbeResult
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
ProbeResult.Constant

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 sometimes 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
Version:
0.4
See Also:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private static final class 
    Implementation of static constants defined in ProbeResult.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final ProbeResult
    The open capability cannot be determined because the ByteBuffer contains an insufficient amount of bytes.
    private final boolean
    true if the storage is supported by the DataStoreProvider.
    private final String
    The storage MIME type, or null if unknown or not applicable.
    private static final long
    For cross-version compatibility.
    static final ProbeResult
    The DataStoreProvider recognizes the given storage, but has no additional information.
    static final ProbeResult
    The open capability cannot be determined.
    static final ProbeResult
    The DataStoreProvider does not recognize the given storage object, file format or database schema.
    private final Version
    The version of file format or database schema used by the storage, or null if unknown or not applicable.
  • 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

    Modifier and Type
    Method
    Description
    boolean
    equals(Object object)
    Compares this ProbeResult with the given object for equality.
    Returns the MIME type of the storage file format, 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.
    int
    Returns a hash code value for this instance.
    boolean
    Returns true if the storage is supported by the DataStoreProvider.
    Returns a string representation of this ProbeResult for debugging purpose.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      For cross-version compatibility.
      See Also:
    • 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 of 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 of 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 cannot be determined because the ByteBuffer contains an insufficient amount of bytes. This value can be returned by DataStoreProvider.probeContent(StorageConnector) implementations as below: 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 another 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 cannot 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.

    • isSupported

      private final boolean isSupported
      true if the storage is supported by the DataStoreProvider.
      See Also:
    • mimeType

      private final String mimeType
      The storage MIME type, or null if unknown or not applicable.
      See Also:
    • version

      private final Version version
      The version of file format or database schema used by the storage, or null if unknown or not applicable.
      See Also:
  • Constructor Details

    • 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 Details

    • 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 ProbeResults 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