com.tangosol.net.cache.NonBlockingEntryStore Maven / Gradle / Ivy
Show all versions of coherence Show documentation
/*
* Copyright (c) 2000, 2021, Oracle and/or its affiliates.
*
* Licensed under the Universal Permissive License v 1.0 as shown at
* http://oss.oracle.com/licenses/upl.
*/
package com.tangosol.net.cache;
import com.tangosol.util.BinaryEntry;
import java.util.Set;
/**
* 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 {@link 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 {@code 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 {@link StoreObserver} via {@link StoreObserver#onNext onNext} or
* {@link StoreObserver#onError onError} passing the same BinaryEntry that was
* provided which correlates to the successful or unsuccessful operation. Additionally,
* the {@link StoreObserver} offers an {@link StoreObserver#onComplete 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(Set> setBinEntries, StoreObserver observer)
* {
* SomeReactiveResource resource;
* for (BinaryEntry 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 {@link StoreObserver#onComplete()}:
*
* - The StoreObserver instance will throw a IllegalStateExcpetion on
* any future calls to {@link StoreObserver#onNext onNext} or {@link StoreObserver#onError 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 StoreObserver
*/
public interface NonBlockingEntryStore
{
/**
* Load the value from the underlying store, update the provided entry and
* call the {@link StoreObserver#onNext onNext} method of the provided
* {@link StoreObserver} object, or {@link StoreObserver#onError onError} if the store operation
* failed.
*
* @param binEntry an entry that needs to be updated with the loaded value
* @param observer {@link StoreObserver} provided to caller to notify
*/
public void load(BinaryEntry binEntry, StoreObserver observer);
/**
* Load the values from the underlying store and update the specified entries
* by calling the onNext method of the provided
* {@link 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.
*
* @param setBinEntries a set of entries that needs to be updated with the
* loaded values
* @param observer {@link StoreObserver} provided to caller to notify
*
* @throws UnsupportedOperationException if this implementation or the
* underlying store is read-only
*/
public void loadAll(Set> setBinEntries, StoreObserver 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 {@link StoreObserver#onNext onNext} or {@link StoreObserver#onError
* 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).
*
* @param binEntry the entry to be stored
* @param observer {@link StoreObserver} provided to caller to notify
*
* @throws UnsupportedOperationException if this implementation or the
* underlying store is read-only
*/
public void store(BinaryEntry binEntry, StoreObserver 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 {@link StoreObserver}. An error during an underlying store
* operation, or custom logic, should invoke onError instead.
*
* {@link StoreObserver#onNext} or {@link StoreObserver#onError} 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).
*
* @param setBinEntries the set of entries to be stored
* @param observer {@link StoreObserver} provided to caller to notify
*
* @throws UnsupportedOperationException if this implementation or the
* underlying store is read-only
*/
public void storeAll(Set> setBinEntries, StoreObserver observer);
/**
* Remove the specified entry from the underlying store.
*
* @param binEntry the entry to be removed from the store
*
* @throws UnsupportedOperationException if this implementation or the
* underlying store is read-only
*/
public void erase(BinaryEntry binEntry);
/**
* 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.
*
* @param setBinEntries the set entries to be removed from the store
*
* @throws UnsupportedOperationException if this implementation or the
* underlying store is read-only
*/
public void eraseAll(Set> setBinEntries);
}