Configure named Infinispan cache regions for Hibernate Second Level cache (2LC) in EAP

Environment

• Red Hat JBoss Enterprise Application Platform (EAP)
  • 7
  • 6
• Hibernate
  • 5
  • 4
• Infinispan
  • 5
  • 8

Issue

• How can eviction max_entries be configured for a named cache region?
• How can the eviction strategy be configured for a named cache region?
• How can expiration max_idle be configured for a named cache region?
• How can expiration lifespan be configured for a named cache region?

Resolution

• A named cache region consists of two components and has the form <prefix>.<suffix>

  • The prefix defaults to <application_archive>#<persistence_unit_name> (e.g. example.war#ps-unit)
    • The prefix may be overridden in each persistence unit by adding the following to the persistence unit's properties
      <property name="hibernate.cache.region_prefix" value="region-seven" />
  • The suffix for each entity cache defaults to the fully qualified entity name (e.g. org.entities.Employee)
    • The suffix may be overridden in each entity by using the Hibernate specific annotation
      @org.hibernate.annotations.Cache(region = "HR-Entities" ...)

• Given the above, configuration may be supplied per region by adding properties to each persistence unit

  
      <!-- If using the default region naming -->
      <properties>
          ...
          <property name="hibernate.cache.infinispan.example.war#ps-unit.org.entities.Employee.eviction.max_entries" value="54321" />
          <property name="hibernate.cache.infinispan.example.war#ps-unit.org.entities.Employee.eviction.strategy" value="LRU" />
          <property name="hibernate.cache.infinispan.example.war#ps-unit.org.entities.Employee.expiration.max_idle" value="654321" />
          <property name="hibernate.cache.infinispan.example.war#ps-unit.org.entities.Employee.expiration.lifespan" value="7654321" />
      </properties>
  
      <!-- If using the prefix 'region-seven' and '@Cache(region = "HR-Entities")' -->
      <properties>
          ...
          <property name="hibernate.cache.region_prefix" value="region-seven" />
          <property name="hibernate.cache.infinispan.region-seven.HR-Entities.eviction.max_entries" value="54321" />
          <property name="hibernate.cache.infinispan.region-seven.HR-Entities.eviction.strategy" value="LRU" />
          <property name="hibernate.cache.infinispan.region-seven.HR-Entities.expiration.max_idle" value="654321" />
          <property name="hibernate.cache.infinispan.region-seven.HR-Entities.expiration.lifespan" value="7654321" />
      </properties>
  

• The default query cache is <prefix>.org.hibernate.cache.internal.StandardQueryCache

  • Configuration can be overridden by the use of a property such as:

    <property name="hibernate.cache.infinispan.region-seven.org.hibernate.cache.internal.StandardQueryCache.eviction.max_entries" value="54321" />
    

  • Similar configuration can be used for a custom region (e.g. referenced by query hint using org.hibernate.cacheRegion) using the property syntax <prefix>.<region-name>

• Default entity and local-query region configuration is found in standalone*.xml or domain.xml in the infinispan subsystem's hibernate cache container

  • Note that only the shipped cache configurations have been tested for compatibility with JBoss EAP

• Referencing a named cache configuration template (defined in the standalone*.xml or domain.xml) is possible using:

          <!-- Configure org.entities.CustomCacheConfig in standalone*.xml or domain.xml -->
  
          <!-- Use @Cache(... region="org.entities.CustomRegion") -->
          <property name="hibernate.cache.infinispan.region-seven.org.entities.CustomRegion.cfg"
              value="org.entities.CustomCacheConfig"/>
  
          <!-- Use default entity region name (when not specified, defaults to <package>.<class>) -->
          <property name="hibernate.cache.infinispan.region-seven.org.entities.Employee.cfg"
              value="org.entities.CustomCacheConfig"/>
  
          <!-- Configure org.entities.CustomQueryCacheConfig in standalone*.xml or domain.xml -->
  
          <!-- Configure default query cache -->
          <property name="hibernate.cache.infinispan.region-seven.org.hibernate.cache.internal.StandardQueryCache.cfg"
              value="org.entities.CustomQueryCacheConfig" />
  
          <!-- Configure named query cache -->
          <property name="hibernate.cache.infinispan.region-seven.org.entities.CustomQueryRegion.cfg"
              value="org.entities.CustomQueryCacheConfig" />
  

• Note that the use of custom Infinispan configuration files to configure cache regions, etc. is not supported

Diagnostic Steps

The Byteman rule below can be used to trace configuration of cache regions

RULE CacheManagerDefineConfig
#INTERFACE ^org.infinispan.manager.EmbeddedCacheManager
CLASS org.jboss.as.clustering.infinispan.DefaultCacheContainer
METHOD defineConfiguration
BIND config:org.infinispan.config.Configuration = $3;
#IF $1.endsWith("Employee")
IF true
DO traceStack("[BMAN] Configuration (" + $1 + ", " + $2 + ", " + $3 + ")\n", 5);
   System.out.println("[BMAN] getEvictionMaxEntries() => " + config.getEvictionMaxEntries());
   System.out.println("[BMAN] getEvictionStrategy() => " + config.getEvictionStrategy());
   System.out.println("[BMAN] getExpirationMaxIdle() => " + config.getExpirationMaxIdle());
   System.out.println("[BMAN] getExpirationLifespan() => " + config.getExpirationLifespan());
ENDRULE

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.