de.schlichtherle.truezip.socket
Class IOCache

java.lang.Object
  de.schlichtherle.truezip.socket.IOCache

@ThreadSafe
@DefaultAnnotation(value=edu.umd.cs.findbugs.annotations.NonNull.class)
public final class IOCache
extends Object

Provides temporary caching services for input and output sockets with the following features:

• Upon the first read operation, the entry data will be read from the backing store and temporarily stored in the cache. Subsequent or concurrent read operations will be served from the cache without re-reading the entry data from the backing store again until the cache gets cleared.
• At the discretion of the IOCache.Strategy, entry data written to the cache may not be written to the backing store until the cache gets flushed.
• After a write operation, the entry data will be stored in the cache for subsequent read operations until the cache gets cleared.
• As a side effect, caching decouples the underlying storage from its clients, allowing it to create, read, update or delete the entry data while some clients are still busy on reading or writing the cached entry data.
• When a cache gets picked up by the finalizer thread of the JVM, it gets cleared (this class is not a persistence service).

Author:

Christian Schlichtherle

lock

private final IOCache.Lock lock

strategy

private final IOCache.Strategy strategy

pool

private final IOPool<?> pool

input

@Nullable
private volatile InputSocket<?> input

output

@Nullable
private volatile OutputSocket<?> output

inputBufferPool

@CheckForNull
private volatile IOCache.InputBufferPool inputBufferPool

outputBufferPool

@CheckForNull
private volatile IOCache.OutputBufferPool outputBufferPool

buffer

@CheckForNull
private volatile IOCache.Buffer buffer

IOCache

private IOCache(IOCache.Strategy strategy,
                IOPool<?> pool)

Constructs a new cache which applies the given caching strategy and uses the given pool to allocate and release temporary I/O entries.

Note that you need to call configure(InputSocket) before you can do any input. Likewise, you need to call configure(OutputSocket) before you can do any output.

Parameters:

strategy - the caching strategy.

pool - the pool for allocating and releasing temporary I/O entries.

configure

public IOCache configure(InputSocket<?> input)

Configures the input socket for reading the entry data from the backing store. This method needs to be called before any input can be done - otherwise a NullPointerException will be thrown on the first read attempt. Note that calling this method does not clear this cache.

Parameters:

input - an input socket for reading the entry data from the backing store.

Returns:

this

configure

public IOCache configure(OutputSocket<?> output)

Configures the output socket for writing the entry data to the backing store. This method needs to be called before any output can be done - otherwise a NullPointerException will be thrown on the first write attempt. Note that calling this method does not flush this cache.

Parameters:

output - an output socket for writing the entry data to the backing store.

Returns:

this

flush

public IOCache flush()
              throws IOException

Writes the cached entry data to the backing store unless already done. Whether or not this method needs to be called depends on the caching strategy. E.g. the caching strategy IOCache.Strategy.WRITE_THROUGH writes any changed entry data immediately, so calling this method has no effect.

Returns:

this

Throws:

IOException

clear

public IOCache clear()
              throws IOException

Discards the entry data in this buffer.

Returns:

this

Throws:

IOException

getEntry

@Nullable
public Entry getEntry()

getInputSocket

public InputSocket<?> getInputSocket()

Returns an input socket for reading the cached entry data.

Returns:

An input socket for reading the cached entry data.

getOutputSocket

public OutputSocket<?> getOutputSocket()

Returns an output socket for writing the cached entry data.

Returns:

An output socket for writing the cached entry data.

getInputBufferPool

private IOCache.InputBufferPool getInputBufferPool()

getOutputBufferPool

private IOCache.OutputBufferPool getOutputBufferPool()

getBuffer

@CheckForNull
private IOCache.Buffer getBuffer()

setBuffer

private void setBuffer(@CheckForNull
                       IOCache.Buffer newBuffer)
                throws IOException

Throws:

IOException

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable