Interface VariantCache

All Superinterfaces:

Cache

All Known Implementing Classes:

HeapCache

public non-sealed interface VariantCache
extends Cache

Caches variant images.

Field Summary

Fields inherited from interface is.galia.cache.Cache

LOGGER

Method Summary

Modifier and Type	Method	Description
void	evict(OperationList opList)	Deletes the cached image corresponding to the given operation list.
default boolean	exists(OperationList opList)	N.B.: This method is not safe to use in production, as it is not concurrency-safe, i.e. the state of the cache may change between the time this method returns and the time newVariantImageInputStream(is.galia.operation.OperationList) is invoked.
default InputStream	newVariantImageInputStream(OperationList opList)
InputStream	newVariantImageInputStream(OperationList opList, StatResult statResult)	Returns an input stream corresponding to the given operation list, or null if a valid image corresponding to the given operation list does not exist in the cache.
CompletableOutputStream	newVariantImageOutputStream(OperationList opList)	Returns an output stream for writing an image to the cache.

Methods inherited from interface is.galia.cache.Cache

addObserver, cleanUp, evict, evictInvalid, initialize, onCacheWorker, purge, shutdown

Method Details

evict

void evict(OperationList opList)
    throws IOException

Deletes the cached image corresponding to the given operation list.

If no such image exists, nothing is done.

Parameters:

opList -

Throws:

IOException - upon fatal error. Implementations should do the best they can to complete the operation and swallow and log non-fatal errors.

exists

default boolean exists(OperationList opList)
                throws IOException

N.B.: This method is not safe to use in production, as it is not concurrency-safe, i.e. the state of the cache may change between the time this method returns and the time newVariantImageInputStream(is.galia.operation.OperationList) is invoked. This default implementation is a convenience for testing that simply returns true if it can open a stream. Overriding is probably pointless.

Parameters:

opList - Operation list describing the variant image.

Returns:

Whether a valid variant described by the given operation list exists in the cache.

Throws:

IOException

newVariantImageInputStream

default InputStream newVariantImageInputStream(OperationList opList)
                                        throws IOException

Throws:

IOException

See Also:

• newVariantImageInputStream(OperationList, StatResult)

newVariantImageInputStream

InputStream newVariantImageInputStream(OperationList opList,
 StatResult statResult)
                                throws IOException

Returns an input stream corresponding to the given operation list, or null if a valid image corresponding to the given operation list does not exist in the cache.

If an invalid image corresponding to the given operation list exists in the cache, implementations should delete it (ideally asynchronously) and return null.

Parameters:

opList - Operation list for which to retrieve an input stream for reading from the cache.

statResult - May be populated with metadata about the cached image if one is available and if the implementation supports it.

Returns:

Stream corresponding to the given operation list, or null if a valid image does not exist in the cache.

Throws:

IOException

newVariantImageOutputStream

CompletableOutputStream newVariantImageOutputStream(OperationList opList)
                                             throws IOException

Returns an output stream for writing an image to the cache.

If an image corresponding to the given identifier already exists, the stream should overwrite it. Implementations may choose to allow multiple streams to write data to the same target concurrently (assuming this is safe), or else allow only one stream to write to a particular target at a time, with other clients writing to no-op streams.

Important notes about the OutputStream.close() implementation:

• It must check the return value of CompletableOutputStream.isComplete() before committing any data to the cache. If it returns false, any written data should be discarded.
• It must notify all observers when it completes.

Parameters:

opList - Operation list describing the target image in the cache.

Returns:

Output stream to which an image corresponding to the given operation list can be written.

Throws:

IOException - upon an I/O error. Any partially written data is automatically cleaned up.

See Also:

• CacheObserver.onImageWritten(OperationList)