[[jcache_jsr_107]]
==  JCache (JSR-107) provider
{brandname} provides an implementation of
JCache 1.0 API ( link:http://www.jcp.org/en/jsr/detail?id=107[JSR-107] ).
JCache specifies a standard Java API for caching temporary Java objects in
memory. Caching java objects can help get around bottlenecks arising from
using data that is expensive to retrieve (i.e. DB or web service), or data
that is hard to calculate. Caching these type of objects in memory can help
speed up application performance by retrieving the data directly from memory
instead of doing an expensive roundtrip or recalculation. This document
specifies how to use JCache with {brandname}'s implementation of the
specification, and explains key aspects of the API.

=== Dependencies
In order to start using {brandname} JCache implementation, a single dependency
needs to be added to the Maven pom.xml file:

.pom.xml
include::topics/dependencies/jcache.adoc[]

=== Create a local cache
Creating a local cache, using default configuration options as defined by the
JCache API specification, is as simple as doing the following:

[source,java]
----
import javax.cache.*;
import javax.cache.configuration.*;

// Retrieve the system wide cache manager
CacheManager cacheManager = Caching.getCachingProvider().getCacheManager();
// Define a named cache with default JCache configuration
Cache<String, String> cache = cacheManager.createCache("namedCache",
      new MutableConfiguration<String, String>());
----

WARNING: By default, the JCache API specifies that data should be stored as
`storeByValue`, so that object state mutations outside of operations to the
cache, won't have an impact in the objects stored in the cache. {brandname}
has so far implemented this using serialization/marshalling to make copies to
store in the cache, and that way adhere to the spec. Hence, if using default
JCache configuration with {brandname}, data stored must be marshallable.

Alternatively, JCache can be configured to store data by reference
(just like {brandname} or JDK Collections work). To do that, simply call:

[source,java]
----
Cache<String, String> cache = cacheManager.createCache("namedCache",
      new MutableConfiguration<String, String>().setStoreByValue(false));
----


=== Create a remote cache
Creating a remote cache (client-server mode), using default configuration options
as defined by the JCache API specification, is as simple as doing the following:

[source,java]
----
import javax.cache.*;
import javax.cache.configuration.*;

// Retrieve the system wide cache manager via org.infinispan.jcache.remote.JCachingProvider
CacheManager cacheManager = Caching.getCachingProvider("org.infinispan.jcache.remote.JCachingProvider").getCacheManager();
// Define a named cache with default JCache configuration
Cache<String, String> cache = cacheManager.createCache("remoteNamedCache",
      new MutableConfiguration<String, String>());
----

NOTE: In order to use the org.infinispan.jcache.remote.JCachingProvider, infinispan-jcache-remote-<version>.jar
and all its transitive dependencies need to be on put your classpath.

=== Store and retrieve data
Even though JCache API does not extend neither
link:{jdkdocroot}/java/util/Map.html[java.util.Map]
not link:{jdkdocroot}/java/util/concurrent/ConcurrentMap.html[java.util.concurrent.ConcurrentMap],
it providers a key/value API to store and retrieve data:

[source,java]
----
import javax.cache.*;
import javax.cache.configuration.*;

CacheManager cacheManager = Caching.getCacheManager();
Cache<String, String> cache = cacheManager.createCache("namedCache",
      new MutableConfiguration<String, String>());
cache.put("hello", "world"); // Notice that javax.cache.Cache.put(K) returns void!
String value = cache.get("hello"); // Returns "world"
----

Contrary to standard link:{jdkdocroot}/java/util/Map.html[java.util.Map],
link:https://github.com/jsr107/jsr107spec/blob/v1.0.0-RC1/src/main/java/javax/cache/Cache.java[javax.cache.Cache]
comes with two basic put methods called put and getAndPut. The former returns
`void` whereas the latter returns the previous value associated with the key.
So, the equivalent of link:{jdkdocroot}/java/util/Map.html#put-K-V-[java.util.Map.put(K)]
in JCache is link:https://github.com/jsr107/jsr107spec/blob/v1.0.0-RC1/src/main/java/javax/cache/Cache.java#L230[javax.cache.Cache.getAndPut(K)].


TIP: Even though JCache API only covers standalone caching, it can be plugged
with a persistence store, and has been designed with clustering or
distribution in mind. The reason why javax.cache.Cache offers two put methods
is because standard java.util.Map put call forces implementors to calculate
the previous value. When a persistent store is in use, or the cache is
distributed, returning the previous value could be an expensive operation, and
often users call standard link:{jdkdocroot}/java/util/Map.html#put-K-V-[java.util.Map.put(K)]
without using the return value. Hence, JCache users need to think about
whether the return value is relevant to them, in which case they need to call
link:https://github.com/jsr107/jsr107spec/blob/v1.0.0-RC1/src/main/java/javax/cache/Cache.java#L230[javax.cache.Cache.getAndPut(K)] ,
otherwise they can call link:{jdkdocroot}/java/util/Map.html#put-K-V-[java.util.Map.put(K, V)]
which avoids returning the potentially expensive operation of returning the
previous value.


=== Comparing java.util.concurrent.ConcurrentMap and javax.cache.Cache APIs
Here's a brief comparison of the data manipulation APIs provided by
link:{jdkdocroot}/java/util/concurrent/ConcurrentMap.html[java.util.concurrent.ConcurrentMap]
and link:https://github.com/jsr107/jsr107spec/blob/v1.0.0-RC1/src/main/java/javax/cache/Cache.java[javax.cache.Cache] APIs.

[options="header"]
|===============
|Operation| `java.util.concurrent.ConcurrentMap<K, V>` | `javax.cache.Cache<K, V>`
|store and no return| N/A | `void put(K key)`
|store and return previous value| `V put(K key)` | `V getAndPut(K key)`
|store if not present| `V putIfAbsent(K key, V value)` | `boolean putIfAbsent(K key, V value)`
|retrieve| `V get(Object key)` | `V get(K key)`
|delete if present| `V remove(Object key)` | `boolean remove(K key)`
|delete and return previous value| `V remove(Object key)` | `V getAndRemove(K key)`
|delete conditional| `boolean remove(Object key, Object value)` | `boolean remove(K key, V oldValue)`
|replace if present| `V replace(K key, V value)` | `boolean replace(K key, V value)`
|replace and return previous value| `V replace(K key, V value)` | `V getAndReplace(K key, V value)`
|replace conditional| `boolean replace(K key, V oldValue, V newValue)` | `boolean replace(K key, V oldValue, V newValue)`

|===============

Comparing the two APIs, it's obvious to see that, where possible, JCache
avoids returning the previous value to avoid operations doing expensive
network or IO operations. This is an overriding principle in the design of
JCache API. In fact, there's a set of operations that are present in
link:{jdkdocroot}/java/util/concurrent/ConcurrentMap.html[java.util.concurrent.ConcurrentMap] ,
but are not present in the link:https://github.com/jsr107/jsr107spec/blob/v1.0.0-RC1/src/main/java/javax/cache/Cache.java[javax.cache.Cache]
because they could be expensive to compute in a distributed cache.
The only exception is iterating over the contents of the cache:

[options="header"]
|===============
|Operation| `java.util.concurrent.ConcurrentMap<K, V>` | `javax.cache.Cache<K, V>`
|calculate size of cache| `int size()` | N/A
|return all keys in the cache| `Set<K> keySet()` | N/A
|return all values in the cache| `Collection<V> values()` | N/A
|return all entries in the cache| `Set<Map.Entry<K, V>> entrySet()` | N/A
|iterate over the cache| use `iterator()` method on keySet, values or entrySet | `Iterator<Cache.Entry<K, V>> iterator()`

|===============


=== Clustering JCache instances
{brandname} JCache implementation goes beyond the specification in order to
provide the possibility to cluster caches using the standard API. Given a
{brandname} configuration file configured to replicate caches like this:

.infinispan.xml
[source,xml]
----
<infinispan>
   <cache-container default-cache="namedCache">
      <transport cluster="jcache-cluster" />
      <replicated-cache name="namedCache" />
   </cache-container>
</infinispan>
----

You can create a cluster of caches using this code:

[source,java]
----
import javax.cache.*;
import java.net.URI;

// For multiple cache managers to be constructed with the standard JCache API
// and live in the same JVM, either their names, or their classloaders, must
// be different.
// This example shows how to force their classloaders to be different.
// An alternative method would have been to duplicate the XML file and give
// it a different name, but this results in unnecessary file duplication.
ClassLoader tccl = Thread.currentThread().getContextClassLoader();
CacheManager cacheManager1 = Caching.getCachingProvider().getCacheManager(
      URI.create("infinispan-jcache-cluster.xml"), new TestClassLoader(tccl));
CacheManager cacheManager2 = Caching.getCachingProvider().getCacheManager(
      URI.create("infinispan-jcache-cluster.xml"), new TestClassLoader(tccl));

Cache<String, String> cache1 = cacheManager1.getCache("namedCache");
Cache<String, String> cache2 = cacheManager2.getCache("namedCache");

cache1.put("hello", "world");
String value = cache2.get("hello"); // Returns "world" if clustering is working

// --

public static class TestClassLoader extends ClassLoader {
  public TestClassLoader(ClassLoader parent) {
     super(parent);
  }
}
----
