MutableCacheEntry (cache2k API 1.3.2.Alpha API)

All Superinterfaces:

CacheEntry<K,V>
```
public interface MutableCacheEntry<K,V>
extends CacheEntry<K,V>
```
A mutable entry is used inside the EntryProcessor to perform updates and retrieve information from a cache entry.
A mutation is only done if a method for mutation is called, e.g. setValue or remove. If multiple mutate methods are called in sequence only the last method will have an effect.
One instance is only usable by a single thread and for one call of EntryProcessor.process(MutableCacheEntry).

Author:

Jens Wilke

See Also:

EntryProcessor

Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
Modifier and Type	Method and Description
`boolean`	`exists()` True if a mapping exists in the cache, never invokes the loader / cache source.
`long`	`getCurrentTime()` Deprecated. Replaced with `getStartTime()`
`Throwable`	`getException()` The exception happened when the value was loaded and the exception could not be suppressed.
`V`	`getOldValue()` The current value in the cache.
`long`	`getRefreshedTime()` Timestamp of the last refresh of the cached value.
`long`	`getStartTime()` Current time as provided by the internal time source (usually `System.currentTimeMillis()`.
`V`	`getValue()` Returns the value to which the cache associated the key, or `null` if the cache contains no mapping for this key.
`MutableCacheEntry<K,V>`	`remove()` Removes an entry from the cache.
`MutableCacheEntry<K,V>`	`setException(Throwable ex)` Insert or update the entry and sets an exception.
`MutableCacheEntry<K,V>`	`setExpiryTime(long t)` Set a new expiry time for the entry.
`MutableCacheEntry<K,V>`	`setRefreshedTime(long t)` If `setValue(Object)` is used, this sets an alternative refreshed time for expiry calculations.
`MutableCacheEntry<K,V>`	`setValue(V v)` Insert or updates the cache value assigned to this key.
`boolean`	`wasExisting()` True if a mapping exists in the cache, never invokes the loader / cache source.

Methods inherited from interface org.cache2k.CacheEntry
getKey, getLastModification

- Method Detail
  - getValue
```
V getValue()
```
    Returns the value to which the cache associated the key, or null if the cache contains no mapping for this key. null is also returned if this entry contains an exception.
    If the cache does permit null values, then a return value of null does not necessarily indicate that the cache contained no mapping for the key. It is also possible that the cache explicitly associated the key to the value null. Use exists() to check whether an entry is existing instead of a null check.
    If read through operation is enabled and the entry is not yet existing in the cache, the call to this method triggers a call to the cache loader.
    In contrast to the main cache interface there is no no peekValue method, since the same effect can be achieved by the combination of exists() and getValue().
    
    Specified by:
    
    getValue in interface CacheEntry<K,V>
    
    Throws:
    
    RestartException - If the information is not yet available and the cache needs to do an asynchronous operation to supply it. After completion, the entry processor will be executed again.
    
    CacheLoaderException - if loading produced an exception
    
    See Also:
    
    CacheLoader
  - getException
```
Throwable getException()
```
    The exception happened when the value was loaded and the exception could not be suppressed. null if no exception happened or it was suppressed. If null then getValue() returns a value and does not throw an exception.
    If a loader is present and the entry is not yet loaded or expired, a load is triggered.
    
    Specified by:
    
    getException in interface CacheEntry<K,V>
  - exists
```
boolean exists()
```
    True if a mapping exists in the cache, never invokes the loader / cache source.
    After this method returns true, a call to getValue will always return the cached value and never invoke the loader. The potential expiry of the value is only checked once and the return values of this method and getValue will be consistent.
    
    Throws:
    
    RestartException - If the information is not yet available and the cache needs to do an asynchronous operation to supply it. After completion, the entry processor will be executed again.
  - getOldValue
```
V getOldValue()
```
    The current value in the cache. Identical to getValue(), but not modified after a mutation method is called. Intended for fluent operation.
    If read through operation is enabled and the entry is not yet existing in the cache, the call to this method triggers a call to the cache loader.
    
    Throws:
    
    RestartException - If the information is not yet available and the cache needs to do an asynchronous operation to supply it. After completion, the entry processor will be executed again.
  - wasExisting
```
boolean wasExisting()
```
    True if a mapping exists in the cache, never invokes the loader / cache source. Identical to exists(), but not modified after a mutation method is called. Intended for fluent operation.
    
    Throws:
    
    RestartException - If the information is not yet available and the cache needs to do an asynchronous operation to supply it. After completion, the entry processor will be executed again.
  - getCurrentTime
```
long getCurrentTime()
```
    Deprecated. Replaced with getStartTime()
    
    Current time as provided by the internal time source (usually System.currentTimeMillis(). The time is retrieved once when the entry processor is invoked and will not change afterwards. If a load is triggered this value will be identical to AdvancedCacheLoader.load(Object, long, CacheEntry) and ExceptionInformation.getLoadTime()
  - getStartTime
```
long getStartTime()
```
    Current time as provided by the internal time source (usually System.currentTimeMillis(). The time is retrieved once when the entry processor is invoked and will not change afterwards. If a load is triggered this value will be identical to the startTime AdvancedCacheLoader.load(K, long, org.cache2k.CacheEntry<K, V>), ExceptionInformation.getLoadTime() or AsyncCacheLoader.Context#getLoadStartTime()
  - setValue
```
MutableCacheEntry<K,V> setValue(V v)
```
    Insert or updates the cache value assigned to this key. After calling this method exists will return true and getValue will return the set value.
    If a writer is registered, the CacheWriter.write(Object, Object) is called.
  - remove
```
MutableCacheEntry<K,V> remove()
```
    Removes an entry from the cache.
    In case a writer is registered, CacheWriter.delete(K) is called. If a remove is performed on a not existing cache entry the writer method will also be called.
    
    See Also:
    
    JSR107 TCK issue 84
  - setException
```
MutableCacheEntry<K,V> setException(Throwable ex)
```
    Insert or update the entry and sets an exception. The exception will be propagated as CacheLoaderException.
    Identical to setValue an expiry of the exception will be determined according to the resilience settings. Hint: If no expiry is configured the default behavior will be that the set exception expires immediately, so the effect will be similar to remove in this case.
  - setExpiryTime
```
MutableCacheEntry<K,V> setExpiryTime(long t)
```
    Set a new expiry time for the entry. If combined with setValue(V) the entry will be updated or inserted with this expiry time, otherwise just the expiry time will be updated.
    Special time values are defined and described at ExpiryTimeValues
    
    Parameters:
    
    t - Time in millis since epoch.
  - getRefreshedTime
```
long getRefreshedTime()
```
    Timestamp of the last refresh of the cached value. This is the start time (before the loader was called) of a successful load operation, or the time the value was modified directly via Cache.put(K, V) or other sorts of mutation. Does not trigger a load.
    Rationale: We call it "refreshed" time since we don't know whether the value actually changed. If a load produces the same value as before the entry is refreshed but effectively not updated or modified. The past tense means its the time of the last refresh and is not the upcoming refresh.
  - setRefreshedTime
```
MutableCacheEntry<K,V> setRefreshedTime(long t)
```
    If setValue(Object) is used, this sets an alternative refreshed time for expiry calculations. The entry refreshed time is not updated, if the entry is not mutated.
    If refresh ahead is enabled via Cache2kBuilder.refreshAhead(boolean), the next refresh time is controlled by the expiry time.

Interface MutableCacheEntry<K,V>

Method Summary

Methods inherited from interface org.cache2k.CacheEntry

Method Detail

getValue

getException

exists

getOldValue

wasExisting

getCurrentTime

getStartTime

setValue

remove

setException

setExpiryTime

getRefreshedTime

setRefreshedTime