public class StorageConnector extends Object implements Serializable
DataStore
in read and/or write mode.
StorageConnector
wraps an input Object
, which can be any of the following types:
File
for a file or a directory.URI
or a URL
to a distant resource.CharSequence
interpreted as a filename or a URL.Channel
, DataInput
, InputStream
or Reader
.DataSource
or a Connection
to a JDBC database.DataStore
-specific object, for example NetcdfFile
.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.
Defined in the sis-storage
module
Constructor and Description |
---|
StorageConnector(Object storage)
Creates a new data store connection wrapping the given input/output object.
|
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. |
public StorageConnector(Object storage)
storage
- The input/output object as a URL, file, image input stream, etc..public <T> T getOption(OptionKey<T> key)
null
if none.T
- The type of option value.key
- The option for which to get the value.null
if none.public <T> void setOption(OptionKey<T> key, T value)
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.T
- The type of option value.key
- The option for which to set the value.value
- The new value for the given option, or null
for removing the value.public Object getStorage()
getStorageAs(Class)
public String getStorageName()
File
, URI
or URL
instances, this method uses dedicated API.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.public String getFileExtension()
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
.null
.null
if the storage
is an object of unknown type.public <T> T getStorageAs(Class<T> type) throws IllegalArgumentException, DataStoreException
null
otherwise.
The default implementation accepts the following types:
String
:
File
, URL
, URI
or CharSequence
types,
returns the string representation of their path.null
.ByteBuffer
:
DataInput
section below, then this method returns the associated byte buffer.null
.DataInput
:
DataInput
(including the ImageInputStream
and ImageOutputStream
types),
then it is returned unchanged.File
,
URI
, URL
, CharSequence
, InputStream
or
ReadableByteChannel
, then an ImageInputStream
backed by a
ByteBuffer
is created when first needed and returned.ImageIO.createImageInputStream(Object)
returns a non-null value,
then this value is cached and returned.null
.ImageInputStream
:
DataInput
can be created and casted to ImageInputStream
, returns it.null
.InputStream
:
InputStream
,
then it is returned unchanged.ImageInputStream
can be created,
returns a wrapper around that stream.null
.Reader
:
Reader
,
then it is returned unchanged.InputStream
can be created, returns an InputStreamReader
using the encoding specified by OptionKey.ENCODING
if any, or using the system default
encoding otherwise.null
.Connection
:
Connection
,
then it is returned unchanged.DataSource
, then a connection is obtained
when first needed and returned.null
.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.T
- The compile-time type of the type
argument.type
- The desired type as one of ByteBuffer
, DataInput
, Connection
class or other type supported by StorageConnector
subclasses.null
if no view can be created for the given type.IllegalArgumentException
- If the given type
argument is not a known type.DataStoreException
- If an error occurred while opening a stream or database connection.getStorage()
,
closeAllExcept(Object)
public void closeAllExcept(Object view) throws DataStoreException
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.
view
- The view to leave open, or null
if none.DataStoreException
- If an error occurred while closing the stream or database connection.getStorageAs(Class)
,
DataStoreProvider.open(StorageConnector)
Copyright © 2010–2015 The Apache Software Foundation. All rights reserved.