org.apache.sis.storage

Class StorageConnector

Object

StorageConnector

All Implemented Interfaces:

Serializable

public class StorageConnector
extends Object
implements Serializable

Information for creating a connection to a DataStore in read and/or write mode. StorageConnector wraps an input Object, which can be any of the following types:

• A File for a file or a directory.
• A URI or a URL to a distant resource.
• A CharSequence interpreted as a filename or a URL.
• A Channel, DataInput, InputStream or Reader.
• A DataSource or a Connection to a JDBC database.
• Any other DataStore-specific object, for example ucar.nc2.NetcdfFile.

The getStorageAs(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 getStorageAs(…) may return the same input stream.

This class is used only for discovery of a DataStore implementation capable to handle the input. Once a suitable DataStore has been found, the StorageConnector 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 Summary

Constructors

Constructor and Description
StorageConnector(Object storage) Creates a new data store connection wrapping the given input/output object.

Method Summary

Methods

Modifier and Type	Method and Description
void	closeAllExcept(Object view) Closes all streams and connections created by this StorageConnector except the given view.
String	getFileExtension() Returns the filename extension of the input/output object.
<T> T	getOption(OptionKey<T> key) Returns the option value for the given key, or null if none.
Object	getStorage() Returns the input/output object given at construction time.
<T> T	getStorageAs(Class<T> type) Returns the storage as a view of the given type if possible, or null otherwise.
String	getStorageName() Returns a short name of the input/output object.
<T> void	setOption(OptionKey<T> key, T value) Sets the option value for the given key.
String	toString() Returns a string representation of this StorageConnector for debugging purpose.

Methods inherited from class Object

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

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:

• OptionKey.ENCODING for decoding characters in an input stream, if needed.
• OptionKey.URL_ENCODING for converting URL to URI or filename, if needed.
• OptionKey.OPEN_OPTIONS for specifying whether the data store shall be read only or read/write.
• OptionKey.BYTE_BUFFER for allowing users to control the byte buffer to be created.

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()

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..

See Also:

getStorageAs(Class)

getStorageName

public String getStorageName()

Returns a short name of the input/output object. The default implementation performs the following choices based on the type of the storage object:

• For File, URI or URL instances, this method uses dedicated API.
• For CharSequence 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 File, URI, URL or CharSequence 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:

• String:
  • If the storage object is an instance of the File, URL, URI or CharSequence types, returns the string representation of their path.
  • Otherwise this method returns null.
• ByteBuffer:
  • If the storage object can be obtained as described in bullet 2 of the DataInput section below, then this method returns the associated byte buffer.
  • Otherwise this method returns null.
• DataInput:
  • If the storage object is already an instance of DataInput (including the ImageInputStream and ImageOutputStream types), then it is returned unchanged.
  • Otherwise if the input is an instance of File, URI, URL, CharSequence, InputStream or ReadableByteChannel, then an ImageInputStream backed by a ByteBuffer is created when first needed and returned.
  • Otherwise if ImageIO.createImageInputStream(Object) returns a non-null value, then this value is cached and returned.
  • Otherwise this method returns null.
• ImageInputStream:
  • If the above DataInput can be created and casted to ImageInputStream, returns it.
  • Otherwise this method returns null.
• InputStream:
  • If the storage object is already an instance of InputStream, then it is returned unchanged.
  • Otherwise if the above ImageInputStream can be created, returns a wrapper around that stream.
  • Otherwise this method returns null.
• Reader:
  • If the storage object is already an instance of Reader, then it is returned unchanged.
  • Otherwise if the above InputStream can be created, returns an InputStreamReader using the encoding specified by OptionKey.ENCODING if any, or using the system default encoding otherwise.
  • Otherwise this method returns null.
• Connection:
  • If the storage object is already an instance of Connection, then it is returned unchanged.
  • Otherwise if the storage is an instance of DataSource, then a connection is obtained when first needed and returned.
  • Otherwise this method returns null.

Multiple invocations of this method on the same StorageConnector instance will try to return the same instance on a best effort basis. Consequently, implementations of DataStoreProvider.probeContent(StorageConnector) methods shall not close the stream or database connection returned by this method. In addition, those probeContent(StorageConnector) 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 ByteBuffer, DataInput, Connection class or other type supported by StorageConnector subclasses.

Returns:

The storage as a view of the given type, or null if no view can be created for the given type.

Throws:

IllegalArgumentException - If the given type argument is not a known type.

DataStoreException - If an error occurred while opening a stream or database connection.

See Also:

getStorage(), closeAllExcept(Object)

closeAllExcept

public void closeAllExcept(Object view)
                    throws DataStoreException

Closes all streams and connections created by this StorageConnector except the given view. This method closes all objects created by the getStorageAs(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 DataStore has been found - in which case the view used by the data store is given in argument to this method - or when no suitable DataStore has been found - in which case the view argument is null.

This StorageConnector instance shall not be used anymore after invocation of this method.

Parameters:

view - The view to leave open, or null if none.

Throws:

DataStoreException - If an error occurred while closing the stream or database connection.

See Also:

getStorageAs(Class), DataStoreProvider.open(StorageConnector)

toString

@Debug
public String toString()

Returns a string representation of this StorageConnector for debugging purpose.

Overrides:

toString in class Object