net.sf.ehcache.writer
Interface CacheWriter

All Known Implementing Classes:

AbstractCacheWriter

public interface CacheWriter

A CacheWriter is an interface used for write-through and write-behind caching to a underlying resource.

If configured for a cache, CacheWriter's methods will be called on a cache operation. A cache put will cause a CacheWriter write and a cache remove will cause a writer delete.

Implementers should create an implementation which handles storing and deleting to an underlying resource.

Write-Through

In write-through mode, the cache operation will occur and the writer operation will occur before CacheEventListeners are notified. If the write operation fails an exception will be thrown. This can result in a cache which is inconsistent with the underlying resource. To avoid this, the cache and the underlying resource should be configured to participate in a transaction. In the event of a failure a rollback can return all components to a consistent state.

Write-Behind

In write-behind mode, writes are written to a write-behind queue. They are written by a separate execution thread in a configurable way. When used with Terracotta Server Array, the queue is highly available. In addition any node in the cluster may perform the write-behind operations.

It's important to note that the operations that are handled by the CacheWriter don't have any guaranteed ordering in write-behind mode. The processing ordering can be different than the scheduling ordering, so your application needs to be written with this in mind. More information in the CacheWriter chapter of the documentation.

Creation and Configuration

CacheWriters can be created using the CacheWriterFactory or explicitly by instantiating them through Java code, giving you access to local resources.

The manner upon which a CacheWriter is actually called is determined by the CacheWriterConfiguration that is set up for cache that is using the CacheWriter.

See the CacheWriter chapter in the documentation for more information on how to use writers.

Version:

$Id: CacheWriter.java 5594 2012-05-07 16:04:31Z cdennis $

Author:

Greg Luck, Geert Bevin

Method Summary

CacheWriter	clone(Ehcache cache) Creates a clone of this writer.
void	delete(CacheEntry entry) Delete the cache entry from the store
void	deleteAll(Collection<CacheEntry> entries) Remove data and keys from the underlying store for the given collection of keys, if present.
void	dispose() Providers may be doing all sorts of exotic things and need to be able to clean up on dispose.
void	init() Notifies writer to initialise themselves.
void	throwAway(Element element, SingleOperationType operationType, RuntimeException e) This method will be called, whenever an Element couldn't be handled by the writer and all the retryAttempts have been tried.
void	write(Element element) Write the specified value under the specified key to the underlying store.
void	writeAll(Collection<Element> elements) Write the specified Elements to the underlying store.

Method Detail

clone

CacheWriter clone(Ehcache cache)
                  throws CloneNotSupportedException

Creates a clone of this writer. This method will only be called by ehcache before a cache is initialized.

Implementations should throw CloneNotSupportedException if they do not support clone but that will stop them from being used with defaultCache.

Returns:

a clone

Throws:

CloneNotSupportedException - if the extension could not be cloned.

init

void init()

Notifies writer to initialise themselves.

This method is called during the Cache's initialise method after it has changed it's status to alive. Cache operations are legal in this method. If you register a cache writer manually after a cache has been initialised already, this method will be called on the cache writer as soon as it has been registered.

Note that if you reuse cache writer instances or create a factory that returns the same cache writer instance as a singleton, your init method should be able to handle that situation. Unless you perform this multiple usage of a cache writer yourself, Ehcache will not do this though. So in the majority of the use cases, you don't need to do anything special.

Throws:

CacheException

dispose

void dispose()
             throws CacheException

Providers may be doing all sorts of exotic things and need to be able to clean up on dispose.

Cache operations are illegal when this method is called. The cache itself is partly disposed when this method is called.

Throws:

CacheException

write

void write(Element element)
           throws CacheException

Write the specified value under the specified key to the underlying store. This method is intended to support both key/value creation and value update for a specific key.

Parameters:

element - the element to be written

Throws:

CacheException

writeAll

void writeAll(Collection<Element> elements)
              throws CacheException

Write the specified Elements to the underlying store. This method is intended to support both insert and update. If this operation fails (by throwing an exception) after a partial success, the convention is that entries which have been written successfully are to be removed from the specified mapEntries, indicating that the write operation for the entries left in the map has failed or has not been attempted.

Parameters:

elements - the Elements to be written

Throws:

CacheException

delete

void delete(CacheEntry entry)
            throws CacheException

Delete the cache entry from the store

Parameters:

entry - the cache entry that is used for the delete operation

Throws:

CacheException

deleteAll

void deleteAll(Collection<CacheEntry> entries)
               throws CacheException

Remove data and keys from the underlying store for the given collection of keys, if present. If this operation fails (by throwing an exception) after a partial success, the convention is that keys which have been erased successfully are to be removed from the specified keys, indicating that the erase operation for the keys left in the collection has failed or has not been attempted.

Parameters:

entries - the entries that have been removed from the cache

Throws:

CacheException

throwAway

void throwAway(Element element,
               SingleOperationType operationType,
               RuntimeException e)

This method will be called, whenever an Element couldn't be handled by the writer and all the retryAttempts have been tried.

When batching is enabled all the elements in the failing batch will be passed to this methods

Try to not throw RuntimeExceptions from this method. Should an Exception occur, it will be logged, but the element will be lost anyways.

Parameters:

element - the Element that triggered the failure, or one of the elements part of the batch that failed

operationType - the operation we tried to execute

e - the RuntimeException thrown by the Writer when the last retry attempt was being executed