From do-not-reply at jboss.org Tue Dec 28 13:47:59 2010
Content-Type: multipart/mixed; boundary="===============0866698836441279090=="
MIME-Version: 1.0
From: do-not-reply at jboss.org
To: exo-jcr-commits at lists.jboss.org
Subject: [exo-jcr-commits] exo-jcr SVN: r3748 -
jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/kernel.
Date: Tue, 28 Dec 2010 13:47:59 -0500
Message-ID: <201012281847.oBSIlxol023919@svn01.web.mwc.hst.phx2.redhat.com>
--===============0866698836441279090==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
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
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- 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 @@
Understanding a cache creator
=
The factory for jboss cache, delegates the cache creation to
- ExoCacheCreator that is defines as
+ ExoCacheCreator that is defined as
below:package org.exoplatform.services.cache.impl.=
jboss;
...
public interface ExoCacheCreator {
@@ -1146,4 +1146,453 @@
+
+
+ eXo Cache based on Infinispan
+
+
+ Configure the ExoCacheFactory
+
+ 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 configurati=
on
+ if you wish as you can do with any components.
+
+ The default configuration of the factory is:&l=
t;configuration> =
+ <component>
+ <key>org.exoplatform.services.cache.ExoCacheFactory</key>
+ <type>org.exoplatform.services.cache.impl.infinispan.ExoCacheFac=
toryImpl</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>
+
+ As you can see the factory requires one single parameter which=
is
+ cache.config.template, this parameter allows yo=
u to
+ define the location of the default configuration template of your
+ infinispan. In the default configuration, we ask the eXo container to
+ get the file shipped into the jar at
+ /conf/portal/cache-configuration-template.xml.<=
/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.
+ All the cache instances that will rely on this cache
+ configuration will share the same
+ EmbeddedCacheManager.
+
+
+
+
+ Add specific configuration for a cache
+
+ If for a given reason, you need to use a specific configuration
+ for a cache, you can register one thanks to an "external
+ plugin", see an example below:<configu=
ration>
+ ...
+ <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.ExoCacheF=
actoryConfigPlugin</type>
+ <description>add Custom Configurations</description>
+ <init-params>
+ <value-param>
+ <name>myCustomCache</name>
+ <value>jar:/conf/portal/custom-cache-configuration.xml<=
/value>
+ </value-param> =
+ </init-params>
+ </component-plugin> =
+ </external-component-plugins> =
+ ... =
+</configuration>
+
+ In the example above, I call the method
+ addConfig(ExoCacheFactoryConfigPlugin plugin) on
+ the current implementation of ExoCacheFactory which is
+ actually the infinispan implementation.
+
+ In the init-params block, you can define a
+ set of value-param blocks and for each
+ value-param, we expect the name of cache that n=
eeds
+ a specific configuration as name and the location of your custom
+ configuration as value.
+
+ In this example, we indicates to the factory that we would like
+ that the cache myCustomCache use the configurat=
ion
+ available at
+ jar:/conf/portal/custom-cache-configuration.xml=
.
+
+
+ All the cache instances that will rely on the cache
+ configuration located at the same location will share the same
+ EmbeddedCacheManager.
+
+
+
+
+ Add a cache creator
+
+
+ Understanding a cache creator
+
+ The factory for infinispan, delegates the cache creation to
+ ExoCacheCreator that is defined as
+ below:package org.exoplatform.services.cache.impl.=
infinispan;
+...
+public interface ExoCacheCreator {
+
+ /**
+ * Creates an eXo cache according to the given configuration {@link org=
.exoplatform.services.cache.ExoCacheConfig}
+ * @param config the configuration of the cache to apply
+ * @param 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 initi=
alizing the cache
+ */
+ public ExoCache<Serializable, Object> create(ExoCacheConfig confi=
g, Configuration cacheConfig, Callable<Cache<Serializable, Object>=
> cacheGetter) throws ExoCacheInitException;
+
+ /**
+ * Returns the type of {@link org.exoplatform.services.cache.ExoCacheCo=
nfig} expected by the creator =
+ * @return the expected type
+ */
+ public Class<? extends ExoCacheConfig> getExpectedConfigType();
+
+ /**
+ * Returns a set of all the implementations expected by the creator. Th=
is is mainly used to be backward compatible
+ * @return the expected by the creator
+ */
+ public Set<String> getExpectedImplementations();
+}
+
+ The ExoCacheCreator allows you to define any =
kind
+ of infinispan cache instance that you would like to have. It has b=
een
+ designed to give you the ability to have your own type of
+ configuration and to always be backward compatible.
+
+ In an ExoCacheCreator, you need to implement 3
+ methods which are:
+
+
+
+ create - this method is used to cre=
ate
+ a new ExoCache from the
+ ExoCacheConfig, an inifinispan cache configurat=
ion
+ and a Callable object to allow you to get the cache
+ instance.
+
+
+
+ getExpectedConfigType - this method=
is
+ used to indicate the factory the subtype of
+ ExoCacheConfig supported by the creator.
+
+
+
+ getExpectedImplementations - this
+ method is used to indicate the factory the values of the field
+ implementation of
+ ExoCacheConfig that is supported by the creator.
+ This is used for backward compatibility, in other words you can
+ still configure your cache with an instance of
+ ExoCacheConfig.
+
+
+
+
+
+ Register a cache creator
+
+ You can register any cache creator you want thanks to an
+ "external plugin", see an example
+ below: <external-component-plugins>
+ <target-component>org.exoplatform.services.cache.ExoCacheFactory=
</target-component>
+ <component-plugin>
+ <name>addCreator</name>
+ <set-method>addCreator</set-method>
+ <type>org.exoplatform.services.cache.impl.infinispan.ExoCacheC=
reatorPlugin</type>
+ <description>add Exo Cache Creator</description>
+ <init-params>
+ <object-param>
+ <name>Test</name>
+ <description>The cache creator for testing purpose</des=
cription>
+ <object type=3D"org.exoplatform.services.cache.impl.infinispa=
n.TestExoCacheCreator"></object>
+ </object-param> =
+ </init-params>
+ </component-plugin>
+ </external-component-plugins>
+
+ In the example above, I call the method
+ addCreator(ExoCacheCreatorPlugin plugin) on t=
he
+ current implementation of ExoCacheFactory which is
+ actually the infinispan implementation.
+
+ In the init-params block, you can defin=
e a
+ set of object-param blocks and for each
+ object-param, we expect any object definition=
of
+ type ExoCacheCreator.
+
+ In this example, we register the cache creator related to the
+ eviction policy Test.
+
+
+
+ The cache creators available
+
+ By default, no cache creator are defined, so you need to def=
ine
+ them yourself by adding them in your configuration files.
+
+
+ Generic Cache Creator
+
+ This is the generic cache creator that allows you to use a=
ny
+ eviction strategies defined by default in Infinispan.
+
+ ..
+<object-param>
+ <name>GENERIC</name>
+ <description>The generic cache creator</description>
+ <object type=3D"org.exoplatform.services.cache.impl.infinispan.generi=
c.GenericExoCacheCreator">
+ <field name=3D"implementations">
+ <collection type=3D"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=3D"defaultStrategy"><string>${my-value}</st=
ring></field>
+ <field name=3D"defaultMaxIdle"><long>${my-value}</long&=
gt;</field>
+ <field name=3D"defaultWakeUpInterval"><long>${my-value}<=
;/long></field>
+ </object>
+</object-param>
+...
+
+
+ Fields description
+
+
+
+
+ implementations
+
+ This is the list of all the
+ implementations supported by the ca=
che
+ 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 h=
ave
+ the full list of all the eviction strategies currently
+ supported by infinispan 4.1. This field is used to manage
+ the backward compatibility.
+
+
+
+ defaultStrategy
+
+ This is the name of the default eviction strategy=
to
+ use. By default the value is LRU. T=
his
+ value is only use when we define a cache of this type wi=
th
+ the old configuration.
+
+
+
+ defaultMaxIdle
+
+ This is the default value of the field
+ maxIdle described in the section
+ dedicated to this cache type. By default the value is
+ -1.This value is only use when we
+ define a cache of this type with the old
+ configuration.
+
+
+
+ defaultWakeUpInterval
+
+ his is the default value of the field
+ wakeUpInterval described in the sec=
tion
+ dedicated to this cache type. By default the value is
+ 5000.This value is only use when we
+ define a cache of this type with the old
+ configuration
+
+
+
+
+
+
+
+
+
+ Define an infinispan cache instance
+
+
+ How to define a distributed or a local cache?
+
+ 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.
+
+ In case, you decide to use the default configuration templat=
e,
+ we use the field distributed of your
+ ExoCacheConfig to decide. In other words, if the va=
lue
+ of this field is false (the default value), the cache will be a lo=
cal
+ cache otherwise it will be the cache mode defined in your default
+ configuration template that should be distributed.
+
+
+
+ How to define an infinispan cache instance
+
+ All the eviction strategies proposed by default in infinispan
+ rely on the generic cache creator.
+
+
+
+ New configuration
+
+ ...
+ <object-param>
+ <name>myCache</name>
+ <description>My cache configuration</description>
+ <object type=3D"org.exoplatform.services.cache.impl.infinispan.=
generic.GenericExoCacheConfig">
+ <field name=3D"name"><string>myCacheName</string&=
gt;</field>
+ <field name=3D"strategy"><int>${my-value}</int>=
;</field>
+ <field name=3D"maxEntries"><long>${my-value}</lon=
g></field>
+ <field name=3D"lifespan"><long>${my-value}</long&=
gt;</field>
+ <field name=3D"maxIdle"><long>${my-value}</long&g=
t;</field>
+ <field name=3D"wakeUpInterval"><long>${my-value}<=
/long></field>
+ </object>
+ </object-param> =
+...
+ Fields description
+
+
+
+
+ strategy
+
+ The name of the strategy to use such as
+ 'UNORDERED', 'FIFO', 'LRU', 'LIRS' and 'NONE' (to
+ disable eviction).
+
+
+
+ maxEntries
+
+ Maximum number of entries in a cache instance=
. If
+ selected value is not a power of two the actual value
+ will default to the least power of two larger than
+ selected value. -1 means no limit which is also the
+ default value.
+
+
+
+ lifespan
+
+ Maximum lifespan of a cache entry, after which
+ the entry is expired cluster-wide, in milliseconds. =
-1
+ means the entries never expire which is also the def=
ault
+ value.
+
+
+
+ maxIdle
+
+ Maximum idle time a cache entry will be
+ maintained in the cache, in milliseconds. If the idle
+ time is exceeded, the entry will be expired
+ cluster-wide. -1 means the entries never expire whic=
h is
+ also the default value.
+
+
+
+ wakeUpInterval
+
+ 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.
+
+
+
+
+
+
+
+ Old configuration
+
+ ...
+ <object-param>
+ <name>myCache</name>
+ <description>My cache configuration</description>
+ <field name=3D"name"><string>lru-with-old-config<=
/string></field>
+ <field name=3D"maxSize"><int>${my-value}</int>=
</field>
+ <field name=3D"liveTime"><long>${my-value}</long&=
gt;</field>
+ <field name=3D"implementation"><string>${my-value}&l=
t;/string></field>
+ </object>
+ </object-param> =
+...
+
+
+ Fields description
+
+
+
+
+ maxSize
+
+ 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.
+
+
+
+ liveTime
+
+ Maximum lifespan of a cache entry, after which =
the
+ entry is expired cluster-wide, in milliseconds. -1 mea=
ns
+ the entries never expire which is also the default
+ value.
+
+
+
+ implementation
+
+ The name of the implementation to use the expec=
ted
+ value is one of the eviction strategies defined in the
+ field implementations of the gene=
ric
+ cache creator.
+
+
+
+
+
+
+ For the fields maxIdle and
+ wakeUpInterval needed by infinispan, =
we
+ will use the default values provided by the creator.
+
+
+
+
+
+
--===============0866698836441279090==--