You are looking at documentation for an older release. Not what you want? See the current release documentation.
When you add the related jar file in your classpath, the eXo service container will use the default configuration provided in the library itself but of course you can still redefine the configuration if you wish as you can do with any components.
The default configuration of the factory is:
<configuration>
<component>
<key>org.exoplatform.services.cache.ExoCacheFactory</key>
<type>org.exoplatform.services.cache.impl.infinispan.ExoCacheFactoryImpl</type>
<init-params>
<value-param>
<name>cache.config.template</name>
<value>${exo.cache.config.template:jar:/conf/platform/cache/infinispan/local/cache-config.xml}</value>
</value-param>
<value-param profiles="cluster">
<name>cache.config.template</name>
<value>${exo.cache.config.template:jar:/conf/platform/cache/infinispan/cluster/cache-config.xml}</value>
</value-param>
<value-param profiles="cluster">
<name>cache.async.config.template</name>
<value>${exo.cache.async.config.template:jar:/conf/platform/cache/infinispan/cluster/cache-async-config.xml}</value>
</value-param>
</init-params>
</component>
</configuration>
As you can see the factory requires one single parameter which is cache.config.template, this parameter allows you to define
the location of the default configuration template of your infinispan. In the default configuration, we ask the eXo container to get the file shipped
into the jar at /conf/portal/cache-configuration-template.xml.
The default configuration template aims to be the skeleton from which we will create any type of infinispan cache instance, thus it must be very generic.
All the cache instances for which we configure the same cluster name will also share the same EmbeddedCacheManager.
If for a given reason, you need to use a specific configuration for a cache, you can register one thanks to 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.infinispan.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 the example above, I call the method addConfig(ExoCacheFactoryConfigPlugin plugin) on the current implementation of
ExoCacheFactory which is actually the infinispan implementation.
In the init-params block, you can define a set of value-param blocks and for each value-param, we expect the name of cache that needs a specific configuration as name and the location of your custom configuration as value.
In this example, we indicated to the factory that we would like that the cache myCustomCache use the configuration available at
jar:/conf/portal/custom-cache-configuration.xml.
All the cache instances that will rely on the cache configuration located at the same location will share the same EmbeddedCacheManager.
Understanding a cache creator
The factory for infinispan, delegates the cache creation to ExoCacheCreator that is defined as below:
package org.exoplatform.services.cache.impl.infinispan;
...
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 confBuilder the configuration builder of the infinispan cache
* @param cacheGetter a {@link Callable} instance from which we can get the cache
* @exception ExoCacheInitException if an exception happens while initializing the cache
*/
public ExoCache<Serializable, Object> create(ExoCacheConfig config, ConfigurationBuilder confBuilder,
Callable<Cache<Serializable, Object>> cacheGetter) 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 a set of all the implementations expected by the creator. This is mainly used to be backward compatible
* @return the expected by the creator
*/
public Set<String> getExpectedImplementations();
}
The ExoCacheCreator allows you to define any kind of infinispan 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.
In an ExoCacheCreator, you need to implement 3 methods which are:
create: this method is used to create a new ExoCache from the ExoCacheConfig,
an inifinispan cache configuration and a Callable object to allow you to get the cache instance.
>getExpectedConfigType: this method is used to indicate the factory the subtype of
ExoCacheConfig supported by the creator.
>getExpectedImplementations: this method is used to indicate the factory the values of the field
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 an instance of ExoCacheConfig.
Register a cache creator
You can register any cache creator 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.infinispan.ExoCacheCreatorPlugin</type>
<description>add Exo Cache Creator</description>
<init-params>
<object-param>
<name>Test</name>
<description>The cache creator for testing purpose</description>
<object type="org.exoplatform.services.cache.impl.infinispan.TestExoCacheCreator"></object>
</object-param>
</init-params>
</component-plugin>
</external-component-plugins>
In the example above, I call the method addCreator(ExoCacheCreatorPlugin plugin) on the current implementation of
ExoCacheFactory which is actually the infinispan 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 type ExoCacheCreator.
In this example, we register the cache creator related to the eviction policy Test.
The cache creators available
By default, no cache creator are defined, so you need to define them yourself by adding them in your configuration files.
Generic Cache Creator
This is the generic cache creator that allows you to use any eviction strategies defined by default in Infinispan.
..
<object-param>
<name>GENERIC</name>
<description>The generic cache creator</description>
<object type="org.exoplatform.services.cache.impl.infinispan.generic.GenericExoCacheCreator">
<field name="implementations">
<collection type="java.util.HashSet">
<value>
<string>NONE</string>
</value>
<value>
<string>LRU</string>
</value>
<value>
<string>UNORDERED</string>
</value>
<value>
<string>MANUAL</string>
</value>
<value>
<string>LIRS</string>
</value>
</collection>
</field>
<field name="defaultStrategy"><string>${my-value}</string></field>
<field name="defaultMaxIdle"><long>${my-value}</long></field>
<field name="defaultWakeUpInterval"><long>${my-value}</long></field>
</object>
</object-param>
...
| implementations | This is the list of all the implementations supported by the cache creator. Actualy, it is a subset of the full list of the eviction strategies supported by infinispan to which you want to give access to. In the configuraton above, you have the full list of all the eviction strategies currently supported by infinispan 8.2. This field is used to manage the backward compatibility. |
| defaultStrategy | This is the name of the default eviction strategy to use. By default the value is LRU. This value is only used when we define a cache of this type with the old configuration. |
| defaultMaxIdle | This is the default value of the field maxIdle described in the section dedicated to this cache type. By default the value is -1.This value is only used when we define a cache of this type with the old configuration. |
| defaultWakeUpInterval | This is the default value of the field wakeUpInterval described in the section dedicated to this cache type. By default the value is 5000. This value is only used when we define a cache of this type with the old configuration. |
How to define an infinispan cache instance?
All the eviction strategies proposed by default in infinispan rely on the generic cache creator.
...
<object-param>
<name>myCache</name>
<description>myCache configuration</description>
<object type="org.exoplatform.services.cache.impl.infinispan.generic.GenericExoCacheConfig">
<field name="name"><string>myCacheName</string></field>
<field name="strategy"><int>${my-value}</int></field>
<field name="maxEntries"><long>${my-value}</long></field>
<field name="lifespan"><long>${my-value}</long></field>
<field name="maxIdle"><long>${my-value}</long></field>
<field name="wakeUpInterval"><long>${my-value}</long></field>
<field name="cacheMode"><string>${my-value}</string></field>
</object>
</object-param>
...
| strategy | The name of the strategy to use such as LIRS, LRU, UNORDERED, MANUAL and NONE(to disable eviction, it is the default value).
You can find below more details about each strategy mode. |
| maxEntries | Maximum number of entries in a cache instance. If selected value is not a power of two the actual value will default to the least power of two larger than selected value. -1 means no limit which is also the default value. |
| lifespan | Maximum lifespan of a cache entry, after which the entry is expired cluster-wide, in milliseconds. -1 means the entries never expire which is also the default value. |
| cacheMode | It is the cache topology which could take these values: local: Data is not replicated and it is the default value, replication: Data is replicated synchronously, asyncReplication: Data is replicated asynchronously, syncInvalidation: Data is invalidated synchronously and asyncInvalidation: Data invalidated asynchronously. |
| maxIdle | Maximum idle time a cache entry will be maintained in the cache, in milliseconds. If the idle time is exceeded, the entry will be expired cluster-wide. -1 means the entries never expire which is also the default value. |
| wakeUpInterval | nterval between subsequent eviction runs, in milliseconds. If you wish to disable the periodic eviction process altogether, set wakeupInterval to -1. The default value is 5000. |
For the fields maxIdle and wakeUpInterval needed by infinispan, we will use the default values provided by the creator.
NONE: This eviction strategy disables the eviction thread. It is the default configuration.
LRU: If LRU eviction strategy is used, cache entries are selected for eviction using a well known least-recently-used pattern.
UNORDERED: UNORDERED eviction strategy is a legacy eviction strategy that has been deprecated. If UNORDERED strategy is specified LRU eviction algorithm will be used.
MANUAL: This eviction strategy is identical to NONE, in that it disables automatic eviction altogether, but signals the intention that the user wants to evict entries manually. The effect is to disable misleading warning validation messages.
LIRS: This eviction strategy relies on history information of cache entries accesses using so called Inter-Reference Recency (a.k.a IRR) and the Recency.