From do-not-reply at jboss.org Fri Aug 13 08:26:42 2010 Content-Type: multipart/mixed; boundary="===============6439597713039153005==" 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: r2916 - jcr/branches/1.14-ISPN/docs/reference/en/src/main/docbook/en-US/modules/kernel. Date: Fri, 13 Aug 2010 08:26:42 -0400 Message-ID: <201008131226.o7DCQge7001856@svn01.web.mwc.hst.phx2.redhat.com> --===============6439597713039153005== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: nfilotto Date: 2010-08-13 08:26:42 -0400 (Fri, 13 Aug 2010) New Revision: 2916 Modified: jcr/branches/1.14-ISPN/docs/reference/en/src/main/docbook/en-US/modules/= kernel/cache.xml Log: EXOJCR-802: The doc Modified: jcr/branches/1.14-ISPN/docs/reference/en/src/main/docbook/en-US/m= odules/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/branches/1.14-ISPN/docs/reference/en/src/main/docbook/en-US/modules= /kernel/cache.xml 2010-08-13 12:25:27 UTC (rev 2915) +++ jcr/branches/1.14-ISPN/docs/reference/en/src/main/docbook/en-US/modules= /kernel/cache.xml 2010-08-13 12:26:42 UTC (rev 2916) @@ -1,1089 +1,1538 @@ - - - - - eXo Cache - -
- Basic concepts - - All applications on the top of eXo JCR that need a cache, can re= ly - on an org.exoplatform.services.cache.ExoCache instance = that - is managed by the - org.exoplatform.services.cache.CacheService. The main - implementation of this service is - org.exoplatform.services.cache.impl.CacheServiceImpl wh= ich - depends on the - org.exoplatform.services.cache.ExoCacheConfig in order = to - create new ExoCache instances. See below an example of - org.exoplatform.services.cache.CacheService - definition: <component> - <key>org.exoplatform.services.cache.CacheService</key> - <jmx-name>cache:type=3DCacheService</jmx-name> - <type>org.exoplatform.services.cache.impl.CacheServiceImpl</t= ype> - <init-params> - <object-param> - <name>cache.config.default</name> - <description>The default cache configuration</description= > - <object type=3D"org.exoplatform.services.cache.ExoCacheConfig"&= gt; - <field name=3D"name"><string>default</string>&= lt;/field> - <field name=3D"maxSize"><int>300</int></fie= ld> - <field name=3D"liveTime"><long>600</long></= field> - <field name=3D"distributed"><boolean>false</boole= an></field> - <field name=3D"implementation"><string>org.exoplatfo= rm.services.cache.concurrent.ConcurrentFIFOExoCache</string></fiel= d> = - </object> - </object-param> - </init-params> - </component> - - - The ExoCacheConfig which name is - default, will be the default configuration of all t= he - ExoCache instances that don't have dedicated - configuration. - See below an example of how to define a new - ExoCacheConfig thanks to a - external-component-plugin: <e= xternal-component-plugins> - <target-component>org.exoplatform.services.cache.CacheService<= ;/target-component> - <component-plugin> - <name>addExoCacheConfig</name> - <set-method>addExoCacheConfig</set-method> - <type>org.exoplatform.services.cache.ExoCacheConfigPlugin</= type> - <description>Configures the cache for query service</descri= ption> - <init-params> - <object-param> - <name>cache.config.wcm.composer</name> - <description>The default cache configuration</descripti= on> - <object type=3D"org.exoplatform.services.cache.ExoCacheConfig= "> - <field name=3D"name"><string>wcm.composer</stri= ng></field> - <field name=3D"maxSize"><int>300</int></f= ield> - <field name=3D"liveTime"><long>600</long><= ;/field> - <field name=3D"distributed"><boolean>false</boo= lean></field> - <field name=3D"implementation"><string>org.exoplat= form.services.cache.concurrent.ConcurrentFIFOExoCache</string></fi= eld> = - </object> - </object-param> - </init-params> - </component-plugin> - </external-component-plugins> - - - Descriptions of the fields of - <envar>ExoCacheConfig</envar> - - - - - name - - The name of the cache. This field is mandatory since it - will be used to retrieve the ExoCacheConfig - corresponding to a given cache name. - - - - label - - The label of the cache. This field is optional. It is - mainly used to indicate the purpose of the cache. - - - - maxSize - - The maximum numbers of elements in cache. This field is - mandatory. - - - - liveTime - - The amount of time (in seconds) an element is not writt= en - or read before it is evicted. This field is mandatory. - - - - implementation - - The full qualified name of the cache implementation to = use. - This field is optional. This field is only used for simple cac= he - implementation. The default and main implementation is - org.exoplatform.services.cache.concurrent.ConcurrentFIF= OExoCache, - this implementation only works with local caches with FIFO as - eviction policy. For more complex implementation see the next - sections. - - - - distributed - - Indicates if the cache is distributed. This field is - optional. This field is used for backward compatibility. - - - - replicated - - Indicates if the cache is replicated. This field is - optional. This field is deprecated. - - - - logEnabled - - Indicates if the log is enabled. This field is optional. - This field is used for backward compatibility. - - - -
- - -
- -
- eXo Cache extension - - In the previous versions of eXo kernel, it was quite complex to - implement your own ExoCache because it was not open enough. Since kern= el - 2.0.8, it is possible to easily integrate your favorite cache provider= in - eXo Products. - - You just need to implement your own ExoCacheFactory - and register it in an eXo container, as described below:package org.exoplatform.services.cache; -... -public interface ExoCacheFactory { - = - /** - * Creates a new instance of {@link org.exoplatform.services.cache.ExoCa= che} - * @param config the cache to create - * @return the new instance of {@link org.exoplatform.services.cache.Exo= Cache} - * @exception ExoCacheInitException if an exception happens while initia= lizing the cache - */ - public ExoCache createCache(ExoCacheConfig config) throws ExoCacheInitEx= ception; = -} - - As you can see, there is only one method to implement which cans= be - seen as a converter of an ExoCacheConfig to get an inst= ance - of ExoCache. Once, you created your own implementation = you - can simply register your factory by adding a file - conf/portal/configuration.xml with a content of t= he - following type:<configuration> - <component> - <key>org.exoplatform.services.cache.ExoCacheFactory</key> - <type>org.exoplatform.tutorial.MyExoCacheFactoryImpl</type> - ... - </component> = -</configuration> -
- -
- eXo Cache based on JBoss Cache - -
- Configure the ExoCacheFactory - - When you add, the eXo library in your classpath, the eXo servi= ce - 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. - - The default configuration of the factory is:&l= t;configuration> = - <component> - <key>org.exoplatform.services.cache.ExoCacheFactory</key> - <type>org.exoplatform.services.cache.impl.jboss.ExoCacheFactoryI= mpl</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 jb= oss - cache. 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 jboss cache instance, thus it must = be - very generic. - The default configuration template provided with the jar a= ims - to work with any application servers, but if you intend to use J= Boss - AS, you should redefine it in your custom configuration to fit - better with your AS. - -
- -
- 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.jboss.ExoCacheFactor= yConfigPlugin</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 jboss cache 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= . -
- -
- Add a cache creator - -
- Understanding a cache creator - - The factory for jboss cache, delegates the cache creation to - ExoCacheCreator that is defines as - below: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 initia= lizing the cache - */ - public ExoCache create(ExoCacheConfig config, Cache<Serializable, Obj= ect> cache) throws ExoCacheInitException; - = - /** - * Returns the type of {@link org.exoplatform.services.cache.ExoCacheCon= fig} expected by the creator = - * @return the expected type - */ - public Class<? extends ExoCacheConfig> getExpectedConfigType(); - = - /** - * Returns the name of the implementation expected by the creator. This = is mainly used to be backward compatible - * @return the expected by the creator - */ - public String getExpectedImplementation(); -} - - The ExoCacheCreator 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. - - 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 and a jboss cache instance. - - - - getExpectedConfigType - this method= is - used to indicate the factory the subtype of - ExoCacheConfig supported by the creator. - - - - getExpectedImplementation - this me= thod - is used to indicate the factory the value of field implementat= ion - of ExoCacheConfig that is supported by the crea= tor. - This is used for backward compatibility, in other words you can - still configure your cache with a super class - 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.jboss.ExoCacheCreato= rPlugin</type> - <description>add Exo Cache Creator</description> - <init-params> - <object-param> - <name>LRU</name> - <description>The lru cache creator</description> - <object type=3D"org.exoplatform.services.cache.impl.jboss.lru= .LRUExoCacheCreator"> - <field name=3D"defaultTimeToLive"><long>1500</l= ong></field> - <field name=3D"defaultMaxAge"><long>2000</long&= gt;</field> - </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 jboss cache 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 action creator related to t= he - eviction policy LRU. -
- -
- 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. - -
- LRU Cache Creator - Least Recently Used - - .. -<object-param> - <name>LRU</name> - <description>The lru cache creator</description> - <object type=3D"org.exoplatform.services.cache.impl.jboss.lru.LRUExoC= acheCreator"> - <field name=3D"defaultTimeToLive"><long>${my-value}</lo= ng></field> - <field name=3D"defaultMaxAge"><long>${my-value}</long&g= t;</field> - </object> -</object-param> -... - - - Fields description - - - - - defaultTimeToLive - - This is the default value of the field - timeToLive described in the section - dedicated to this cache type. This value is only use whe= n we - define a cache of this type with the old - configuration. - - - - defaultMaxAge - - his is the default value of the field - maxAge described in the section - dedicated to this cache type. This value is only use whe= n we - define a cache of this type with the old - configuration. - - - -
-
- -
- FIFO Cache Creator - First In, First Out - - ... -<object-param> - <name>FIFO</name> - <description>The fifo cache creator</description> - <object type=3D"org.exoplatform.services.cache.impl.jboss.fifo.FIFOExo= CacheCreator"></object> -</object-param> -... -
- -
- MRU Cache Creator - Most Recently Used - - ... -<object-param> - <name>MRU</name> - <description>The mru cache creator</description> - <object type=3D"org.exoplatform.services.cache.impl.jboss.mru.MRUExoC= acheCreator"></object> -</object-param> -... -
- -
- LFU Cache Creator - Least Frequently Used - - ... -<object-param> - <name>LFU</name> - <description>The lfu cache creator</description> - <object type=3D"org.exoplatform.services.cache.impl.jboss.lfu.LFUExoC= acheCreator"> - <field name=3D"defaultMinNodes"><int>${my-value}</int&g= t;</field> - </object> -</object-param> -... - - - Fields description - - - - - defaultMinNodes - - This is the default value of the field - minNodes described in the section - dedicated to this cache type. This value is only use whe= n we - define a cache of this type with the old - configuration. - - - -
-
- -
- EA Cache Creator - Expiration Algorithm - - ... -<object-param> - <name>EA</name> - <description>The ea cache creator</description> - <object type=3D"org.exoplatform.services.cache.impl.jboss.ea.EAExoCac= heCreator"> - <field name=3D"defaultExpirationTimeout"><long>2000</lo= ng></field> - </object> -</object-param> -... - - - Fields description - - - - - defaultExpirationTimeout - - This is the default value of the field - minNodes described in the section - dedicated to this cache type. This value is only use whe= n we - define a cache of this type with the old - configuration. - - - -
-
-
-
- -
- Define a cache - -
- How to define a cache? - - You have 2 ways to define a cache which are: - - - - At CacheService initialization - - - - With an "external plugin" - - - -
- At <envar>CacheService</envar> initialization - - ... - <component> - <key>org.exoplatform.services.cache.CacheService</key> - <type>org.exoplatform.services.cache.impl.CacheServiceImpl</t= ype> - <init-params> - ... - <object-param> - <name>fifocache</name> - <description>The default cache configuration</description= > - <object type=3D"org.exoplatform.services.cache.ExoCacheConfig"&= gt; - <field name=3D"name"><string>fifocache</string>= ;</field> - <field name=3D"maxSize"><int>${my-value}</int>= </field> - <field name=3D"liveTime"><long>${my-value}</long&= gt;</field> - <field name=3D"distributed"><boolean>false</boole= an></field> - <field name=3D"implementation"><string>org.exoplatfo= rm.services.cache.FIFOExoCache</string></field> - </object> - </object-param> = - ... - </init-params> - </component> = -... - - In this example, we define a new cache called - fifocache. -
- -
- With an <emphasis>"external plugin"</emphasis> - - ... - <external-component-plugins> - <target-component>org.exoplatform.services.cache.CacheService<= ;/target-component> - <component-plugin> - <name>addExoCacheConfig</name> - <set-method>addExoCacheConfig</set-method> - <type>org.exoplatform.services.cache.ExoCacheConfigPlugin</= type> - <description>add ExoCache configuration component plugin </= description> - <init-params> - ... = - <object-param> = - <name>fifoCache</name> - <description>The fifo cache configuration</description&= gt; - <object type=3D"org.exoplatform.services.cache.ExoCacheConfig= "> - <field name=3D"name"><string>fifocache</string&= gt;</field> - <field name=3D"maxSize"><int>${my-value}</int&g= t;</field> - <field name=3D"liveTime"><long>${my-value}</lon= g></field> - <field name=3D"distributed"><boolean>false</boo= lean></field> - <field name=3D"implementation"><string>org.exoplat= form.services.cache.FIFOExoCache</string></field> - </object> - </object-param> = -... = - </init-params> - </component-plugin> - </external-component-plugins> = -... - - In this example, we define a new cache called - fifocache which is in fact the same cache a= s in - previous example but defined in a different manner. -
-
- -
- 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. -
- -
- LRU Cache - Least Recently Used - - - - New configuration - - ... - <object-param> - <name>lru</name> - <description>The lru cache configuration</description> - <object type=3D"org.exoplatform.services.cache.impl.jboss.lru.L= RUExoCacheConfig"> - <field name=3D"name"><string>lru</string></= field> - <field name=3D"maxNodes"><int>${my-value}</int>= ;</field> - <field name=3D"minTimeToLive"><long>${my-value}</= long></field> - <field name=3D"maxAge"><long>${my-value}</long>= ;</field> - <field name=3D"timeToLive"><long>${my-value}</lon= g></field> - </object> - </object-param> = -... - Fields description - - - - - maxNodes - - This is the maximum number of nodes allowed in - this region. 0 denotes immediate expiry, -1 denotes = no - limit. - - - - minTimeToLive - - The minimum amount of time (in milliseconds) a - node must be allowed to live after being accessed be= fore - it is allowed to be considered for eviction. 0 denot= es - that this feature is disabled, which is the default - value. - - - - maxAge - - Lifespan of a node (in milliseconds) regardle= ss - of idle time before the node is swept away. 0 denotes - immediate expiry, -1 denotes no limit. - - - - timeToLive - - The amount of time a node is not written to or - read (in milliseconds) before the node is swept away= . 0 - denotes immediate expiry, -1 denotes no limit. - - - -
- - - - Old configuration - - ... - <object-param> - <name>lru-with-old-config</name> - <description>The lru cache configuration</description> - <object type=3D"org.exoplatform.services.cache.ExoCacheConfig"&= gt; - <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>LRU</strin= g></field> - </object> - </object-param> = -... - - - Fields description - - - - - maxSize - - This is the maximum number of nodes allowed in = this - region. 0 denotes immediate expiry, -1 denotes no - limit. - - - - liveTime - - The minimum amount of time (in seconds) a node = must - be allowed to live after being accessed before it is - allowed to be considered for eviction. 0 denotes that = this - feature is disabled, which is the default value. - - - -
- - - For the fields maxAge and - timeToLive needed by JBoss cache, we = will - use the default values provided by the creator. - - - -
- -
- FIFO Cache - First In, First Out - - - - New configuration... - <object-param> - <name>fifo</name> - <description>The fifo cache configuration</description> - <object type=3D"org.exoplatform.services.cache.impl.jboss.fifo.= FIFOExoCacheConfig"> - <field name=3D"name"><string>fifo</string><= /field> - <field name=3D"maxNodes"><int>${my-value}</int>= ;</field> - <field name=3D"minTimeToLive"><long>${my-value}</= long></field> - </object> - </object-param> -... - - - Fields description - - - - - maxNodes - - This is the maximum number of nodes allowed in = this - region. 0 denotes immediate expiry, -1 denotes no - limit. - - - - minTimeToLive - - The minimum amount of time (in milliseconds) a = node - must be allowed to live after being accessed before it= is - allowed to be considered for eviction. 0 denotes that = this - feature is disabled, which is the default value. - - - -
- - - - Old configuration... - <object-param> - <name>fifo-with-old-config</name> - <description>The fifo cache configuration</description> - <object type=3D"org.exoplatform.services.cache.ExoCacheConfig"&= gt; - <field name=3D"name"><string>fifo-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>FIFO</stri= ng></field> - </object> - </object-param> -... - - - Fields description - - - - - maxSize - - This is the maximum number of nodes allowed in = this - region. 0 denotes immediate expiry, -1 denotes no - limit. - - - - liveTime - - The minimum amount of time (in seconds) a node = must - be allowed to live after being accessed before it is - allowed to be considered for eviction. 0 denotes that = this - feature is disabled, which is the default value. - - - -
- - -
- -
- MRU Cache - Most Recently Used - - - - New configuration... - <object-param> - <name>mru</name> - <description>The mru cache configuration</description> - <object type=3D"org.exoplatform.services.cache.impl.jboss.mru.M= RUExoCacheConfig"> - <field name=3D"name"><string>mru</string></= field> - <field name=3D"maxNodes"><int>${my-value}</int>= ;</field> - <field name=3D"minTimeToLive"><long>${my-value}</= long></field> - </object> - </object-param> = -... - - - Fields description - - - - - maxNodes - - This is the maximum number of nodes allowed in = this - region. 0 denotes immediate expiry, -1 denotes no - limit. - - - - minTimeToLive - - The minimum amount of time (in milliseconds) a = node - must be allowed to live after being accessed before it= is - allowed to be considered for eviction. 0 denotes that = this - feature is disabled, which is the default value. - - - -
- - - - Old configuration... - <object-param> - <name>mru-with-old-config</name> - <description>The mru cache configuration</description> - <object type=3D"org.exoplatform.services.cache.ExoCacheConfig"&= gt; - <field name=3D"name"><string>mru-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>MRU</strin= g></field> - </object> - </object-param> = -... - - - Fields description - - - - - maxSize - - This is the maximum number of nodes allowed in = this - region. 0 denotes immediate expiry, -1 denotes no - limit. - - - - liveTime - - The minimum amount of time (in seconds) a node = must - be allowed to live after being accessed before it is - allowed to be considered for eviction. 0 denotes that = this - feature is disabled, which is the default value. - - - -
- - -
- -
- LFU Cache - Least Frequently Used - - - - New configuration... - <object-param> - <name>lfu</name> - <description>The lfu cache configuration</description> - <object type=3D"org.exoplatform.services.cache.impl.jboss.lfu.L= FUExoCacheConfig"> - <field name=3D"name"><string>lfu</string></= field> - <field name=3D"maxNodes"><int>${my-value}</int>= ;</field> - <field name=3D"minNodes"><int>${my-value}</int>= ;</field> - <field name=3D"minTimeToLive"><long>${my-value}</= long></field> - </object> - </object-param> = -... - - - Fields description - - - - - maxNodes - - This is the maximum number of nodes allowed in = this - region. 0 denotes immediate expiry, -1 denotes no - limit. - - - - minNodes - - 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 ti= mer - makes a pass through the eviction algorithm. - - - - minTimeToLive - - The minimum amount of time (in milliseconds) a = node - must be allowed to live after being accessed before it= is - allowed to be considered for eviction. 0 denotes that = this - feature is disabled, which is the default value. - - - -
- - - - Old configuration... - <object-param> - <name>lfu-with-old-config</name> - <description>The lfu cache configuration</description> - <object type=3D"org.exoplatform.services.cache.ExoCacheConfig"&= gt; - <field name=3D"name"><string>lfu-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>LFU</strin= g></field> - </object> - </object-param> = -... - - - Fields description - - - - - maxSize - - This is the maximum number of nodes allowed in = this - region. 0 denotes immediate expiry, -1 denotes no - limit. - - - - liveTime - - The minimum amount of time (in milliseconds) a = node - must be allowed to live after being accessed before it= is - allowed to be considered for eviction. 0 denotes that = this - feature is disabled, which is the default value. - - - -
- - - For the fields minNodes and - timeToLive needed by JBoss cache, we = will - use the default values provided by the creator. - - - -
- -
- EA Cache - Expiration Algorithm - - - - New configuration... - <object-param> - <name>ea</name> - <description>The ea cache configuration</description> - <object type=3D"org.exoplatform.services.cache.impl.jboss.ea.EA= ExoCacheConfig"> - <field name=3D"name"><string>ea</string></f= ield> - <field name=3D"maxNodes"><int>${my-value}</int>= ;</field> - <field name=3D"minTimeToLive"><long>${my-value}</= long></field> - <field name=3D"expirationTimeout"><long>${my-value}&= lt;/long></field> - </object> - </object-param> = -... - - - Fields description - - - - - maxNodes - - This is the maximum number of nodes allowed in = this - region. 0 denotes immediate expiry, -1 denotes no - limit. - - - - minTimeToLive - - The minimum amount of time (in milliseconds) a = node - must be allowed to live after being accessed before it= is - allowed to be considered for eviction. 0 denotes that = this - feature is disabled, which is the default value. - - - - expirationTimeout - - This is the timeout after which the cache entry - must be evicted. - - - -
- - - - Old configuration... - <object-param> - <name>ea-with-old-config</name> - <description>The ea cache configuration</description> - <object type=3D"org.exoplatform.services.cache.ExoCacheConfig"&= gt; - <field name=3D"name"><string>lfu-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>EA</string= ></field> - </object> - </object-param> = -... - - - Fields description - - - - - maxSize - - This is the maximum number of nodes allowed in = this - region. 0 denotes immediate expiry, -1 denotes no - limit. - - - - liveTime - - The minimum amount of time (in milliseconds) a = node - must be allowed to live after being accessed before it= is - allowed to be considered for eviction. 0 denotes that = this - feature is disabled, which is the default value. - - - -
- - - For the fields expirationTimeout - needed by JBoss cache, we will use the default values prov= ided - by the creator. - - - -
-
-
- + + + + + + eXo Cache + +
+ Basic concepts + + All applications on the top of eXo JCR that need a cache, can re= ly + on an org.exoplatform.services.cache.ExoCache instance = that + is managed by the + org.exoplatform.services.cache.CacheService. The main + implementation of this service is + org.exoplatform.services.cache.impl.CacheServiceImpl wh= ich + depends on the + org.exoplatform.services.cache.ExoCacheConfig in order = to + create new ExoCache instances. See below an example of + org.exoplatform.services.cache.CacheService + definition: <component> + <key>org.exoplatform.services.cache.CacheService</key> + <jmx-name>cache:type=3DCacheService</jmx-name> + <type>org.exoplatform.services.cache.impl.CacheServiceImpl</t= ype> + <init-params> + <object-param> + <name>cache.config.default</name> + <description>The default cache configuration</description= > + <object type=3D"org.exoplatform.services.cache.ExoCacheConfig"&= gt; + <field name=3D"name"><string>default</string>&= lt;/field> + <field name=3D"maxSize"><int>300</int></fie= ld> + <field name=3D"liveTime"><long>600</long></= field> + <field name=3D"distributed"><boolean>false</boole= an></field> + <field name=3D"implementation"><string>org.exoplatfo= rm.services.cache.concurrent.ConcurrentFIFOExoCache</string></fiel= d> = + </object> + </object-param> + </init-params> + </component> + + + The ExoCacheConfig which name is + default, will be the default configuration of all t= he + ExoCache instances that don't have dedicated + configuration. + See below an example of how to define a new + ExoCacheConfig thanks to a + external-component-plugin: <e= xternal-component-plugins> + <target-component>org.exoplatform.services.cache.CacheService<= ;/target-component> + <component-plugin> + <name>addExoCacheConfig</name> + <set-method>addExoCacheConfig</set-method> + <type>org.exoplatform.services.cache.ExoCacheConfigPlugin</= type> + <description>Configures the cache for query service</descri= ption> + <init-params> + <object-param> + <name>cache.config.wcm.composer</name> + <description>The default cache configuration</descripti= on> + <object type=3D"org.exoplatform.services.cache.ExoCacheConfig= "> + <field name=3D"name"><string>wcm.composer</stri= ng></field> + <field name=3D"maxSize"><int>300</int></f= ield> + <field name=3D"liveTime"><long>600</long><= ;/field> + <field name=3D"distributed"><boolean>false</boo= lean></field> + <field name=3D"implementation"><string>org.exoplat= form.services.cache.concurrent.ConcurrentFIFOExoCache</string></fi= eld> = + </object> + </object-param> + </init-params> + </component-plugin> + </external-component-plugins> + + + Descriptions of the fields of + <envar>ExoCacheConfig</envar> + + + + + name + + The name of the cache. This field is mandatory since it + will be used to retrieve the ExoCacheConfig + corresponding to a given cache name. + + + + label + + The label of the cache. This field is optional. It is + mainly used to indicate the purpose of the cache. + + + + maxSize + + The maximum numbers of elements in cache. This field is + mandatory. + + + + liveTime + + The amount of time (in seconds) an element is not writt= en + or read before it is evicted. This field is mandatory. + + + + implementation + + The full qualified name of the cache implementation to = use. + This field is optional. This field is only used for simple cac= he + implementation. The default and main implementation is + org.exoplatform.services.cache.concurrent.ConcurrentFIF= OExoCache, + this implementation only works with local caches with FIFO as + eviction policy. For more complex implementation see the next + sections. + + + + distributed + + Indicates if the cache is distributed. This field is + optional. This field is used for backward compatibility. + + + + replicated + + Indicates if the cache is replicated. This field is + optional. This field is deprecated. + + + + logEnabled + + Indicates if the log is enabled. This field is optional. + This field is used for backward compatibility. + + + +
+
+ +
+ How to define a cache? + + You have 2 ways to define a cache which are: + + + + At CacheService initialization + + + + With an "external plugin" + + + +
+ At <envar>CacheService</envar> initialization + + ... + <component> + <key>org.exoplatform.services.cache.CacheService</key> + <type>org.exoplatform.services.cache.impl.CacheServiceImpl</t= ype> + <init-params> + ... + <object-param> + <name>fifocache</name> + <description>The default cache configuration</description= > + <object type=3D"org.exoplatform.services.cache.ExoCacheConfig"&= gt; + <field name=3D"name"><string>fifocache</string>= ;</field> + <field name=3D"maxSize"><int>${my-value}</int>= </field> + <field name=3D"liveTime"><long>${my-value}</long&= gt;</field> + <field name=3D"distributed"><boolean>false</boole= an></field> + <field name=3D"implementation"><string>org.exoplatfo= rm.services.cache.FIFOExoCache</string></field> + </object> + </object-param> = + ... + </init-params> + </component> = +... + + In this example, we define a new cache called + fifocache. +
+ +
+ With an <emphasis>"external plugin"</emphasis> + + ... + <external-component-plugins> + <target-component>org.exoplatform.services.cache.CacheService<= ;/target-component> + <component-plugin> + <name>addExoCacheConfig</name> + <set-method>addExoCacheConfig</set-method> + <type>org.exoplatform.services.cache.ExoCacheConfigPlugin</= type> + <description>add ExoCache configuration component plugin </= description> + <init-params> + ... = + <object-param> = + <name>fifoCache</name> + <description>The fifo cache configuration</description&= gt; + <object type=3D"org.exoplatform.services.cache.ExoCacheConfig= "> + <field name=3D"name"><string>fifocache</string&= gt;</field> + <field name=3D"maxSize"><int>${my-value}</int&g= t;</field> + <field name=3D"liveTime"><long>${my-value}</lon= g></field> + <field name=3D"distributed"><boolean>false</boo= lean></field> + <field name=3D"implementation"><string>org.exoplat= form.services.cache.FIFOExoCache</string></field> + </object> + </object-param> = +... = + </init-params> + </component-plugin> + </external-component-plugins> = +... + + In this example, we define a new cache called + fifocache which is in fact the same cache as in + previous example but defined in a different manner. +
+
+ +
+ eXo Cache extension + + In the previous versions of eXo kernel, it was quite complex to + implement your own ExoCache because it was not open enough. Since kern= el + 2.0.8, it is possible to easily integrate your favorite cache provider= in + eXo Products. + + You just need to implement your own ExoCacheFactory + and register it in an eXo container, as described below:package org.exoplatform.services.cache; +... +public interface ExoCacheFactory { + = + /** + * Creates a new instance of {@link org.exoplatform.services.cache.ExoCa= che} + * @param config the cache to create + * @return the new instance of {@link org.exoplatform.services.cache.Exo= Cache} + * @exception ExoCacheInitException if an exception happens while initia= lizing the cache + */ + public ExoCache createCache(ExoCacheConfig config) throws ExoCacheInitEx= ception; = +} + + As you can see, there is only one method to implement which cans= be + seen as a converter of an ExoCacheConfig to get an inst= ance + of ExoCache. Once, you created your own implementation = you + can simply register your factory by adding a file + conf/portal/configuration.xml with a content of t= he + following type:<configuration> + <component> + <key>org.exoplatform.services.cache.ExoCacheFactory</key> + <type>org.exoplatform.tutorial.MyExoCacheFactoryImpl</type> + ... + </component> = +</configuration> +
+ +
+ eXo Cache based on JBoss Cache + +
+ 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.jboss.ExoCacheFactoryI= mpl</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 jb= oss + cache. 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 jboss cache instance, thus it must = be + very generic. + The default configuration template provided with the jar a= ims + to work with any application servers, but if you intend to use J= Boss + AS, you should redefine it in your custom configuration to fit + better with your AS. + +
+ +
+ 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.jboss.ExoCacheFactor= yConfigPlugin</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 jboss cache 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= . +
+ +
+ Add a cache creator + +
+ Understanding a cache creator + + The factory for jboss cache, delegates the cache creation to + ExoCacheCreator that is defined as + below: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 initia= lizing the cache + */ + public ExoCache create(ExoCacheConfig config, Cache<Serializable, Obj= ect> cache) throws ExoCacheInitException; + = + /** + * Returns the type of {@link org.exoplatform.services.cache.ExoCacheCon= fig} expected by the creator = + * @return the expected type + */ + public Class<? extends ExoCacheConfig> getExpectedConfigType(); + = + /** + * Returns the name of the implementation expected by the creator. This = is mainly used to be backward compatible + * @return the expected by the creator + */ + public String getExpectedImplementation(); +} + + The ExoCacheCreator 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. + + 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 and a jboss cache instance. + + + + getExpectedConfigType - this method= is + used to indicate the factory the subtype of + ExoCacheConfig supported by the creator. + + + + getExpectedImplementation - this me= thod + is used to indicate the factory the value 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.jboss.ExoCacheCreato= rPlugin</type> + <description>add Exo Cache Creator</description> + <init-params> + <object-param> + <name>LRU</name> + <description>The lru cache creator</description> + <object type=3D"org.exoplatform.services.cache.impl.jboss.lru= .LRUExoCacheCreator"> + <field name=3D"defaultTimeToLive"><long>1500</l= ong></field> + <field name=3D"defaultMaxAge"><long>2000</long&= gt;</field> + </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 jboss cache 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 LRU. +
+ +
+ 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. + +
+ LRU Cache Creator - Least Recently Used + + .. +<object-param> + <name>LRU</name> + <description>The lru cache creator</description> + <object type=3D"org.exoplatform.services.cache.impl.jboss.lru.LRUExoC= acheCreator"> + <field name=3D"defaultTimeToLive"><long>${my-value}</lo= ng></field> + <field name=3D"defaultMaxAge"><long>${my-value}</long&g= t;</field> + </object> +</object-param> +... + + + Fields description + + + + + defaultTimeToLive + + This is the default value of the field + timeToLive described in the section + dedicated to this cache type. This value is only use whe= n we + define a cache of this type with the old + configuration. + + + + defaultMaxAge + + his is the default value of the field + maxAge described in the section + dedicated to this cache type. This value is only use whe= n we + define a cache of this type with the old + configuration. + + + +
+
+ +
+ FIFO Cache Creator - First In, First Out + + ... +<object-param> + <name>FIFO</name> + <description>The fifo cache creator</description> + <object type=3D"org.exoplatform.services.cache.impl.jboss.fifo.FIFOExo= CacheCreator"></object> +</object-param> +... +
+ +
+ MRU Cache Creator - Most Recently Used + + ... +<object-param> + <name>MRU</name> + <description>The mru cache creator</description> + <object type=3D"org.exoplatform.services.cache.impl.jboss.mru.MRUExoC= acheCreator"></object> +</object-param> +... +
+ +
+ LFU Cache Creator - Least Frequently Used + + ... +<object-param> + <name>LFU</name> + <description>The lfu cache creator</description> + <object type=3D"org.exoplatform.services.cache.impl.jboss.lfu.LFUExoC= acheCreator"> + <field name=3D"defaultMinNodes"><int>${my-value}</int&g= t;</field> + </object> +</object-param> +... + + + Fields description + + + + + defaultMinNodes + + This is the default value of the field + minNodes described in the section + dedicated to this cache type. This value is only use whe= n we + define a cache of this type with the old + configuration. + + + +
+
+ +
+ EA Cache Creator - Expiration Algorithm + + ... +<object-param> + <name>EA</name> + <description>The ea cache creator</description> + <object type=3D"org.exoplatform.services.cache.impl.jboss.ea.EAExoCac= heCreator"> + <field name=3D"defaultExpirationTimeout"><long>2000</lo= ng></field> + </object> +</object-param> +... + + + Fields description + + + + + defaultExpirationTimeout + + This is the default value of the field + minNodes described in the section + dedicated to this cache type. This value is only use whe= n we + define a cache of this type with the old + configuration. + + + +
+
+
+
+ +
+ Define a JBoss 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. +
+ +
+ LRU Cache - Least Recently Used + + + + New configuration + + ... + <object-param> + <name>lru</name> + <description>The lru cache configuration</description> + <object type=3D"org.exoplatform.services.cache.impl.jboss.lru.L= RUExoCacheConfig"> + <field name=3D"name"><string>lru</string></= field> + <field name=3D"maxNodes"><int>${my-value}</int>= ;</field> + <field name=3D"minTimeToLive"><long>${my-value}</= long></field> + <field name=3D"maxAge"><long>${my-value}</long>= ;</field> + <field name=3D"timeToLive"><long>${my-value}</lon= g></field> + </object> + </object-param> = +... + Fields description + + + + + maxNodes + + This is the maximum number of nodes allowed in + this region. 0 denotes immediate expiry, -1 denotes = no + limit. + + + + minTimeToLive + + The minimum amount of time (in milliseconds) a + node must be allowed to live after being accessed be= fore + it is allowed to be considered for eviction. 0 denot= es + that this feature is disabled, which is the default + value. + + + + maxAge + + Lifespan of a node (in milliseconds) regardle= ss + of idle time before the node is swept away. 0 denotes + immediate expiry, -1 denotes no limit. + + + + timeToLive + + The amount of time a node is not written to or + read (in milliseconds) before the node is swept away= . 0 + denotes immediate expiry, -1 denotes no limit. + + + +
+ + + + Old configuration + + ... + <object-param> + <name>lru-with-old-config</name> + <description>The lru cache configuration</description> + <object type=3D"org.exoplatform.services.cache.ExoCacheConfig"&= gt; + <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>LRU</strin= g></field> + </object> + </object-param> = +... + + + Fields description + + + + + maxSize + + This is the maximum number of nodes allowed in = this + region. 0 denotes immediate expiry, -1 denotes no + limit. + + + + liveTime + + The minimum amount of time (in seconds) a node = must + be allowed to live after being accessed before it is + allowed to be considered for eviction. 0 denotes that = this + feature is disabled, which is the default value. + + + +
+ + + For the fields maxAge and + timeToLive needed by JBoss cache, we = will + use the default values provided by the creator. + + + +
+ +
+ FIFO Cache - First In, First Out + + + + New configuration... + <object-param> + <name>fifo</name> + <description>The fifo cache configuration</description> + <object type=3D"org.exoplatform.services.cache.impl.jboss.fifo.= FIFOExoCacheConfig"> + <field name=3D"name"><string>fifo</string><= /field> + <field name=3D"maxNodes"><int>${my-value}</int>= ;</field> + <field name=3D"minTimeToLive"><long>${my-value}</= long></field> + </object> + </object-param> +... + + + Fields description + + + + + maxNodes + + This is the maximum number of nodes allowed in = this + region. 0 denotes immediate expiry, -1 denotes no + limit. + + + + minTimeToLive + + The minimum amount of time (in milliseconds) a = node + must be allowed to live after being accessed before it= is + allowed to be considered for eviction. 0 denotes that = this + feature is disabled, which is the default value. + + + +
+ + + + Old configuration... + <object-param> + <name>fifo-with-old-config</name> + <description>The fifo cache configuration</description> + <object type=3D"org.exoplatform.services.cache.ExoCacheConfig"&= gt; + <field name=3D"name"><string>fifo-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>FIFO</stri= ng></field> + </object> + </object-param> +... + + + Fields description + + + + + maxSize + + This is the maximum number of nodes allowed in = this + region. 0 denotes immediate expiry, -1 denotes no + limit. + + + + liveTime + + The minimum amount of time (in seconds) a node = must + be allowed to live after being accessed before it is + allowed to be considered for eviction. 0 denotes that = this + feature is disabled, which is the default value. + + + +
+ + +
+ +
+ MRU Cache - Most Recently Used + + + + New configuration... + <object-param> + <name>mru</name> + <description>The mru cache configuration</description> + <object type=3D"org.exoplatform.services.cache.impl.jboss.mru.M= RUExoCacheConfig"> + <field name=3D"name"><string>mru</string></= field> + <field name=3D"maxNodes"><int>${my-value}</int>= ;</field> + <field name=3D"minTimeToLive"><long>${my-value}</= long></field> + </object> + </object-param> = +... + + + Fields description + + + + + maxNodes + + This is the maximum number of nodes allowed in = this + region. 0 denotes immediate expiry, -1 denotes no + limit. + + + + minTimeToLive + + The minimum amount of time (in milliseconds) a = node + must be allowed to live after being accessed before it= is + allowed to be considered for eviction. 0 denotes that = this + feature is disabled, which is the default value. + + + +
+ + + + Old configuration... + <object-param> + <name>mru-with-old-config</name> + <description>The mru cache configuration</description> + <object type=3D"org.exoplatform.services.cache.ExoCacheConfig"&= gt; + <field name=3D"name"><string>mru-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>MRU</strin= g></field> + </object> + </object-param> = +... + + + Fields description + + + + + maxSize + + This is the maximum number of nodes allowed in = this + region. 0 denotes immediate expiry, -1 denotes no + limit. + + + + liveTime + + The minimum amount of time (in seconds) a node = must + be allowed to live after being accessed before it is + allowed to be considered for eviction. 0 denotes that = this + feature is disabled, which is the default value. + + + +
+ + +
+ +
+ LFU Cache - Least Frequently Used + + + + New configuration... + <object-param> + <name>lfu</name> + <description>The lfu cache configuration</description> + <object type=3D"org.exoplatform.services.cache.impl.jboss.lfu.L= FUExoCacheConfig"> + <field name=3D"name"><string>lfu</string></= field> + <field name=3D"maxNodes"><int>${my-value}</int>= ;</field> + <field name=3D"minNodes"><int>${my-value}</int>= ;</field> + <field name=3D"minTimeToLive"><long>${my-value}</= long></field> + </object> + </object-param> = +... + + + Fields description + + + + + maxNodes + + This is the maximum number of nodes allowed in = this + region. 0 denotes immediate expiry, -1 denotes no + limit. + + + + minNodes + + 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 ti= mer + makes a pass through the eviction algorithm. + + + + minTimeToLive + + The minimum amount of time (in milliseconds) a = node + must be allowed to live after being accessed before it= is + allowed to be considered for eviction. 0 denotes that = this + feature is disabled, which is the default value. + + + +
+ + + + Old configuration... + <object-param> + <name>lfu-with-old-config</name> + <description>The lfu cache configuration</description> + <object type=3D"org.exoplatform.services.cache.ExoCacheConfig"&= gt; + <field name=3D"name"><string>lfu-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>LFU</strin= g></field> + </object> + </object-param> = +... + + + Fields description + + + + + maxSize + + This is the maximum number of nodes allowed in = this + region. 0 denotes immediate expiry, -1 denotes no + limit. + + + + liveTime + + The minimum amount of time (in milliseconds) a = node + must be allowed to live after being accessed before it= is + allowed to be considered for eviction. 0 denotes that = this + feature is disabled, which is the default value. + + + +
+ + + For the fields minNodes and + timeToLive needed by JBoss cache, we = will + use the default values provided by the creator. + + + +
+ +
+ EA Cache - Expiration Algorithm + + + + New configuration... + <object-param> + <name>ea</name> + <description>The ea cache configuration</description> + <object type=3D"org.exoplatform.services.cache.impl.jboss.ea.EA= ExoCacheConfig"> + <field name=3D"name"><string>ea</string></f= ield> + <field name=3D"maxNodes"><int>${my-value}</int>= ;</field> + <field name=3D"minTimeToLive"><long>${my-value}</= long></field> + <field name=3D"expirationTimeout"><long>${my-value}&= lt;/long></field> + </object> + </object-param> = +... + + + Fields description + + + + + maxNodes + + This is the maximum number of nodes allowed in = this + region. 0 denotes immediate expiry, -1 denotes no + limit. + + + + minTimeToLive + + The minimum amount of time (in milliseconds) a = node + must be allowed to live after being accessed before it= is + allowed to be considered for eviction. 0 denotes that = this + feature is disabled, which is the default value. + + + + expirationTimeout + + This is the timeout after which the cache entry + must be evicted. + + + +
+ + + + Old configuration... + <object-param> + <name>ea-with-old-config</name> + <description>The ea cache configuration</description> + <object type=3D"org.exoplatform.services.cache.ExoCacheConfig"&= gt; + <field name=3D"name"><string>lfu-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>EA</string= ></field> + </object> + </object-param> = +... + + + Fields description + + + + + maxSize + + This is the maximum number of nodes allowed in = this + region. 0 denotes immediate expiry, -1 denotes no + limit. + + + + liveTime + + The minimum amount of time (in milliseconds) a = node + must be allowed to live after being accessed before it= is + allowed to be considered for eviction. 0 denotes that = this + feature is disabled, which is the default value. + + + +
+ + + For the fields expirationTimeout + needed by JBoss cache, we will use the default values prov= ided + by the creator. + + + +
+
+
+ +
+ 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. + + + +
+
+
+ --===============6439597713039153005==--