[exo-jcr-commits] exo-jcr SVN: r3748 - jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/kernel.
do-not-reply at jboss.org
do-not-reply at jboss.org
Tue Dec 28 13:47:59 EST 2010
Author: nfilotto
Date: 2010-12-28 13:47:59 -0500 (Tue, 28 Dec 2010)
New Revision: 3748
Modified:
jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/kernel/cache.xml
Log:
EXOJCR-1129: doc of the ISPN implementation of eXo Cache has been added
Modified: jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/kernel/cache.xml
===================================================================
--- jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/kernel/cache.xml 2010-12-28 16:31:16 UTC (rev 3747)
+++ jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/kernel/cache.xml 2010-12-28 18:47:59 UTC (rev 3748)
@@ -300,7 +300,7 @@
<title>Understanding a cache creator</title>
<para>The factory for jboss cache, delegates the cache creation to
- <envar>ExoCacheCreator</envar> that is defines as
+ <envar>ExoCacheCreator</envar> that is defined as
below:<programlisting>package org.exoplatform.services.cache.impl.jboss;
...
public interface ExoCacheCreator {
@@ -1146,4 +1146,453 @@
</section>
</section>
</section>
+
+ <section>
+ <title>eXo Cache based on Infinispan</title>
+
+ <section>
+ <title>Configure the ExoCacheFactory</title>
+
+ <para>When you add the related jar file in your classpath, the eXo
+ service container will use the default configuration provided in the
+ library itself but of course you can still redefined the configuration
+ if you wish as you can do with any components.</para>
+
+ <para>The default configuration of the factory is:<programlisting><configuration>
+ <component>
+ <key>org.exoplatform.services.cache.ExoCacheFactory</key>
+ <type>org.exoplatform.services.cache.impl.infinispan.ExoCacheFactoryImpl</type>
+ <init-params>
+ <value-param>
+ <name>cache.config.template</name>
+ <value>jar:/conf/portal/cache-configuration-template.xml</value>
+ </value-param>
+ </init-params>
+ </component>
+</configuration></programlisting></para>
+
+ <para>As you can see the factory requires one single parameter which is
+ <emphasis>cache.config.template</emphasis>, this parameter allows you to
+ define the location of the default configuration template of your
+ infinispan. In the default configuration, we ask the eXo container to
+ get the file shipped into the jar at
+ <emphasis>/conf/portal/cache-configuration-template.xml</emphasis>.</para>
+
+ <para>The default configuration template aims to be the skeleton from
+ which we will create any type of infinispan cache instance, thus it must
+ be very generic. <note>
+ <para>All the cache instances that will rely on this cache
+ configuration will share the same
+ <envar>EmbeddedCacheManager.</envar></para>
+ </note></para>
+ </section>
+
+ <section>
+ <title>Add specific configuration for a cache</title>
+
+ <para>If for a given reason, you need to use a specific configuration
+ for a cache, you can register one thanks to an "<emphasis>external
+ plugin</emphasis>", see an example below:<programlisting><configuration>
+ ...
+ <external-component-plugins>
+ <target-component>org.exoplatform.services.cache.ExoCacheFactory</target-component>
+ <component-plugin>
+ <name>addConfig</name>
+ <set-method>addConfig</set-method>
+ <type>org.exoplatform.services.cache.impl.infinispan.ExoCacheFactoryConfigPlugin</type>
+ <description>add Custom Configurations</description>
+ <init-params>
+ <value-param>
+ <name>myCustomCache</name>
+ <value>jar:/conf/portal/custom-cache-configuration.xml</value>
+ </value-param>
+ </init-params>
+ </component-plugin>
+ </external-component-plugins>
+ ...
+</configuration></programlisting></para>
+
+ <para>In the example above, I call the method
+ <emphasis>addConfig(ExoCacheFactoryConfigPlugin plugin)</emphasis> on
+ the current implementation of <envar>ExoCacheFactory</envar> which is
+ actually the infinispan implementation.</para>
+
+ <para>In the <emphasis>init-params</emphasis> block, you can define a
+ set of <emphasis>value-param</emphasis> blocks and for each
+ <emphasis>value-param</emphasis>, we expect the name of cache that needs
+ a specific configuration as name and the location of your custom
+ configuration as <emphasis>value</emphasis>.</para>
+
+ <para>In this example, we indicates to the factory that we would like
+ that the cache <emphasis>myCustomCache</emphasis> use the configuration
+ available at
+ <emphasis>jar:/conf/portal/custom-cache-configuration.xml</emphasis>.</para>
+
+ <note>
+ <para>All the cache instances that will rely on the cache
+ configuration located at the same location will share the same
+ <envar>EmbeddedCacheManager</envar>.</para>
+ </note>
+ </section>
+
+ <section>
+ <title>Add a cache creator</title>
+
+ <section>
+ <title>Understanding a cache creator</title>
+
+ <para>The factory for infinispan, delegates the cache creation to
+ <envar>ExoCacheCreator</envar> that is defined as
+ below:<programlisting>package org.exoplatform.services.cache.impl.infinispan;
+...
+public interface ExoCacheCreator {
+
+ /**
+ * Creates an eXo cache according to the given configuration {@link org.exoplatform.services.cache.ExoCacheConfig}
+ * @param config the configuration of the cache to apply
+ * @param cacheConfig the configuration of the infinispan cache
+ * @param cacheGetter a {@link Callable} instance from which we can get the cache
+ * @exception ExoCacheInitException if an exception happens while initializing the cache
+ */
+ public ExoCache<Serializable, Object> create(ExoCacheConfig config, Configuration cacheConfig, Callable<Cache<Serializable, Object>> cacheGetter) throws ExoCacheInitException;
+
+ /**
+ * Returns the type of {@link org.exoplatform.services.cache.ExoCacheConfig} expected by the creator
+ * @return the expected type
+ */
+ public Class<? extends ExoCacheConfig> getExpectedConfigType();
+
+ /**
+ * Returns a set of all the implementations expected by the creator. This is mainly used to be backward compatible
+ * @return the expected by the creator
+ */
+ public Set<String> getExpectedImplementations();
+}</programlisting></para>
+
+ <para>The <envar>ExoCacheCreator</envar> allows you to define any kind
+ of infinispan cache instance that you would like to have. It has been
+ designed to give you the ability to have your own type of
+ configuration and to always be backward compatible.</para>
+
+ <para>In an <envar>ExoCacheCreator</envar>, you need to implement 3
+ methods which are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>create</emphasis> - this method is used to create
+ a new <envar>ExoCache</envar> from the
+ <envar>ExoCacheConfig</envar>, an inifinispan cache configuration
+ and a Callable object to allow you to get the cache
+ instance.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>getExpectedConfigType</emphasis> - this method is
+ used to indicate the factory the subtype of
+ <envar>ExoCacheConfig</envar> supported by the creator.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>getExpectedImplementation</emphasis>s - this
+ method is used to indicate the factory the values of the field
+ <emphasis>implementation</emphasis> of
+ <envar>ExoCacheConfig</envar> that is supported by the creator.
+ This is used for backward compatibility, in other words you can
+ still configure your cache with an instance of
+ <envar>ExoCacheConfig</envar>.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Register a cache creator</title>
+
+ <para>You can register any cache creator you want thanks to an
+ <emphasis>"external plugin"</emphasis>, see an example
+ below:<programlisting> <external-component-plugins>
+ <target-component>org.exoplatform.services.cache.ExoCacheFactory</target-component>
+ <component-plugin>
+ <name>addCreator</name>
+ <set-method>addCreator</set-method>
+ <type>org.exoplatform.services.cache.impl.infinispan.ExoCacheCreatorPlugin</type>
+ <description>add Exo Cache Creator</description>
+ <init-params>
+ <object-param>
+ <name>Test</name>
+ <description>The cache creator for testing purpose</description>
+ <object type="org.exoplatform.services.cache.impl.infinispan.TestExoCacheCreator"></object>
+ </object-param>
+ </init-params>
+ </component-plugin>
+ </external-component-plugins></programlisting></para>
+
+ <para>In the example above, I call the method
+ <emphasis>addCreator(ExoCacheCreatorPlugin plugin)</emphasis> on the
+ current implementation of <envar>ExoCacheFactory</envar> which is
+ actually the infinispan implementation.</para>
+
+ <para>In the <emphasis>init-params</emphasis> block, you can define a
+ set of <emphasis>object-param</emphasis> blocks and for each
+ <emphasis>object-param</emphasis>, we expect any object definition of
+ type <envar>ExoCacheCreator</envar>.</para>
+
+ <para>In this example, we register the cache creator related to the
+ eviction policy <emphasis>Test</emphasis>.</para>
+ </section>
+
+ <section>
+ <title>The cache creators available</title>
+
+ <para>By default, no cache creator are defined, so you need to define
+ them yourself by adding them in your configuration files.</para>
+
+ <section>
+ <title>Generic Cache Creator</title>
+
+ <para>This is the generic cache creator that allows you to use any
+ eviction strategies defined by default in Infinispan.</para>
+
+ <programlisting>..
+<object-param>
+ <name>GENERIC</name>
+ <description>The generic cache creator</description>
+ <object type="org.exoplatform.services.cache.impl.infinispan.generic.GenericExoCacheCreator">
+ <field name="implementations">
+ <collection type="java.util.HashSet">
+ <value>
+ <string>NONE</string>
+ </value>
+ <value>
+ <string>FIFO</string>
+ </value>
+ <value>
+ <string>LRU</string>
+ </value>
+ <value>
+ <string>UNORDERED</string>
+ </value>
+ <value>
+ <string>LIRS</string>
+ </value>
+ </collection>
+ </field>
+ <field name="defaultStrategy"><string>${my-value}</string></field>
+ <field name="defaultMaxIdle"><long>${my-value}</long></field>
+ <field name="defaultWakeUpInterval"><long>${my-value}</long></field>
+ </object>
+</object-param>
+...</programlisting>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>implementations</entry>
+
+ <entry>This is the list of all the
+ <emphasis>implementations</emphasis> supported by the cache
+ creator. Actualy, it is a subset of the full list of the
+ eviction strategies supported by infinispan to which you
+ want to give access to. In the configuraton above, you have
+ the full list of all the eviction strategies currently
+ supported by infinispan 4.1. This field is used to manage
+ the backward compatibility.</entry>
+ </row>
+
+ <row>
+ <entry>defaultStrategy</entry>
+
+ <entry>This is the name of the default eviction strategy to
+ use. By default the value is <emphasis>LRU</emphasis>. This
+ value is only use when we define a cache of this type with
+ the old configuration.</entry>
+ </row>
+
+ <row>
+ <entry>defaultMaxIdle</entry>
+
+ <entry>This is the default value of the field
+ <emphasis>maxIdle</emphasis> described in the section
+ dedicated to this cache type. By default the value is
+ <emphasis>-1</emphasis>.This value is only use when we
+ define a cache of this type with the old
+ configuration.</entry>
+ </row>
+
+ <row>
+ <entry>defaultWakeUpInterval</entry>
+
+ <entry>his is the default value of the field
+ <emphasis>wakeUpInterval</emphasis> described in the section
+ dedicated to this cache type. By default the value is
+ <emphasis>5000</emphasis>.This value is only use when we
+ define a cache of this type with the old
+ configuration</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <title>Define an infinispan cache instance</title>
+
+ <section>
+ <title>How to define a distributed or a local cache?</title>
+
+ <para>Actually, if you use a custom configuration for your cache as
+ described in a previous section, we will use the cache mode define in
+ your configuration file.</para>
+
+ <para>In case, you decide to use the default configuration template,
+ we use the field <emphasis>distributed</emphasis> of your
+ <envar>ExoCacheConfig</envar> to decide. In other words, if the value
+ of this field is false (the default value), the cache will be a local
+ cache otherwise it will be the cache mode defined in your default
+ configuration template that should be distributed.</para>
+ </section>
+
+ <section>
+ <title>How to define an infinispan cache instance</title>
+
+ <para>All the eviction strategies proposed by default in infinispan
+ rely on the generic cache creator.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>New configuration</para>
+
+ <para><programlisting>...
+ <object-param>
+ <name>myCache</name>
+ <description>My cache configuration</description>
+ <object type="org.exoplatform.services.cache.impl.infinispan.generic.GenericExoCacheConfig">
+ <field name="name"><string>myCacheName</string></field>
+ <field name="strategy"><int>${my-value}</int></field>
+ <field name="maxEntries"><long>${my-value}</long></field>
+ <field name="lifespan"><long>${my-value}</long></field>
+ <field name="maxIdle"><long>${my-value}</long></field>
+ <field name="wakeUpInterval"><long>${my-value}</long></field>
+ </object>
+ </object-param>
+...</programlisting><table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>strategy</entry>
+
+ <entry>The name of the strategy to use such as
+ 'UNORDERED', 'FIFO', 'LRU', 'LIRS' and 'NONE' (to
+ disable eviction).</entry>
+ </row>
+
+ <row>
+ <entry>maxEntries</entry>
+
+ <entry>Maximum number of entries in a cache instance. If
+ selected value is not a power of two the actual value
+ will default to the least power of two larger than
+ selected value. -1 means no limit which is also the
+ default value.</entry>
+ </row>
+
+ <row>
+ <entry>lifespan</entry>
+
+ <entry>Maximum lifespan of a cache entry, after which
+ the entry is expired cluster-wide, in milliseconds. -1
+ means the entries never expire which is also the default
+ value.</entry>
+ </row>
+
+ <row>
+ <entry>maxIdle</entry>
+
+ <entry>Maximum idle time a cache entry will be
+ maintained in the cache, in milliseconds. If the idle
+ time is exceeded, the entry will be expired
+ cluster-wide. -1 means the entries never expire which is
+ also the default value.</entry>
+ </row>
+
+ <row>
+ <entry>wakeUpInterval</entry>
+
+ <entry>Interval between subsequent eviction runs, in
+ milliseconds. If you wish to disable the periodic
+ eviction process altogether, set wakeupInterval to -1.
+ The default value is 5000.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table></para>
+ </listitem>
+
+ <listitem>
+ <para>Old configuration</para>
+
+ <programlisting>...
+ <object-param>
+ <name>myCache</name>
+ <description>My cache configuration</description>
+ <field name="name"><string>lru-with-old-config</string></field>
+ <field name="maxSize"><int>${my-value}</int></field>
+ <field name="liveTime"><long>${my-value}</long></field>
+ <field name="implementation"><string>${my-value}</string></field>
+ </object>
+ </object-param>
+...</programlisting>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>maxSize</entry>
+
+ <entry>Maximum number of entries in a cache instance. If
+ selected value is not a power of two the actual value will
+ default to the least power of two larger than selected
+ value. -1 means no limit which is also the default
+ value.</entry>
+ </row>
+
+ <row>
+ <entry>liveTime</entry>
+
+ <entry>Maximum lifespan of a cache entry, after which the
+ entry is expired cluster-wide, in milliseconds. -1 means
+ the entries never expire which is also the default
+ value.</entry>
+ </row>
+
+ <row>
+ <entry>implementation</entry>
+
+ <entry>The name of the implementation to use the expected
+ value is one of the eviction strategies defined in the
+ field <emphasis>implementations</emphasis> of the generic
+ cache creator.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para><note>
+ <para>For the fields <emphasis>maxIdle</emphasis> and
+ <emphasis>wakeUpInterval</emphasis> needed by infinispan, we
+ will use the default values provided by the creator.</para>
+ </note></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+ </section>
</chapter>
More information about the exo-jcr-commits
mailing list