ISPN-7780 multimap embedded, simple implementation

* The API is asynchronous
* Mutimap cache is based on regular cache
* There is a limitation on tx caches, some mehods will block
* Added storage type test, attending ISPN-7993
* Added getEntry method for hotrod
* Eenhancements in MultiMap tests

core/pom.xml

@@ -177,6 +177,7 @@
                   <Export-Package>
                      !${project.groupId}.commons.*,
                      !${project.groupId}.counter.*,
+                     !${project.groupId}.multimap.*,
                      org.infinispan.marshall.core,
                      ${project.groupId}.*;version=${project.version};-split-package:=error
                   </Export-Package>

core/src/main/java/org/infinispan/expiration/impl/ClusterExpirationManager.java

@@ -54,6 +54,10 @@ public class ClusterExpirationManager<K, V> extends ExpirationManagerImpl<K, V>
    private AdvancedCache<K, V> cache;
    private boolean needTransaction;
 
+   public ExecutorService getAsyncExecutor() {
+      return asyncExecutor;
+   }
+
    @Inject
    public void inject(AdvancedCache<K, V> cache, Configuration configuration,
            @ComponentName(KnownComponentNames.ASYNC_OPERATIONS_EXECUTOR) ExecutorService asyncExecutor) {

core/src/test/java/org/infinispan/distribution/DistributionTestHelper.java

@@ -47,7 +47,6 @@ public static void assertIsInContainerImmortal(Cache<?, ?> cache, Object key) {
          log.fatal(msg);
          assert false : msg;
       }
-
       if (!(ice instanceof ImmortalCacheEntry)) {
          String msg = "Entry for key [" + key + "] on cache at [" + addressOf(cache) + "] should be immortal but was [" + ice + "]!";
          log.fatal(msg);

documentation/src/main/asciidoc/user_guide/marshalling.adoc

@@ -440,6 +440,7 @@ This is the list of Externalizer identifiers that are used by Infinispan based m
 |Infinispan Server Event Logger Module:|1850 - 1899
 |Infinispan Remote Store:|1900 - 1999
 |Infinispan Counters:|2000 - 2049
+|Infinispan Multimap:|2050 - 2099
 |===============
 
 

documentation/src/main/asciidoc/user_guide/multimapcache.adoc

@@ -0,0 +1,155 @@
+== Multimap Cache
+
+Infinispan Multimap Cache is a new distributed and clustered collection type introduced in Infinispan 9.
+MutimapCache is a type of Infinispan Cache that maps keys to values in which each key can contain multiple values.
+
+=== Installation and configuration
+
+.pom.xml
+[source,xml]
+----
+<dependency>
+   <groupId>org.infinispan</groupId>
+   <artifactId>infinispan-multimap</artifactId>
+   <version>...</version> <!-- 9.2.0.Final or higher -->
+</dependency>
+----
+
+=== MultimapCache API
+
+MultimapCache API exposes several methods to interact with the Multimap Cache.
+All these methods are non-blocking in most of the cases. See [limitations]
+
+[source,java]
+----
+
+public interface MultimapCache<K, V> {
+
+   CompletableFuture<Void> put(K key, V value);
+
+   CompletableFuture<Collection<V>> get(K key);
+
+   CompletableFuture<Boolean> remove(K key);
+
+   CompletableFuture<Boolean> remove(K key, V value);
+
+   CompletableFuture<Void> remove(Predicate<? super V> p);
+
+   CompletableFuture<Boolean> containsKey(K key);
+
+   CompletableFuture<Boolean> containsValue(V value);
+
+   CompletableFuture<Boolean> containsEntry(K key, V value);
+
+   CompletableFuture<Long> size();
+
+   boolean supportsDuplicates();
+
+}
+
+----
+
+==== CompletableFuture<Void> put(K key, V value)
+Puts a key-value pair in the multimap cache.
+
+[source,java]
+----
+MultimapCache<String, String> multimapCache = ...;
+
+multimapCache.put("girlNames", "marie")
+             .thenCompose(r1 -> multimapCache.put("girlNames", "oihana"))
+             .thenCompose(r3 -> multimapCache.get("girlNames"))
+             .thenAccept(names -> {
+                          if(names.contains("marie"))
+                              System.out.println("Marie is a girl name");
+
+                           if(names.contains("oihana"))
+                              System.out.println("Oihana is a girl name");
+                        });
+----
+The output of this code is :
+
+[source, txt]
+----
+Marie is a girl name
+Oihana is a girl name
+----
+
+==== CompletableFuture<Collection<V>> get(K key)
+
+Asynchronous that 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.
+
+==== CompletableFuture<Boolean> remove(K key)
+Asynchronous that removes the entry associated with the key from the multimap cache, if such exists.
+
+==== CompletableFuture<Boolean> remove(K key, V value)
+Asynchronous that removes a key-value pair from the multimap cache, if such exists.
+
+==== CompletableFuture<Void> remove(Predicate<? super V> p)
+Asynchronous method. Removes every value that match the given predicate.
+
+==== CompletableFuture<Boolean> containsKey(K key)
+Asynchronous that returns true if this multimap contains the key.
+
+==== CompletableFuture<Boolean> containsValue(V value)
+Asynchronous that returns true if this multimap contains the value in at least one key.
+
+==== CompletableFuture<Boolean> containsEntry(K key, V value)
+
+Asynchronous that returns true if this multimap contains at least one key-value pair with the value.
+
+==== CompletableFuture<Long> size()
+Asynchronous that returns the number of key-value pairs in the multimap cache. It doesn't return the distinct number of keys.
+
+==== boolean supportsDuplicates()
+Asynchronous that returns true if the multimap cache supports duplicates. This means that the content of the multimap can be
+'a' -> ['1', '1', '2']. For now this method will always return false, as duplicates are not yet supported.
+The existence of a given value is determined by 'equals' and `hashcode' method's contract.
+
+=== Creating a Multimap Cache
+
+In version 9.2, the MultimapCache is configured as a regular cache. This can be done either by code or XML configuration.
+See how to configure a regular Cache in the section link to [configure a cache].
+
+==== Embedded mode
+
+[source,java]
+----
+// create or obtain your EmbeddedCacheManager
+EmbeddedCacheManager cm = ... ;
+
+// create or obtain a MultimapCacheManager passing the EmbeddedCacheManager
+MultimapCacheManager multimapCacheManager = EmbeddedMultimapCacheManagerFactory.from(cm);
+
+// define the configuration for the multimap cache
+multimapCacheManager.defineConfiguration(multimapCacheName, c.build());
+
+// get the multimap cache
+multimapCache = multimapCacheManager.get(multimapCacheName);
+----
+
+==== Server mode
+
+TODO
+
+=== Limitations
+
+In almost every case the Multimap Cache will behave as a regular Cache, but some limitations exist in the first 9.2 version.
+
+==== Support for duplicates
+Duplicates are not supported yet. This means that the multimap won't contain any duplicate key-value pair.
+Whenever put method is called, if the key-value pair already exist, this key-value par won't be added.
+Methods used to check if a key-value pair is already present in the Multimap are the `equals` and `hashcode`.
+
+==== Eviction
+
+For now, the eviction works per key, and not per key-value pair.
+This means that whenever a key is evicted, all the values associated with the key will be evicted too.
+Eviction per key-value could be supported in the future.
+
+==== Transactions
+
+Implicit transactions are supported through the auto-commit and all the methods are non blocking.
+Explicit transactions work without blocking in most of the cases.
+Methods that will block are `size`, `containsEntry` and `remove(Predicate<? super V> p)`

documentation/src/main/asciidoc/user_guide/user_guide.asciidoc

@@ -36,3 +36,4 @@ include::rolling_upgrades.adoc[]
 include::extending.adoc[]
 include::architecture.adoc[]
 include::counters.adoc[]
+include::multimapcache.adoc[]

multimap/pom.xml

@@ -0,0 +1,53 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>org.infinispan</groupId>
+        <artifactId>infinispan-parent</artifactId>
+        <version>9.2.0-SNAPSHOT</version>
+        <relativePath>../parent/pom.xml</relativePath>
+    </parent>
+
+    <artifactId>infinispan-multimap</artifactId>
+    <packaging>jar</packaging>
+    <name>Infinispan Multimap</name>
+    <description>Infinispan Multimap module</description>
+
+    <properties>
+        <module.skipComponentMetaDataProcessing>false</module.skipComponentMetaDataProcessing>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>${project.groupId}</groupId>
+            <artifactId>infinispan-core</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.kohsuke.metainf-services</groupId>
+            <artifactId>metainf-services</artifactId>
+            <optional>true</optional>
+        </dependency>
+
+        <dependency>
+            <groupId>${project.groupId}</groupId>
+            <artifactId>infinispan-core</artifactId>
+            <type>test-jar</type>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>${project.groupId}</groupId>
+            <artifactId>infinispan-commons-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.testng</groupId>
+            <artifactId>testng</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>junit</groupId>
+            <artifactId>junit</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>

multimap/src/main/java/org/infinispan/multimap/api/EmbeddedMultimapCacheManagerFactory.java

@@ -0,0 +1,20 @@
+package org.infinispan.multimap.api;
+
+import org.infinispan.manager.EmbeddedCacheManager;
+import org.infinispan.multimap.impl.EmbeddedMultimapCacheManager;
+
+/**
+ * A {@link MultimapCache} factory for embedded cached.
+ *
+ * @author Katia Aresti, karesti@redhat.com
+ * @since 9.2
+ */
+public final class EmbeddedMultimapCacheManagerFactory {
+
+   private EmbeddedMultimapCacheManagerFactory() {
+   }
+
+   public static MultimapCacheManager from(EmbeddedCacheManager cacheManager) {
+      return new EmbeddedMultimapCacheManager(cacheManager);
+   }
+}