1.11.4. eXo Cache based on JBoss Cache

Configuring the ExoCacheFactory

You can override the default configuration of ExoCacheFactory like any other component.

The default configuration of ExoCacheFactory is:


<configuration>  
  <component>
    <key>org.exoplatform.services.cache.ExoCacheFactory</key>
    <type>org.exoplatform.services.cache.impl.jboss.ExoCacheFactoryImpl</type>
    <init-params>
      <value-param>
        <name>cache.config.template</name>
        <value>jar:/conf/portal/cache-configuration-template.xml</value>
      </value-param>
      <value-param>
        <name>allow.shareable.cache</name>
        <value>true</value>
      </value-param>
    </init-params>
  </component>   
</configuration>

cache.config.templateThe location of the default configuration template of JBoss Cache. By default the template is shipped in the jar at /conf/portal/cache-configuration-template.xml. The default template aims to be the skeleton from which we create any type of JBoss cache instance, thus it must be very generic.
allow.shareable.cacheIndicates whether your JBoss Cache instance can by default be shared between several eXo Caches instances. Indeed to consume less resources, you can share your JBoss Cache instance to be used by several eXo Cache instances, each of them have its own cache region with its own eviction configuration. The default value of this parameter is false.

Note

This parameter and the field allowShareableCache in ExoCacheConfig configuration are the same in purpose, so take care that this parameter can be overriden.


Adding specific configuration for a cache

If you need to use your own cache configuration, you can register an "external plugin", see an example below:


<configuration>
  ...
  <external-component-plugins>
    <target-component>org.exoplatform.services.cache.ExoCacheFactory</target-component>
    <component-plugin>
      <name>addConfig</name>
      <set-method>addConfig</set-method>
      <type>org.exoplatform.services.cache.impl.jboss.ExoCacheFactoryConfigPlugin</type>
      <description>add Custom Configurations</description>
      <init-params>
        <value-param>
          <name>myCustomCache</name>
          <value>jar:/conf/portal/custom-cache-configuration.xml</value>
        </value-param>         
      </init-params>
    </component-plugin>    
  </external-component-plugins> 
  ...   
</configuration>

In this example, the method addConfig(ExoCacheFactoryConfigPlugin plugin) is called on the current implementation of ExoCacheFactory which is actually the JBoss Cache implementation.

In the init-params block, you can define a set of value-param blocks and for each value-param, you provide your cache name in name tag and path of your custom configuration file in value tag.

In the example, the cache name is myCustomCache and configuration file is jar:/conf/portal/custom-cache-configuration.xml.

Adding a cache creator

Understanding a cache creator

ExoCacheFactory delegates the cache creation to ExoCacheCreator that is defined as below:

package org.exoplatform.services.cache.impl.jboss;

        ...
        public interface ExoCacheCreator {
        /**
        * Creates an eXo cache according to the given configuration {@link
        org.exoplatform.services.cache.ExoCacheConfig}
        * @param config the configuration of the cache to apply
        * @param cache the cache to initialize
        * @exception ExoCacheInitException if an exception happens while initializing the cache
        */
        public ExoCache create(ExoCacheConfig config, Cache<Serializable, Object> cache) throws
        ExoCacheInitException;
        /**
        * Returns the type of {@link org.exoplatform.services.cache.ExoCacheConfig} expected by the creator
        * @return the expected type
        */
        public Class<? extends ExoCacheConfig> getExpectedConfigType();
        /**
        * Returns the name of the implementation expected by the creator. This is mainly used to be backward compatible
        * @return the expected by the creator
        */
        public String getExpectedImplementation();
        }
      

The ExoCacheCreator allows you to define any kind of JBoss Cache instance that you would like to have. It has been designed to give you the ability to have your own type of configuration and to always be backward compatible.

To implement ExoCacheCreator, you need to implement 3 methods which are:

  • create: this method is used to create a new ExoCache from the ExoCacheConfig and a JBoss Cache instance.

  • getExpectedConfigType: this method gets the subtype of ExoCacheConfig. It is required that the subtype is supported by the creator.

  • getExpectedImplementation: this method gets the implementation of ExoCacheConfig that is supported by the creator. This is used for backward compatibility, in other words, you can still configure your cache with a super class ExoCacheConfig.

Registering a cache creator

You can register any cache creator that you want thanks to an "external plugin", see an example below:


<external-component-plugins>
    <target-component>org.exoplatform.services.cache.ExoCacheFactory</target-component>
    <component-plugin>
        <name>addCreator</name>
        <set-method>addCreator</set-method>
        <type>org.exoplatform.services.cache.impl.jboss.ExoCacheCreatorPlugin</type>
        <description>add Exo Cache Creator</description>
        <init-params>
            <object-param>
                <name>LRU</name>
                <description>The lru cache creator</description>
                <object type="org.exoplatform.services.cache.impl.jboss.lru.LRUExoCacheCreator">
                    <field name="defaultTimeToLive"><long>1500</long></field>
                    <field name="defaultMaxAge"><long>2000</long></field>
                </object>
            </object-param>
        </init-params>
    </component-plugin>
</external-component-plugins>

In this example, the method addCreator(ExoCacheCreatorPlugin plugin) is called on the current implementation of ExoCacheFactory which is actually the JBoss Cache implementation.

In the init-params block, you can define a set of object-param blocks and for each object-param, we expect any object definition of typeExoCacheCreator. It is org.exoplatform.services.cache.impl.jboss.lru.LRUExoCacheCreator in the example.

The availabe cache creators

By default, no cache creator are defined, so you need to add them in your configuration files. The following is available cache creators:

  • LRU Cache Creator - Least Recently Used

    
    ...
                <object-param>
                <name>LRU</name>
                <description>The lru cache creator</description>
                <object type="org.exoplatform.services.cache.impl.jboss.lru.LRUExoCacheCreator">
                <field name="defaultTimeToLive"><long>${my-value}</long></field>
                <field name="defaultMaxAge"><long>${my-value}</long></field>
                </object>
                </object-param>
                ...
              

    defaultTimeToLiveThis is the default value of the field timeToLive described in the section dedicated to this cache type. This value is only used when we define a cache of this type with the old configuration.
    defaultMaxAgeThis is the default value of the field maxAge described in the section dedicated to this cache type. This value is only used when we define a cache of this type with the old configuration.

  • FIFO Cache Creator - First In, First Out

    
    ...
                <object-param>
                <name>FIFO</name>
                <description>The fifo cache creator</description>
                <object type="org.exoplatform.services.cache.impl.jboss.fifo.FIFOExoCacheCreator"></object>
                </object-param>
                ...
              
  • MRU Cache Creator - Most Recently Used

    
    ...
                <object-param>
                <name>MRU</name>
                <description>The mru cache creator</description>
                <object type="org.exoplatform.services.cache.impl.jboss.mru.MRUExoCacheCreator"></object>
                </object-param>
                ...
              
  • LFU Cache Creator - Least Frequently Used

    
    ...
                <object-param>
                <name>LFU</name>
                <description>The lfu cache creator</description>
                <object type="org.exoplatform.services.cache.impl.jboss.lfu.LFUExoCacheCreator">
                <field name="defaultMinNodes"><int>${my-value}</int></field>
                </object>
                </object-param>
                ...
              

    defaultMinNodesThis is the default value of the field minNodes described in the section dedicated to this cache type. This value is only used when we define a cache of this type with the old configuration.

  • EA Cache Creator - Expiration Algorithm

    
    ...
                <object-param>
                <name>EA</name>
                <description>The ea cache creator</description>
                <object type="org.exoplatform.services.cache.impl.jboss.ea.EAExoCacheCreator">
                <field name="defaultExpirationTimeout"><long>2000</long></field>
                </object>
                </object-param>
                ...
              

    defaultExpirationTimeoutThis is the default value of the field ExpirationTimeout described in the section dedicated to this cache type. This value is only used when we define a cache of this type with the old configuration.

Copyright ©. All rights reserved. eXo Platform SAS
blog comments powered byDisqus