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> &lt;component&gt; - &lt;key&gt;org.exoplatform.services.cache.CacheService&lt;/key&gt; - &lt;jmx-name&gt;cache:type=CacheService&lt;/jmx-name&gt; - &lt;type&gt;org.exoplatform.services.cache.impl.CacheServiceImpl&lt;/type&gt; - &lt;init-params&gt; - &lt;object-param&gt; - &lt;name&gt;cache.config.default&lt;/name&gt; - &lt;description&gt;The default cache configuration&lt;/description&gt; - &lt;object type="org.exoplatform.services.cache.ExoCacheConfig"&gt; - &lt;field name="name"&gt;&lt;string&gt;default&lt;/string&gt;&lt;/field&gt; - &lt;field name="maxSize"&gt;&lt;int&gt;300&lt;/int&gt;&lt;/field&gt; - &lt;field name="liveTime"&gt;&lt;long&gt;600&lt;/long&gt;&lt;/field&gt; - &lt;field name="distributed"&gt;&lt;boolean&gt;false&lt;/boolean&gt;&lt;/field&gt; - &lt;field name="implementation"&gt;&lt;string&gt;org.exoplatform.services.cache.concurrent.ConcurrentFIFOExoCache&lt;/string&gt;&lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; - &lt;/init-params&gt; - &lt;/component&gt;</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> &lt;external-component-plugins&gt; - &lt;target-component&gt;org.exoplatform.services.cache.CacheService&lt;/target-component&gt; - &lt;component-plugin&gt; - &lt;name&gt;addExoCacheConfig&lt;/name&gt; - &lt;set-method&gt;addExoCacheConfig&lt;/set-method&gt; - &lt;type&gt;org.exoplatform.services.cache.ExoCacheConfigPlugin&lt;/type&gt; - &lt;description&gt;Configures the cache for query service&lt;/description&gt; - &lt;init-params&gt; - &lt;object-param&gt; - &lt;name&gt;cache.config.wcm.composer&lt;/name&gt; - &lt;description&gt;The default cache configuration&lt;/description&gt; - &lt;object type="org.exoplatform.services.cache.ExoCacheConfig"&gt; - &lt;field name="name"&gt;&lt;string&gt;wcm.composer&lt;/string&gt;&lt;/field&gt; - &lt;field name="maxSize"&gt;&lt;int&gt;300&lt;/int&gt;&lt;/field&gt; - &lt;field name="liveTime"&gt;&lt;long&gt;600&lt;/long&gt;&lt;/field&gt; - &lt;field name="distributed"&gt;&lt;boolean&gt;false&lt;/boolean&gt;&lt;/field&gt; - &lt;field name="implementation"&gt;&lt;string&gt;org.exoplatform.services.cache.concurrent.ConcurrentFIFOExoCache&lt;/string&gt;&lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; - &lt;/external-component-plugins&gt;</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>&lt;configuration&gt; - &lt;component&gt; - &lt;key&gt;org.exoplatform.services.cache.ExoCacheFactory&lt;/key&gt; - &lt;type&gt;org.exoplatform.tutorial.MyExoCacheFactoryImpl&lt;/type&gt; - ... - &lt;/component&gt; -&lt;/configuration&gt;</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>&lt;configuration&gt; - &lt;component&gt; - &lt;key&gt;org.exoplatform.services.cache.ExoCacheFactory&lt;/key&gt; - &lt;type&gt;org.exoplatform.services.cache.impl.jboss.ExoCacheFactoryImpl&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;cache.config.template&lt;/name&gt; - &lt;value&gt;jar:/conf/portal/cache-configuration-template.xml&lt;/value&gt; - &lt;/value-param&gt; - &lt;/init-params&gt; - &lt;/component&gt; -&lt;/configuration&gt;</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>&lt;configuration&gt; - ... - &lt;external-component-plugins&gt; - &lt;target-component&gt;org.exoplatform.services.cache.ExoCacheFactory&lt;/target-component&gt; - &lt;component-plugin&gt; - &lt;name&gt;addConfig&lt;/name&gt; - &lt;set-method&gt;addConfig&lt;/set-method&gt; - &lt;type&gt;org.exoplatform.services.cache.impl.jboss.ExoCacheFactoryConfigPlugin&lt;/type&gt; - &lt;description&gt;add Custom Configurations&lt;/description&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;myCustomCache&lt;/name&gt; - &lt;value&gt;jar:/conf/portal/custom-cache-configuration.xml&lt;/value&gt; - &lt;/value-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; - &lt;/external-component-plugins&gt; - ... -&lt;/configuration&gt;</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&lt;Serializable, Object&gt; cache) throws ExoCacheInitException; - - /** - * Returns the type of {@link org.exoplatform.services.cache.ExoCacheConfig} expected by the creator - * @return the expected type - */ - public Class&lt;? extends ExoCacheConfig&gt; 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> &lt;external-component-plugins&gt; - &lt;target-component&gt;org.exoplatform.services.cache.ExoCacheFactory&lt;/target-component&gt; - &lt;component-plugin&gt; - &lt;name&gt;addCreator&lt;/name&gt; - &lt;set-method&gt;addCreator&lt;/set-method&gt; - &lt;type&gt;org.exoplatform.services.cache.impl.jboss.ExoCacheCreatorPlugin&lt;/type&gt; - &lt;description&gt;add Exo Cache Creator&lt;/description&gt; - &lt;init-params&gt; - &lt;object-param&gt; - &lt;name&gt;LRU&lt;/name&gt; - &lt;description&gt;The lru cache creator&lt;/description&gt; - &lt;object type="org.exoplatform.services.cache.impl.jboss.lru.LRUExoCacheCreator"&gt; - &lt;field name="defaultTimeToLive"&gt;&lt;long&gt;1500&lt;/long&gt;&lt;/field&gt; - &lt;field name="defaultMaxAge"&gt;&lt;long&gt;2000&lt;/long&gt;&lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; - &lt;/external-component-plugins&gt;</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>.. -&lt;object-param&gt; - &lt;name&gt;LRU&lt;/name&gt; - &lt;description&gt;The lru cache creator&lt;/description&gt; - &lt;object type="org.exoplatform.services.cache.impl.jboss.lru.LRUExoCacheCreator"&gt; - &lt;field name="defaultTimeToLive"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; - &lt;field name="defaultMaxAge"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; - &lt;/object&gt; -&lt;/object-param&gt; -...</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>... -&lt;object-param&gt; - &lt;name&gt;FIFO&lt;/name&gt; - &lt;description&gt;The fifo cache creator&lt;/description&gt; - &lt;object type="org.exoplatform.services.cache.impl.jboss.fifo.FIFOExoCacheCreator"&gt;&lt;/object&gt; -&lt;/object-param&gt; -...</programlisting> - </section> - - <section> - <title>MRU Cache Creator - Most Recently Used</title> - - <programlisting>... -&lt;object-param&gt; - &lt;name&gt;MRU&lt;/name&gt; - &lt;description&gt;The mru cache creator&lt;/description&gt; - &lt;object type="org.exoplatform.services.cache.impl.jboss.mru.MRUExoCacheCreator"&gt;&lt;/object&gt; -&lt;/object-param&gt; -...</programlisting> - </section> - - <section> - <title>LFU Cache Creator - Least Frequently Used</title> - - <programlisting>... -&lt;object-param&gt; - &lt;name&gt;LFU&lt;/name&gt; - &lt;description&gt;The lfu cache creator&lt;/description&gt; - &lt;object type="org.exoplatform.services.cache.impl.jboss.lfu.LFUExoCacheCreator"&gt; - &lt;field name="defaultMinNodes"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; - &lt;/object&gt; -&lt;/object-param&gt; -...</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>... -&lt;object-param&gt; - &lt;name&gt;EA&lt;/name&gt; - &lt;description&gt;The ea cache creator&lt;/description&gt; - &lt;object type="org.exoplatform.services.cache.impl.jboss.ea.EAExoCacheCreator"&gt; - &lt;field name="defaultExpirationTimeout"&gt;&lt;long&gt;2000&lt;/long&gt;&lt;/field&gt; - &lt;/object&gt; -&lt;/object-param&gt; -...</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>... - &lt;component&gt; - &lt;key&gt;org.exoplatform.services.cache.CacheService&lt;/key&gt; - &lt;type&gt;org.exoplatform.services.cache.impl.CacheServiceImpl&lt;/type&gt; - &lt;init-params&gt; - ... - &lt;object-param&gt; - &lt;name&gt;fifocache&lt;/name&gt; - &lt;description&gt;The default cache configuration&lt;/description&gt; - &lt;object type="org.exoplatform.services.cache.ExoCacheConfig"&gt; - &lt;field name="name"&gt;&lt;string&gt;fifocache&lt;/string&gt;&lt;/field&gt; - &lt;field name="maxSize"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; - &lt;field name="liveTime"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; - &lt;field name="distributed"&gt;&lt;boolean&gt;false&lt;/boolean&gt;&lt;/field&gt; - &lt;field name="implementation"&gt;&lt;string&gt;org.exoplatform.services.cache.FIFOExoCache&lt;/string&gt;&lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; - ... - &lt;/init-params&gt; - &lt;/component&gt; -...</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>... - &lt;external-component-plugins&gt; - &lt;target-component&gt;org.exoplatform.services.cache.CacheService&lt;/target-component&gt; - &lt;component-plugin&gt; - &lt;name&gt;addExoCacheConfig&lt;/name&gt; - &lt;set-method&gt;addExoCacheConfig&lt;/set-method&gt; - &lt;type&gt;org.exoplatform.services.cache.ExoCacheConfigPlugin&lt;/type&gt; - &lt;description&gt;add ExoCache configuration component plugin &lt;/description&gt; - &lt;init-params&gt; - ... - &lt;object-param&gt; - &lt;name&gt;fifoCache&lt;/name&gt; - &lt;description&gt;The fifo cache configuration&lt;/description&gt; - &lt;object type="org.exoplatform.services.cache.ExoCacheConfig"&gt; - &lt;field name="name"&gt;&lt;string&gt;fifocache&lt;/string&gt;&lt;/field&gt; - &lt;field name="maxSize"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; - &lt;field name="liveTime"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; - &lt;field name="distributed"&gt;&lt;boolean&gt;false&lt;/boolean&gt;&lt;/field&gt; - &lt;field name="implementation"&gt;&lt;string&gt;org.exoplatform.services.cache.FIFOExoCache&lt;/string&gt;&lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; -... - &lt;/init-params&gt; - &lt;/component-plugin&gt; - &lt;/external-component-plugins&gt; -...</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>... - &lt;object-param&gt; - &lt;name&gt;lru&lt;/name&gt; - &lt;description&gt;The lru cache configuration&lt;/description&gt; - &lt;object type="org.exoplatform.services.cache.impl.jboss.lru.LRUExoCacheConfig"&gt; - &lt;field name="name"&gt;&lt;string&gt;lru&lt;/string&gt;&lt;/field&gt; - &lt;field name="maxNodes"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; - &lt;field name="minTimeToLive"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; - &lt;field name="maxAge"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; - &lt;field name="timeToLive"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; -...</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>... - &lt;object-param&gt; - &lt;name&gt;lru-with-old-config&lt;/name&gt; - &lt;description&gt;The lru cache configuration&lt;/description&gt; - &lt;object type="org.exoplatform.services.cache.ExoCacheConfig"&gt; - &lt;field name="name"&gt;&lt;string&gt;lru-with-old-config&lt;/string&gt;&lt;/field&gt; - &lt;field name="maxSize"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; - &lt;field name="liveTime"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; - &lt;field name="implementation"&gt;&lt;string&gt;LRU&lt;/string&gt;&lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; -...</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>... - &lt;object-param&gt; - &lt;name&gt;fifo&lt;/name&gt; - &lt;description&gt;The fifo cache configuration&lt;/description&gt; - &lt;object type="org.exoplatform.services.cache.impl.jboss.fifo.FIFOExoCacheConfig"&gt; - &lt;field name="name"&gt;&lt;string&gt;fifo&lt;/string&gt;&lt;/field&gt; - &lt;field name="maxNodes"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; - &lt;field name="minTimeToLive"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; -...</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>... - &lt;object-param&gt; - &lt;name&gt;fifo-with-old-config&lt;/name&gt; - &lt;description&gt;The fifo cache configuration&lt;/description&gt; - &lt;object type="org.exoplatform.services.cache.ExoCacheConfig"&gt; - &lt;field name="name"&gt;&lt;string&gt;fifo-with-old-config&lt;/string&gt;&lt;/field&gt; - &lt;field name="maxSize"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; - &lt;field name="liveTime"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; - &lt;field name="implementation"&gt;&lt;string&gt;FIFO&lt;/string&gt;&lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; -...</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>... - &lt;object-param&gt; - &lt;name&gt;mru&lt;/name&gt; - &lt;description&gt;The mru cache configuration&lt;/description&gt; - &lt;object type="org.exoplatform.services.cache.impl.jboss.mru.MRUExoCacheConfig"&gt; - &lt;field name="name"&gt;&lt;string&gt;mru&lt;/string&gt;&lt;/field&gt; - &lt;field name="maxNodes"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; - &lt;field name="minTimeToLive"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; -...</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>... - &lt;object-param&gt; - &lt;name&gt;mru-with-old-config&lt;/name&gt; - &lt;description&gt;The mru cache configuration&lt;/description&gt; - &lt;object type="org.exoplatform.services.cache.ExoCacheConfig"&gt; - &lt;field name="name"&gt;&lt;string&gt;mru-with-old-config&lt;/string&gt;&lt;/field&gt; - &lt;field name="maxSize"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; - &lt;field name="liveTime"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; - &lt;field name="implementation"&gt;&lt;string&gt;MRU&lt;/string&gt;&lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; -...</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>... - &lt;object-param&gt; - &lt;name&gt;lfu&lt;/name&gt; - &lt;description&gt;The lfu cache configuration&lt;/description&gt; - &lt;object type="org.exoplatform.services.cache.impl.jboss.lfu.LFUExoCacheConfig"&gt; - &lt;field name="name"&gt;&lt;string&gt;lfu&lt;/string&gt;&lt;/field&gt; - &lt;field name="maxNodes"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; - &lt;field name="minNodes"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; - &lt;field name="minTimeToLive"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; -...</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>... - &lt;object-param&gt; - &lt;name&gt;lfu-with-old-config&lt;/name&gt; - &lt;description&gt;The lfu cache configuration&lt;/description&gt; - &lt;object type="org.exoplatform.services.cache.ExoCacheConfig"&gt; - &lt;field name="name"&gt;&lt;string&gt;lfu-with-old-config&lt;/string&gt;&lt;/field&gt; - &lt;field name="maxSize"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; - &lt;field name="liveTime"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; - &lt;field name="implementation"&gt;&lt;string&gt;LFU&lt;/string&gt;&lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; -...</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>... - &lt;object-param&gt; - &lt;name&gt;ea&lt;/name&gt; - &lt;description&gt;The ea cache configuration&lt;/description&gt; - &lt;object type="org.exoplatform.services.cache.impl.jboss.ea.EAExoCacheConfig"&gt; - &lt;field name="name"&gt;&lt;string&gt;ea&lt;/string&gt;&lt;/field&gt; - &lt;field name="maxNodes"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; - &lt;field name="minTimeToLive"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; - &lt;field name="expirationTimeout"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; -...</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>... - &lt;object-param&gt; - &lt;name&gt;ea-with-old-config&lt;/name&gt; - &lt;description&gt;The ea cache configuration&lt;/description&gt; - &lt;object type="org.exoplatform.services.cache.ExoCacheConfig"&gt; - &lt;field name="name"&gt;&lt;string&gt;lfu-with-old-config&lt;/string&gt;&lt;/field&gt; - &lt;field name="maxSize"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; - &lt;field name="liveTime"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; - &lt;field name="implementation"&gt;&lt;string&gt;EA&lt;/string&gt;&lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; -...</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> &lt;component&gt; + &lt;key&gt;org.exoplatform.services.cache.CacheService&lt;/key&gt; + &lt;jmx-name&gt;cache:type=CacheService&lt;/jmx-name&gt; + &lt;type&gt;org.exoplatform.services.cache.impl.CacheServiceImpl&lt;/type&gt; + &lt;init-params&gt; + &lt;object-param&gt; + &lt;name&gt;cache.config.default&lt;/name&gt; + &lt;description&gt;The default cache configuration&lt;/description&gt; + &lt;object type="org.exoplatform.services.cache.ExoCacheConfig"&gt; + &lt;field name="name"&gt;&lt;string&gt;default&lt;/string&gt;&lt;/field&gt; + &lt;field name="maxSize"&gt;&lt;int&gt;300&lt;/int&gt;&lt;/field&gt; + &lt;field name="liveTime"&gt;&lt;long&gt;600&lt;/long&gt;&lt;/field&gt; + &lt;field name="distributed"&gt;&lt;boolean&gt;false&lt;/boolean&gt;&lt;/field&gt; + &lt;field name="implementation"&gt;&lt;string&gt;org.exoplatform.services.cache.concurrent.ConcurrentFIFOExoCache&lt;/string&gt;&lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; + &lt;/init-params&gt; + &lt;/component&gt;</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> &lt;external-component-plugins&gt; + &lt;target-component&gt;org.exoplatform.services.cache.CacheService&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;name&gt;addExoCacheConfig&lt;/name&gt; + &lt;set-method&gt;addExoCacheConfig&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.cache.ExoCacheConfigPlugin&lt;/type&gt; + &lt;description&gt;Configures the cache for query service&lt;/description&gt; + &lt;init-params&gt; + &lt;object-param&gt; + &lt;name&gt;cache.config.wcm.composer&lt;/name&gt; + &lt;description&gt;The default cache configuration&lt;/description&gt; + &lt;object type="org.exoplatform.services.cache.ExoCacheConfig"&gt; + &lt;field name="name"&gt;&lt;string&gt;wcm.composer&lt;/string&gt;&lt;/field&gt; + &lt;field name="maxSize"&gt;&lt;int&gt;300&lt;/int&gt;&lt;/field&gt; + &lt;field name="liveTime"&gt;&lt;long&gt;600&lt;/long&gt;&lt;/field&gt; + &lt;field name="distributed"&gt;&lt;boolean&gt;false&lt;/boolean&gt;&lt;/field&gt; + &lt;field name="implementation"&gt;&lt;string&gt;org.exoplatform.services.cache.concurrent.ConcurrentFIFOExoCache&lt;/string&gt;&lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; + &lt;/external-component-plugins&gt;</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>... + &lt;component&gt; + &lt;key&gt;org.exoplatform.services.cache.CacheService&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.cache.impl.CacheServiceImpl&lt;/type&gt; + &lt;init-params&gt; + ... + &lt;object-param&gt; + &lt;name&gt;fifocache&lt;/name&gt; + &lt;description&gt;The default cache configuration&lt;/description&gt; + &lt;object type="org.exoplatform.services.cache.ExoCacheConfig"&gt; + &lt;field name="name"&gt;&lt;string&gt;fifocache&lt;/string&gt;&lt;/field&gt; + &lt;field name="maxSize"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; + &lt;field name="liveTime"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;field name="distributed"&gt;&lt;boolean&gt;false&lt;/boolean&gt;&lt;/field&gt; + &lt;field name="implementation"&gt;&lt;string&gt;org.exoplatform.services.cache.FIFOExoCache&lt;/string&gt;&lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; + ... + &lt;/init-params&gt; + &lt;/component&gt; +...</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>... + &lt;external-component-plugins&gt; + &lt;target-component&gt;org.exoplatform.services.cache.CacheService&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;name&gt;addExoCacheConfig&lt;/name&gt; + &lt;set-method&gt;addExoCacheConfig&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.cache.ExoCacheConfigPlugin&lt;/type&gt; + &lt;description&gt;add ExoCache configuration component plugin &lt;/description&gt; + &lt;init-params&gt; + ... + &lt;object-param&gt; + &lt;name&gt;fifoCache&lt;/name&gt; + &lt;description&gt;The fifo cache configuration&lt;/description&gt; + &lt;object type="org.exoplatform.services.cache.ExoCacheConfig"&gt; + &lt;field name="name"&gt;&lt;string&gt;fifocache&lt;/string&gt;&lt;/field&gt; + &lt;field name="maxSize"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; + &lt;field name="liveTime"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;field name="distributed"&gt;&lt;boolean&gt;false&lt;/boolean&gt;&lt;/field&gt; + &lt;field name="implementation"&gt;&lt;string&gt;org.exoplatform.services.cache.FIFOExoCache&lt;/string&gt;&lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; +... + &lt;/init-params&gt; + &lt;/component-plugin&gt; + &lt;/external-component-plugins&gt; +...</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>&lt;configuration&gt; + &lt;component&gt; + &lt;key&gt;org.exoplatform.services.cache.ExoCacheFactory&lt;/key&gt; + &lt;type&gt;org.exoplatform.tutorial.MyExoCacheFactoryImpl&lt;/type&gt; + ... + &lt;/component&gt; +&lt;/configuration&gt;</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>&lt;configuration&gt; + &lt;component&gt; + &lt;key&gt;org.exoplatform.services.cache.ExoCacheFactory&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.cache.impl.jboss.ExoCacheFactoryImpl&lt;/type&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;cache.config.template&lt;/name&gt; + &lt;value&gt;jar:/conf/portal/cache-configuration-template.xml&lt;/value&gt; + &lt;/value-param&gt; + &lt;/init-params&gt; + &lt;/component&gt; +&lt;/configuration&gt;</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>&lt;configuration&gt; + ... + &lt;external-component-plugins&gt; + &lt;target-component&gt;org.exoplatform.services.cache.ExoCacheFactory&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;name&gt;addConfig&lt;/name&gt; + &lt;set-method&gt;addConfig&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.cache.impl.jboss.ExoCacheFactoryConfigPlugin&lt;/type&gt; + &lt;description&gt;add Custom Configurations&lt;/description&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;myCustomCache&lt;/name&gt; + &lt;value&gt;jar:/conf/portal/custom-cache-configuration.xml&lt;/value&gt; + &lt;/value-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; + &lt;/external-component-plugins&gt; + ... +&lt;/configuration&gt;</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&lt;Serializable, Object&gt; cache) throws ExoCacheInitException; + + /** + * Returns the type of {@link org.exoplatform.services.cache.ExoCacheConfig} expected by the creator + * @return the expected type + */ + public Class&lt;? extends ExoCacheConfig&gt; 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> &lt;external-component-plugins&gt; + &lt;target-component&gt;org.exoplatform.services.cache.ExoCacheFactory&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;name&gt;addCreator&lt;/name&gt; + &lt;set-method&gt;addCreator&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.cache.impl.jboss.ExoCacheCreatorPlugin&lt;/type&gt; + &lt;description&gt;add Exo Cache Creator&lt;/description&gt; + &lt;init-params&gt; + &lt;object-param&gt; + &lt;name&gt;LRU&lt;/name&gt; + &lt;description&gt;The lru cache creator&lt;/description&gt; + &lt;object type="org.exoplatform.services.cache.impl.jboss.lru.LRUExoCacheCreator"&gt; + &lt;field name="defaultTimeToLive"&gt;&lt;long&gt;1500&lt;/long&gt;&lt;/field&gt; + &lt;field name="defaultMaxAge"&gt;&lt;long&gt;2000&lt;/long&gt;&lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; + &lt;/external-component-plugins&gt;</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>.. +&lt;object-param&gt; + &lt;name&gt;LRU&lt;/name&gt; + &lt;description&gt;The lru cache creator&lt;/description&gt; + &lt;object type="org.exoplatform.services.cache.impl.jboss.lru.LRUExoCacheCreator"&gt; + &lt;field name="defaultTimeToLive"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;field name="defaultMaxAge"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;/object&gt; +&lt;/object-param&gt; +...</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>... +&lt;object-param&gt; + &lt;name&gt;FIFO&lt;/name&gt; + &lt;description&gt;The fifo cache creator&lt;/description&gt; + &lt;object type="org.exoplatform.services.cache.impl.jboss.fifo.FIFOExoCacheCreator"&gt;&lt;/object&gt; +&lt;/object-param&gt; +...</programlisting> + </section> + + <section> + <title>MRU Cache Creator - Most Recently Used</title> + + <programlisting>... +&lt;object-param&gt; + &lt;name&gt;MRU&lt;/name&gt; + &lt;description&gt;The mru cache creator&lt;/description&gt; + &lt;object type="org.exoplatform.services.cache.impl.jboss.mru.MRUExoCacheCreator"&gt;&lt;/object&gt; +&lt;/object-param&gt; +...</programlisting> + </section> + + <section> + <title>LFU Cache Creator - Least Frequently Used</title> + + <programlisting>... +&lt;object-param&gt; + &lt;name&gt;LFU&lt;/name&gt; + &lt;description&gt;The lfu cache creator&lt;/description&gt; + &lt;object type="org.exoplatform.services.cache.impl.jboss.lfu.LFUExoCacheCreator"&gt; + &lt;field name="defaultMinNodes"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; + &lt;/object&gt; +&lt;/object-param&gt; +...</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>... +&lt;object-param&gt; + &lt;name&gt;EA&lt;/name&gt; + &lt;description&gt;The ea cache creator&lt;/description&gt; + &lt;object type="org.exoplatform.services.cache.impl.jboss.ea.EAExoCacheCreator"&gt; + &lt;field name="defaultExpirationTimeout"&gt;&lt;long&gt;2000&lt;/long&gt;&lt;/field&gt; + &lt;/object&gt; +&lt;/object-param&gt; +...</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>... + &lt;object-param&gt; + &lt;name&gt;lru&lt;/name&gt; + &lt;description&gt;The lru cache configuration&lt;/description&gt; + &lt;object type="org.exoplatform.services.cache.impl.jboss.lru.LRUExoCacheConfig"&gt; + &lt;field name="name"&gt;&lt;string&gt;lru&lt;/string&gt;&lt;/field&gt; + &lt;field name="maxNodes"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; + &lt;field name="minTimeToLive"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;field name="maxAge"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;field name="timeToLive"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; +...</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>... + &lt;object-param&gt; + &lt;name&gt;lru-with-old-config&lt;/name&gt; + &lt;description&gt;The lru cache configuration&lt;/description&gt; + &lt;object type="org.exoplatform.services.cache.ExoCacheConfig"&gt; + &lt;field name="name"&gt;&lt;string&gt;lru-with-old-config&lt;/string&gt;&lt;/field&gt; + &lt;field name="maxSize"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; + &lt;field name="liveTime"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;field name="implementation"&gt;&lt;string&gt;LRU&lt;/string&gt;&lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; +...</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>... + &lt;object-param&gt; + &lt;name&gt;fifo&lt;/name&gt; + &lt;description&gt;The fifo cache configuration&lt;/description&gt; + &lt;object type="org.exoplatform.services.cache.impl.jboss.fifo.FIFOExoCacheConfig"&gt; + &lt;field name="name"&gt;&lt;string&gt;fifo&lt;/string&gt;&lt;/field&gt; + &lt;field name="maxNodes"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; + &lt;field name="minTimeToLive"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; +...</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>... + &lt;object-param&gt; + &lt;name&gt;fifo-with-old-config&lt;/name&gt; + &lt;description&gt;The fifo cache configuration&lt;/description&gt; + &lt;object type="org.exoplatform.services.cache.ExoCacheConfig"&gt; + &lt;field name="name"&gt;&lt;string&gt;fifo-with-old-config&lt;/string&gt;&lt;/field&gt; + &lt;field name="maxSize"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; + &lt;field name="liveTime"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;field name="implementation"&gt;&lt;string&gt;FIFO&lt;/string&gt;&lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; +...</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>... + &lt;object-param&gt; + &lt;name&gt;mru&lt;/name&gt; + &lt;description&gt;The mru cache configuration&lt;/description&gt; + &lt;object type="org.exoplatform.services.cache.impl.jboss.mru.MRUExoCacheConfig"&gt; + &lt;field name="name"&gt;&lt;string&gt;mru&lt;/string&gt;&lt;/field&gt; + &lt;field name="maxNodes"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; + &lt;field name="minTimeToLive"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; +...</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>... + &lt;object-param&gt; + &lt;name&gt;mru-with-old-config&lt;/name&gt; + &lt;description&gt;The mru cache configuration&lt;/description&gt; + &lt;object type="org.exoplatform.services.cache.ExoCacheConfig"&gt; + &lt;field name="name"&gt;&lt;string&gt;mru-with-old-config&lt;/string&gt;&lt;/field&gt; + &lt;field name="maxSize"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; + &lt;field name="liveTime"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;field name="implementation"&gt;&lt;string&gt;MRU&lt;/string&gt;&lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; +...</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>... + &lt;object-param&gt; + &lt;name&gt;lfu&lt;/name&gt; + &lt;description&gt;The lfu cache configuration&lt;/description&gt; + &lt;object type="org.exoplatform.services.cache.impl.jboss.lfu.LFUExoCacheConfig"&gt; + &lt;field name="name"&gt;&lt;string&gt;lfu&lt;/string&gt;&lt;/field&gt; + &lt;field name="maxNodes"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; + &lt;field name="minNodes"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; + &lt;field name="minTimeToLive"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; +...</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>... + &lt;object-param&gt; + &lt;name&gt;lfu-with-old-config&lt;/name&gt; + &lt;description&gt;The lfu cache configuration&lt;/description&gt; + &lt;object type="org.exoplatform.services.cache.ExoCacheConfig"&gt; + &lt;field name="name"&gt;&lt;string&gt;lfu-with-old-config&lt;/string&gt;&lt;/field&gt; + &lt;field name="maxSize"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; + &lt;field name="liveTime"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;field name="implementation"&gt;&lt;string&gt;LFU&lt;/string&gt;&lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; +...</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>... + &lt;object-param&gt; + &lt;name&gt;ea&lt;/name&gt; + &lt;description&gt;The ea cache configuration&lt;/description&gt; + &lt;object type="org.exoplatform.services.cache.impl.jboss.ea.EAExoCacheConfig"&gt; + &lt;field name="name"&gt;&lt;string&gt;ea&lt;/string&gt;&lt;/field&gt; + &lt;field name="maxNodes"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; + &lt;field name="minTimeToLive"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;field name="expirationTimeout"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; +...</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>... + &lt;object-param&gt; + &lt;name&gt;ea-with-old-config&lt;/name&gt; + &lt;description&gt;The ea cache configuration&lt;/description&gt; + &lt;object type="org.exoplatform.services.cache.ExoCacheConfig"&gt; + &lt;field name="name"&gt;&lt;string&gt;lfu-with-old-config&lt;/string&gt;&lt;/field&gt; + &lt;field name="maxSize"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; + &lt;field name="liveTime"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;field name="implementation"&gt;&lt;string&gt;EA&lt;/string&gt;&lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; +...</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>&lt;configuration&gt; + &lt;component&gt; + &lt;key&gt;org.exoplatform.services.cache.ExoCacheFactory&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.cache.impl.infinispan.ExoCacheFactoryImpl&lt;/type&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;cache.config.template&lt;/name&gt; + &lt;value&gt;jar:/conf/portal/cache-configuration-template.xml&lt;/value&gt; + &lt;/value-param&gt; + &lt;/init-params&gt; + &lt;/component&gt; +&lt;/configuration&gt;</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>&lt;configuration&gt; + ... + &lt;external-component-plugins&gt; + &lt;target-component&gt;org.exoplatform.services.cache.ExoCacheFactory&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;name&gt;addConfig&lt;/name&gt; + &lt;set-method&gt;addConfig&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.cache.impl.infinispan.ExoCacheFactoryConfigPlugin&lt;/type&gt; + &lt;description&gt;add Custom Configurations&lt;/description&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;myCustomCache&lt;/name&gt; + &lt;value&gt;jar:/conf/portal/custom-cache-configuration.xml&lt;/value&gt; + &lt;/value-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; + &lt;/external-component-plugins&gt; + ... +&lt;/configuration&gt;</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&lt;Serializable, Object&gt; create(ExoCacheConfig config, Configuration cacheConfig, Callable&lt;Cache&lt;Serializable, Object&gt;&gt; cacheGetter) throws ExoCacheInitException; + + /** + * Returns the type of {@link org.exoplatform.services.cache.ExoCacheConfig} expected by the creator + * @return the expected type + */ + public Class&lt;? extends ExoCacheConfig&gt; 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&lt;String&gt; 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> &lt;external-component-plugins&gt; + &lt;target-component&gt;org.exoplatform.services.cache.ExoCacheFactory&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;name&gt;addCreator&lt;/name&gt; + &lt;set-method&gt;addCreator&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.cache.impl.infinispan.ExoCacheCreatorPlugin&lt;/type&gt; + &lt;description&gt;add Exo Cache Creator&lt;/description&gt; + &lt;init-params&gt; + &lt;object-param&gt; + &lt;name&gt;Test&lt;/name&gt; + &lt;description&gt;The cache creator for testing purpose&lt;/description&gt; + &lt;object type="org.exoplatform.services.cache.impl.infinispan.TestExoCacheCreator"&gt;&lt;/object&gt; + &lt;/object-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; + &lt;/external-component-plugins&gt;</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>.. +&lt;object-param&gt; + &lt;name&gt;GENERIC&lt;/name&gt; + &lt;description&gt;The generic cache creator&lt;/description&gt; + &lt;object type="org.exoplatform.services.cache.impl.infinispan.generic.GenericExoCacheCreator"&gt; + &lt;field name="implementations"&gt; + &lt;collection type="java.util.HashSet"&gt; + &lt;value&gt; + &lt;string&gt;NONE&lt;/string&gt; + &lt;/value&gt; + &lt;value&gt; + &lt;string&gt;FIFO&lt;/string&gt; + &lt;/value&gt; + &lt;value&gt; + &lt;string&gt;LRU&lt;/string&gt; + &lt;/value&gt; + &lt;value&gt; + &lt;string&gt;UNORDERED&lt;/string&gt; + &lt;/value&gt; + &lt;value&gt; + &lt;string&gt;LIRS&lt;/string&gt; + &lt;/value&gt; + &lt;/collection&gt; + &lt;/field&gt; + &lt;field name="defaultStrategy"&gt;&lt;string&gt;${my-value}&lt;/string&gt;&lt;/field&gt; + &lt;field name="defaultMaxIdle"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;field name="defaultWakeUpInterval"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;/object&gt; +&lt;/object-param&gt; +...</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>... + &lt;object-param&gt; + &lt;name&gt;myCache&lt;/name&gt; + &lt;description&gt;My cache configuration&lt;/description&gt; + &lt;object type="org.exoplatform.services.cache.impl.infinispan.generic.GenericExoCacheConfig"&gt; + &lt;field name="name"&gt;&lt;string&gt;myCacheName&lt;/string&gt;&lt;/field&gt; + &lt;field name="strategy"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; + &lt;field name="maxEntries"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;field name="lifespan"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;field name="maxIdle"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;field name="wakeUpInterval"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; +...</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>... + &lt;object-param&gt; + &lt;name&gt;myCache&lt;/name&gt; + &lt;description&gt;My cache configuration&lt;/description&gt; + &lt;field name="name"&gt;&lt;string&gt;lru-with-old-config&lt;/string&gt;&lt;/field&gt; + &lt;field name="maxSize"&gt;&lt;int&gt;${my-value}&lt;/int&gt;&lt;/field&gt; + &lt;field name="liveTime"&gt;&lt;long&gt;${my-value}&lt;/long&gt;&lt;/field&gt; + &lt;field name="implementation"&gt;&lt;string&gt;${my-value}&lt;/string&gt;&lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; +...</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>