Interface CacheWriter<K,​V>

  • Type Parameters:
    K - the type of keys maintained by this map
    V - the type of mapped values

    public interface CacheWriter<K,​V>
    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.

    Since:
    1.0
    Author:
    Greg Luck, Brian Oliver
    See Also:
    CacheLoader
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void delete​(Object key)
      Delete the cache entry from the external resource.
      void deleteAll​(Collection<?> keys)
      Remove data and keys from the external resource for the given collection of keys, if present.
      void write​(Cache.Entry<? extends K,​? extends V> entry)
      Write the specified value under the specified key to the external resource.
      void writeAll​(Collection<Cache.Entry<? extends K,​? extends V>> entries)
      Write the specified entries to the external resource.
    • Method Detail

      • write

        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 - the entry to be written
        Throws:
        CacheWriterException - if the write fails. If thrown the cache mutation will not occur.
      • writeAll

        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 - 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)
        Throws:
        CacheWriterException - if one or more of the writes fail. If thrown cache mutations will occur for entries that succeeded.
      • delete

        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 - the key that is used for the delete operation
        Throws:
        CacheWriterException - if delete fails. If thrown the cache delete will not occur.
      • deleteAll

        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 - 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)
        Throws:
        CacheWriterException - if one or more deletes fail. If thrown cache deletes will occur for entries that succeeded.