org.infinispan.multimap.api.BasicMultimapCache Maven / Gradle / Ivy
package org.infinispan.multimap.api;
import java.util.Collection;
import java.util.concurrent.CompletableFuture;
import org.infinispan.commons.util.Experimental;
/**
* {@link BasicMultimapCache} provides the common API for the two different types of multimap caches that Infinispan
* provides: embedded and remote. Please see the Infinispan
* documentation and/or the 5 Minute
* Usage Tutorial for more details on Infinispan.
*
* MutimapCache is a type of Infinispan Cache that maps keys to values, similar to {@link
* org.infinispan.commons.api.AsyncCache} in which each key can contain multiple values.
*
* foo → 1
* bar → 3, 4, 5
*
*
Example
*
*
* multimapCache.put("k", "v1").join();
* multimapCache.put("k", "v2").join();
* multimapCache.put("k", "v3").join();
*
* Collection results = multimapCache.get("k").join();
*
*
*
Eviction
Eviction works per key. This means all the values associated on a key will be evicted.
*
*
*
Views
*
* The returned collections when calling "get" are views of the values on the key. Any change on these collections won't
* affect the cache values on the key.
*
*
Null values
Null values are not supported. The multimap cache won't have a null key or any null value.
*
* Example
*
* multimapCache.put(null, "v1").join() → fails
* multimapCache.put("k", null).join() → fails
* multimapCache.put("k", "v1").join() → works and add's v1
* multimapCache.containsKey("k").join() → true
* multimapCache.remove("k", "v1").join() → works, removes v1 and as the remaining collection is empty, the key is
* removed
* multimapCache.containsKey("k").join() → false
*
*
*
* @author Katia Aresti, [email protected]
* @see Infinispan documentation
* @since 9.2
*/
@Experimental
public interface BasicMultimapCache {
/**
* Puts a key-value pair in this multimap cache. - If this multimap cache supports
* duplicates, the value will be always added.
- If this multimap cache does not support duplicates and
* the value exists on the key, nothing will be done.
*
* @param key the key to be put
* @param value the value to added
* @return {@link CompletableFuture} containing a {@link Void}
* @since 9.2
*/
CompletableFuture put(K key, V value);
/***
* Returns a view collection of the values associated with key in this multimap cache,
* if any. Any changes to the retrieved collection won't change the values in this multimap cache.
* When this method returns an empty collection, it means the key was not found.
*
* @param key to be retrieved
* @return a {@link CompletableFuture} containing {@link Collection } which is a view of the underlying values.
* @since 9.2
*/
CompletableFuture> get(K key);
/**
* Removes all the key-value pairs associated with the key from this multimap cache, if such exists.
*
* @param key to be removed
* @return a {@link CompletableFuture} containing {@link Boolean#TRUE} if the entry was removed, and {@link
* Boolean#FALSE} when the entry was not removed
* @since 9.2
*/
CompletableFuture remove(K key);
/**
* Removes a key-value pair from this multimap cache, if such exists. Returns true when the
* key-value pair has been removed from the key.
*
*
- In the case where duplicates are not supported, only one the key-value pair will be
* removed, if such exists.
- In the case where duplicates are supported, all the key-value pairs will
* be removed.
- If the values remaining after the remove call are empty, the whole entry will be
* removed.
*
* @param key key to be removed
* @param value value to be removed
* @return {@link CompletableFuture} containing {@link Boolean#TRUE} if the key-value pair was removed, and {@link
* Boolean#FALSE} when the key-value pair was not removed
* @since 9.2
*/
CompletableFuture remove(K key, V value);
/**
* Returns {@link Boolean#TRUE} if this multimap cache contains the key.
*
* @param key the key that might exists in this multimap cache
* @return {@link CompletableFuture} containing a {@link Boolean}
* @since 9.2
*/
CompletableFuture containsKey(K key);
/**
* Asynchronous method that returns {@link Boolean#TRUE} if this multimap cache contains the value at any key.
*
* @param value the value that might exists in any entry
* @return {@link CompletableFuture} containing a {@link Boolean}
* @since 9.2
*/
CompletableFuture containsValue(V value);
/**
* Returns {@link Boolean#TRUE} if this multimap cache contains the key-value pair.
*
* @param key the key of the key-value pair
* @param value the value of the key-value pair
* @return {@link CompletableFuture} containing a {@link Boolean}
* @since 9.2
*/
CompletableFuture containsEntry(K key, V value);
/**
* Returns the number of key-value pairs in this multimap cache. It doesn't return the distinct number of keys.
*
* This method is blocking in a explicit transaction context.
*
* The {@link CompletableFuture} is a
*
* @return {@link CompletableFuture} containing the size as {@link Long}
* @since 9.2
*/
CompletableFuture size();
/**
* Multimap can support duplicates on the same key k → ['a', 'a', 'b'] or not k → ['a', 'b'] depending on
* configuration.
*
* Returns duplicates are supported or not in this multimap cache.
*
* @return {@code true} if this multimap supports duplicate values for a given key.
* @since 9.2
*/
boolean supportsDuplicates();
}