<?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">
<section id="Kernel.Cache">
  <title>eXo Cache</title>
  <para>
    This section will provide you all the basic knowledge about eXo Cache, from basic concepts to advanced concepts, sample codes, and more.
  </para>
  <section id="Kernel.Cache.Basic_concepts">
    <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 the below example of
    <envar>org.exoplatform.services.cache.CacheService</envar>
    definition:</para>

    <programlisting language="xml">  &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>

    <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>

    <para>See the below example about how to define a new
    <envar>ExoCacheConfig</envar> thanks to a
    <emphasis>external-component-plugin</emphasis>:</para>

    <programlisting language="xml">  &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>

    <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) that 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 deprecated.</entry>
          </row>

          <row>
            <entry>replicated</entry>

            <entry>Indicates if the cache is replicated. This field is
            optional.</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>

          <row>
            <entry>avoidValueReplication</entry>

            <entry>Indicates whether the values of the cache should be
            replicated or not in case of a replicated cache. This field is
            optional. By default it is disabled. Find more details about this
            field in the next section.</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
  </section>

  <section id="Kernel.Cache.Advanced_concepts">
    <title>Advanced concepts</title>

    <section id="Kernel.Cache.Advanced_concepts.Invalidation">
      <title>Invalidation</title>

      <para>In case, you have big values or non serializable values and you
      need a replicated cache to at list invalidate the data when it is
      needed, you can use the invalidation mode that will work on top of any
      replicated cache implementations. This is possible thanks to the class
      <emphasis>InvalidationExoCache</emphasis> which is actually a decorator
      whose idea is to replicate the the hash code of the value in order to
      know if it is needed or not to invalidate the local data, if the new
      hash code of the value is the same as the old value, we assume that it
      is the same value so we don't invalidate the old value. This is required
      to avoid the following infinite loop that we will face with invalidation
      mode proposed out of the box by JBoss Cache for example:</para>

      <orderedlist>
        <listitem>
          <para>Cluster node #1 puts (key1, value1) into the cache</para>
        </listitem>

        <listitem>
          <para>On cluster node #2 key1 is invalidated by put call in node
          #1</para>
        </listitem>

        <listitem>
          <para>Node #2 re-loads key1 and puts (key1, value1) into the
          cache</para>
        </listitem>

        <listitem>
          <para>On cluster node #1 key1 is invalidated, so we get back to step
          #1</para>
        </listitem>
      </orderedlist>

      <para>In the use case above, thanks to the
      <emphasis>InvalidationExoCache</emphasis> since the value loaded at step
      #3 has the same hash code as the value loaded as step #1, the step #4
      won't invalidate the data on the cluster node #1.</para>

      <para>It exists 2 ways to use the invalidation mode which are the
      following:</para>

      <orderedlist>
        <listitem>
          <para>By configuration: For this you simply need to set the
          parameter <emphasis>avoidValueReplication</emphasis> to
          <emphasis>true</emphasis> in your eXo cache configuration, this will
          indicate the CacheService to wrap your eXo cache instance into an
          <emphasis>InvalidationExoCache</emphasis> in case the cache is
          defined as replicated or distributed.</para>
        </listitem>

        <listitem>
          <para>Programmatically; You can wrap your eXo cache instance into an
          <emphasis>org.exoplatform.services.cache.invalidation.InvalidationExoCache</emphasis>
          yourself using the public constructors that are available. Please
          note that if you use <emphasis>CacheListeners</emphasis> add them to
          the InvalidationExoCache instance instead of the nested eXo Cache
          because the nested eXo Cache will contain only hash codes so the
          related listeners will get hash codes instead of the real
          values.</para>
        </listitem>
      </orderedlist>

      <note>
        <para>The invalidation will be efficient if and only if the hash code
        method is properly implemented, in other words 2 value objects
        representing the same data need to return the same hash code otherwise
        the infinite loop described above will still be effective.</para>
      </note>
    </section>

    <section id="Kernel.Cache.Advanced_concepts.FutureExoCache">
      <title>FutureExoCache</title>

      <para>If the data that you want to store into your eXo Cache instance
      takes a lot of time to load and/or you would like to prevent multiple
      concurrent loading of the same data at the same time, you can use
      <emphasis>org.exoplatform.services.cache.future.FutureExoCache</emphasis>
      on top of your eXo Cache instance in order to delegate the loading of
      your data to a loader that will be called only once whatever the total
      amount of concurrent threads looking for it. See below an example of how
      the FutureExoCache can be used:</para>

      <programlisting language="java">import org.exoplatform.services.cache.future.Loader;
import org.exoplatform.services.cache.future.FutureExoCache;
...
   // Define first your loader and choose properly your context object in order
   // to be able to reuse the same loader for different FutureExoCache instances
   Loader&lt;String, String, String&gt; loader = new Loader&lt;String, String, String&gt;()
   { 
      public String retrieve(String context, String key) throws Exception
      {
         return "Value loaded thanks to the key = '" + key + "' and the context = '" + context + "'";
      }
   };
   // Create your FutureExoCache from your eXo cache instance and your loader
   FutureExoCache&lt;String, String, String&gt; myFutureExoCache = new FutureExoCache&lt;String, String, String&gt;(loader, myExoCache);
   // Get your data from your future cache instance
   System.out.println(myFutureExoCache.get("my context", "foo"));</programlisting>
    </section>
  </section>

  <section id="Kernel.Cache.Extension">
    <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:</para>

    <programlisting language="java">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>As you can see, there is only one method to implement which can 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:</para>

    <programlisting language="xml">&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>

    <note>
      <para>Since kernel 2.3.0-CR1, if the configuration is not a sub class of
      <envar>ExoCacheConfig</envar> and the implementation given in the
      configuration is the full qualified name of an existing implementation
      of eXo Cache, we will assume that the user expects to have an instance
      of this eXo Cache type so we won't use the configured cache
      factory.</para>
    </note>
  </section>

  <section id="Kernel.Cache.eXo_Cache_based_Jobss_Cache">
    <title>eXo Cache based on JBoss Cache</title>

    <section id="Kernel.Cache.eXo_Cache_based_Jobss_Cache.ConfiguringExoCacheFactory">
      <title>Configuring 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:</para>

      <programlisting language="xml">&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;value-param&gt;
        &lt;name&gt;allow.shareable.cache&lt;/name&gt;
        &lt;value&gt;true&lt;/value&gt;
      &lt;/value-param&gt;
    &lt;/init-params&gt;
  &lt;/component&gt;   
&lt;/configuration&gt;</programlisting>

      <table>
        <title>Fields description</title>

        <tgroup cols="2">
          <tbody>
            <row>
              <entry>cache.config.template</entry>

              <entry>This parameter allows you to define the location of the
              default configuration template of JBoss Cache. In the default
              configuration, we ask the eXo kernel to get the file shipped
              into the jar at
              <emphasis>/conf/portal/cache-configuration-template.xml</emphasis>.
              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></entry>
            </row>

            <row>
              <entry>allow.shareable.cache</entry>

              <entry>This parameter allows you to Indicate whether the JBoss
              Cache instances used can by default be shared between several
              eXo caches instances. indeed to consume less resources, you can
              allow to use the same instance of JBoss Cache for several eXo
              Cache instances, each eXo Cache Instances will have his own
              cache region with its own eviction configuration. The default
              value of this parameter is <emphasis>false</emphasis>.<note>
                  <para>This value is only the default value that cans be
                  redefined at <envar>ExoCacheConfig</envar> level thanks to
                  the field <emphasis>allowShareableCache</emphasis> for more
                  details see the next sections.</para>
                </note></entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    </section>

    <section id="Kernel.Cache.eXo_Cache_based_Jobss_Cache.AddingSpecificConfigurationForCache">
      <title>Adding 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:</para>

      <programlisting language="xml">&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>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 id="Kernel.Cache.eXo_Cache_based_Jobss_Cache.AddingCacheCreator">
      <title>Adding a cache creator</title>

      <section id="Kernel.Cache.eXo_Cache_based_Jobss_Cache.UnderstandingCacheCreator">
        <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:</para>

        <programlisting language="java">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>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 and 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 id="Kernel.Cache.eXo_Cache_based_Jobss_Cache.RegisteringCacheCreator">
        <title>Registering a cache creator</title>

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

        <programlisting language="xml">  &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>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 id="Kernel.Cache.eXo_Cache_based_Jobss_Cache.CacheCreatorsAvailable">
        <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 id="Kernel.Cache.eXo_Cache_based_Jobss_Cache.CacheCreatorsAvailable.LRUCacheCreator">
          <title>LRU Cache Creator - Least Recently Used</title>

          <programlisting language="xml">..
&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 used when
                  we define a cache of this type with the old
                  configuration.</entry>
                </row>

                <row>
                  <entry>defaultMaxAge</entry>

                  <entry>This is the default value of the field
                  <emphasis>maxAge</emphasis> described in the section
                  dedicated to this cache type. This value is only used when
                  we define a cache of this type with the old
                  configuration.</entry>
                </row>
              </tbody>
            </tgroup>
          </table>
        </section>

        <section id="Kernel.Cache.eXo_Cache_based_Jobss_Cache.CacheCreatorsAvailable.FIFOCacheCreator">
          <title>FIFO Cache Creator - First In, First Out</title>

          <programlisting language="xml">...
&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 id="Kernel.Cache.eXo_Cache_based_Jobss_Cache.CacheCreatorsAvailable.MRUCacheCreator">
          <title>MRU Cache Creator - Most Recently Used</title>

          <programlisting language="xml">...
&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 id="Kernel.Cache.eXo_Cache_based_Jobss_Cache.CacheCreatorsAvailable.LFUCacheCreator">
          <title>LFU Cache Creator - Least Frequently Used</title>

          <programlisting language="xml">...
&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 used when
                  we define a cache of this type with the old
                  configuration.</entry>
                </row>
              </tbody>
            </tgroup>
          </table>
        </section>

        <section id="Kernel.Cache.eXo_Cache_based_Jobss_Cache.CacheCreatorsAvailable.EACacheCreator">
          <title>EA Cache Creator - Expiration Algorithm</title>

          <programlisting language="xml">...
&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 used when
                  we define a cache of this type with the old
                  configuration.</entry>
                </row>
              </tbody>
            </tgroup>
          </table>
        </section>
      </section>
    </section>

    <section id="Kernel.Cache.eXo_Cache_based_Jobss_Cache.DefiningCache">
      <title>Defining a cache</title>

      <section id="Kernel.Cache.eXo_Cache_based_Jobss_Cache.DefiningCache.HowDefineCache">
        <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 id="Kernel.Cache.eXo_Cache_based_Jobss_Cache.DefiningCache.HowDefineCache.CacheServiceInitialization">
          <title>At <envar>CacheService</envar> initialization</title>

          <programlisting language="xml">...
  &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 id="Kernel.Cache.eXo_Cache_based_Jobss_Cache.DefiningCache.HowDefineCache.ExternalPlugin">
          <title>With an <emphasis>"external plugin"</emphasis></title>

          <programlisting language="xml">...
  &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 id="Kernel.Cache.eXo_Cache_based_Jobss_Cache.DefiningCache.HowDefineDistributedLocalCache">
        <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 definde 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 id="Kernel.Cache.eXo_Cache_based_Jobss_Cache.DefiningCache.HowShareJBossCacheInstanceBetMultipleeXoCacheInstances">
        <title>How to share a JBoss Cache instance between multiple eXo Cache
        instances</title>

        <para>In order to avoid creating several JBoss Cache instances that
        consume resources, it is possible to share the same JBoss Cache
        instance between multiple eXo Cache instances that rely on the same
        JBoss Cache config. Each eXo Cache instances will then have their own
        cache region with their own eviction configuration. To allow sharing
        JBoss Cache instances, you can set the global value at
        <emphasis>ExoCacheFactory</emphasis> level and if needed set the local
        value at <emphasis>ExoCacheConfig</emphasis> level knowing that local
        value will redefine the global value. Each new
        <emphasis>ExoCacheConfig</emphasis> described below are a sub class of
        <emphasis>AbstractExoCacheConfig</emphasis> that gives access to the
        parameter <emphasis>allowShareableCache</emphasis>, if this parameter
        is set, it will be the value used otherwise it will use the global
        value. For all the old <emphasis>ExoCacheConfig</emphasis>, only the
        global value will be used.</para>
      </section>

      <section id="Kernel.Cache.eXo_Cache_based_Jobss_Cache.DefiningCache.LRUCache">
        <title>LRU Cache - Least Recently Used</title>

        <itemizedlist>
          <listitem>
            <para>New configuration</para>
          </listitem>
        </itemizedlist>

        <programlisting language="xml">...
       &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) that 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 that 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>

        <itemizedlist>
          <listitem>
            <para>Old configuration</para>
          </listitem>
        </itemizedlist>

        <programlisting language="xml">...
      &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) that 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>

        <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>
      </section>

      <section id="Kernel.Cache.eXo_Cache_based_Jobss_Cache.DefiningCache.FIFOCache">
        <title>FIFO Cache - First In, First Out</title>

        <itemizedlist>
          <listitem>
            <para>New configuration</para>
          </listitem>
        </itemizedlist>

        <programlisting language="xml">...
       &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>

        <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) that 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>

        <itemizedlist>
          <listitem>
            <para>Old configuration</para>
          </listitem>
        </itemizedlist>

        <programlisting language="xml">...
       &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>

        <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) that 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>
      </section>

      <section id="Kernel.Cache.eXo_Cache_based_Jobss_Cache.DefiningCache.MRUCache">
        <title>MRU Cache - Most Recently Used</title>

        <itemizedlist>
          <listitem>
            <para>New configuration</para>
          </listitem>
        </itemizedlist>

        <programlisting language="xml">...
       &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>

        <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) that 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>

        <itemizedlist>
          <listitem>
            <para>Old configuration</para>
          </listitem>
        </itemizedlist>

        <programlisting language="xml">...
      &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>

        <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) that 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>
      </section>

      <section id="Kernel.Cache.eXo_Cache_based_Jobss_Cache.DefiningCache.LFUCache">
        <title>LFU Cache - Least Frequently Used</title>

        <itemizedlist>
          <listitem>
            <para>New configuration</para>
          </listitem>
        </itemizedlist>

        <programlisting language="xml">...
       &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>

        <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) that 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>

        <itemizedlist>
          <listitem>
            <para>Old configuration</para>
          </listitem>
        </itemizedlist>

        <programlisting language="xml">...
      &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>

        <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) that 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>
      </section>

      <section id="Kernel.Cache.eXo_Cache_based_Jobss_Cache.DefiningCache.EACache">
        <title>EA Cache - Expiration Algorithm</title>

        <itemizedlist>
          <listitem>
            <para>New configuration</para>
          </listitem>
        </itemizedlist>

        <programlisting language="xml">...
       &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>

        <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) that 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>

        <itemizedlist>
          <listitem>
            <para>Old configuration</para>
          </listitem>
        </itemizedlist>

        <programlisting language="xml">...
      &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>

        <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) that 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>
      </section>
    </section>
  </section>

  <section id="Kernel.Cache.Based_Infinispan">
    <title>eXo Cache based on Infinispan</title>

    <section id="Kernel.Cache.Based_Infinispan.ConfigureExoCacheFactory">
      <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:</para>

      <programlisting language="xml">&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>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.</para>

      <note>
        <para>All the cache instances fo which we configure the same cluster
        name will also share the same
        <envar>EmbeddedCacheManager.</envar></para>
      </note>
    </section>

    <section id="Kernel.Cache.Based_Infinispan.AddSpecificConfigurationForCache">
      <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:</para>

      <programlisting language="xml">&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>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 id="Kernel.Cache.Based_Infinispan.AddCacheCreator">
      <title>Add a cache creator</title>

      <section id="Kernel.Cache.Based_Infinispan.AddCacheCreator.UnderstandingCacheCreator">
        <title>Understanding a cache creator</title>

        <para>The factory for infinispan, delegates the cache creation to
        <envar>ExoCacheCreator</envar> that is defined as below:</para>

        <programlisting language="java">package org.exoplatform.services.cache.impl.infinispan;
...
public interface ExoCacheCreator {

   /**
    * Creates an eXo cache according to the given configuration {@link org.exoplatform.services.cache.ExoCacheConfig}
    * @param config the configuration of the cache to apply
    * @param confBuilder the configuration builder of the infinispan cache
    * @param cacheGetter a {@link Callable} instance from which we can get the cache
    * @exception ExoCacheInitException if an exception happens while initializing the cache
    */
   public ExoCache&lt;Serializable, Object&gt; create(ExoCacheConfig config, ConfigurationBuilder confBuilder, 
            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>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 id="Kernel.Cache.Based_Infinispan.AddCacheCreator.RegisterCacheCreator">
        <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:</para>

        <programlisting language="xml">  &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>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 id="Kernel.Cache.Based_Infinispan.AddCacheCreator.CacheCreatorsAvailable">
        <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 id="Kernel.Cache.Based_Infinispan.AddCacheCreator.CacheCreatorsAvailable.GenericCacheCreator">
          <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 language="xml">..
&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 id="Kernel.Cache.Based_Infinispan.DefineInfinispanCacheInstance">
      <title>Define an infinispan cache instance</title>

      <section id="Kernel.Cache.Based_Infinispan.DefineInfinispanCacheInstance.HowDefineReplicatedDistributedLocalCache">
        <title>How to define a replicated, 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 fields <emphasis>distributed</emphasis> and
        <emphasis>replicated</emphasis> of your <envar>ExoCacheConfig</envar>
        to decide. In other words, if the value of these fields is false (the
        default value), the cache will be a local cache otherwise if the field
        <emphasis>distributed</emphasis> is set to true, the cache will be
        then be considered as distrbuted and will be retrieved from the
        <emphasis>DistributedCacheManager</emphasis> (more details about it in
        the next section). Finally if the field
        <emphasis>replicated</emphasis> is set to true, the cache mode of your
        cache will be the one defined in the configuration assuming that it
        should be replicated.</para>
      </section>

      <section id="Kernel.Cache.Based_Infinispan.DefineInfinispanCacheInstance.HowDefineInfinispanCacheInstance">
        <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>
          </listitem>
        </itemizedlist>

        <programlisting language="xml">...
       &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>

        <itemizedlist>
          <listitem>
            <para>Old configuration</para>
          </listitem>
        </itemizedlist>

        <programlisting language="xml">...
      &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>
      </section>
    </section>

    <section id="Kernel.Cache.Based_Infinispan.UsingInfinispanInDistributedMode">
      <title>Using Infinispan in distributed mode</title>

      <para>In order to be able to use infinispan in distributed mode with the
      ability to launch external JVM instances that will manage a part of the
      cache, we need to configure the
      <emphasis>DistributedCacheManager</emphasis>. In the next sections, we
      will show how to configure the component and how to launch external JVM
      instances.</para>

      <section id="Kernel.Cache.Based_Infinispan.UsingInfinispanInDistributedMode.ConfigurationOfDistributedCacheManager">
        <title>Configuration of the DistributedCacheManager</title>

        <para>The <emphasis>DistributedCacheManager</emphasis> is the
        component that will manage all the cache instances that we expect to
        be distributed, it must be unique in the whole JVM which means that it
        must be declared at <emphasis>RootContainer</emphasis> level in portal
        mode or at <emphasis>StandaloneContainer</emphasis> in standalone
        mode. See below an example of configuration.</para>

        <programlisting language="xml">&lt;component&gt;
  &lt;type&gt;org.exoplatform.services.ispn.DistributedCacheManager&lt;/type&gt;
  &lt;init-params&gt;
    &lt;value-param&gt;
      &lt;name&gt;infinispan-configuration&lt;/name&gt;
      &lt;value&gt;jar:/conf/distributed-cache-configuration.xml&lt;/value&gt;
    &lt;/value-param&gt;
    &lt;properties-param&gt;
      &lt;name&gt;parameters&lt;/name&gt;
      &lt;description&gt;The parameters of the configuration&lt;/description&gt;
      &lt;property name="configurationFile" value="${gatein.jcr.jgroups.config}"&gt;&lt;/property&gt;
      &lt;property name="invalidationThreshold" value="0"&gt;&lt;/property&gt;
      &lt;property name="numOwners" value="3"&gt;&lt;/property&gt;
      &lt;property name="numVirtualNodes" value="2"&gt;&lt;/property&gt;
    &lt;/properties-param&gt;     
  &lt;/init-params&gt;
&lt;/component&gt;</programlisting>

        <table>
          <title>Fields description</title>

          <tgroup cols="2">
            <tbody>
              <row>
                <entry>infinispan-configuration</entry>

                <entry>Location of the infinispan configuration to use in
                which all the distributed caches must be configured by name.
                All paths supported by the ConfigurationManager with prefixes
                like jar:/..., classpath:/..., etc. This parameter is
                mandatory.</entry>
              </row>

              <row>
                <entry>parameters</entry>

                <entry>In the configuration file, you can add a set of
                variables of type ${variable-name}, these variables will be
                solved using the values of the parameters. The name of the
                variable in the configuration file must match with the name of
                the parameter. This parameter is optional.</entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <para>As described above, the configuration of infinispan must defined
        explicitly each cache using the <emphasis>nameCache</emphasis> block
        no dynamic configuration of cache is supported. Indeed to ensure that
        the whole cluster is consistent in term of defined cache, it is
        required to configure all the cache that you will need and register it
        using its future name.</para>

        <para>For now, we have 2 supported cache name which are
        <emphasis>JCRCache</emphasis> and <emphasis>eXoCache</emphasis>.
        <emphasis>JCRCache</emphasis> is the name of the cache that we use in
        case we would like to store the data of the JCR into a distributed
        cache. <emphasis>eXoCache</emphasis> is the name of the cache that we
        use in case we would like to store the data of some eXo Cache
        instances into a distributed cache.</para>

        <para>See below an example of infinispan configuration with both
        <emphasis>eXoCache</emphasis> and <emphasis>JCRCache</emphasis>
        defined:</para>

        <programlisting>&lt;infinispan xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:infinispan:config:5.1 http://www.infinispan.org/schemas/infinispan-config-5.1.xsd"
  xmlns="urn:infinispan:config:5.1"&gt;
   &lt;global&gt;
      &lt;globalJmxStatistics jmxDomain="exo" enabled="true" allowDuplicateDomains="true"/&gt;
      &lt;transport transportClass="org.infinispan.remoting.transport.jgroups.JGroupsTransport" clusterName="JCR-cluster" distributedSyncTimeout="20000"&gt;
        &lt;properties&gt;
          &lt;property name="configurationFile" value="${configurationFile}"/&gt;
        &lt;/properties&gt;
      &lt;/transport&gt;
      &lt;shutdown hookBehavior="DEFAULT"/&gt;
   &lt;/global&gt;
   &lt;namedCache name="JCRCache"&gt;
      &lt;locking isolationLevel="READ_COMMITTED" lockAcquisitionTimeout="120000" writeSkewCheck="false" concurrencyLevel="500" useLockStriping="true" /&gt;
      &lt;transaction transactionManagerLookupClass="org.infinispan.transaction.lookup.GenericTransactionManagerLookup" syncRollbackPhase="true" syncCommitPhase="true" eagerLockSingleNode="true" transactionMode="TRANSACTIONAL"/&gt;
      &lt;jmxStatistics enabled="true"/&gt;
      &lt;clustering mode="distribution"&gt;
        &lt;l1 enabled="true" invalidationThreshold="${invalidationThreshold}"/&gt;
         &lt;hash numOwners="${numOwners}" numVirtualNodes="${numVirtualNodes}" rehashRpcTimeout="120000"&gt;
           &lt;groups enabled="true"/&gt;
         &lt;/hash&gt;
         &lt;sync replTimeout="180000"/&gt;
      &lt;/clustering&gt;
   &lt;/namedCache&gt;
   &lt;namedCache name="eXoCache"&gt;
      &lt;locking isolationLevel="READ_COMMITTED" lockAcquisitionTimeout="120000" writeSkewCheck="false" concurrencyLevel="500" useLockStriping="true" /&gt;
      &lt;transaction transactionManagerLookupClass="org.infinispan.transaction.lookup.GenericTransactionManagerLookup" syncRollbackPhase="true" syncCommitPhase="true" eagerLockSingleNode="true" transactionMode="TRANSACTIONAL"/&gt;
      &lt;jmxStatistics enabled="true"/&gt;
      &lt;clustering mode="distribution"&gt;
         &lt;l1 enabled="true" invalidationThreshold="${invalidationThreshold}"/&gt;
         &lt;hash numOwners="${numOwners}" numVirtualNodes="${numVirtualNodes}" rehashRpcTimeout="120000"/&gt;
         &lt;sync replTimeout="180000"/&gt;
      &lt;/clustering&gt;
   &lt;/namedCache&gt;
&lt;/infinispan&gt;</programlisting>
      </section>

      <section id="Kernel.Cache.Based_Infinispan.UsingInfinispanInDistributedMode.LaunchCacheServer">
        <title>Launch a CacheServer</title>

        <para>In case you intend to use the distribued mode, you can launch
        external JVM in standalone mode to provide more memory to your current
        cache. To do so, you will need to get the file of type
        <emphasis>exo.jcr.component.core.impl.infinispan.v5-binary.zip</emphasis>
        in which you will find scripts to launch your cache servers. These
        scripts allow optional arguments that are described below:</para>

        <para><emphasis>help|?|&lt;configuration-file-path&gt;|udp|tcp
        &lt;initial-hosts&gt;</emphasis></para>

        <table>
          <title>Arguments description</title>

          <tgroup cols="2">
            <tbody>
              <row>
                <entry>help</entry>

                <entry>Print the expected syntax.</entry>
              </row>

              <row>
                <entry>?</entry>

                <entry>Print the expected syntax.</entry>
              </row>

              <row>
                <entry>configuration-file-path</entry>

                <entry>The location of the configuration file to use, we
                expect an absolute path. It will try to get it using the
                current class loader, if it cannot be found it will get it
                from the file system. By default it will use the path
                <emphasis>/conf/cache-server-configuration.xml</emphasis> that
                is actually a file bundled into the jar.</entry>
              </row>

              <row>
                <entry>udp</entry>

                <entry>We use this parameter value when we want to use the
                default configuration file with udp as transport stack which
                is actually the default stack used which means that it will
                have the exact same behavior as when we don't provide any
                parameter.</entry>
              </row>

              <row>
                <entry>tcp</entry>

                <entry>We use this parameter value when we want to use the
                default configuration file with tcp as transport
                stack.</entry>
              </row>

              <row>
                <entry>initial-hosts</entry>

                <entry>This parameter is optional and is only allowed in case
                the tcp stack is enabled, it will allow you to define the set
                of hosts that will be part of the cluster. The syntax of this
                parameter is a list of hostname[port] comma-separated. Knowing
                that the default value is "localhost[7800],localhost[7801]" if
                this parameter is not set, the bind address will be
                automatically set to 127.0.0.1 so you need to ensure that your
                server is configured to have it mapped to localhost.</entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <note>
          <para>If you intend to use the CacheServer in order to manage some
          of your eXo Cache instances, don't forget to add the jar files that
          define both the keys and the values in the lib directory of the
          CacheServer distribution and restarts your CacheServer instances
          otherwise the unmarshalling will fail with
          <emphasis>java.lang.ClassNotFoundException</emphasis>.</para>
        </note>
      </section>

      <section id="Kernel.Cache.Based_Infinispan.UsingInfinispanInDistributedMode.ConfigureCacheOfWorkspace">
        <title>Configure the cache of your workspace</title>

        <para>In case you would like to configure your workspace in order to
        rely on a distributed cache apart using
        <emphasis>org.exoplatform.services.jcr.impl.dataflow.persistent.infinispan.ISPNCacheWorkspaceStorageCache</emphasis>
        as FQN of your cache you will need to set the property
        <emphasis>use-distributed-cache</emphasis> to
        <emphasis>true</emphasis>. If you do so the JCR cache will rely on the
        cache called <emphasis>JCRCache</emphasis> defined in the infinispan
        configuration provided to the
        <emphasis>DistributedCacheManager</emphasis>.</para>
      </section>
    </section>
  </section>
</section>
