JSR107 API and SPI 1.1.1 · javax.cache.integration.CacheWriter

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.

Method Summary

Modifier and Type	Method and Description
public void	delete(Object the key that is used for the delete operation key) Delete the cache entry from the external resource.
public void	deleteAll(Collection<?> 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) keys) Remove data and keys from the external resource for the given collection of keys, if present.
public void	write(Cache.Entry<? extends K, ? extends V> the entry to be written entry) Write the specified value under the specified key to the external resource.
public void	writeAll(Collection<Cache.Entry<? extends K, ? extends V>> 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) entries) Write the specified entries to the external resource.

Method Detail

delete	back to summary
public 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:Object the key that is used for the delete operation Exceptions CacheWriterException: if delete fails. If thrown the cache delete will not occur.

delete

back to summary

public 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:Object: the key that is used for the delete operation

Exceptions

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

deleteAll back to summary

deleteAll	back to summary
public 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:Collection<?> 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) Exceptions CacheWriterException: if one or more deletes fail. If thrown cache deletes will occur for entries that succeeded.

public 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:Collection<?>: 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)

Exceptions

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

write	back to summary
public 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:Cache.Entry<? extends K, ? extends V> the entry to be written Exceptions CacheWriterException: if the write fails. If thrown the cache mutation will not occur.

write

back to summary

public 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:Cache.Entry<? extends K, ? extends V>: the entry to be written

Exceptions

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

writeAll back to summary

writeAll	back to summary
public 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:Collection<Cache.Entry<? extends K, ? extends V>> 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) Exceptions CacheWriterException: if one or more of the writes fail. If thrown cache mutations will occur for entries that succeeded.

public 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.

Parameters

entries:Collection<Cache.Entry<? extends K, ? extends V>>: 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)

Exceptions

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

public Interface CacheWriter<K, V>

Method Summary

Method Detail