Package org.apache.sis.storage

Class StorageConnector.Coupled

java.lang.Object

org.apache.sis.storage.StorageConnector.Coupled

Enclosing class:

StorageConnector

private static final class StorageConnector.Coupled
extends Object

Wraps an instance of @link InputStream}, DataInput, Reader, etc. together with additional information about other objects that are coupled with the wrapped object. For example if a Reader is a wrapper around the user supplied InputStream, then those two objects will be wrapped in Coupled instances together with information about how they are related One purpose of Coupled information is to keep trace of objects which will need to be closed by the StorageConnector.closeAllExcept(Object) method (for example an InputStreamReader wrapping an InputStream). Another purpose is to determine which views need to be synchronized if StorageConnector.storage is used independently. They are views that may advance storage position, but not at the same time than the view position (typically because the view reads some bytes in advance and stores them in a buffer). Such coupling may occur when the storage is an InputStream, an OutputStream or a Channel. The coupled view can be:

• Reader that are wrappers around InputStream.
• ChannelDataInput when the channel come from an InputStream.
• ChannelDataInput when the channel has been explicitly given to the constructor.

Field Summary

Fields

Modifier and Type	Field	Description
(package private) final byte	cascade	Bitwise combination of StorageConnector.CASCADE_ON_CLOSE, StorageConnector.CASCADE_ON_RESET or StorageConnector.CLEAR_ON_RESET.
(package private) boolean	isValid	true if the position of view is synchronized with the position of wrapperFor.
(package private) Object	view	The StorageConnector.storage viewed as another kind of object.
private StorageConnector.Coupled[]	wrappedBy	The other views that are consuming view, or null if none.
(package private) final StorageConnector.Coupled	wrapperFor	The object that view is wrapping.

Constructor Summary

Constructors

Constructor	Description
Coupled(Object storage)	Creates a wrapper for StorageConnector.storage.
Coupled(StorageConnector.Coupled wrapperFor, byte cascade)	Creates a wrapper for a view wrapping the given Coupled instance.

Method Summary

Modifier and Type	Method	Description
(package private) final void	append(TreeTable.Node appendTo, Map<Class<?>,StorageConnector.Coupled> views)	Formats the current Coupled and all its children as a tree in the given tree table node.
(package private) final boolean	cascadeOnClose()	true if after closing the view, we need to also close the wrapperFor.
(package private) final boolean	cascadeOnReset()	true if calls to reset() should cascade to wrapperFor.
(package private) final void	invalidateSources()	Declares as invalid all unsynchronized Coupled instances which are used, directly or indirectly, by this instance.
(package private) final void	invalidateUsages()	Declares as invalid all unsynchronized Coupled instances which are using, directly or indirectly, this instance.
(package private) final void	protect(Map<AutoCloseable,Boolean> toClose)	Identifies the other views to not close if we don't want to close the view wrapped by this Coupled.
(package private) final boolean	reset()	Resets the position of all sources of the view, then the view itself.
String	toString()	Returns a string representation for debugging purpose.

Methods inherited from class java.lang.Object

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

Field Details

view

Object view

The StorageConnector.storage viewed as another kind of object. Supported types are:

• ByteBuffer: A read-only view of the buffer over the first bytes of the stream.
• DataInput: The input as a data input stream. Unless the StorageConnector.storage is already an instance of DataInput, this entry will be given an instance of ChannelImageInputStream if possible rather than an arbitrary stream. In particular, we invoke the ImageIO.createImageInputStream(Object) factory method only in last resort because some SIS data stores will want to access the channel and buffer directly.
• ImageInputStream: Same as DataInput if it can be casted, or null otherwise.
• InputStream: If not explicitly provided, this is a wrapper around the above ImageInputStream.
• Reader: If not explicitly provided, this is a wrapper around the above InputStream.
• Connection: The storage object as a JDBC connection.

wrapperFor

final StorageConnector.Coupled wrapperFor

The object that view is wrapping. For example if view is an InputStreamReader, then wrapperFor.view is an InputStream. This field is null if view == StorageConnector.storage.

wrappedBy

private StorageConnector.Coupled[] wrappedBy

The other views that are consuming view, or null if none. For each element in this array, wrappedBy[i].wrapperFor == this.

cascade

final byte cascade

Bitwise combination of StorageConnector.CASCADE_ON_CLOSE, StorageConnector.CASCADE_ON_RESET or StorageConnector.CLEAR_ON_RESET.

isValid

boolean isValid

true if the position of view is synchronized with the position of wrapperFor.

Constructor Details

Coupled

Coupled(Object storage)

Creates a wrapper for StorageConnector.storage. This constructor is used when we need to create a Coupled instance for another view wrapping storage.

Coupled

Coupled(StorageConnector.Coupled wrapperFor,
 byte cascade)

Creates a wrapper for a view wrapping the given Coupled instance. Caller is responsible to set the view field after this constructor call.

Parameters:

wrapperFor - the object that view will wrap, or null if none.

cascade - bitwise combination of StorageConnector.CASCADE_ON_CLOSE, StorageConnector.CASCADE_ON_RESET or StorageConnector.CLEAR_ON_RESET.

Method Details

cascadeOnClose

final boolean cascadeOnClose()

true if after closing the view, we need to also close the wrapperFor. Should be true when the view is an ImageInputStream because Java I/O FileCacheImageInputStream.close() does not close the underlying stream. For most other kinds of view, should be false.

cascadeOnReset

final boolean cascadeOnReset()

true if calls to reset() should cascade to wrapperFor. This is false if any change in the position of view is immediately reflected in the position of wrapperFor, and vice-versa.

invalidateSources

final void invalidateSources()

Declares as invalid all unsynchronized Coupled instances which are used, directly or indirectly, by this instance. This method is invoked before StorageConnector.getStorageAs(Class) returns a view, in order to remember which views would need to be resynchronized if they are requested.

invalidateUsages

final void invalidateUsages()

Declares as invalid all unsynchronized Coupled instances which are using, directly or indirectly, this instance. This method is invoked before StorageConnector.getStorageAs(Class) returns a view, in order to remember which views would need to be resynchronized if they are requested.

protect

final void protect(Map<AutoCloseable,Boolean> toClose)

Identifies the other views to not close if we don't want to close the view wrapped by this Coupled. This method identifies only the views that use this view; it does not identify the views used by this view. This method is for StorageConnector.closeAllExcept(Object) internal usage.

Parameters:

toClose - the map where to write the list of views to not close.

reset

final boolean reset()
             throws IOException

Resets the position of all sources of the view, then the view itself.

Returns:

true if some kind of reset has been performed. Note that it does means that the view isValid is true.

Throws:

IOException

toString

public String toString()

Returns a string representation for debugging purpose.

Overrides:

toString in class Object

append

@Debug
final void append(TreeTable.Node appendTo,
 Map<Class<?>,StorageConnector.Coupled> views)

Formats the current Coupled and all its children as a tree in the given tree table node. This method is used for StorageConnector.toString() implementation only and may change in any future version.

Parameters:

appendTo - where to write name, value and children.

views - reference to the StorageConnector.views map. Will be read only.