Adding the dependencies.

We’ll start by adding this special CDI module to our Java Sample Room as a library.

Firstly, edit the pom.xml in your room project and find the <dependencies>…​</dependencies> block. Add these dependencies after the existing ones, just before the </dependencies> tag.

<dependency>
    <groupId>org.redisson</groupId>
    <artifactId>redisson</artifactId>
    <version>3.2.3</version>
</dependency>
<dependency>
    <groupId>javax.cache</groupId>
    <artifactId>cache-api</artifactId>
    <version>1.0.0</version>
</dependency>
<dependency>
    <groupId>com.github.BarDweller</groupId>
    <artifactId>JSR107-RI-CDI-Custom-CacheManager</artifactId>
    <version>v1.0.9-STILETTO</version>
</dependency>

The first is the Redisson client, that will provide the implementation of the API for our room, the second provides the API interfaces, and the last is the CDI Module to enable the JSR-107 annotations.

Creating the default cache manager provider

The CDI Module allows us to configure the CacheManager the JSR-107 annotations should use. It provides this capability by using a Java Service, our room needs to include an implementation of the DefaultCacheManagerProvider interface, which looks like this:

public interface DefaultCacheManagerProvider {
  public CacheManager getDefaultCacheManager();
}

As this walk-through is based off of a CF app, we’ll create an implementation of this interface that parses VCAP_SERVICES. If you get adventurous and deploy your room elsewhere, you should be able to follow a similar pattern for retrieving the configuration of your endpoint from the environment.

So, to configure and create a CacheManager based on VCAP_SERVICES environment settings, we’ll do the following:

You are almost done, and the code would work as-is, but you need to be aware of a few issues.

So, if you plan to use more than a single annotated method, you will need to cache the RedissonClient and reuse it each time you are asked for a new CacheManager.

Here’s a full example implementation of a DefaultCacheManagerProvider that may be handy for you to reference. It parses VCAP_SERVICES and caches the RedissonClient instance as suggested.

Adding the META-INF/services entry

As mentioned earlier, the fork we are using of the JSR-107 CDI Module allows us to create the CacheManager for use by the annotations by supplying an implementation of a Java Service. We’ve created the implementation, and now we create the metadata that allows the implementation to be located at runtime.

Create a file in your Room project at src/main/webapp/META-INF/services and call it org.JSR-107.ri.annotations.DefaultCacheResolverFactory$DefaultCacheManagerProvider

Inside the file, place the full name for your DefaultCacheManagerProvider class, eg the example has the line saying…​

org.gameontext.sample.JSR-107defaultprovider.RedissonCacheManagerProvider

Congratulations! Your room is now able to use JSR-107 annotations, backed by your Redis service instance. Let’s look at a few ways we can use that in a room.

Creating the Store

The code for the secret store is deceptively simple;

@CacheDefaults(cacheName="secrets")
public class SecretDataBean {
    @CachePut
    public void setSecretForUser(@CacheKey String userid, @CacheValue String secret){
        //no-op
    }
    @CacheResult
    public String getSecretForUser(String userid){
        return null;
    }
}

The @CacheDefaults annotation sets up the class to use the cache called secrets. Using this annotation means we don’t need to specify the cache name on our other annotated methods.

The @CachePut annotated method will always update the cache. In this instance, we’re using the @CacheKey and @CacheValue annotations to have the cache values be identified straight from the method arguments themselves. Which means we don’t need a method body at all.

The @CacheResult annotation would normally be used to cache the result of invoking a method. It’s normal effect is to wrap the method invocation, and check the cache for a value with the key derived from the method arguments. If the cache has a value the method invocation is skipped entirely, otherwise the method is invoked, and the result of the method is set as the cached value, and returned to the caller.

In this example, we’re relying on the @CachePut to have updated the cache with the value we want to retrieve, so the only time the getSecretForUser method will actually execute is when there has been no value placed into the cache for the user via the put method. Effectively, this means the getSecretForUser method returns the "default" secret for when the user has not set one yet. Here we’re returning null which we’ll use in our command to identify there is no secret set for the user. But we could have chosen to do a database lookup, and retrieve a persisted key for the user.

Overall, this call conceptually acts a little bit like a Map, except the Map content is shared between all users of the Cache, which in this case could be multiple instances of our Room as it scales up under load. It can feel a bit strange to think of this as a Map, as it has no apparent storage within the class for the Keys & Values, because they are all managed by the Cache.

Adding a command to drive the Store

To test our Secret cache, lets add the new /secret command to our room to invoke it.

First, inject the SecretDataBean into the RoomImplementation class, add the annotated declaration near the top where other class variables are declared.

@Inject
protected SecretDataBean secret;

Then find the switch statement in the processCommand method, and add another case to the statement.

case "/secret":
    if (remainder == null) {
        String userSecret = secret.getSecretForUser(userId);
        if (userSecret == null) {
            endpoint.sendMessage(session,
                                 Message.createSpecificEvent(userId,
                                 "You apparently don't have a secret at the moment."+
                                 "Maybe you should set one with /secret ilikepie"));
        } else {
            endpoint.sendMessage(session,
                                 Message.createSpecificEvent(userId,
                                 "Your secret is currently '"+userSecret+"'"));
        }
    } else {
        secret.setSecretForUser(userId, remainder);
        endpoint.sendMessage(session,
                             Message.createSpecificEvent(userId,
                             "Your secret has been set to '"+remainder+"'"));
    }
    break;

Here when the command /secret is invoked with no arguments, we ask the secret store if it has a secret for the user, and output an appropriate message.

When invoked with arguments, we store that as the secret for the user.

Cache expiry

With our current Secret Store, we’ll hold onto the secret for the user until our Redis instance is restarted. This might not be quite what we want, if we had a large number of users who only try the Store once, we should clean up the Cache to remove old entries.

JSR-107 supports this concept by way of setting a CacheExpiry when the Cache is created. Unfortunately, when using the JSR-107 annotations, there is no handy 'expiry' annotation or attribute we can make use of. If we want to configure a cache used by the annotations, we are given a single option; the CacheResolverFactory.

A CacheResolverFactory can be set as an attribute for the various method annotations, and can also be set via the @CacheDefaults annotation. It has the responsibility of giving back a CacheResolver (which in turn gives back a Cache) for a given annotated method.

Here’s a simple CacheResolverFactory that will use the DefaultCacheManagerProvider we created earlier, to obtain a Redisson configured Cache with a 5 minute expiry. The Cache is then used to create a CacheResolver to return.

public class MyCacheResolverFactory implements CacheResolverFactory{

  CacheManager cacheManager = (new RedissonCacheManagerProvider())
                                 .getDefaultCacheManager();

  private Cache<?,?> getCache(String name){
    Cache<?, ?> cache = cacheManager.getCache(name);
    if (cache == null) {
      MutableConfiguration<Object, Object> config = getConfig();
      cacheManager.createCache(name, config);
      cache = cacheManager.getCache(name);
    }
  }

  private MutableConfiguration<Object,Object> getConfig(){
    MutableConfiguration<Object,Object> config = new MutableConfiguration<Object,Object>();
    config.setExpiryPolicyFactory(CreatedExpiryPolicy.factoryOf(Duration.FIVE_MINUTES));
    return config;
  }


  @Override
  public CacheResolver getCacheResolver(
         CacheMethodDetails<? extends Annotation> cacheMethodDetails) {

      Cache<?, ?> cache = getCache(cacheMethodDetails.getCacheName();)
      return new DefaultCacheResolver(cache);
  }

  @Override
  public CacheResolver getExceptionCacheResolver(
         CacheMethodDetails<CacheResult> cacheMethodDetails) {

      final CacheResult cacheResultAnnotation = cacheMethodDetails.getCacheAnnotation();
      Cache<?, ?> cache = getCache(cacheResultAnnotation.exceptionCacheName(););
      return new DefaultCacheResolver(cache);
  }
}

The code is pretty simple, the getCacheResolver and getExceptionCacheResolver methods obtain the cache name from the annotated method information, and then use the CacheManager from our DefaultCacheManagerProvider to lookup that cache. If the cache doesn’t exist, it’s created, and then it’s returned wrapped in a DefaultCacheResolver that will return the Cache when requested.

If we return to our SecretDataBean class and update it’s @CacheDefaults annotation to look like;

@CacheDefaults( cacheName="secrets" , cacheResolverFactory=MyCacheResolverFactory.class)

Then JSR-107 will now use our factory to obtain the cache used. Resulting in a 5 minute expiry time (from creation) for the Secrets in the Store.

To test it out, set a secret with the /secret command, then wait 6 minutes and ask for your secret.

Although we’ve used the cache here as a Secret Store, consider that the cache could be used to manage any sort of information we’d want to share between instances of our Service. You might use it to track Players in your room, or to assign virtual attributes to Players in your room, like health, or score. Or you might use it to track Room Inventory, or Inventory per Player. Or you might use it to manage state of items in your room, eg. If a light bulb in the room is on, or off.