Module org.apache.sis.storage

Package 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 Data­Store in read and/or write mode. Storage­Connector wraps an input Object, which can be any of the following types:

• A Path or a File for a file or a directory.
• A URI or a URL to a distant resource.
• A Char­Sequence interpreted as a filename or a URL.
• A Channel, Data­Input, Input­Stream or Reader.
• A Data­Source or a Connection to a JDBC database.
• Any other Data­Store-specific object, for example Netcdf­File.

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.

Limitations

This class is not thread-safe. Not only Storage­Connector should be used by a single thread, but the objects returned by get­Storage­As(Class) should also be used by the same thread.

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

Since:

0.3

See Also:

• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
static final int	DEFAULT_BUFFER_SIZE	The default size (in bytes) of Byte­Buffers created by storage connectors.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
void	close­All­Except(Object view)	Closes all streams and connections created by this Storage­Connector except the given view.
<S> S	commit(Class<S> type, String format)	Returns the storage as a view of the given type and closes all other views.
String	get­File­Extension()	Returns the filename extension of the input/output object.
<T> T	get­Option(Option­Key<T> key)	Returns the option value for the given key, or null if none.
Object	get­Storage()	Returns the input/output object given at construction time.
<S> S	get­Storage­As(Class<S> type)	Returns the storage as a view of the given type if possible, or null otherwise.
String	get­Storage­Name()	Returns a short name of the input/output object.
<T> void	set­Option(Option­Key<T> key, T value)	Sets the option value for the given key.
String	to­String()	Returns a string representation of this Storage­Connector for debugging purpose.
boolean	was­Probing­Absent­File()	Returns whether returning the storage would have required the creation of a new file.

Methods inherited from class Object

clone, equals, finalize, get­Class, hash­Code, notify, notify­All, wait, wait, wait

Field Details

DEFAULT_BUFFER_SIZE

public static final int DEFAULT_BUFFER_SIZE

The default size (in bytes) of Byte­Buffers created by storage connectors. Those buffers are typically created when the specified storage object is a File, Path, URL or URI. The default buffer size is arbitrary and may change in any future Apache SIS version.

Users can override this value by providing a value for Option­Key.BYTE_BUFFER.

Since:

1.4

See Also:

• Option­Key.BYTE_BUFFER
• Constant Field Values

Constructor Details

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 Details

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:

• Option­Key.ENCODING for decoding characters in an input stream, if needed.
• Option­Key.URL_ENCODING for converting URL to URI or filename, if needed.
• Option­Key.OPEN_OPTIONS for specifying whether the data store shall be read only or read/write.
• Option­Key.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()
                  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 cannot 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 <S> S getStorageAs(Class<S> 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 Path, File, URL, URI or Char­Sequence types, returns the string representation of their path.
  • Otherwise this method returns null.
• Path, URI, URL, File:
  • If the storage object is an instance of the Path, File, URL, URI or Char­Sequence types and that type can be converted to the requested type, returned the conversion result.
  • Otherwise this method returns null.
• Byte­Buffer:
  • If the storage object can be obtained as described in bullet 2 of the Data­Input section below, then this method returns the associated byte buffer.
  • Otherwise this method returns null.
• Data­Input:
  • If the storage object is already an instance of Data­Input (including the Image­Input­Stream and Image­Output­Stream types), then it is returned unchanged.
  • Otherwise if the input is an instance of Byte­Buffer, then an Image­Input­Stream backed by a read-only view of that buffer is created when first needed and returned. The properties (position, mark, limit) of the original buffer are unmodified.
  • Otherwise if the input is an instance of Path, File, URI, URL, Char­Sequence, Input­Stream or Readable­Byte­Channel, then an Image­Input­Stream backed by a Byte­Buffer is created when first needed and returned.
  • Otherwise if Image­IO.create­Image­Input­Stream(Object) returns a non-null value, then this value is cached and returned.
  • Otherwise this method returns null.
• Image­Input­Stream:
  • If the above Data­Input can be created and casted to Image­Input­Stream, returns it.
  • Otherwise this method returns null.
• Input­Stream:
  • If the storage object is already an instance of Input­Stream, then it is returned unchanged.
  • Otherwise if the above Image­Input­Stream 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 Input­Stream can be created, returns an Input­Stream­Reader using the encoding specified by Option­Key.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 Data­Source, then a connection is obtained when first needed and returned.
  • Otherwise this method returns null.
• Any other types:
  • If the storage given at construction time is already an instance of the requested type, returns it as-is.
  • Otherwise this method throws Illegal­Argument­Exception.

Usage for probing operations

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. For an easier and safer way to ensure that the storage position is not modified, see Data­Store­Provider.probe­Content(Storage­Connector, Class, Prober).

Type Parameters:

S - the compile-time type of the type argument (the source or storage type).

Parameters:

type - the desired type as one of Byte­Buffer, Data­Input, Connection class or other types 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. In the latter case, was­Probing­Absent­File() can be invoked for determining whether the reason is that the file does not exist but could be created.

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)
• Data­Store­Provider.probe­Content(Storage­Connector, Class, Prober)

wasProbingAbsentFile

public boolean wasProbingAbsentFile()

Returns whether returning the storage would have required the creation of a new file. This method may return true if all the following conditions are true:

• A previous get­Storage­As(Class) call requested some kind of input stream (e.g. Input­Stream, Image­Input­Stream, Data­Input, Reader).
• The storage is an object convertible to a Path and the file identified by that path does not exist.
• The optons given to this Storage­Connector include Standard­Open­Option.CREATE or CREATE_NEW.
• The get­Storage­As(…) and was­Probing­Absent­File() calls happened in the context of Data­Stores probing the storage content in order to choose a Data­Store­Provider.

If all above conditions are true, then get­Storage­As(Class) returns null instead of creating a new empty file. In such case, Data­Store­Provider may use this was­Probing­Absent­File() method for deciding whether to report Probe­Result.SUPPORTED or Probe­Result.UNSUPPORTED_STORAGE.

Rational

When the file does not exist and the CREATE or CREATE_NEW option is provided, get­Storage­As(…) would normally create a new empty file. However this behavior is modified during probing (the first condition in above list) because newly created files are empty and probing empty files may result in EOFException to be thrown or in providers declaring that they do not support the storage.

IF the CREATE or CREATE_NEW options were not provided, then probing the storage content of an absent file will rather throw No­Such­File­Exception or File­Not­Found­Exception. So this method is useful only for Data­Store having write capabilities.

Returns:

whether returning the storage would have required the creation of a new file.

Since:

1.4

commit

public <S> S commit(Class<S> type,
 String format)
             throws IllegalArgumentException,
DataStoreException

Returns the storage as a view of the given type and closes all other views. Invoking this method is equivalent to invoking get­Storage­As(Class) followed by close­All­Except(Object) except that the latter method is always invoked (in a way similar to "try with resource") and that this method never returns null.

Type Parameters:

S - the compile-time type of the type argument (the source or storage type).

Parameters:

type - the desired type as one of the types documented in get­Storage­As(Class) (example: Byte­Buffer, Data­Input, Connection).

format - short name or abbreviation of the data format (e.g. "CSV", "GML", "WKT", etc). Used for information purpose in error messages if needed.

Returns:

the storage as a view of the given type. Never null.

Throws:

Illegal­Argument­Exception - if the given type argument is not one of the supported types.

Illegal­State­Exception - if this Storage­Connector has been closed.

Data­Store­Exception - if an error occurred while opening a stream or database connection.

Since:

1.2

See Also:

• get­Storage­As(Class)
• 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 diagnostic and may change in any future version.

Overrides:

to­String in class Object

Returns:

a string representation of this Storage­Connector for debugging purpose.