7:26 a.m.
Author: nfilotto
Date: 2010-08-13 08:26:42 -0400 (Fri, 13 Aug 2010)
New Revision: 2916
Modified:
jcr/branches/1.14-ISPN/docs/reference/en/src/main/docbook/en-US/modules/kernel/cache.xml
Log:
EXOJCR-802: The doc
Modified:
jcr/branches/1.14-ISPN/docs/reference/en/src/main/docbook/en-US/modules/kernel/cache.xml
===================================================================
---
jcr/branches/1.14-ISPN/docs/reference/en/src/main/docbook/en-US/modules/kernel/cache.xml 2010-08-13
12:25:27 UTC (rev 2915)
+++
jcr/branches/1.14-ISPN/docs/reference/en/src/main/docbook/en-US/modules/kernel/cache.xml 2010-08-13
12:26:42 UTC (rev 2916)
@@ -1,1089 +1,1538 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter>
- <?dbhtml filename="ch-cache.html"?>
- <title>eXo Cache</title>
-
- <section>
- <title>Basic concepts</title>
-
- <para>All applications on the top of eXo JCR that need a cache, can rely
- on an <envar>org.exoplatform.services.cache.ExoCache</envar> instance
that
- is managed by the
- <envar>org.exoplatform.services.cache.CacheService</envar>. The main
- implementation of this service is
- <envar>org.exoplatform.services.cache.impl.CacheServiceImpl</envar>
which
- depends on the
- <envar>org.exoplatform.services.cache.ExoCacheConfig</envar> in order to
- create new <envar>ExoCache</envar> instances. See below an example of
- <envar>org.exoplatform.services.cache.CacheService</envar>
- definition:<programlisting> <component>
- <key>org.exoplatform.services.cache.CacheService</key>
- <jmx-name>cache:type=CacheService</jmx-name>
-
<type>org.exoplatform.services.cache.impl.CacheServiceImpl</type>
- <init-params>
- <object-param>
- <name>cache.config.default</name>
- <description>The default cache
configuration</description>
- <object
type="org.exoplatform.services.cache.ExoCacheConfig">
- <field
name="name"><string>default</string></field>
- <field
name="maxSize"><int>300</int></field>
- <field
name="liveTime"><long>600</long></field>
- <field
name="distributed"><boolean>false</boolean></field>
- <field
name="implementation"><string>org.exoplatform.services.cache.concurrent.ConcurrentFIFOExoCache</string></field>
- </object>
- </object-param>
- </init-params>
- </component></programlisting></para>
-
- <para><note>
- <para>The <envar>ExoCacheConfig</envar> which name is
- <envar>default</envar>, will be the default configuration of all the
- <envar>ExoCache</envar> instances that don't have dedicated
- configuration.</para>
- </note>See below an example of how to define a new
- <envar>ExoCacheConfig</envar> thanks to a
- <emphasis>external-component-plugin</emphasis>:<programlisting>
<external-component-plugins>
-
<target-component>org.exoplatform.services.cache.CacheService</target-component>
- <component-plugin>
- <name>addExoCacheConfig</name>
- <set-method>addExoCacheConfig</set-method>
-
<type>org.exoplatform.services.cache.ExoCacheConfigPlugin</type>
- <description>Configures the cache for query
service</description>
- <init-params>
- <object-param>
- <name>cache.config.wcm.composer</name>
- <description>The default cache
configuration</description>
- <object
type="org.exoplatform.services.cache.ExoCacheConfig">
- <field
name="name"><string>wcm.composer</string></field>
- <field
name="maxSize"><int>300</int></field>
- <field
name="liveTime"><long>600</long></field>
- <field
name="distributed"><boolean>false</boolean></field>
- <field
name="implementation"><string>org.exoplatform.services.cache.concurrent.ConcurrentFIFOExoCache</string></field>
- </object>
- </object-param>
- </init-params>
- </component-plugin>
- </external-component-plugins></programlisting></para>
-
- <table>
- <title>Descriptions of the fields of
- <envar>ExoCacheConfig</envar></title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>name</entry>
-
- <entry>The name of the cache. This field is mandatory since it
- will be used to retrieve the <envar>ExoCacheConfig</envar>
- corresponding to a given cache name.</entry>
- </row>
-
- <row>
- <entry>label</entry>
-
- <entry>The label of the cache. This field is optional. It is
- mainly used to indicate the purpose of the cache.</entry>
- </row>
-
- <row>
- <entry>maxSize</entry>
-
- <entry>The maximum numbers of elements in cache. This field is
- mandatory.</entry>
- </row>
-
- <row>
- <entry>liveTime</entry>
-
- <entry>The amount of time (in seconds) an element is not written
- or read before it is evicted. This field is mandatory.</entry>
- </row>
-
- <row>
- <entry>implementation</entry>
-
- <entry>The full qualified name of the cache implementation to use.
- This field is optional. This field is only used for simple cache
- implementation. The default and main implementation is
-
<envar>org.exoplatform.services.cache.concurrent.ConcurrentFIFOExoCache</envar>,
- this implementation only works with local caches with FIFO as
- eviction policy. For more complex implementation see the next
- sections.</entry>
- </row>
-
- <row>
- <entry>distributed</entry>
-
- <entry>Indicates if the cache is distributed. This field is
- optional. This field is used for backward compatibility.</entry>
- </row>
-
- <row>
- <entry>replicated</entry>
-
- <entry>Indicates if the cache is replicated. This field is
- optional. This field is deprecated.</entry>
- </row>
-
- <row>
- <entry>logEnabled</entry>
-
- <entry>Indicates if the log is enabled. This field is optional.
- This field is used for backward compatibility.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para></para>
- </section>
-
- <section>
- <title>eXo Cache extension</title>
-
- <para>In the previous versions of eXo kernel, it was quite complex to
- implement your own ExoCache because it was not open enough. Since kernel
- 2.0.8, it is possible to easily integrate your favorite cache provider in
- eXo Products.</para>
-
- <para>You just need to implement your own
<envar>ExoCacheFactory</envar>
- and register it in an eXo container, as described below:<programlisting>package
org.exoplatform.services.cache;
-...
-public interface ExoCacheFactory {
-
- /**
- * Creates a new instance of {@link org.exoplatform.services.cache.ExoCache}
- * @param config the cache to create
- * @return the new instance of {@link org.exoplatform.services.cache.ExoCache}
- * @exception ExoCacheInitException if an exception happens while initializing the
cache
- */
- public ExoCache createCache(ExoCacheConfig config) throws ExoCacheInitException;
-}</programlisting></para>
-
- <para>As you can see, there is only one method to implement which cans be
- seen as a converter of an <envar>ExoCacheConfig</envar> to get an
instance
- of <envar>ExoCache</envar>. Once, you created your own implementation
you
- can simply register your factory by adding a file
- <emphasis>conf/portal/configuration.xml</emphasis> with a content of the
- following type:<programlisting><configuration>
- <component>
-
<key>org.exoplatform.services.cache.ExoCacheFactory</key>
-
<type>org.exoplatform.tutorial.MyExoCacheFactoryImpl</type>
- ...
- </component>
-</configuration></programlisting></para>
- </section>
-
- <section>
- <title>eXo Cache based on JBoss Cache</title>
-
- <section>
- <title>Configure the ExoCacheFactory</title>
-
- <para>When you add, the eXo library in your classpath, the eXo service
- container will use the default configuration provided in the library
- itself but of course you can still redefined the configuration if you
- wish as you can do with any components.</para>
-
- <para>The default configuration of the factory
is:<programlisting><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>
- </init-params>
- </component>
-</configuration></programlisting></para>
-
- <para>As you can see the factory requires one single parameter which is
- <emphasis>cache.config.template</emphasis>, this parameter allows you
to
- define the location of the default configuration template of your jboss
- cache. In the default configuration, we ask the eXo container to get the
- file shipped into the jar at
-
<emphasis>/conf/portal/cache-configuration-template.xml</emphasis>.</para>
-
- <para>The default configuration template aims to be the skeleton from
- which we will create any type of jboss cache instance, thus it must be
- very generic.<note>
- <para>The default configuration template provided with the jar aims
- to work with any application servers, but if you intend to use JBoss
- AS, you should redefine it in your custom configuration to fit
- better with your AS.</para>
- </note></para>
- </section>
-
- <section>
- <title>Add specific configuration for a cache</title>
-
- <para>If for a given reason, you need to use a specific configuration
- for a cache, you can register one thanks to an "<emphasis>external
- plugin</emphasis>", see an example
below:<programlisting><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></programlisting></para>
-
- <para>In the example above, I call the method
- <emphasis>addConfig(ExoCacheFactoryConfigPlugin plugin)</emphasis> on
- the current implementation of <envar>ExoCacheFactory</envar> which is
- actually the jboss cache implementation.</para>
-
- <para>In the <emphasis>init-params</emphasis> block, you can
define a
- set of <emphasis>value-param</emphasis> blocks and for each
- <emphasis>value-param</emphasis>, we expect the name of cache that
needs
- a specific configuration as name and the location of your custom
- configuration as <emphasis>value</emphasis>.</para>
-
- <para>In this example, we indicates to the factory that we would like
- that the cache <emphasis>myCustomCache</emphasis> use the
configuration
- available at
-
<emphasis>jar:/conf/portal/custom-cache-configuration.xml</emphasis>.</para>
- </section>
-
- <section>
- <title>Add a cache creator</title>
-
- <section>
- <title>Understanding a cache creator</title>
-
- <para>The factory for jboss cache, delegates the cache creation to
- <envar>ExoCacheCreator</envar> that is defines as
- below:<programlisting>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();
-}</programlisting></para>
-
- <para>The <envar>ExoCacheCreator</envar> 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.</para>
-
- <para>In an <envar>ExoCacheCreator</envar>, you need to
implement 3
- methods which are:</para>
-
- <itemizedlist>
- <listitem>
- <para><emphasis>create</emphasis> - this method is used to
create
- a new <envar>ExoCache</envar> from the
- <envar>ExoCacheConfig</envar> and a jboss cache
instance.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>getExpectedConfigType</emphasis> - this
method is
- used to indicate the factory the subtype of
- <envar>ExoCacheConfig</envar> supported by the
creator.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>getExpectedImplementation</emphasis> - this
method
- is used to indicate the factory the value of field implementation
- of <envar>ExoCacheConfig</envar> 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
- <envar>ExoCacheConfig</envar>.</para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Register a cache creator</title>
-
- <para>You can register any cache creator you want thanks to an
- <emphasis>"external plugin"</emphasis>, see an example
- below:<programlisting> <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></programlisting></para>
-
- <para>In the example above, I call the method
- <emphasis>addCreator(ExoCacheCreatorPlugin plugin)</emphasis> on the
- current implementation of <envar>ExoCacheFactory</envar> which is
- actually the jboss cache implementation.</para>
-
- <para>In the <emphasis>init-params</emphasis> block, you can
define a
- set of <emphasis>object-param</emphasis> blocks and for each
- <emphasis>object-param</emphasis>, we expect any object definition
of
- type <envar>ExoCacheCreator</envar>.</para>
-
- <para>In this example, we register the action creator related to the
- eviction policy <emphasis>LRU</emphasis>.</para>
- </section>
-
- <section>
- <title>The cache creators available</title>
-
- <para>By default, no cache creator are defined, so you need to define
- them yourself by adding them in your configuration files.</para>
-
- <section>
- <title>LRU Cache Creator - Least Recently Used</title>
-
- <programlisting>..
-<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>
-...</programlisting>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>defaultTimeToLive</entry>
-
- <entry>This is the default value of the field
- <emphasis>timeToLive</emphasis> described in the section
- dedicated to this cache type. This value is only use when we
- define a cache of this type with the old
- configuration.</entry>
- </row>
-
- <row>
- <entry>defaultMaxAge</entry>
-
- <entry>his is the default value of the field
- <emphasis>maxAge</emphasis> described in the section
- dedicated to this cache type. This value is only use when we
- define a cache of this type with the old
- configuration.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section>
- <title>FIFO Cache Creator - First In, First Out</title>
-
- <programlisting>...
-<object-param>
- <name>FIFO</name>
- <description>The fifo cache creator</description>
- <object
type="org.exoplatform.services.cache.impl.jboss.fifo.FIFOExoCacheCreator"></object>
-</object-param>
-...</programlisting>
- </section>
-
- <section>
- <title>MRU Cache Creator - Most Recently Used</title>
-
- <programlisting>...
-<object-param>
- <name>MRU</name>
- <description>The mru cache creator</description>
- <object
type="org.exoplatform.services.cache.impl.jboss.mru.MRUExoCacheCreator"></object>
-</object-param>
-...</programlisting>
- </section>
-
- <section>
- <title>LFU Cache Creator - Least Frequently Used</title>
-
- <programlisting>...
-<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>
-...</programlisting>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>defaultMinNodes</entry>
-
- <entry>This is the default value of the field
- <emphasis>minNodes</emphasis> described in the section
- dedicated to this cache type. This value is only use when we
- define a cache of this type with the old
- configuration.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section>
- <title>EA Cache Creator - Expiration Algorithm</title>
-
- <programlisting>...
-<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>
-...</programlisting>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>defaultExpirationTimeout</entry>
-
- <entry>This is the default value of the field
- <emphasis>minNodes</emphasis> described in the section
- dedicated to this cache type. This value is only use when we
- define a cache of this type with the old
- configuration.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- </section>
- </section>
-
- <section>
- <title>Define a cache</title>
-
- <section>
- <title>How to define a cache?</title>
-
- <para>You have 2 ways to define a cache which are:</para>
-
- <itemizedlist>
- <listitem>
- <para>At <envar>CacheService</envar>
initialization</para>
- </listitem>
-
- <listitem>
- <para>With an <emphasis>"external
plugin"</emphasis></para>
- </listitem>
- </itemizedlist>
-
- <section>
- <title>At <envar>CacheService</envar>
initialization</title>
-
- <programlisting>...
- <component>
- <key>org.exoplatform.services.cache.CacheService</key>
-
<type>org.exoplatform.services.cache.impl.CacheServiceImpl</type>
- <init-params>
- ...
- <object-param>
- <name>fifocache</name>
- <description>The default cache
configuration</description>
- <object
type="org.exoplatform.services.cache.ExoCacheConfig">
- <field
name="name"><string>fifocache</string></field>
- <field
name="maxSize"><int>${my-value}</int></field>
- <field
name="liveTime"><long>${my-value}</long></field>
- <field
name="distributed"><boolean>false</boolean></field>
- <field
name="implementation"><string>org.exoplatform.services.cache.FIFOExoCache</string></field>
- </object>
- </object-param>
- ...
- </init-params>
- </component>
-...</programlisting>
-
- <para>In this example, we define a new cache called
- <emphasis>fifocache</emphasis>.</para>
- </section>
-
- <section>
- <title>With an <emphasis>"external
plugin"</emphasis></title>
-
- <programlisting>...
- <external-component-plugins>
-
<target-component>org.exoplatform.services.cache.CacheService</target-component>
- <component-plugin>
- <name>addExoCacheConfig</name>
- <set-method>addExoCacheConfig</set-method>
-
<type>org.exoplatform.services.cache.ExoCacheConfigPlugin</type>
- <description>add ExoCache configuration component plugin
</description>
- <init-params>
- ...
- <object-param>
- <name>fifoCache</name>
- <description>The fifo cache
configuration</description>
- <object
type="org.exoplatform.services.cache.ExoCacheConfig">
- <field
name="name"><string>fifocache</string></field>
- <field
name="maxSize"><int>${my-value}</int></field>
- <field
name="liveTime"><long>${my-value}</long></field>
- <field
name="distributed"><boolean>false</boolean></field>
- <field
name="implementation"><string>org.exoplatform.services.cache.FIFOExoCache</string></field>
- </object>
- </object-param>
-...
- </init-params>
- </component-plugin>
- </external-component-plugins>
-...</programlisting>
-
- <para>In this example, we define a new cache called
- <emphasis>fifocache</emphasis> which is in fact the same cache as
in
- previous example but defined in a different manner.</para>
- </section>
- </section>
-
- <section>
- <title>How to define a distributed or a local cache?</title>
-
- <para>Actually, if you use a custom configuration for your cache as
- described in a previous section, we will use the cache mode define in
- your configuration file.</para>
-
- <para>In case, you decide to use the default configuration template,
- we use the field <emphasis>distributed</emphasis> of your
- <envar>ExoCacheConfig</envar> to decide. In other words, if the
value
- of this field is false (the default value), the cache will be a local
- cache otherwise it will be the cache mode defined in your default
- configuration template that should be distributed.</para>
- </section>
-
- <section>
- <title>LRU Cache - Least Recently Used</title>
-
- <itemizedlist>
- <listitem>
- <para>New configuration</para>
-
- <para><programlisting>...
- <object-param>
- <name>lru</name>
- <description>The lru cache
configuration</description>
- <object
type="org.exoplatform.services.cache.impl.jboss.lru.LRUExoCacheConfig">
- <field
name="name"><string>lru</string></field>
- <field
name="maxNodes"><int>${my-value}</int></field>
- <field
name="minTimeToLive"><long>${my-value}</long></field>
- <field
name="maxAge"><long>${my-value}</long></field>
- <field
name="timeToLive"><long>${my-value}</long></field>
- </object>
- </object-param>
-...</programlisting><table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>maxNodes</entry>
-
- <entry>This is the maximum number of nodes allowed in
- this region. 0 denotes immediate expiry, -1 denotes no
- limit.</entry>
- </row>
-
- <row>
- <entry>minTimeToLive</entry>
-
- <entry>The minimum amount of time (in milliseconds) a
- node must be allowed to live after being accessed before
- it is allowed to be considered for eviction. 0 denotes
- that this feature is disabled, which is the default
- value.</entry>
- </row>
-
- <row>
- <entry>maxAge</entry>
-
- <entry>Lifespan of a node (in milliseconds) regardless
- of idle time before the node is swept away. 0 denotes
- immediate expiry, -1 denotes no limit.</entry>
- </row>
-
- <row>
- <entry>timeToLive</entry>
-
- <entry>The amount of time a node is not written to or
- read (in milliseconds) before the node is swept away. 0
- denotes immediate expiry, -1 denotes no limit.</entry>
- </row>
- </tbody>
- </tgroup>
- </table></para>
- </listitem>
-
- <listitem>
- <para>Old configuration</para>
-
- <programlisting>...
- <object-param>
- <name>lru-with-old-config</name>
- <description>The lru cache
configuration</description>
- <object
type="org.exoplatform.services.cache.ExoCacheConfig">
- <field
name="name"><string>lru-with-old-config</string></field>
- <field
name="maxSize"><int>${my-value}</int></field>
- <field
name="liveTime"><long>${my-value}</long></field>
- <field
name="implementation"><string>LRU</string></field>
- </object>
- </object-param>
-...</programlisting>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>maxSize</entry>
-
- <entry>This is the maximum number of nodes allowed in this
- region. 0 denotes immediate expiry, -1 denotes no
- limit.</entry>
- </row>
-
- <row>
- <entry>liveTime</entry>
-
- <entry>The minimum amount of time (in seconds) a node must
- be allowed to live after being accessed before it is
- allowed to be considered for eviction. 0 denotes that this
- feature is disabled, which is the default value.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para><note>
- <para>For the fields <emphasis>maxAge</emphasis> and
- <emphasis>timeToLive</emphasis> needed by JBoss cache, we
will
- use the default values provided by the creator.</para>
- </note></para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>FIFO Cache - First In, First Out</title>
-
- <itemizedlist>
- <listitem>
- <para>New configuration<programlisting>...
- <object-param>
- <name>fifo</name>
- <description>The fifo cache
configuration</description>
- <object
type="org.exoplatform.services.cache.impl.jboss.fifo.FIFOExoCacheConfig">
- <field
name="name"><string>fifo</string></field>
- <field
name="maxNodes"><int>${my-value}</int></field>
- <field
name="minTimeToLive"><long>${my-value}</long></field>
- </object>
- </object-param>
-...</programlisting></para>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>maxNodes</entry>
-
- <entry>This is the maximum number of nodes allowed in this
- region. 0 denotes immediate expiry, -1 denotes no
- limit.</entry>
- </row>
-
- <row>
- <entry>minTimeToLive</entry>
-
- <entry>The minimum amount of time (in milliseconds) a node
- must be allowed to live after being accessed before it is
- allowed to be considered for eviction. 0 denotes that this
- feature is disabled, which is the default value.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </listitem>
-
- <listitem>
- <para>Old configuration<programlisting>...
- <object-param>
- <name>fifo-with-old-config</name>
- <description>The fifo cache
configuration</description>
- <object
type="org.exoplatform.services.cache.ExoCacheConfig">
- <field
name="name"><string>fifo-with-old-config</string></field>
- <field
name="maxSize"><int>${my-value}</int></field>
- <field
name="liveTime"><long>${my-value}</long></field>
- <field
name="implementation"><string>FIFO</string></field>
- </object>
- </object-param>
-...</programlisting></para>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>maxSize</entry>
-
- <entry>This is the maximum number of nodes allowed in this
- region. 0 denotes immediate expiry, -1 denotes no
- limit.</entry>
- </row>
-
- <row>
- <entry>liveTime</entry>
-
- <entry>The minimum amount of time (in seconds) a node must
- be allowed to live after being accessed before it is
- allowed to be considered for eviction. 0 denotes that this
- feature is disabled, which is the default value.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>MRU Cache - Most Recently Used</title>
-
- <itemizedlist>
- <listitem>
- <para>New configuration<programlisting>...
- <object-param>
- <name>mru</name>
- <description>The mru cache
configuration</description>
- <object
type="org.exoplatform.services.cache.impl.jboss.mru.MRUExoCacheConfig">
- <field
name="name"><string>mru</string></field>
- <field
name="maxNodes"><int>${my-value}</int></field>
- <field
name="minTimeToLive"><long>${my-value}</long></field>
- </object>
- </object-param>
-...</programlisting></para>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>maxNodes</entry>
-
- <entry>This is the maximum number of nodes allowed in this
- region. 0 denotes immediate expiry, -1 denotes no
- limit.</entry>
- </row>
-
- <row>
- <entry>minTimeToLive</entry>
-
- <entry>The minimum amount of time (in milliseconds) a node
- must be allowed to live after being accessed before it is
- allowed to be considered for eviction. 0 denotes that this
- feature is disabled, which is the default value.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </listitem>
-
- <listitem>
- <para>Old configuration<programlisting>...
- <object-param>
- <name>mru-with-old-config</name>
- <description>The mru cache
configuration</description>
- <object
type="org.exoplatform.services.cache.ExoCacheConfig">
- <field
name="name"><string>mru-with-old-config</string></field>
- <field
name="maxSize"><int>${my-value}</int></field>
- <field
name="liveTime"><long>${my-value}</long></field>
- <field
name="implementation"><string>MRU</string></field>
- </object>
- </object-param>
-...</programlisting></para>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>maxSize</entry>
-
- <entry>This is the maximum number of nodes allowed in this
- region. 0 denotes immediate expiry, -1 denotes no
- limit.</entry>
- </row>
-
- <row>
- <entry>liveTime</entry>
-
- <entry>The minimum amount of time (in seconds) a node must
- be allowed to live after being accessed before it is
- allowed to be considered for eviction. 0 denotes that this
- feature is disabled, which is the default value.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>LFU Cache - Least Frequently Used</title>
-
- <itemizedlist>
- <listitem>
- <para>New configuration<programlisting>...
- <object-param>
- <name>lfu</name>
- <description>The lfu cache
configuration</description>
- <object
type="org.exoplatform.services.cache.impl.jboss.lfu.LFUExoCacheConfig">
- <field
name="name"><string>lfu</string></field>
- <field
name="maxNodes"><int>${my-value}</int></field>
- <field
name="minNodes"><int>${my-value}</int></field>
- <field
name="minTimeToLive"><long>${my-value}</long></field>
- </object>
- </object-param>
-...</programlisting></para>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>maxNodes</entry>
-
- <entry>This is the maximum number of nodes allowed in this
- region. 0 denotes immediate expiry, -1 denotes no
- limit.</entry>
- </row>
-
- <row>
- <entry>minNodes</entry>
-
- <entry>This is the minimum number of nodes allowed in this
- region. This value determines what the eviction queue
- should prune down to per pass. e.g. If minNodes is 10 and
- the cache grows to 100 nodes, the cache is pruned down to
- the 10 most frequently used nodes when the eviction timer
- makes a pass through the eviction algorithm.</entry>
- </row>
-
- <row>
- <entry>minTimeToLive</entry>
-
- <entry>The minimum amount of time (in milliseconds) a node
- must be allowed to live after being accessed before it is
- allowed to be considered for eviction. 0 denotes that this
- feature is disabled, which is the default value.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </listitem>
-
- <listitem>
- <para>Old configuration<programlisting>...
- <object-param>
- <name>lfu-with-old-config</name>
- <description>The lfu cache
configuration</description>
- <object
type="org.exoplatform.services.cache.ExoCacheConfig">
- <field
name="name"><string>lfu-with-old-config</string></field>
- <field
name="maxSize"><int>${my-value}</int></field>
- <field
name="liveTime"><long>${my-value}</long></field>
- <field
name="implementation"><string>LFU</string></field>
- </object>
- </object-param>
-...</programlisting></para>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>maxSize</entry>
-
- <entry>This is the maximum number of nodes allowed in this
- region. 0 denotes immediate expiry, -1 denotes no
- limit.</entry>
- </row>
-
- <row>
- <entry>liveTime</entry>
-
- <entry>The minimum amount of time (in milliseconds) a node
- must be allowed to live after being accessed before it is
- allowed to be considered for eviction. 0 denotes that this
- feature is disabled, which is the default value.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para><note>
- <para>For the fields <emphasis>minNodes</emphasis> and
- <emphasis>timeToLive</emphasis> needed by JBoss cache, we
will
- use the default values provided by the creator.</para>
- </note></para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>EA Cache - Expiration Algorithm</title>
-
- <itemizedlist>
- <listitem>
- <para>New configuration<programlisting>...
- <object-param>
- <name>ea</name>
- <description>The ea cache
configuration</description>
- <object
type="org.exoplatform.services.cache.impl.jboss.ea.EAExoCacheConfig">
- <field
name="name"><string>ea</string></field>
- <field
name="maxNodes"><int>${my-value}</int></field>
- <field
name="minTimeToLive"><long>${my-value}</long></field>
- <field
name="expirationTimeout"><long>${my-value}</long></field>
- </object>
- </object-param>
-...</programlisting></para>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>maxNodes</entry>
-
- <entry>This is the maximum number of nodes allowed in this
- region. 0 denotes immediate expiry, -1 denotes no
- limit.</entry>
- </row>
-
- <row>
- <entry>minTimeToLive</entry>
-
- <entry>The minimum amount of time (in milliseconds) a node
- must be allowed to live after being accessed before it is
- allowed to be considered for eviction. 0 denotes that this
- feature is disabled, which is the default value.</entry>
- </row>
-
- <row>
- <entry>expirationTimeout</entry>
-
- <entry>This is the timeout after which the cache entry
- must be evicted.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </listitem>
-
- <listitem>
- <para>Old configuration<programlisting>...
- <object-param>
- <name>ea-with-old-config</name>
- <description>The ea cache
configuration</description>
- <object
type="org.exoplatform.services.cache.ExoCacheConfig">
- <field
name="name"><string>lfu-with-old-config</string></field>
- <field
name="maxSize"><int>${my-value}</int></field>
- <field
name="liveTime"><long>${my-value}</long></field>
- <field
name="implementation"><string>EA</string></field>
- </object>
- </object-param>
-...</programlisting></para>
-
- <table>
- <title>Fields description</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>maxSize</entry>
-
- <entry>This is the maximum number of nodes allowed in this
- region. 0 denotes immediate expiry, -1 denotes no
- limit.</entry>
- </row>
-
- <row>
- <entry>liveTime</entry>
-
- <entry>The minimum amount of time (in milliseconds) a node
- must be allowed to live after being accessed before it is
- allowed to be considered for eviction. 0 denotes that this
- feature is disabled, which is the default value.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para><note>
- <para>For the fields
<emphasis>expirationTimeout</emphasis>
- needed by JBoss cache, we will use the default values provided
- by the creator.</para>
- </note></para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
- </section>
-</chapter>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter>
+ <?dbhtml filename="ch-cache.html"?>
+
+ <title>eXo Cache</title>
+
+ <section>
+ <title>Basic concepts</title>
+
+ <para>All applications on the top of eXo JCR that need a cache, can rely
+ on an <envar>org.exoplatform.services.cache.ExoCache</envar> instance
that
+ is managed by the
+ <envar>org.exoplatform.services.cache.CacheService</envar>. The main
+ implementation of this service is
+ <envar>org.exoplatform.services.cache.impl.CacheServiceImpl</envar>
which
+ depends on the
+ <envar>org.exoplatform.services.cache.ExoCacheConfig</envar> in order to
+ create new <envar>ExoCache</envar> instances. See below an example of
+ <envar>org.exoplatform.services.cache.CacheService</envar>
+ definition:<programlisting> <component>
+ <key>org.exoplatform.services.cache.CacheService</key>
+ <jmx-name>cache:type=CacheService</jmx-name>
+
<type>org.exoplatform.services.cache.impl.CacheServiceImpl</type>
+ <init-params>
+ <object-param>
+ <name>cache.config.default</name>
+ <description>The default cache
configuration</description>
+ <object
type="org.exoplatform.services.cache.ExoCacheConfig">
+ <field
name="name"><string>default</string></field>
+ <field
name="maxSize"><int>300</int></field>
+ <field
name="liveTime"><long>600</long></field>
+ <field
name="distributed"><boolean>false</boolean></field>
+ <field
name="implementation"><string>org.exoplatform.services.cache.concurrent.ConcurrentFIFOExoCache</string></field>
+ </object>
+ </object-param>
+ </init-params>
+ </component></programlisting></para>
+
+ <para><note>
+ <para>The <envar>ExoCacheConfig</envar> which name is
+ <envar>default</envar>, will be the default configuration of all the
+ <envar>ExoCache</envar> instances that don't have dedicated
+ configuration.</para>
+ </note>See below an example of how to define a new
+ <envar>ExoCacheConfig</envar> thanks to a
+ <emphasis>external-component-plugin</emphasis>:<programlisting>
<external-component-plugins>
+
<target-component>org.exoplatform.services.cache.CacheService</target-component>
+ <component-plugin>
+ <name>addExoCacheConfig</name>
+ <set-method>addExoCacheConfig</set-method>
+
<type>org.exoplatform.services.cache.ExoCacheConfigPlugin</type>
+ <description>Configures the cache for query
service</description>
+ <init-params>
+ <object-param>
+ <name>cache.config.wcm.composer</name>
+ <description>The default cache
configuration</description>
+ <object
type="org.exoplatform.services.cache.ExoCacheConfig">
+ <field
name="name"><string>wcm.composer</string></field>
+ <field
name="maxSize"><int>300</int></field>
+ <field
name="liveTime"><long>600</long></field>
+ <field
name="distributed"><boolean>false</boolean></field>
+ <field
name="implementation"><string>org.exoplatform.services.cache.concurrent.ConcurrentFIFOExoCache</string></field>
+ </object>
+ </object-param>
+ </init-params>
+ </component-plugin>
+ </external-component-plugins></programlisting></para>
+
+ <table>
+ <title>Descriptions of the fields of
+ <envar>ExoCacheConfig</envar></title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>name</entry>
+
+ <entry>The name of the cache. This field is mandatory since it
+ will be used to retrieve the <envar>ExoCacheConfig</envar>
+ corresponding to a given cache name.</entry>
+ </row>
+
+ <row>
+ <entry>label</entry>
+
+ <entry>The label of the cache. This field is optional. It is
+ mainly used to indicate the purpose of the cache.</entry>
+ </row>
+
+ <row>
+ <entry>maxSize</entry>
+
+ <entry>The maximum numbers of elements in cache. This field is
+ mandatory.</entry>
+ </row>
+
+ <row>
+ <entry>liveTime</entry>
+
+ <entry>The amount of time (in seconds) an element is not written
+ or read before it is evicted. This field is mandatory.</entry>
+ </row>
+
+ <row>
+ <entry>implementation</entry>
+
+ <entry>The full qualified name of the cache implementation to use.
+ This field is optional. This field is only used for simple cache
+ implementation. The default and main implementation is
+
<envar>org.exoplatform.services.cache.concurrent.ConcurrentFIFOExoCache</envar>,
+ this implementation only works with local caches with FIFO as
+ eviction policy. For more complex implementation see the next
+ sections.</entry>
+ </row>
+
+ <row>
+ <entry>distributed</entry>
+
+ <entry>Indicates if the cache is distributed. This field is
+ optional. This field is used for backward compatibility.</entry>
+ </row>
+
+ <row>
+ <entry>replicated</entry>
+
+ <entry>Indicates if the cache is replicated. This field is
+ optional. This field is deprecated.</entry>
+ </row>
+
+ <row>
+ <entry>logEnabled</entry>
+
+ <entry>Indicates if the log is enabled. This field is optional.
+ This field is used for backward compatibility.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section>
+ <title>How to define a cache?</title>
+
+ <para>You have 2 ways to define a cache which are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>At <envar>CacheService</envar>
initialization</para>
+ </listitem>
+
+ <listitem>
+ <para>With an <emphasis>"external
plugin"</emphasis></para>
+ </listitem>
+ </itemizedlist>
+
+ <section>
+ <title>At <envar>CacheService</envar>
initialization</title>
+
+ <programlisting>...
+ <component>
+ <key>org.exoplatform.services.cache.CacheService</key>
+
<type>org.exoplatform.services.cache.impl.CacheServiceImpl</type>
+ <init-params>
+ ...
+ <object-param>
+ <name>fifocache</name>
+ <description>The default cache
configuration</description>
+ <object
type="org.exoplatform.services.cache.ExoCacheConfig">
+ <field
name="name"><string>fifocache</string></field>
+ <field
name="maxSize"><int>${my-value}</int></field>
+ <field
name="liveTime"><long>${my-value}</long></field>
+ <field
name="distributed"><boolean>false</boolean></field>
+ <field
name="implementation"><string>org.exoplatform.services.cache.FIFOExoCache</string></field>
+ </object>
+ </object-param>
+ ...
+ </init-params>
+ </component>
+...</programlisting>
+
+ <para>In this example, we define a new cache called
+ <emphasis>fifocache</emphasis>.</para>
+ </section>
+
+ <section>
+ <title>With an <emphasis>"external
plugin"</emphasis></title>
+
+ <programlisting>...
+ <external-component-plugins>
+
<target-component>org.exoplatform.services.cache.CacheService</target-component>
+ <component-plugin>
+ <name>addExoCacheConfig</name>
+ <set-method>addExoCacheConfig</set-method>
+
<type>org.exoplatform.services.cache.ExoCacheConfigPlugin</type>
+ <description>add ExoCache configuration component plugin
</description>
+ <init-params>
+ ...
+ <object-param>
+ <name>fifoCache</name>
+ <description>The fifo cache
configuration</description>
+ <object
type="org.exoplatform.services.cache.ExoCacheConfig">
+ <field
name="name"><string>fifocache</string></field>
+ <field
name="maxSize"><int>${my-value}</int></field>
+ <field
name="liveTime"><long>${my-value}</long></field>
+ <field
name="distributed"><boolean>false</boolean></field>
+ <field
name="implementation"><string>org.exoplatform.services.cache.FIFOExoCache</string></field>
+ </object>
+ </object-param>
+...
+ </init-params>
+ </component-plugin>
+ </external-component-plugins>
+...</programlisting>
+
+ <para>In this example, we define a new cache called
+ <emphasis>fifocache</emphasis> which is in fact the same cache as in
+ previous example but defined in a different manner.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>eXo Cache extension</title>
+
+ <para>In the previous versions of eXo kernel, it was quite complex to
+ implement your own ExoCache because it was not open enough. Since kernel
+ 2.0.8, it is possible to easily integrate your favorite cache provider in
+ eXo Products.</para>
+
+ <para>You just need to implement your own
<envar>ExoCacheFactory</envar>
+ and register it in an eXo container, as described below:<programlisting>package
org.exoplatform.services.cache;
+...
+public interface ExoCacheFactory {
+
+ /**
+ * Creates a new instance of {@link org.exoplatform.services.cache.ExoCache}
+ * @param config the cache to create
+ * @return the new instance of {@link org.exoplatform.services.cache.ExoCache}
+ * @exception ExoCacheInitException if an exception happens while initializing the
cache
+ */
+ public ExoCache createCache(ExoCacheConfig config) throws ExoCacheInitException;
+}</programlisting></para>
+
+ <para>As you can see, there is only one method to implement which cans be
+ seen as a converter of an <envar>ExoCacheConfig</envar> to get an
instance
+ of <envar>ExoCache</envar>. Once, you created your own implementation
you
+ can simply register your factory by adding a file
+ <emphasis>conf/portal/configuration.xml</emphasis> with a content of the
+ following type:<programlisting><configuration>
+ <component>
+
<key>org.exoplatform.services.cache.ExoCacheFactory</key>
+
<type>org.exoplatform.tutorial.MyExoCacheFactoryImpl</type>
+ ...
+ </component>
+</configuration></programlisting></para>
+ </section>
+
+ <section>
+ <title>eXo Cache based on JBoss Cache</title>
+
+ <section>
+ <title>Configure the ExoCacheFactory</title>
+
+ <para>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 redefined the configuration
+ if you wish as you can do with any components.</para>
+
+ <para>The default configuration of the factory
is:<programlisting><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>
+ </init-params>
+ </component>
+</configuration></programlisting></para>
+
+ <para>As you can see the factory requires one single parameter which is
+ <emphasis>cache.config.template</emphasis>, this parameter allows you
to
+ define the location of the default configuration template of your jboss
+ cache. In the default configuration, we ask the eXo container to get the
+ file shipped into the jar at
+
<emphasis>/conf/portal/cache-configuration-template.xml</emphasis>.</para>
+
+ <para>The default configuration template aims to be the skeleton from
+ which we will create any type of jboss cache instance, thus it must be
+ very generic.<note>
+ <para>The default configuration template provided with the jar aims
+ to work with any application servers, but if you intend to use JBoss
+ AS, you should redefine it in your custom configuration to fit
+ better with your AS.</para>
+ </note></para>
+ </section>
+
+ <section>
+ <title>Add specific configuration for a cache</title>
+
+ <para>If for a given reason, you need to use a specific configuration
+ for a cache, you can register one thanks to an "<emphasis>external
+ plugin</emphasis>", see an example
below:<programlisting><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></programlisting></para>
+
+ <para>In the example above, I call the method
+ <emphasis>addConfig(ExoCacheFactoryConfigPlugin plugin)</emphasis> on
+ the current implementation of <envar>ExoCacheFactory</envar> which is
+ actually the jboss cache implementation.</para>
+
+ <para>In the <emphasis>init-params</emphasis> block, you can
define a
+ set of <emphasis>value-param</emphasis> blocks and for each
+ <emphasis>value-param</emphasis>, we expect the name of cache that
needs
+ a specific configuration as name and the location of your custom
+ configuration as <emphasis>value</emphasis>.</para>
+
+ <para>In this example, we indicates to the factory that we would like
+ that the cache <emphasis>myCustomCache</emphasis> use the
configuration
+ available at
+
<emphasis>jar:/conf/portal/custom-cache-configuration.xml</emphasis>.</para>
+ </section>
+
+ <section>
+ <title>Add a cache creator</title>
+
+ <section>
+ <title>Understanding a cache creator</title>
+
+ <para>The factory for jboss cache, delegates the cache creation to
+ <envar>ExoCacheCreator</envar> that is defined as
+ below:<programlisting>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();
+}</programlisting></para>
+
+ <para>The <envar>ExoCacheCreator</envar> 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.</para>
+
+ <para>In an <envar>ExoCacheCreator</envar>, you need to
implement 3
+ methods which are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>create</emphasis> - this method is used to
create
+ a new <envar>ExoCache</envar> from the
+ <envar>ExoCacheConfig</envar> and a jboss cache
instance.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>getExpectedConfigType</emphasis> - this
method is
+ used to indicate the factory the subtype of
+ <envar>ExoCacheConfig</envar> supported by the
creator.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>getExpectedImplementation</emphasis> - this
method
+ is used to indicate the factory the value of the field
+ <emphasis>implementation</emphasis> of
+ <envar>ExoCacheConfig</envar> 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
+ <envar>ExoCacheConfig</envar>.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Register a cache creator</title>
+
+ <para>You can register any cache creator you want thanks to an
+ <emphasis>"external plugin"</emphasis>, see an example
+ below:<programlisting> <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></programlisting></para>
+
+ <para>In the example above, I call the method
+ <emphasis>addCreator(ExoCacheCreatorPlugin plugin)</emphasis> on the
+ current implementation of <envar>ExoCacheFactory</envar> which is
+ actually the jboss cache implementation.</para>
+
+ <para>In the <emphasis>init-params</emphasis> block, you can
define a
+ set of <emphasis>object-param</emphasis> blocks and for each
+ <emphasis>object-param</emphasis>, we expect any object definition
of
+ type <envar>ExoCacheCreator</envar>.</para>
+
+ <para>In this example, we register the cache creator related to the
+ eviction policy <emphasis>LRU</emphasis>.</para>
+ </section>
+
+ <section>
+ <title>The cache creators available</title>
+
+ <para>By default, no cache creator are defined, so you need to define
+ them yourself by adding them in your configuration files.</para>
+
+ <section>
+ <title>LRU Cache Creator - Least Recently Used</title>
+
+ <programlisting>..
+<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>
+...</programlisting>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>defaultTimeToLive</entry>
+
+ <entry>This is the default value of the field
+ <emphasis>timeToLive</emphasis> described in the section
+ dedicated to this cache type. This value is only use when we
+ define a cache of this type with the old
+ configuration.</entry>
+ </row>
+
+ <row>
+ <entry>defaultMaxAge</entry>
+
+ <entry>his is the default value of the field
+ <emphasis>maxAge</emphasis> described in the section
+ dedicated to this cache type. This value is only use when we
+ define a cache of this type with the old
+ configuration.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section>
+ <title>FIFO Cache Creator - First In, First Out</title>
+
+ <programlisting>...
+<object-param>
+ <name>FIFO</name>
+ <description>The fifo cache creator</description>
+ <object
type="org.exoplatform.services.cache.impl.jboss.fifo.FIFOExoCacheCreator"></object>
+</object-param>
+...</programlisting>
+ </section>
+
+ <section>
+ <title>MRU Cache Creator - Most Recently Used</title>
+
+ <programlisting>...
+<object-param>
+ <name>MRU</name>
+ <description>The mru cache creator</description>
+ <object
type="org.exoplatform.services.cache.impl.jboss.mru.MRUExoCacheCreator"></object>
+</object-param>
+...</programlisting>
+ </section>
+
+ <section>
+ <title>LFU Cache Creator - Least Frequently Used</title>
+
+ <programlisting>...
+<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>
+...</programlisting>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>defaultMinNodes</entry>
+
+ <entry>This is the default value of the field
+ <emphasis>minNodes</emphasis> described in the section
+ dedicated to this cache type. This value is only use when we
+ define a cache of this type with the old
+ configuration.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section>
+ <title>EA Cache Creator - Expiration Algorithm</title>
+
+ <programlisting>...
+<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>
+...</programlisting>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>defaultExpirationTimeout</entry>
+
+ <entry>This is the default value of the field
+ <emphasis>minNodes</emphasis> described in the section
+ dedicated to this cache type. This value is only use when we
+ define a cache of this type with the old
+ configuration.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <title>Define a JBoss cache instance</title>
+
+ <section>
+ <title>How to define a distributed or a local cache?</title>
+
+ <para>Actually, if you use a custom configuration for your cache as
+ described in a previous section, we will use the cache mode define in
+ your configuration file.</para>
+
+ <para>In case, you decide to use the default configuration template,
+ we use the field <emphasis>distributed</emphasis> of your
+ <envar>ExoCacheConfig</envar> to decide. In other words, if the
value
+ of this field is false (the default value), the cache will be a local
+ cache otherwise it will be the cache mode defined in your default
+ configuration template that should be distributed.</para>
+ </section>
+
+ <section>
+ <title>LRU Cache - Least Recently Used</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>New configuration</para>
+
+ <para><programlisting>...
+ <object-param>
+ <name>lru</name>
+ <description>The lru cache
configuration</description>
+ <object
type="org.exoplatform.services.cache.impl.jboss.lru.LRUExoCacheConfig">
+ <field
name="name"><string>lru</string></field>
+ <field
name="maxNodes"><int>${my-value}</int></field>
+ <field
name="minTimeToLive"><long>${my-value}</long></field>
+ <field
name="maxAge"><long>${my-value}</long></field>
+ <field
name="timeToLive"><long>${my-value}</long></field>
+ </object>
+ </object-param>
+...</programlisting><table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>maxNodes</entry>
+
+ <entry>This is the maximum number of nodes allowed in
+ this region. 0 denotes immediate expiry, -1 denotes no
+ limit.</entry>
+ </row>
+
+ <row>
+ <entry>minTimeToLive</entry>
+
+ <entry>The minimum amount of time (in milliseconds) a
+ node must be allowed to live after being accessed before
+ it is allowed to be considered for eviction. 0 denotes
+ that this feature is disabled, which is the default
+ value.</entry>
+ </row>
+
+ <row>
+ <entry>maxAge</entry>
+
+ <entry>Lifespan of a node (in milliseconds) regardless
+ of idle time before the node is swept away. 0 denotes
+ immediate expiry, -1 denotes no limit.</entry>
+ </row>
+
+ <row>
+ <entry>timeToLive</entry>
+
+ <entry>The amount of time a node is not written to or
+ read (in milliseconds) before the node is swept away. 0
+ denotes immediate expiry, -1 denotes no limit.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table></para>
+ </listitem>
+
+ <listitem>
+ <para>Old configuration</para>
+
+ <programlisting>...
+ <object-param>
+ <name>lru-with-old-config</name>
+ <description>The lru cache
configuration</description>
+ <object
type="org.exoplatform.services.cache.ExoCacheConfig">
+ <field
name="name"><string>lru-with-old-config</string></field>
+ <field
name="maxSize"><int>${my-value}</int></field>
+ <field
name="liveTime"><long>${my-value}</long></field>
+ <field
name="implementation"><string>LRU</string></field>
+ </object>
+ </object-param>
+...</programlisting>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>maxSize</entry>
+
+ <entry>This is the maximum number of nodes allowed in this
+ region. 0 denotes immediate expiry, -1 denotes no
+ limit.</entry>
+ </row>
+
+ <row>
+ <entry>liveTime</entry>
+
+ <entry>The minimum amount of time (in seconds) a node must
+ be allowed to live after being accessed before it is
+ allowed to be considered for eviction. 0 denotes that this
+ feature is disabled, which is the default value.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para><note>
+ <para>For the fields <emphasis>maxAge</emphasis> and
+ <emphasis>timeToLive</emphasis> needed by JBoss cache, we
will
+ use the default values provided by the creator.</para>
+ </note></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>FIFO Cache - First In, First Out</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>New configuration<programlisting>...
+ <object-param>
+ <name>fifo</name>
+ <description>The fifo cache
configuration</description>
+ <object
type="org.exoplatform.services.cache.impl.jboss.fifo.FIFOExoCacheConfig">
+ <field
name="name"><string>fifo</string></field>
+ <field
name="maxNodes"><int>${my-value}</int></field>
+ <field
name="minTimeToLive"><long>${my-value}</long></field>
+ </object>
+ </object-param>
+...</programlisting></para>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>maxNodes</entry>
+
+ <entry>This is the maximum number of nodes allowed in this
+ region. 0 denotes immediate expiry, -1 denotes no
+ limit.</entry>
+ </row>
+
+ <row>
+ <entry>minTimeToLive</entry>
+
+ <entry>The minimum amount of time (in milliseconds) a node
+ must be allowed to live after being accessed before it is
+ allowed to be considered for eviction. 0 denotes that this
+ feature is disabled, which is the default value.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </listitem>
+
+ <listitem>
+ <para>Old configuration<programlisting>...
+ <object-param>
+ <name>fifo-with-old-config</name>
+ <description>The fifo cache
configuration</description>
+ <object
type="org.exoplatform.services.cache.ExoCacheConfig">
+ <field
name="name"><string>fifo-with-old-config</string></field>
+ <field
name="maxSize"><int>${my-value}</int></field>
+ <field
name="liveTime"><long>${my-value}</long></field>
+ <field
name="implementation"><string>FIFO</string></field>
+ </object>
+ </object-param>
+...</programlisting></para>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>maxSize</entry>
+
+ <entry>This is the maximum number of nodes allowed in this
+ region. 0 denotes immediate expiry, -1 denotes no
+ limit.</entry>
+ </row>
+
+ <row>
+ <entry>liveTime</entry>
+
+ <entry>The minimum amount of time (in seconds) a node must
+ be allowed to live after being accessed before it is
+ allowed to be considered for eviction. 0 denotes that this
+ feature is disabled, which is the default value.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>MRU Cache - Most Recently Used</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>New configuration<programlisting>...
+ <object-param>
+ <name>mru</name>
+ <description>The mru cache
configuration</description>
+ <object
type="org.exoplatform.services.cache.impl.jboss.mru.MRUExoCacheConfig">
+ <field
name="name"><string>mru</string></field>
+ <field
name="maxNodes"><int>${my-value}</int></field>
+ <field
name="minTimeToLive"><long>${my-value}</long></field>
+ </object>
+ </object-param>
+...</programlisting></para>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>maxNodes</entry>
+
+ <entry>This is the maximum number of nodes allowed in this
+ region. 0 denotes immediate expiry, -1 denotes no
+ limit.</entry>
+ </row>
+
+ <row>
+ <entry>minTimeToLive</entry>
+
+ <entry>The minimum amount of time (in milliseconds) a node
+ must be allowed to live after being accessed before it is
+ allowed to be considered for eviction. 0 denotes that this
+ feature is disabled, which is the default value.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </listitem>
+
+ <listitem>
+ <para>Old configuration<programlisting>...
+ <object-param>
+ <name>mru-with-old-config</name>
+ <description>The mru cache
configuration</description>
+ <object
type="org.exoplatform.services.cache.ExoCacheConfig">
+ <field
name="name"><string>mru-with-old-config</string></field>
+ <field
name="maxSize"><int>${my-value}</int></field>
+ <field
name="liveTime"><long>${my-value}</long></field>
+ <field
name="implementation"><string>MRU</string></field>
+ </object>
+ </object-param>
+...</programlisting></para>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>maxSize</entry>
+
+ <entry>This is the maximum number of nodes allowed in this
+ region. 0 denotes immediate expiry, -1 denotes no
+ limit.</entry>
+ </row>
+
+ <row>
+ <entry>liveTime</entry>
+
+ <entry>The minimum amount of time (in seconds) a node must
+ be allowed to live after being accessed before it is
+ allowed to be considered for eviction. 0 denotes that this
+ feature is disabled, which is the default value.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>LFU Cache - Least Frequently Used</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>New configuration<programlisting>...
+ <object-param>
+ <name>lfu</name>
+ <description>The lfu cache
configuration</description>
+ <object
type="org.exoplatform.services.cache.impl.jboss.lfu.LFUExoCacheConfig">
+ <field
name="name"><string>lfu</string></field>
+ <field
name="maxNodes"><int>${my-value}</int></field>
+ <field
name="minNodes"><int>${my-value}</int></field>
+ <field
name="minTimeToLive"><long>${my-value}</long></field>
+ </object>
+ </object-param>
+...</programlisting></para>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>maxNodes</entry>
+
+ <entry>This is the maximum number of nodes allowed in this
+ region. 0 denotes immediate expiry, -1 denotes no
+ limit.</entry>
+ </row>
+
+ <row>
+ <entry>minNodes</entry>
+
+ <entry>This is the minimum number of nodes allowed in this
+ region. This value determines what the eviction queue
+ should prune down to per pass. e.g. If minNodes is 10 and
+ the cache grows to 100 nodes, the cache is pruned down to
+ the 10 most frequently used nodes when the eviction timer
+ makes a pass through the eviction algorithm.</entry>
+ </row>
+
+ <row>
+ <entry>minTimeToLive</entry>
+
+ <entry>The minimum amount of time (in milliseconds) a node
+ must be allowed to live after being accessed before it is
+ allowed to be considered for eviction. 0 denotes that this
+ feature is disabled, which is the default value.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </listitem>
+
+ <listitem>
+ <para>Old configuration<programlisting>...
+ <object-param>
+ <name>lfu-with-old-config</name>
+ <description>The lfu cache
configuration</description>
+ <object
type="org.exoplatform.services.cache.ExoCacheConfig">
+ <field
name="name"><string>lfu-with-old-config</string></field>
+ <field
name="maxSize"><int>${my-value}</int></field>
+ <field
name="liveTime"><long>${my-value}</long></field>
+ <field
name="implementation"><string>LFU</string></field>
+ </object>
+ </object-param>
+...</programlisting></para>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>maxSize</entry>
+
+ <entry>This is the maximum number of nodes allowed in this
+ region. 0 denotes immediate expiry, -1 denotes no
+ limit.</entry>
+ </row>
+
+ <row>
+ <entry>liveTime</entry>
+
+ <entry>The minimum amount of time (in milliseconds) a node
+ must be allowed to live after being accessed before it is
+ allowed to be considered for eviction. 0 denotes that this
+ feature is disabled, which is the default value.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para><note>
+ <para>For the fields <emphasis>minNodes</emphasis> and
+ <emphasis>timeToLive</emphasis> needed by JBoss cache, we
will
+ use the default values provided by the creator.</para>
+ </note></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>EA Cache - Expiration Algorithm</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>New configuration<programlisting>...
+ <object-param>
+ <name>ea</name>
+ <description>The ea cache
configuration</description>
+ <object
type="org.exoplatform.services.cache.impl.jboss.ea.EAExoCacheConfig">
+ <field
name="name"><string>ea</string></field>
+ <field
name="maxNodes"><int>${my-value}</int></field>
+ <field
name="minTimeToLive"><long>${my-value}</long></field>
+ <field
name="expirationTimeout"><long>${my-value}</long></field>
+ </object>
+ </object-param>
+...</programlisting></para>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>maxNodes</entry>
+
+ <entry>This is the maximum number of nodes allowed in this
+ region. 0 denotes immediate expiry, -1 denotes no
+ limit.</entry>
+ </row>
+
+ <row>
+ <entry>minTimeToLive</entry>
+
+ <entry>The minimum amount of time (in milliseconds) a node
+ must be allowed to live after being accessed before it is
+ allowed to be considered for eviction. 0 denotes that this
+ feature is disabled, which is the default value.</entry>
+ </row>
+
+ <row>
+ <entry>expirationTimeout</entry>
+
+ <entry>This is the timeout after which the cache entry
+ must be evicted.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </listitem>
+
+ <listitem>
+ <para>Old configuration<programlisting>...
+ <object-param>
+ <name>ea-with-old-config</name>
+ <description>The ea cache
configuration</description>
+ <object
type="org.exoplatform.services.cache.ExoCacheConfig">
+ <field
name="name"><string>lfu-with-old-config</string></field>
+ <field
name="maxSize"><int>${my-value}</int></field>
+ <field
name="liveTime"><long>${my-value}</long></field>
+ <field
name="implementation"><string>EA</string></field>
+ </object>
+ </object-param>
+...</programlisting></para>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>maxSize</entry>
+
+ <entry>This is the maximum number of nodes allowed in this
+ region. 0 denotes immediate expiry, -1 denotes no
+ limit.</entry>
+ </row>
+
+ <row>
+ <entry>liveTime</entry>
+
+ <entry>The minimum amount of time (in milliseconds) a node
+ must be allowed to live after being accessed before it is
+ allowed to be considered for eviction. 0 denotes that this
+ feature is disabled, which is the default value.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para><note>
+ <para>For the fields
<emphasis>expirationTimeout</emphasis>
+ needed by JBoss cache, we will use the default values provided
+ by the creator.</para>
+ </note></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <title>eXo Cache based on Infinispan</title>
+
+ <section>
+ <title>Configure the ExoCacheFactory</title>
+
+ <para>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 redefined the configuration
+ if you wish as you can do with any components.</para>
+
+ <para>The default configuration of the factory
is:<programlisting><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>jar:/conf/portal/cache-configuration-template.xml</value>
+ </value-param>
+ </init-params>
+ </component>
+</configuration></programlisting></para>
+
+ <para>As you can see the factory requires one single parameter which is
+ <emphasis>cache.config.template</emphasis>, 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
+
<emphasis>/conf/portal/cache-configuration-template.xml</emphasis>.</para>
+
+ <para>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. <note>
+ <para>All the cache instances that will rely on this cache
+ configuration will share the same
+ <envar>EmbeddedCacheManager.</envar></para>
+ </note></para>
+ </section>
+
+ <section>
+ <title>Add specific configuration for a cache</title>
+
+ <para>If for a given reason, you need to use a specific configuration
+ for a cache, you can register one thanks to an "<emphasis>external
+ plugin</emphasis>", see an example
below:<programlisting><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></programlisting></para>
+
+ <para>In the example above, I call the method
+ <emphasis>addConfig(ExoCacheFactoryConfigPlugin plugin)</emphasis> on
+ the current implementation of <envar>ExoCacheFactory</envar> which is
+ actually the infinispan implementation.</para>
+
+ <para>In the <emphasis>init-params</emphasis> block, you can
define a
+ set of <emphasis>value-param</emphasis> blocks and for each
+ <emphasis>value-param</emphasis>, we expect the name of cache that
needs
+ a specific configuration as name and the location of your custom
+ configuration as <emphasis>value</emphasis>.</para>
+
+ <para>In this example, we indicates to the factory that we would like
+ that the cache <emphasis>myCustomCache</emphasis> use the
configuration
+ available at
+
<emphasis>jar:/conf/portal/custom-cache-configuration.xml</emphasis>.</para>
+
+ <note>
+ <para>All the cache instances that will rely on the cache
+ configuration located at the same location will share the same
+ <envar>EmbeddedCacheManager</envar>.</para>
+ </note>
+ </section>
+
+ <section>
+ <title>Add a cache creator</title>
+
+ <section>
+ <title>Understanding a cache creator</title>
+
+ <para>The factory for infinispan, delegates the cache creation to
+ <envar>ExoCacheCreator</envar> that is defined as
+ below:<programlisting>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 cacheConfig the configuration 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,
Configuration cacheConfig, 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();
+}</programlisting></para>
+
+ <para>The <envar>ExoCacheCreator</envar> 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.</para>
+
+ <para>In an <envar>ExoCacheCreator</envar>, you need to
implement 3
+ methods which are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>create</emphasis> - this method is used to
create
+ a new <envar>ExoCache</envar> from the
+ <envar>ExoCacheConfig</envar>, an inifinispan cache
configuration
+ and a Callable object to allow you to get the cache
+ instance.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>getExpectedConfigType</emphasis> - this
method is
+ used to indicate the factory the subtype of
+ <envar>ExoCacheConfig</envar> supported by the
creator.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>getExpectedImplementation</emphasis>s -
this
+ method is used to indicate the factory the values of the field
+ <emphasis>implementation</emphasis> of
+ <envar>ExoCacheConfig</envar> 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
+ <envar>ExoCacheConfig</envar>.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Register a cache creator</title>
+
+ <para>You can register any cache creator you want thanks to an
+ <emphasis>"external plugin"</emphasis>, see an example
+ below:<programlisting> <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></programlisting></para>
+
+ <para>In the example above, I call the method
+ <emphasis>addCreator(ExoCacheCreatorPlugin plugin)</emphasis> on the
+ current implementation of <envar>ExoCacheFactory</envar> which is
+ actually the infinispan implementation.</para>
+
+ <para>In the <emphasis>init-params</emphasis> block, you can
define a
+ set of <emphasis>object-param</emphasis> blocks and for each
+ <emphasis>object-param</emphasis>, we expect any object definition
of
+ type <envar>ExoCacheCreator</envar>.</para>
+
+ <para>In this example, we register the cache creator related to the
+ eviction policy <emphasis>Test</emphasis>.</para>
+ </section>
+
+ <section>
+ <title>The cache creators available</title>
+
+ <para>By default, no cache creator are defined, so you need to define
+ them yourself by adding them in your configuration files.</para>
+
+ <section>
+ <title>Generic Cache Creator</title>
+
+ <para>This is the generic cache creator that allows you to use any
+ eviction strategies defined by default in Infinispan.</para>
+
+ <programlisting>..
+<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>FIFO</string>
+ </value>
+ <value>
+ <string>LRU</string>
+ </value>
+ <value>
+ <string>UNORDERED</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>
+...</programlisting>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>implementations</entry>
+
+ <entry>This is the list of all the
+ <emphasis>implementations</emphasis> 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 4.1. This field is used to manage
+ the backward compatibility.</entry>
+ </row>
+
+ <row>
+ <entry>defaultStrategy</entry>
+
+ <entry>This is the name of the default eviction strategy to
+ use. By default the value is <emphasis>LRU</emphasis>.
This
+ value is only use when we define a cache of this type with
+ the old configuration.</entry>
+ </row>
+
+ <row>
+ <entry>defaultMaxIdle</entry>
+
+ <entry>This is the default value of the field
+ <emphasis>maxIdle</emphasis> described in the section
+ dedicated to this cache type. By default the value is
+ <emphasis>-1</emphasis>.This value is only use when we
+ define a cache of this type with the old
+ configuration.</entry>
+ </row>
+
+ <row>
+ <entry>defaultWakeUpInterval</entry>
+
+ <entry>his is the default value of the field
+ <emphasis>wakeUpInterval</emphasis> described in the
section
+ dedicated to this cache type. By default the value is
+ <emphasis>5000</emphasis>.This value is only use when we
+ define a cache of this type with the old
+ configuration</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <title>Define an infinispan cache instance</title>
+
+ <section>
+ <title>How to define a distributed or a local cache?</title>
+
+ <para>Actually, if you use a custom configuration for your cache as
+ described in a previous section, we will use the cache mode define in
+ your configuration file.</para>
+
+ <para>In case, you decide to use the default configuration template,
+ we use the field <emphasis>distributed</emphasis> of your
+ <envar>ExoCacheConfig</envar> to decide. In other words, if the
value
+ of this field is false (the default value), the cache will be a local
+ cache otherwise it will be the cache mode defined in your default
+ configuration template that should be distributed.</para>
+ </section>
+
+ <section>
+ <title>How to define an infinispan cache instance</title>
+
+ <para>All the eviction strategies proposed by default in infinispan
+ rely on the generic cache creator.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>New configuration</para>
+
+ <para><programlisting>...
+ <object-param>
+ <name>myCache</name>
+ <description>My cache 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>
+ </object>
+ </object-param>
+...</programlisting><table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>strategy</entry>
+
+ <entry>The name of the strategy to use such as
+ 'UNORDERED', 'FIFO', 'LRU', 'LIRS'
and 'NONE' (to
+ disable eviction).</entry>
+ </row>
+
+ <row>
+ <entry>maxEntries</entry>
+
+ <entry>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.</entry>
+ </row>
+
+ <row>
+ <entry>lifespan</entry>
+
+ <entry>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.</entry>
+ </row>
+
+ <row>
+ <entry>maxIdle</entry>
+
+ <entry>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.</entry>
+ </row>
+
+ <row>
+ <entry>wakeUpInterval</entry>
+
+ <entry>Interval 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.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table></para>
+ </listitem>
+
+ <listitem>
+ <para>Old configuration</para>
+
+ <programlisting>...
+ <object-param>
+ <name>myCache</name>
+ <description>My cache configuration</description>
+ <field
name="name"><string>lru-with-old-config</string></field>
+ <field
name="maxSize"><int>${my-value}</int></field>
+ <field
name="liveTime"><long>${my-value}</long></field>
+ <field
name="implementation"><string>${my-value}</string></field>
+ </object>
+ </object-param>
+...</programlisting>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>maxSize</entry>
+
+ <entry>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.</entry>
+ </row>
+
+ <row>
+ <entry>liveTime</entry>
+
+ <entry>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.</entry>
+ </row>
+
+ <row>
+ <entry>implementation</entry>
+
+ <entry>The name of the implementation to use the expected
+ value is one of the eviction strategies defined in the
+ field <emphasis>implementations</emphasis> of the
generic
+ cache creator.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para><note>
+ <para>For the fields <emphasis>maxIdle</emphasis> and
+ <emphasis>wakeUpInterval</emphasis> needed by infinispan, we
+ will use the default values provided by the creator.</para>
+ </note></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+ </section>
+</chapter>