About¶

Fathom-JCache provides your application with seamless caching integration.

Installation¶

Add the Fathom-JCache artifact…

<dependency>
    <groupId>com.gitblit.fathom</groupId>
    <artifactId>fathom-jcache</artifactId>
    <version>${fathom.version}</version>
</dependency>

… and also add your preferred JCache provider:

Provider	Artifact
Hazelcast	com.hazelcast:hazelcast
Infinispan	org.infinispan:infinispan-jcache
Ehcache	org.ehcache:jcache

Layout¶

YourApp
└── src
    └── main
        └── java
            └── conf
                └── Caches.java

Configuration¶

You don’t have to configure your JCache provider to use it. Each provider ships with default settings which allows you to get up-and-running very quickly.

If you need to specify a provider-specific configuration you may do so.

# Ehcache configuration file
# see http://ehcache.org/documentation
# specify 'jcache' to default to the Jcache default configuration
# ehcache.configurationFile = "classpath:conf/ehcache.xml"
ehcache.configurationFile = "jcache"

# Infinispan configuration file
# see http://infinispan.org/docs/7.0.x/user_guide/user_guide.html
# specify 'jcache' to default to the Jcache default configuration
# infinispan.configurationFile = "classpath:conf/infinispan.xml"
infinispan.configurationFile = "jcache"

# Hazelcast configuration file
# see http://hazelcast.org/documentation
# specify 'jcache' to default to the Jcache default configuration
# hazelcast.configurationFile = "classpath:conf/hazelcast.xml"
hazelcast.configurationFile = "jcache"

Multiple Providers on the classpath¶

In the event that you have multiple providers on the classpath at the same time, Fathom will pick the first one loaded by the JVM unless you specify a preference.

# Set the preferred JCache provider.
# If unspecified, the first provider discovered will be used.
# You may specify a full provider classname or you may specify
# a nickname for an already registered JCache implementation
# such as: ehcache, infinispan, hazelcast
jcache.preferredProvider = ""

One scenario where you might have multiple providers is using one for DEV mode and a different one for PROD mode. This would be the caching analog of using an SQL db like SQLite or H2 for development and PostgreSQL for production.

Usage¶

Defining your Caches¶

Create a conf/Caches.java class.

package conf;

public class Caches extends CachesModule {

    public static final String EMPLOYEE_CACHE = "employeeCache";

    @Override
    protected void setup(Settings settings, CacheManager cacheManager) {

        // example employee cache
        cacheManager.createCache(EMPLOYEE_CACHE, new MutableConfiguration()
                .setExpiryPolicyFactory(ModifiedExpiryPolicy.factoryOf(Duration.ONE_MINUTE))
                .setStatisticsEnabled(true)
                .setStoreByValue(true));
    }
}

Using your Caches¶

The most elegant way to use Fathom’s JCache integration is with annotations.

In the following non-functional example we are annotating our employee DAO singleton to specify that all methods in this DAO access the EMPLOYEE_CACHE defined in our conf/Caches.java class.

We are also annotating the get, getAll, delete, and save methods. Calling these methods will transparently manage the cache.

@Singleton
@CacheDefaults(cacheName = Caches.EMPLOYEE_CACHE)
public class EmployeeDao {

    private static final Logger log = LoggerFactory.getLogger(EmployeeDao.class);

    public EmployeeDao() {
    }

    @CacheResult
    public Employee get(int id) {
        log.info("Getting employee #{} by id", id);
        Employee employee = employees.get(id);
        return employee;
    }

    @CacheResult
    public List<Employee> getAll() {
        log.info("Getting all employees");
        return new ArrayList<>(employees.values());
    }

    @CacheRemoveAll
    public Employee delete(int id) {
        Employee employee = employees.get(id);
        employees.remove(id);
        return employee;
    }

    @CacheRemoveAll
    public Employee save(Employee employee) {
        return put(employee);
    }
  }

Viewing and Managing your Caches¶

Fathom does not provide a mechansim to view & manage your caches, however, several JCache providers register MBeans which allow cache viewing and management via JConsole or VisualVM.