Package org.apache.sis.util.collection

## Interface Cache.Handler<V>

- Type Parameters:
    `V` - the type of value objects.
  Enclosing class:
    Cache<K,​V>

      public static interface Cache.Handler<V>

  The handler returned by `Cache​.lock(K)`, to be used for unlocking and storing the result. This handler should be used as below (the `try` … `finally` statements are important):

  >     Value V = null;
  >     Cache.Handler<V> handler = cache.lock(key);
  >     try {
  >         value = handler.peek();
  >         if (value == null) {
  >             value = createMyObject(key);
  >         }
  >     } finally {
  >         handler.putAndUnlock(value);
  >     }

  See the `Cache` javadoc for a more complete example.
  Since:
    0.3

  Defined in the `sis-utility` module

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `V` | `peek()` | If the value is already in the cache, returns it.
    `void` | `putAndUnlock​(V result)` | Stores the given value in the cache and release the lock.

- - ### Method Detail

    - #### peek

          V peek()

      If the value is already in the cache, returns it. Otherwise returns `null`. This method should be invoked after the `Handler` creation in case a value has been computed in an other thread.
      Returns:
        the value from the cache, or `null` if none.

    - #### putAndUnlock

          void putAndUnlock​(V result)
                     throws IllegalStateException

      Stores the given value in the cache and release the lock. This method must be invoked in a `finally` block, no matter what the result is.
      Parameters:
        `result` - the result to store in the cache, or `null` for removing the entry from the cache. If an entry is removed, a new computation will be attempted the next time a handler is created for the same key.
      Throws:
        `IllegalStateException` - may be thrown if this method is not invoked in the pattern described in class javadoc, or if a key collision occurs.