An invocable function that allows applications to perform compound operations
on a
javax.cache.Cache.Entry atomically, according the defined
consistency of a
Cache.
Any
javax.cache.Cache.Entry mutations will not take effect until after
the
EntryProcessor#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
javax.cache.Cache.Entry.
Implementations may execute
EntryProcessors in situ, thus avoiding
locking, round-trips and expensive network transfers.
Effect of
MutableEntry operations
javax.cache.Cache.Entry access, via a call to
javax.cache.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
javax.cache.integration.CacheLoader.
javax.cache.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.
javax.cache.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
java.io.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:
-
MutableEntry#getValue()
-
MutableEntry#setValue(Object)
-
MutableEntry#getValue()
-
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 a loader was registered.
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:
-
MutableEntry#getValue()
-
MutableEntry#remove()}
-
MutableEntry#getValue()
-
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 a loader was registered.
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:
-
MutableEntry#getValue()
-
MutableEntry#setValue(Object)}
-
MutableEntry#getValue()
-
MutableEntry#setValue(Object)
-
MutableEntry#remove()
This will have the following
Cache effects:
Final value of the cache: last setValue
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 a loader was
registered.
CacheWriter: Invoked by the remove only as the two puts are internal to
the Entry Processor.
ExpiryPolicy: The first get only is visible to the ExpiryPolicy. There is no
remove event in ExpiryPolicy.