Interface MutableCacheEntry<K,​V>

  • All Superinterfaces:
    CacheEntry<K,​V>, DataAware<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).

    Planed extensions: getExpiryTime, peekValue/peekException....

    Author:
    Jens Wilke
    See Also:
    EntryProcessor
    • Method Detail

      • getValue

        @Nullable
        V getValue()

        Returns the value to which the cache associated the key, or null if the cache contains no mapping for this key. If no mapping exists and a loader is specified, the cache loader is called.

        In contrast to the main cache interface there is 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>
        Returns:
        The cached value, the loaded value or null otherwise
        Throws:
        CacheLoaderException - if loading produced an exception
        RestartException - If the information is not yet available and the cache needs to do an operation to supply it. After completion, the entry processor will be executed again.
        See Also:
        CacheLoader
      • getValueOrNull

        @Nullable
        default V getValueOrNull()
      • getException

        @Nullable
        @Nullable 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 CacheEntry.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>
        Throws:
        RestartException - If the information is not yet available and the cache needs to do an operation to supply it. After completion, the entry processor will be executed again.
      • getExceptionInfo

        @Nullable
        @Nullable LoadExceptionInfo<K,​V> getExceptionInfo()
        Detailed information of latest exception from the loader or null if no exception happened or it was suppressed. If null then CacheEntry.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:
        getExceptionInfo in interface CacheEntry<K,​V>
        Throws:
        RestartException - If the information is not yet available and the cache needs to do an operation to supply it. After completion, the entry processor will be executed again.
      • exists

        boolean exists()
        True if a mapping exists in the cache, never invokes the loader.

        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 operation to supply it. After completion, the entry processor will be executed again.
      • lock

        MutableCacheEntry<K,​V> lock()
        Locks the entry for mutation. Code following this method will be executed once and atomically w.r.t. other operations changing an entry with the same key.
        Throws:
        RestartException - If the information is not yet available and the cache needs to do an operation to supply it. After completion, the entry processor will be executed again.
        UnsupportedOperationException - In case locking is not supported by this cache configuration.
      • setValue

        MutableCacheEntry<K,​V> setValue​(V v)
        Insert or updates the cache value assigned to this key.

        After calling this method the values of exists and getValue will not change. This behavior is different from JSR107/JCache. This definition reduces complexity and is more useful than the JSR107 behavior.

        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.

        After calling this method the values of exists and getValue will not change. This behavior is different from JSR107/JCache. This definition reduces complexity and is more useful than the JSR107 behavior.

        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.

        The effect depends on expiry and resilience setting. An exception will be kept in the cache only if there is an expiry configured or the resilience policy is allowing that.

        Throws:
        RestartException - If the information is not yet available and the cache needs to do an operation to supply it. After completion, the entry processor will be executed again.
        See Also:
        ResiliencePolicy
      • 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.
        Throws:
        RestartException - If the information is not yet available and the cache needs to do an operation to supply it. After completion, the entry processor will be executed again.
      • getExpiryTime

        long getExpiryTime()
        Returns the effective expiry time of the current cache entry in case exists() is false it returnsExpiryTimeValues.NOW. If the entry was loaded, it returns the calculated expiry time from ExpiryPolicy or ResiliencePolicy. A negative value means sharp expiry as described in the expiry policy.
        See Also:
        ExpiryPolicy
      • getModificationTime

        long getModificationTime()
        Timestamp of the last update 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.
        Throws:
        RestartException - If the information is not yet available and the cache needs to do an operation to supply it. After completion, the entry processor will be executed again.
      • setModificationTime

        MutableCacheEntry<K,​V> setModificationTime​(long t)
        If setValue(Object) is used, this sets an alternative 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.

        Throws:
        RestartException - If the information is not yet available and the cache needs to do an operation to supply it. After completion, the entry processor will be executed again.