Contents

• 1. Overview
• 2. Documentation Conventions

• 3. Using JCache in your Applications

  • 3.1 Accessing the JSR107 Caching Provider and Cache Manager

    • 3.1.1 Using Injection

  • 3.2 Creating a Cache using Injection

    • 3.2.1 Creating a custom Cache using Injection

  • 3.3 Using JCache Annotations

• 4. Appendices

  • 4.1 NamedCache Annotation

1. Overview

This page covers how to use the JCache functionality in Payara 4.1.1.162.

JSR107 (JCache) is implemented in Payara by Hazelcast.

2. Documentation Conventions

Any paths listed throughout the documentation will use the Unix\/Linux file path structure (forward slashes).

3. Using JCache in your Applications

The following section will detail how to access and use JCache in your code.

3.1 Accessing the JSR107 Caching Provider and Cache Manager

To create a Cache, you will need a CachingProvider and CacheManager. The embedded Hazelcast member in Payara has a CachingProvider and CacheManager registered to JNDI, so you do not have to create your own. To access them, import the following classes and initialise two variables like so:

import javax.cache.spi.CachingProvider;
import javax.cache.CacheManager;
...
Context ctx = new InitialContext();
CachingProvider provider = (CachingProvider) ctx.lookup("payara/CachingProvider");
CacheManager manager = (CacheManager) ctx.lookup("payara/CacheManager");

3.1.1 Using Injection

You can also use injection to access and use the CachingProvider and CacheManager embedded in Payara. Inject them into your application like so (note, your war or jar must be an implicit or explicit bean archive i.e. contains a CDI Bean with a bean defining annotation, an EJB Session Bean or a beans.xml file):

import javax.cache.CacheManager;
import javax.cache.spi.CachingProvider;
import javax.inject.Inject;
...
@Inject 
CacheManager manager;
@Inject
CachingProvider provider;

3.2 Creating a Cache using Injection

You can create a cache using either the getCache method of a CacheManager, or using injection. Creating the cache with injection uses the Caching Provider and Cache Manager described above.

Creating a cache with injection can be done like so:

import javax.inject.Inject;
import javax.cache.Cache;
...
@Inject
Cache cache;

The name of this cache will be the canonical name of the class it is created in. Caches created in this way will also have JMX statistics and management enabled.

Starting from Payara 4.1.1.164, a typed cache can also be injected in the same manner:

import javax.inject.Inject;
import javax.cache.Cache;
...
@Inject
Cache<Long, Property> cache;

Both key and value types must be Serializable so that the cache can be injected correctly.

3.2.1 Creating a custom Cache using Injection

You can determine the name and other attributes of a cache created through injection using the @NamedCache annotation.

You can specify the desired custom values as a comma separated list of parameters of the NamedCache annotation when creating a cache.

For example, to inject a cache with a custom name and with JMX management enabled:

import fish.payara.cdi.jsr107.impl.NamedCache;
import javax.inject.Inject;
import javax.cache.Cache;
...
@NamedCache(cacheName = "custom", managementEnabled = true)
@Inject
Cache cache;

The full array of parameters can be seen in the NamedCache section of the appendices.

If you only want to set the name of the cache but don't want to depend on the @NamedCache annotation since it's part of the Payara Extras dependencies, you can use the @CacheDefaults annotation on the bean class:

import fish.payara.cdi.jsr107.impl.NamedCache;
import javax.inject.Inject;
import javax.cache.Cache;
import javax.cache.annotation.CacheDefaults;
import javax.enterprise.context.ApplicationScoped;
...
@ApplicationScoped
@CacheDefaults(cacheName = "custom")
public class CacheBean {
    ...
    @Inject
    Cache cache;
    ...
}

Keep in mind that this solution only works if your bean has one injected cache only. If you are in a situation where you must inject more than one cache into the bean then consider using the @NamedCache annotation to avoid name collisions.

3.3 Using JCache Annotations

Payara has the necessary interceptors implemented for allowing the full set of JCache annotations to be used.

The JCache annotations are as follows:

• @CachePut - Puts the specified key and value in the cache.
• @CacheRemove - Removes the specified key and value from the cache.
• @CacheResult - Retrieves the value associated with the specified key.
• @CacheRemoveAll - Removes all keys and values from the cache.
• @CacheDefaults - Allows the configuration of defaults for CacheResult, CachePut, CacheRemove, and CacheRemoveAll at the class level.
• @CacheKey - Marks a method parameter as the key of a cache.
• @CacheValue - Marks a method parameter as the value of a cache key.

4. Appendices

4.1 NamedCache Annotation