Class StorageConnector

  • All Implemented Interfaces:
    Serializable

    public class StorageConnector
    extends Object
    implements Serializable
    Information for creating a connection to a Data­Store in read and/or write mode. Storage­Connector wraps an input Object, which can be any of the following types: The get­Storage­As(Class) method provides the storage as an object of the given type, opening the input stream if necessary. This class tries to open the stream only once - subsequent invocation of get­Storage­As(…) may return the same input stream.

    This class is used only for discovery of a Data­Store implementation capable to handle the input. Once a suitable Data­Store has been found, the Storage­Connector instance is typically discarded since each data store implementation will use their own input/output objects.

    Instances of this class are serializable if the storage object given at construction time is serializable.

    Since:
    0.3
    See Also:
    Serialized Form

    Defined in the sis-storage module

    • Constructor Detail

      • StorageConnector

        public StorageConnector​(Object storage)
        Creates a new data store connection wrapping the given input/output object. The object can be of any type, but the class javadoc lists the most typical ones.
        Parameters:
        storage - the input/output object as a URL, file, image input stream, etc..
    • Method Detail

      • getOption

        public <T> T getOption​(OptionKey<T> key)
        Returns the option value for the given key, or null if none.
        Type Parameters:
        T - the type of option value.
        Parameters:
        key - the option for which to get the value.
        Returns:
        the current value for the given option, or null if none.
      • setOption

        public <T> void setOption​(OptionKey<T> key,
                                  T value)
        Sets the option value for the given key. The default implementation recognizes the following options:
        Type Parameters:
        T - the type of option value.
        Parameters:
        key - the option for which to set the value.
        value - the new value for the given option, or null for removing the value.
      • getStorage

        public Object getStorage()
                          throws DataStoreException
        Returns the input/output object given at construction time. The object can be of any type, but the class javadoc lists the most typical ones.
        Returns:
        the input/output object as a URL, file, image input stream, etc..
        Throws:
        Data­Store­Exception - if the storage object has already been used and can not be reused.
        See Also:
        get­Storage­As(Class)
      • getStorageName

        public String getStorageName()
        Returns a short name of the input/output object. For example if the storage is a file, this method returns the filename without the path (but including the file extension). The default implementation performs the following choices based on the type of the storage object:
        • For Path, File, URI or URL instances, this method uses dedicated API like Path​.get­File­Name().
        • For Char­Sequence instances, this method gets a string representation of the storage object and returns the part after the last '/' character or platform-dependent name separator.
        • For instances of unknown type, this method builds a string representation using the class name. Note that the string representation of unknown types may change in any future SIS version.
        Returns:
        a short name of the storage object.
      • getFileExtension

        public String getFileExtension()
        Returns the filename extension of the input/output object. The default implementation performs the following choices based on the type of the storage object:
        • For Path, File, URI, URL or Char­Sequence instances, this method returns the string after the last '.' character in the filename, provided that the '.' is not the first filename character. This may be an empty string if the filename has no extension, but never null.
        • For instances of unknown type, this method returns null.
        Returns:
        the filename extension, or an empty string if none, or null if the storage is an object of unknown type.
      • getStorageAs

        public <T> T getStorageAs​(Class<T> type)
                           throws IllegalArgumentException,
                                  DataStoreException
        Returns the storage as a view of the given type if possible, or null otherwise. The default implementation accepts the following types: Multiple invocations of this method on the same Storage­Connector instance will try to return the same instance on a best effort basis. Consequently, implementations of Data­Store­Provider​.probe­Content(Storage­Connector) methods shall not close the stream or database connection returned by this method. In addition, those probe­Content(Storage­Connector) methods are responsible for restoring the stream or byte buffer to its original position on return.
        Type Parameters:
        T - the compile-time type of the type argument.
        Parameters:
        type - the desired type as one of Byte­Buffer, Data­Input, Connection class or other type supported by Storage­Connector subclasses.
        Returns:
        the storage as a view of the given type, or null if the given type is one of the supported types listed in javadoc but no view can be created for the source given at construction time.
        Throws:
        Illegal­Argument­Exception - if the given type argument is not one of the supported types listed in this javadoc or in subclass javadoc.
        Illegal­State­Exception - if this Storage­Connector has been closed.
        Data­Store­Exception - if an error occurred while opening a stream or database connection.
        See Also:
        get­Storage(), close­All­Except(Object)
      • closeAllExcept

        public void closeAllExcept​(Object view)
                            throws DataStoreException
        Closes all streams and connections created by this Storage­Connector except the given view. This method closes all objects created by the get­Storage­As(Class) method except the given view. If view is null, then this method closes everything including the storage if it is closeable.

        This method is invoked when a suitable Data­Store has been found - in which case the view used by the data store is given in argument to this method - or when no suitable Data­Store has been found - in which case the view argument is null.

        This Storage­Connector instance shall not be used anymore after invocation of this method.

        Parameters:
        view - the view to leave open, or null if none.
        Throws:
        Data­Store­Exception - if an error occurred while closing the stream or database connection.
        See Also:
        get­Storage­As(Class), Data­Store­Provider​.open(Storage­Connector)
      • toString

        public String toString()
        Returns a string representation of this Storage­Connector for debugging purpose. This string representation is for debugging purpose only and may change in any future version.
        Overrides:
        to­String in class Object
        Returns:
        a string representation of this Storage­Connector for debugging purpose.