Package javax.cache.integration

Interface CacheWriter<K,V>

Type Parameters:

K - the type of keys maintained by this map

V - the type of mapped values

public interface CacheWriter<K,V>

A CacheWriter is used for write-through to an external resource.

Under Default Consistency, the non-batch writer methods are atomic with respect to the corresponding cache operation.

For batch methods under Default Consistency, the entire cache operation is not required to be atomic in Cache and is therefore not required to be atomic in the writer. As individual writer operations can fail, cache operations are not required to occur until after the writer batch method has returned or, in the case of partial success, thrown an exception. In the case of partial success, the collection of entries return must only contain those entries that failed.

The entry passed into write(Cache.Entry) is independent of the cache mapping for that key, meaning that if the value changes in the cache or is removed it does not change the entry.

Since:

1.0

Author:

Greg Luck, Brian Oliver

See Also:

CacheLoader

Method Summary

Modifier and Type	Method	Description
void	delete(Object key)	Delete the cache entry from the external resource.
void	deleteAll(Collection<?> keys)	Remove data and keys from the external resource for the given collection of keys, if present.
void	write(Cache.Entry<? extends K,? extends V> entry)	Write the specified value under the specified key to the external resource.
void	writeAll(Collection<Cache.Entry<? extends K,? extends V>> entries)	Write the specified entries to the external resource.

Method Detail

write

void write(Cache.Entry<? extends K,? extends V> entry)
    throws CacheWriterException

Write the specified value under the specified key to the external resource.

This method is intended to support both key/value creation and value update for a specific key.

Parameters:

entry - the entry to be written

Throws:

CacheWriterException - if the write fails. If thrown the cache mutation will not occur.

writeAll

void writeAll(Collection<Cache.Entry<? extends K,? extends V>> entries)
       throws CacheWriterException

Write the specified entries to the external resource. This method is intended to support both insert and update.

The order that individual writes occur is undefined, as Cache.putAll(java.util.Map) also has undefined ordering.

If this operation fails (by throwing an exception) after a partial success, the writer must remove any successfully written entries from the entries collection so that the caching implementation knows what succeeded and can mutate the cache.

Parameters:

entries - a mutable collection to write. Upon invocation, it contains the entries to write for write-through. Upon return the collection must only contain entries that were not successfully written. (see partial success above)

Throws:

CacheWriterException - if one or more of the writes fail. If thrown cache mutations will occur for entries that succeeded.

delete

void delete(Object key)
     throws CacheWriterException

Delete the cache entry from the external resource.

Expiry of a cache entry is not a delete hence will not cause this method to be invoked.

This method is invoked even if no mapping for the key exists.

Parameters:

key - the key that is used for the delete operation

Throws:

CacheWriterException - if delete fails. If thrown the cache delete will not occur.

deleteAll

void deleteAll(Collection<?> keys)
        throws CacheWriterException

Remove data and keys from the external resource for the given collection of keys, if present.

The order that individual deletes occur is undefined, as Cache.removeAll(java.util.Set) also has undefined ordering.

If this operation fails (by throwing an exception) after a partial success, the writer must remove any successfully written entries from the entries collection so that the caching implementation knows what succeeded and can mutate the cache.

Expiry of a cache entry is not a delete hence will not cause this method to be invoked.

This method may include keys even if there is no mapping for that key, in which case the data represented by that key should be removed from the underlying resource.

Parameters:

keys - a mutable collection of keys for entries to delete. Upon invocation, it contains the keys to delete for write-through. Upon return the collection must only contain the keys that were not successfully deleted. (see partial success above)

Throws:

CacheWriterException - if one or more deletes fail. If thrown cache deletes will occur for entries that succeeded.