javax.cache.processor

Interface EntryProcessor<K,V,T>

Type Parameters:

K - the type of keys maintained by this cache

V - the type of cached values

T - the type of the return value

public interface EntryProcessor<K,V,T>

An invocable function that allows applications to perform compound operations on a Cache.Entry atomically, according to the defined consistency of a Cache.

Any Cache.Entry mutations will not take effect until after the process(MutableEntry, Object...) method has completed execution.

If an exception is thrown by an EntryProcessor, a Caching Implementation must wrap any Exception thrown wrapped in an EntryProcessorException. If this occurs no mutations will be made to the Cache.Entry.

Implementations may execute EntryProcessors in situ, thus avoiding locking, round-trips and expensive network transfers.

Effect of MutableEntry operations

Cache.Entry access, via a call to Cache.Entry.getValue(), will behave as if Cache.get(Object) was called for the key. This includes updating necessary statistics, consulting the configured ExpiryPolicy and loading from a configured CacheLoader.

Cache.Entry mutation, via a call to MutableEntry.setValue(Object), will behave as if Cache.put(Object, Object) was called for the key. This includes updating necessary statistics, consulting the configured ExpiryPolicy, notifying CacheEntryListeners and writing to a configured CacheWriter.

Cache.Entry removal, via a call to MutableEntry.remove(), will behave as if Cache.remove(Object) was called for the key. This includes updating necessary statistics, notifying CacheEntryListeners and causing a delete on a configured CacheWriter.

As implementations may choose to execute EntryProcessors remotely, EntryProcessors, together with specified parameters and return values, may be required to implement Serializable.

Effect of multiple MutableEntry operations performed by one EntryProcessor

Only the net effect of multiple operations has visibility outside of the Entry Processor. The entry is locked by the entry processor for the entire scope of the entry processor, so intermediate effects are not visible.

Example 1

In this example, an EntryProcessor calls:

1. MutableEntry.getValue()
2. MutableEntry.setValue(Object)
3. MutableEntry.getValue()
4. MutableEntry.setValue(Object)

This will have the following Cache effects:
Final value of the cache: last setValue
Statistics: one get and one put as the second get and the first put are internal to the EntryProcessor.
Listeners: second put will cause either a put or an update depending on whether there was an initial value for the entry.
CacheLoader: Invoked by the first get only if the entry is not present, a loader was registered and read through is enabled.
CacheWriter: Invoked by the second put only as the first put was internal to the Entry Processor.
ExpiryPolicy: The first get and the second put only are visible to the ExpiryPolicy.

Example 2

In this example, an EntryProcessor calls:

1. MutableEntry.getValue()
2. MutableEntry.remove()}
3. MutableEntry.getValue()
4. MutableEntry.setValue(Object)

This will have the following Cache effects:
Final value of the cache: last setValue
Statistics: one get and one put as the second get and the first put are internal to the EntryProcessor.
Listeners: second put will cause either a put or an update depending on whether there was an initial value for the entry.
CacheLoader: Invoked by the first get only if the entry is not present, a loader was registered and read through is enabled.
CacheWriter: Invoked by the second put only as the first put was internal to the Entry Processor.
ExpiryPolicy: The first get and the second put only are visible to the ExpiryPolicy.

Example 3

In this example, an EntryProcessor calls:

1. MutableEntry.getValue()
2. MutableEntry.setValue(Object)}
3. MutableEntry.getValue()
4. MutableEntry.setValue(Object)
5. MutableEntry.remove()

This will have the following Cache effects:
Final value of the cache: the entry is removed if it was present
Statistics: one get and one remove as the second get and the two puts are internal to the EntryProcessor.
Listeners: remove if there was initial value in the cache, otherwise no listener invoked.
CacheLoader: Invoked by the first get only if the entry is not present, a loader was registered and read through is enabled.
CacheWriter: Invoked by the remove only as the two puts are internal to the Entry Processor, provided that the first #getValue was non-null.
ExpiryPolicy: The first get only is visible to the ExpiryPolicy. There is no remove event in ExpiryPolicy.

Since:

1.0

Author:

Greg Luck

Method Summary

Modifier and Type	Method and Description
T	process(MutableEntry<K,V> entry, Object... arguments) Process an entry.

Method Detail

process

T process(MutableEntry<K,V> entry,
          Object... arguments)
   throws EntryProcessorException

Process an entry.

Parameters:

entry - the entry

arguments - a number of arguments to the process.

Returns:

the user-defined result of the processing, if any.

Throws:

EntryProcessorException - if there is a failure in entry processing.