Class StorageConnector
- All Implemented Interfaces:
Serializable
DataStore
in read and/or write mode.
StorageConnector
wraps an input Object
, which can be any of the following types:
- A
Path
or aFile
for a file or a directory. - A
URI
or aURL
to a distant resource. - A
CharSequence
interpreted as a filename or a URL. - A
Channel
,DataInput
,InputStream
orReader
. - A
DataSource
or aConnection
to a JDBC database. - Any other
DataStore
-specific object, for exampleinvalid reference
ucar.nc2.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.
Limitations
This class is not thread-safe. Not onlyStorageConnector
should be used by a single thread,
but the objects returned by getStorageAs(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
- Version:
- 1.3
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static final class
private static interface
Handler toStorageConnector.createFoo()
methods associated to given storage types. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final byte
A flag foraddView(…, view, source, flags)
telling that after closing theview
, we also need to close thesource
.private static final byte
A flag foraddView(…, view, source, flags)
telling that before resetting theview
, we need to reset thesource
first.private static final byte
A flag foraddView(…, view, source, flags)
telling thatview
cannot be reset, so it should be set tonull
instead.(package private) static final int
The default size of theByteBuffer
to be created.private String
The filename extension, ornull
if none.(package private) static final int
The minimal size of theByteBuffer
to be created.private String
A name for the input/output object, ornull
if none.private static final Map
<Class<?>, StorageConnector.Opener<?>> List of types recognized bygetStorageAs(Class)
, associated to the methods for opening stream of those types.The options, created only when first needed.private static final long
For cross-version compatibility.(package private) final Object
The input/output object given at construction time.private Map
<Class<?>, StorageConnector.Coupled> Views ofstorage
as instances of types different than the type of the object given to the constructor. -
Constructor Summary
ConstructorsConstructorDescriptionStorageConnector
(Object storage) Creates a new data store connection wrapping the given input/output object. -
Method Summary
Modifier and TypeMethodDescriptionprivate static <S> void
add
(Class<S> type, StorageConnector.Opener<S> op) Helper method forOPENERS
static initialization.private <S> void
Adds the given view in the cache, without dependencies.private <S> void
Adds the given view in the cache together with information about its dependency.void
closeAllExcept
(Object view) Closes all streams and connections created by thisStorageConnector
except the given view.<S> S
Returns the storage as a view of the given type and closes all other views.private ByteBuffer
private ChannelDataInput
createChannelDataInput
(boolean asImageInputStream) Creates a view for the input as aChannelDataInput
if possible.private ChannelDataOutput
Creates a view for the storage as aChannelDataOutput
if possible.private Connection
Creates a database connection if possible.private DataInput
Creates a view for the input as aDataInput
if possible.private DataOutput
Creates a view for the output as aDataOutput
if possible.private ImageInputStream
Creates anImageInputStream
from theDataInput
if possible.private InputStream
Creates an input stream fromReadableByteChannel
if possible, or fromImageInputStream
otherwise.private OutputStream
Creates an output stream fromWritableByteChannel
if possible, or fromImageOutputStream
otherwise.private Reader
Creates a character reader if possible.private String
Returns the storage as a path if possible, ornull
otherwise.private ByteBuffer
getChannelBuffer
(ChannelFactory factory) Returns or allocate a buffer for use with theChannelDataInput
orChannelDataOutput
.Returns the filename extension of the input/output object.<T> T
Returns the option value for the given key, ornull
if none.Returns the input/output object given at construction time.<S> S
getStorageAs
(Class<S> type) Returns the storage as a view of the given type if possible, ornull
otherwise.Returns a short name of the input/output object.private StorageConnector.Coupled
Returns the view for the given type from the cache.(package private) static boolean
isSupportedType
(Class<?> type) Returnstrue
if the given type is one of the types supported byStorageConnector
.(package private) final boolean
prefetch()
Transfers more bytes from theDataInput
to theByteBuffer
, if possible.private void
reset()
Resets the rootstorage
object.private boolean
Resets the given view.<T> void
Sets the option value for the given key.toString()
Returns a string representation of thisStorageConnector
for debugging purpose.private static IOException
Returns the cause of given exception if it exists, or the exception itself otherwise.
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDFor cross-version compatibility.- See Also:
-
DEFAULT_BUFFER_SIZE
static final int DEFAULT_BUFFER_SIZEThe default size of theByteBuffer
to be created. Users can override this value by providing a value forOptionKey.BYTE_BUFFER
.This buffer capacity is also used as read-ahead limit for mark operations. The rational is to allow as many bytes as contained in buffers of default size. For increasing the chances to meet that goal, this size should be the same than
BufferedInputStream
default buffer size.- See Also:
-
MINIMAL_BUFFER_SIZE
static final int MINIMAL_BUFFER_SIZEThe minimal size of theByteBuffer
to be created. This size is used only for temporary buffers that are unlikely to be used for the actual reading process.- See Also:
-
CASCADE_ON_CLOSE
private static final byte CASCADE_ON_CLOSEA flag foraddView(…, view, source, flags)
telling that after closing theview
, we also need to close thesource
. This flag should be set when the view is anImageInputStream
because Java I/OFileCacheImageInputStream.close()
does not close the underlying stream. For most other kinds of view, this flag should not be set.- See Also:
-
CASCADE_ON_RESET
private static final byte CASCADE_ON_RESETA flag foraddView(…, view, source, flags)
telling that before resetting theview
, we need to reset thesource
first. This flag should can be unset if any change in the position ofview
is immediately reflected in the position ofsource
, and vice-versa.- See Also:
-
CLEAR_ON_RESET
private static final byte CLEAR_ON_RESETA flag foraddView(…, view, source, flags)
telling thatview
cannot be reset, so it should be set tonull
instead. This implies that a new view of the same type will be recreated next time it will be requested.When this flag is set, the
CASCADE_ON_RESET
should usually be set at the same time.- See Also:
-
OPENERS
List of types recognized bygetStorageAs(Class)
, associated to the methods for opening stream of those types. This map shall contain every types documented ingetStorageAs(Class)
javadoc.null
values means to useObjectConverters
for that particular type. -
storage
The input/output object given at construction time.- See Also:
-
name
A name for the input/output object, ornull
if none. This field is initialized only when first needed. -
extension
The filename extension, ornull
if none. This field is initialized only when first needed. -
options
The options, created only when first needed.- See Also:
-
views
Views ofstorage
as instances of types different than the type of the object given to the constructor. Thenull
reference can appear in various places:- A non-existent entry (equivalent to an entry associated to the
null
value) means that the value has not yet been computed. - A valid entry with
StorageConnector.Coupled.view
set tonull
means the value has been computed and we have determined thatgetStorageAs(Class)
shall returnnull
for that type. - By convention, the
null
key is associated to thestorage
value.
StorageConnector
has been closed.- See Also:
- A non-existent entry (equivalent to an entry associated to the
-
-
Constructor Details
-
StorageConnector
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
-
add
Helper method forOPENERS
static initialization. -
getOption
Returns the option value for the given key, ornull
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
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, ornull
for removing the value.
-
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..
- Throws:
DataStoreException
- if the storage object has already been used and cannot be reused.- See Also:
-
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
orURL
instances, this method uses dedicated API likePath.getFileName()
. - 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.
- For
-
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
orCharSequence
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 nevernull
. - 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.
- For
-
isSupportedType
Returnstrue
if the given type is one of the types supported byStorageConnector
. The list of supported types is hard-coded and may change in any future version. -
getStorageAs
Returns the storage as a view of the given type if possible, ornull
otherwise. The default implementation accepts the following types:String
:Path
,URI
,URL
,File
: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
.
- If the storage object can be obtained as described in bullet 2 of the
DataInput
:- If the storage object is already an instance of
DataInput
(including theImageInputStream
andImageOutputStream
types), then it is returned unchanged. - Otherwise if the input is an instance of
ByteBuffer
, then anImageInputStream
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
,CharSequence
,InputStream
orReadableByteChannel
, then anImageInputStream
backed by aByteBuffer
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
.
- If the storage object is already an instance of
ImageInputStream
:- If the above
DataInput
can be created and casted toImageInputStream
, returns it. - Otherwise this method returns
null
.
- If the above
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
.
- If the storage object is already an instance of
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 anInputStreamReader
using the encoding specified byOptionKey.ENCODING
if any, or using the system default encoding otherwise. - Otherwise this method returns
null
.
- If the storage object is already an instance of
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
.
- If the storage object is already an instance of
- 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
IllegalArgumentException
.
Usage for probing operations
Multiple invocations of this method on the sameStorageConnector
instance will try to return the same instance on a best effort basis. Consequently, implementations ofDataStoreProvider.probeContent(StorageConnector)
methods shall not close the stream or database connection returned by this method. In addition, thoseprobeContent(StorageConnector)
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, seeDataStoreProvider.probeContent(StorageConnector, Class, Prober)
.- Type Parameters:
S
- the compile-time type of thetype
argument (the source or storage type).- Parameters:
type
- the desired type as one ofByteBuffer
,DataInput
,Connection
class or other types supported byStorageConnector
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:
IllegalArgumentException
- if the giventype
argument is not one of the supported types listed in this javadoc or in subclass javadoc.IllegalStateException
- if thisStorageConnector
has been closed.DataStoreException
- if an error occurred while opening a stream or database connection.- See Also:
-
reset
Resets the given view. If the view is an instance ofInputStream
,ReadableByteChannel
or other objects that may be affected by views operations, this method will reset the storage position. The view must have been previously marked byInputStream.mark(int)
or equivalent method.This method is not a substitute for the requirement that users leave the
getStorageAs(Class)
return value in the same state as they found it. This method is only for handling the cases where using a view has an indirect impact on another view.Rational:DataStoreProvider.probeContent(StorageConnector)
contract requires that implementers reset the input stream themselves. However ifChannelDataInput
orInputStreamReader
has been used, then the user performed a call toChannelData.reset()
(for instance), which did not reset the underlying input stream. So we need to perform the missingInputStream.reset()
here, then synchronize theChannelDataInput
position accordingly.- Parameters:
c
- container of the view to reset, ornull
if none.- Returns:
true
if the given view, after reset, is valid. Note thatStorageConnector.Coupled.view
may be null and valid.- Throws:
DataStoreException
-
reset
Resets the rootstorage
object.- Throws:
DataStoreException
- if the storage cannot be reset.
-
createChannelDataInput
private ChannelDataInput createChannelDataInput(boolean asImageInputStream) throws IOException, DataStoreException Creates a view for the input as aChannelDataInput
if possible. This is also a starting point forcreateDataInput()
andcreateByteBuffer()
. This method is one of theOPENERS
methods and should be invoked at most once perStorageConnector
instance.- Parameters:
asImageInputStream
- whether theChannelDataInput
needs to beChannelImageInputStream
subclass.- Throws:
IOException
- if an error occurred while opening a channel for the input.DataStoreException
- See Also:
-
createDataInput
Creates a view for the input as aDataInput
if possible. This method performs the choice documented in thegetStorageAs(Class)
method for theDataInput
case. Opening the data input may imply creating aByteBuffer
, in which case the buffer will be stored under theByteBuffer.class
key together with theDataInput.class
case.This method is one of the
OPENERS
methods and should be invoked at most once perStorageConnector
instance.- Throws:
IOException
- if an error occurred while opening a stream for the input.DataStoreException
- See Also:
-
getChannelBuffer
Returns or allocate a buffer for use with theChannelDataInput
orChannelDataOutput
. If the user did not specified a buffer, this method may allocate a direct buffer for better leveraging ofChannelDataInput
, which tries hard to transfer data in the most direct way between buffers and arrays. By contrast creating a heap buffer may imply the use of a temporary direct buffer cached by the JDK itself (in JDK internal implementation).- Parameters:
factory
- the factory which will be used for creating the readable or writable channel.- Returns:
- the byte buffer to use with
ChannelDataInput
orChannelDataOutput
.
-
createByteBuffer
Creates aByteBuffer
from theChannelDataInput
if possible, or from theImageInputStream
otherwise. The buffer will be initialized with an arbitrary amount of bytes read from the input. If this amount is not sufficient, it can be increased by a call toprefetch()
.This method is one of the
OPENERS
methods and should be invoked at most once perStorageConnector
instance.- Throws:
IOException
- if an error occurred while opening a stream for the input.DataStoreException
-
prefetch
Transfers more bytes from theDataInput
to theByteBuffer
, if possible. This method returnstrue
on success, orfalse
if input is not a readable channel or stream, we have reached the end of stream, or the buffer is full.This method is invoked when the amount of bytes in the buffer appears to be insufficient for
DataStoreProvider.probeContent(StorageConnector)
purpose.- Returns:
true
on success.- Throws:
DataStoreException
- if an error occurred while reading more bytes.
-
createImageInputStream
Creates anImageInputStream
from theDataInput
if possible. This method simply castsDataInput
if such cast is allowed. SincecreateDataInput()
instantiatesChannelImageInputStream
, this cast is usually possible.This method is one of the
OPENERS
methods and should be invoked at most once perStorageConnector
instance.- Throws:
DataStoreException
-
createInputStream
Creates an input stream fromReadableByteChannel
if possible, or fromImageInputStream
otherwise.This method is one of the
OPENERS
methods and should be invoked at most once perStorageConnector
instance.- Throws:
IOException
DataStoreException
- See Also:
-
createReader
Creates a character reader if possible.This method is one of the
OPENERS
methods and should be invoked at most once perStorageConnector
instance.- Throws:
IOException
DataStoreException
-
createConnection
Creates a database connection if possible.This method is one of the
OPENERS
methods and should be invoked at most once perStorageConnector
instance.- Throws:
SQLException
-
createString
Returns the storage as a path if possible, ornull
otherwise.This method is one of the
OPENERS
methods and should be invoked at most once perStorageConnector
instance. -
addView
Adds the given view in the cache, without dependencies.- Type Parameters:
S
- the compile-time type of thetype
argument.- Parameters:
type
- the view type.view
- the view, ornull
if none.
-
createChannelDataOutput
Creates a view for the storage as aChannelDataOutput
if possible. This code is a partial copy ofcreateDataInput()
adapted for output.- Throws:
IOException
- if an error occurred while opening a channel for the output.DataStoreException
- See Also:
-
createDataOutput
Creates a view for the output as aDataOutput
if possible. This code is a copy ofcreateDataInput()
adapted for output.- Throws:
IOException
- if an error occurred while opening a stream for the output.DataStoreException
- See Also:
-
createOutputStream
Creates an output stream fromWritableByteChannel
if possible, or fromImageOutputStream
otherwise. This code is a partial copy ofcreateInputStream()
adapted for output.- Throws:
IOException
DataStoreException
- See Also:
-
addView
Adds the given view in the cache together with information about its dependency. For example,InputStreamReader
is a wrapper for aInputStream
: read operations from the latter may change position of the former, and closing the latter also close the former.- Type Parameters:
S
- the compile-time type of thetype
argument.- Parameters:
type
- the view type.view
- the view, ornull
if none.source
- the type of input thatview
is wrapping, ornull
forstorage
.cascade
- bitwise combination ofCASCADE_ON_CLOSE
,CASCADE_ON_RESET
orCLEAR_ON_RESET
.
-
getView
Returns the view for the given type from the cache. This method does not reset the view.- Parameters:
type
- the view type, ornull
for thestorage
container.- Returns:
- information associated to the given type. May be
null
if the view has never been requested before.StorageConnector.Coupled.view
may benull
if the view has been requested and we determined that none can be created.
-
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 invokinggetStorageAs(Class)
followed bycloseAllExcept(Object)
except that the latter method is always invoked (in a way similar to "try with resource") and that this method never returnsnull
.- Type Parameters:
S
- the compile-time type of thetype
argument (the source or storage type).- Parameters:
type
- the desired type as one of the types documented ingetStorageAs(Class)
(example:ByteBuffer
,DataInput
,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:
IllegalArgumentException
- if the giventype
argument is not one of the supported types.IllegalStateException
- if thisStorageConnector
has been closed.DataStoreException
- if an error occurred while opening a stream or database connection.- Since:
- 1.2
- See Also:
-
closeAllExcept
Closes all streams and connections created by thisStorageConnector
except the given view. This method closes all objects created by thegetStorageAs(Class)
method except the givenview
. Ifview
isnull
, 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 suitableDataStore
has been found - in which case theview
argument is null.This
StorageConnector
instance shall not be used anymore after invocation of this method.- Parameters:
view
- the view to leave open, ornull
if none.- Throws:
DataStoreException
- if an error occurred while closing the stream or database connection.- See Also:
-
unwrap
Returns the cause of given exception if it exists, or the exception itself otherwise. This method is invoked in thecatch
block of atry
block invokingImageIO.createImageInputStream(Object)
orImageIO.createImageOutputStream(Object)
.Rational
As of Java 18, above-cited methods systematically catch allIOException
s and wrap them in anIIOException
with "Cannot create cache file!" error message. This is conform to Image I/O specification but misleading if the stream provider throws anIOException
for another reason. Even when the failure is really caused by a problem with cache file, we want to propagate the original exception to user because its message may tell that there is no space left on device or no write permission.- See Also:
-
toString
Returns a string representation of thisStorageConnector
for debugging purpose. This string representation is for diagnostic and may change in any future version.
-