Package com.tangosol.net.cache

Interface NonBlockingEntryStore<K,V>

public interface NonBlockingEntryStore<K,V>
NonBlockingEntryStore provides a means to integrate Coherence with an underlying data source that offers a non-blocking API.

The methods on this interface a called based on a get, getAll, put, putAll, remove or removeAll respectively. Similar to BinaryEntryStore, the methods on this interface receive a BinaryEntry allowing them to avoid deserialization, if possible, for the key, value and original value by using the get*Binary* equivalent methods.

The expectation is for implementations to execute non-blocking APIs that will complete at some point in the future. Once the operation completes the implementation can notify the provided StoreObserver via onNext or onError passing the same BinaryEntry that was provided which correlates to the successful or unsuccessful operation. Additionally, the StoreObserver offers an onComplete method to allow an implementation to suggest to Coherence that no further processing will occur for the relevant operation. Below is an example implementation: 


   public void loadAll(Setinvalid input: '<'? extends BinaryEntryinvalid input: '<'K, V>> setBinEntries, StoreObserverinvalid input: '<'K, V> observer)
       {
       SomeReactiveResource resource;
       for (BinaryEntryinvalid input: '<'K, V> binEntry : setBinEntries)
           {
           CompletableFuture future = resource.get(binEntry.getKey);
           future.whenComplete((value, exception) ->
               {
               if (exception == null)
                   {
                   binEntry.setValue(value);
                   observer.onNext(binEntry))
                   }
               else
                   {
                   observer.onError(binEntry, exception))
                   if (isTerminal(exception))
                       {
                       // no futher processing will be possible as resource
                       // is terminally unavailable and assume futures will
                       // not be fired
                       observer.onComplete();
                       }
                   }
               }
           }
       }
Some additional notes on calling StoreObserver.onComplete():
  • The StoreObserver instance will throw a IllegalStateExcpetion on any future calls to onNext or onError.
  • Any unprocessed entires will have their decorations removed thus store will not be called on failover
Since:
21.06
Author:
mg/hr/as
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    erase(BinaryEntry<K,V> binEntry)
    Remove the specified entry from the underlying store.
    void
    eraseAll(Set<? extends BinaryEntry<K,V>> setBinEntries)
    Remove the specified entries from the underlying store.
    void
    load(BinaryEntry<K,V> binEntry, StoreObserver<K,V> observer)
    Load the value from the underlying store, update the provided entry and call the onNext method of the provided StoreObserver object, or onError if the store operation failed.
    void
    loadAll(Set<? extends BinaryEntry<K,V>> setBinEntries, StoreObserver<K,V> observer)
    Load the values from the underlying store and update the specified entries by calling the onNext method of the provided StoreObserver object, or onError if the store operation failed.
    void
    store(BinaryEntry<K,V> binEntry, StoreObserver<K,V> observer)
    Store the specified entry in the underlying store, in an asynchronous fashion.
    void
    storeAll(Set<? extends BinaryEntry<K,V>> setBinEntries, StoreObserver<K,V> observer)
    Asynchronously store the entries in the specified set in the underlying store.

  • Method Details

    • load

      void load(BinaryEntry<K,V> binEntry, StoreObserver<K,V> observer)
      Load the value from the underlying store, update the provided entry and call the onNext method of the provided StoreObserver object, or onError if the store operation failed.
      Parameters:
      binEntry - an entry that needs to be updated with the loaded value
      observer - StoreObserver provided to caller to notify

    • loadAll

      void loadAll(Set<? extends BinaryEntry<K,V>> setBinEntries, StoreObserver<K,V> observer)
      Load the values from the underlying store and update the specified entries by calling the onNext method of the provided StoreObserver object, or onError if the store operation failed.

      If the NonBlockingEntryStore is capable of loading Binary values, it should update the entry using the {#link BinaryEntry.updateBinaryValue} API.

      Parameters:
      setBinEntries - a set of entries that needs to be updated with the loaded values
      observer - StoreObserver provided to caller to notify
      Throws:
      UnsupportedOperationException - if this implementation or the underlying store is read-only

    • store

      void store(BinaryEntry<K,V> binEntry, StoreObserver<K,V> observer)
      Store the specified entry in the underlying store, in an asynchronous fashion. This method will be called for inserts and updates. Once successfully or unsuccessfully stored this implementation should call onNext or onError respectively.

      If the store operation changes the entry's value, a best effort will be made to place the changed value back into the corresponding backing map (for asynchronous store operations a concurrent backing map modification can make it impossible).

      Parameters:
      binEntry - the entry to be stored
      observer - StoreObserver provided to caller to notify
      Throws:
      UnsupportedOperationException - if this implementation or the underlying store is read-only

    • storeAll

      void storeAll(Set<? extends BinaryEntry<K,V>> setBinEntries, StoreObserver<K,V> observer)
      Asynchronously store the entries in the specified set in the underlying store. This method is intended to support both the entry creation and value update upon invocation of the onNext method of the provided StoreObserver. An error during an underlying store operation, or custom logic, should invoke onError instead.

      StoreObserver.onNext(com.tangosol.util.BinaryEntry<K, V>) or StoreObserver.onError(com.tangosol.util.BinaryEntry<K, V>, java.lang.Exception) affects individual entries in the specified set.

      If the storeAll operation changes some entries' values, a best effort will be made to place the changed values back into the corresponding backing map (for asynchronous store operations concurrent backing map modifications can make it impossible).

      Parameters:
      setBinEntries - the set of entries to be stored
      observer - StoreObserver provided to caller to notify
      Throws:
      UnsupportedOperationException - if this implementation or the underlying store is read-only

    • erase

      void erase(BinaryEntry<K,V> binEntry)
      Remove the specified entry from the underlying store.
      Parameters:
      binEntry - the entry to be removed from the store
      Throws:
      UnsupportedOperationException - if this implementation or the underlying store is read-only

    • eraseAll

      void eraseAll(Set<? extends BinaryEntry<K,V>> setBinEntries)
      Remove the specified entries from the underlying store.

      If this operation fails (by throwing an exception) after a partial success, the convention is that entries which have been erased successfully are to be removed from the specified set, indicating that the erase operation for the entries left in the collection has failed or has not been attempted.

      Parameters:
      setBinEntries - the set entries to be removed from the store
      Throws:
      UnsupportedOperationException - if this implementation or the underlying store is read-only