[jboss-cvs] JBossCache/docs/JBossCache-UserGuide/en/modules ...
Manik Surtani
msurtani at jboss.com
Wed Jan 24 12:17:44 EST 2007
User: msurtani
Date: 07/01/24 12:17:44
Modified: docs/JBossCache-UserGuide/en/modules eviction_policies.xml
Log:
Chapter 9
Revision Changes Path
1.5 +215 -601 JBossCache/docs/JBossCache-UserGuide/en/modules/eviction_policies.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: eviction_policies.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/eviction_policies.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -b -r1.4 -r1.5
--- eviction_policies.xml 24 Jan 2007 16:33:57 -0000 1.4
+++ eviction_policies.xml 24 Jan 2007 17:17:44 -0000 1.5
@@ -19,11 +19,43 @@
...
+ <attribute name="EvictionPolicyConfig">
+ <config>
+ <attribute name="wakeUpIntervalSeconds">3</attribute>
+
+ <!-- This defaults to 200000 if not specified -->
+ <attribute name="eventQueueSize">200000</attribute>
+ <!-- Name of the DEFAULT eviction policy class. -->
+ <attribute name="policyClass">org.jboss.cache.eviction.LRUPolicy</attribute>
+
+ <!-- Cache wide default -->
+ <region name="/_default_">
+ <attribute name="maxNodes">100</attribute>
+ </region>
+
+ <!-- override policy used for this region -->
+ <region name="/org/jboss/data" policyClass="org.jboss.cache.eviction.MRUPolicy">
+ <attribute name="maxNodes">250</attribute>
+ </region>
+
+ <region name="/org/jboss/test/data">
+ <attribute name="maxNodes">6</attribute>
+ </region>
+
+ </config>
+ </attribute>
...
]]>
</programlisting>
+
+ <itemizedlist>
+ <listitem><literal>wakeUpIntervalSeconds</literal> - this required parameter defines how often the eviction thread runs</listitem>
+ <listitem><literal>eventQueueSize</literal> - this optional parameter defines how large a queue of items to evict to create. If your eviction thread does not run often enough, you may need to increase this.</listitem>
+ <listitem><literal>policyClass</literal> - this required, unless you set individual policyClass attributes on each and every region. This defines the eviction policy to use if one os not defined for a region.</listitem>
+ </itemizedlist>
+
</para>
</section>
<section>
@@ -33,491 +65,76 @@
when talking about marshalling. Regions also have another use, in that they are used to define the eviction
policy used within the region. In addition to using a region-specific configuration, you can also configure
a default, cache-wide eviction policy for nodes that do not fall into predefined regions or if you do not
- wish to define specific regions.
- </para>
- </section>
- </section>
-
- <section>
- <title>Shipped Eviction Policies</title>
- </section>
-
- <section>
- <title>Writing Your Own Eviction Policies</title>
- </section>
-
- <section>
- <title>Eviction Policy Plugin</title>
-
- <para>The design of the JBoss Cache eviction policy framework is based
- on the
- <literal>EvictionInterceptor</literal>
- to
- handle cache events and relay them back to the eviction policies. During the cache start up,
- an
- <literal>EvictionInterceptor</literal>
- will be added to the cache
- interceptor stack if the eviction policy is specified.
- Then whenever a cached node is added, removed, evicted, or visited, the
- <literal>EvictionInterceptor</literal>
- will maintain state statistics and
- information will be relayed to each individual Eviction Region.
- Each Region can define a different
- <literal>EvictionPolicy</literal>
- implementation that
- will know how to correlate cache add, remove, and visit events back to a
- defined eviction behavior. It's the policy provider's responsibility to
- decide when to call back the cache "evict" operation.
- </para>
-
- <para>There is a single eviction thread (timer) that will run at a
- configured interval. This thread will make calls into each of the policy
- providers and inform it of any aggregated adds,
- removes and visits (gets) events to the cache during the configured interval.
- The eviction thread is responsible for kicking off the eviction policy
- processing (a single pass) for each configured eviction cache
- region.
- </para>
-
- <para>In order to implement an eviction policy, the following interfaces
- must be implemented: org.jboss.cache.eviction.EvictionPolicy,
- org.jboss.cache.eviction.EvictionAlgorithm,
- org.jboss.cache.eviction.EvictionQueue and
- org.jboss.cache.eviction.EvictionConfiguration. When compounded
- together, each of these interface implementations define all the
- underlying mechanics necessary for a complete eviction policy
- implementation.
+ wish to define specific regions. It is important to note that when defining regions using the configuration
+ XML file, all elements of the <literal>Fqn</literal> that defines the region are <literal>java.lang.String</literal>
+ objects.
</para>
-
- <figure>
- <title>TreeCache eviction UML Diagram</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/EvictionUML.png"/>
- </imageobject>
- </mediaobject>
- </figure>
-
<para>
- <emphasis>Note that:</emphasis>
- </para>
-
- <itemizedlist>
- <listitem>
- <para>The EvictionConfiguration class 'parseXMLConfig(Element)'
- method expects only the DOM element pertaining to the region the
- policy is being configured for.
- </para>
- </listitem>
- </itemizedlist>
-
- <itemizedlist>
- <listitem>
- <para>The EvictionConfiguration implementation should maintain
- getter and setter methods for configured properties pertaining to
- the policy used on a given cache region. (e.g. for LRUConfiguration
- there is a int getMaxNodes() and a setMaxNodes(int))
+ Looking at the eviction configuration snippet above, we see that a default region, <literal>_default_</literal>, holds attributes
+ which apply to nodes that do not fall into any of the other regions defined.
</para>
- </listitem>
- </itemizedlist>
-
- <para>Alternatively, the implementation of a new eviction policy
- provider can be further simplified by extending BaseEvictionPolicy and
- BaseEvictionAlgorithm. Or for properly sorted EvictionAlgorithms (sorted
- in eviction order - see LFUAlgorithm) extending
- BaseSortedEvictionAlgorithm and implementing SortedEvictionQueue takes
- care of most of the common functionality available in a set of eviction
- policy provider classes
- </para>
-
-
-
<para>
- <emphasis>Note that:</emphasis>
+ For each region, you can define parameters which affect how the policy which applies to the region chooses to evict nodes.
+ In the example above, the <literal>LRUPolicy</literal> allows a <literal>maxNodes</literal> parameter which defines
+ how many nodes can exist in the region before it chooses to start evicting nodes. See the javadocs for each
+ policy for a list of allowed parameters.
</para>
-
- <itemizedlist>
- <listitem>
- <para>The BaseEvictionAlgorithm class maintains a processing
- structure. It will process the ADD, REMOVE, and VISIT events queued
- by the Region (events are originated from the
- EvictionTreeCacheListener) first. It also maintains an collection of
- items that were not properly evicted during the last go around
- because of held locks. That list is pruned. Finally, the
- EvictionQueue itself is pruned for entries that should be evicted
- based upon the configured eviction rules for the region.
- </para>
- </listitem>
- </itemizedlist>
-
-
-
- <para>
- <emphasis>Note that:</emphasis>
- </para>
-
- <itemizedlist>
- <listitem>
- <para>The BaseSortedEvictionAlgorithm class will maintain a boolean
- through the algorithm processing that will determine if any new
- nodes were added or visited. This allows the Algorithm to determine
- whether to resort the eviction queue items (in first to evict order)
- or to skip the potentially expensive sorting if there have been no
- changes to the cache in this region.
- </para>
- </listitem>
- </itemizedlist>
-
-
- <para>
- <emphasis>Note that:</emphasis>
- </para>
-
- <itemizedlist>
- <listitem>
- <para>The SortedEvictionQueue interface defines the contract used by
- the BaseSortedEvictionAlgorithm abstract class that is used to
- resort the underlying queue. Again, the queue sorting should be
- sorted in first to evict order. The first entry in the list should
- evict before the last entry in the queue. The last entry in the
- queue should be the last entry that will require eviction.
- </para>
- </listitem>
- </itemizedlist>
</section>
-
<section>
- <title>TreeCache Eviction Policy Configuration</title>
-
- <para>TreeCache 1.2.X allows a single eviction policy provider class to
- be configured for use by all regions. As of TreeCache 1.3.x each cache
- region can define its own eviction policy provider or it can use the
- eviction policy provider class defined at the cache level (1.2.x
- backwards compatibility)
- </para>
-
- <para>Please note that configuring the policy via XML has the implicit restriction that
- the region Fqn can only be String based. Afterall, there is no easy way to
- specify a generic object-based Fqn through external XML. If you need to evict
- non-String based Fqn, you will need to do it at runtime via programmatic API. See
- the following section for examples.
- </para>
-
- <para>Here is an example of a legacy 1.2.x EvictionPolicyConfig element
- to configure TreeCache for use with a single eviction policy
- provider
- </para>
-
- <programlisting>
- <![CDATA[
- <attribute name="EvictionPolicyClass">org.jboss.cache.eviction.LRUPolicy</attribute>
- <!-- Specific eviction policy configurations. This is LRU -->
- <attribute name="EvictionPolicyConfig">
- <config>
- <attribute name="wakeUpIntervalSeconds">5</attribute>
- <!-- This defaults to 200000 if not specified -->
- <attribute name="eventQueueSize">100000</attribute>
- <!-- Cache wide default -->
- <region name="/_default_">
- <attribute name="maxNodes">5000</attribute>
- <attribute name="timeToLiveSeconds">1000</attribute>
- </region>
- <region name="/org/jboss/data">
- <attribute name="maxNodes">5000</attribute>
- <attribute name="timeToLiveSeconds">1000</attribute>
- </region>
- <region name="/org/jboss/test/data">
- <attribute name="maxNodes">5</attribute>
- <attribute name="timeToLiveSeconds">4</attribute>
- </region>
- <region name="/test/">
- <attribute name="maxNodes">10000</attribute>
- <attribute name="timeToLiveSeconds">5</attribute>
- </region>
- <region name="/maxAgeTest/">
- <attribute name="maxNodes">10000</attribute>
- <attribute name="timeToLiveSeconds">8</attribute>
- <attribute name="maxAgeSeconds">10</attribute>
- </region>
- </config>
- </attribute>
- ]]>
- </programlisting>
-
- <para>Here is an example of configuring a different eviction provider
- per region
- </para>
-
- <programlisting>
- <![CDATA[
- <attribute name="EvictionPolicyConfig">
- <config>
- <!-- This defaults to 200000 if not specified -->
- <attribute name="eventQueueSize">100000</attribute>
- <attribute name="wakeUpIntervalSeconds">5</attribute>
- <!-- Cache wide default -->
- <region name="/_default_" policyClass="org.jboss.cache.eviction.LRUPolicy">
- <attribute name="maxNodes">5000</attribute>
- <attribute name="timeToLiveSeconds">1000</attribute>
- </region>
- <region name="/org/jboss/data" policyClass="org.jboss.cache.eviction.LFUPolicy">
- <attribute name="maxNodes">5000</attribute>
- <attribute name="minNodes">1000</attribute>
- </region>
- <region name="/org/jboss/test/data" policyClass="org.jboss.cache.eviction.FIFOPolicy">
- <attribute name="maxNodes">5</attribute>
- </region>
- <region name="/test/" policyClass="org.jboss.cache.eviction.MRUPolicy">
- <attribute name="maxNodes">10000</attribute>
- </region>
- <region name="/maxAgeTest/" policyClass="org.jboss.cache.eviction.LRUPolicy">
- <attribute name="maxNodes">10000</attribute>
- <attribute name="timeToLiveSeconds">8</attribute>
- <attribute name="maxAgeSeconds">10</attribute>
- </region>
- </config>
- </attribute>
- ]]>
- </programlisting>
-
- <para>Lastly, an example of mixed mode. In this scenario the regions
- that have a specific policy defined will use that policy. Those that do
- not will default to the policy defined on the entire cache
- instance.
+ <title>Programmatic Configuration</title>
+ <para>
+ Configuring eviction using the <literal>Configuration</literal> object entails the use of the <literal>org.jboss.cache.config.EvictionConfig</literal>
+ bean, which is passed into <literal>Configuration.setEvictionConfig()</literal>.
</para>
-
- <programlisting>
- <![CDATA[
- <attribute name="EvictionPolicyClass">org.jboss.cache.eviction.LRUPolicy</attribute>
- <!-- Specific eviction policy configurations. This is LRU -->
- <attribute name="EvictionPolicyConfig">
- <config>
- <attribute name="wakeUpIntervalSeconds">5</attribute>
- <!-- This defaults to 200000 if not specified -->
- <attribute name="eventQueueSize">100000</attribute>
- <!-- Cache wide default -->
- <region name="/_default_">
- <attribute name="maxNodes">5000</attribute>
- <attribute name="timeToLiveSeconds">1000</attribute>
- </region>
- <region name="/org/jboss/data" policyClass="org.jboss.cache.eviction.FIFOPolicy">
- <attribute name="maxNodes">5000</attribute>
- </region>
- <region name="/test/" policyClass="org.jboss.cache.eviction.MRUPolicy">
- <attribute name="maxNodes">10000</attribute>
- </region>
- <region name="/maxAgeTest/">
- <attribute name="maxNodes">10000</attribute>
- <attribute name="timeToLiveSeconds">8</attribute>
- <attribute name="maxAgeSeconds">10</attribute>
- </region>
- </config>
- </attribute>
- ]]>
- </programlisting>
</section>
- <section>
- <title>Dynamic eviction policy configuration</title>
-
- <para>TreeCache now allows reconfiguration of eviction policy providers
- programatically at runtime. An example of how to reconfigure at runtime
- and how to set an LRU region to have maxNodes to 12345 timeToLiveSeconds
- to 500 and maxAgeSeconds to 1000 programatically.
- </para>
-
- <programlisting>
- <![CDATA[
- // note this is just to show that a running TreeCache instance must be
- // retrieved somehow. How it is implemented is up to the implementor.
- TreeCache cache = getRunningTreeCacheInstance();
-
- org.jboss.cache.RegionManager regionManager = cache.getRegionManager();
- org.jboss.cache.Region region = regionManager.getRegion("/myRegionName", true);
- EvictionConfiguation config = region.getEvictionConfiguration();
- ((LRUConfiguration)config).setMaxNodes(12345);
- ((LRUConfiguration)config).setTimeToLiveSeconds(500);
- ((LRUConfiguration)config).setMaxAgeSeconds(1000);
- ]]>
- </programlisting>
-
- <para>Here is another example that shows how to insert a region at runtime:</para>
- <programlisting>
- <![CDATA[
- // cache needs to be started first
- cache_.start();
-
- // region name is ignored here.
- String xml = "<region name="/dummy">" +
- "<attribute name="maxNodes">10000</attribute>" +
- "<attribute name="timeToLiveSeconds">4</attribute>" +
- "</region>";
- Element element = XmlHelper.stringToElement(xml);
-
- RegionManager regionManager = cache_.getEvictionRegionManager();
- // Fqn is the region name
- Integer ii = new Integer(1);
- Fqn fqn = new Fqn(ii);
- // Create region will be added to the eviction process automatically
- Region region = regionManager.createRegion(fqn, element);
- ]]>
- </programlisting>
- <para>Afterwards, a cache put like the following will be evicted later:</para>
- <programlisting>
- <![CDATA[
- Integer ii = new Integer(1);
- Fqn rootfqn = new Fqn(ii);
- Integer in = new Integer(3);
- Fqn fqn = new Fqn(rootfqn, in);
- cache_.put(fqn, in, in);
- ]]>
- </programlisting>
</section>
<section>
- <title>TreeCache LRU eviction policy implementation</title>
+ <title>Shipped Eviction Policies</title>
+ <section>
+ <title>LRUPolicy - Least Recently Used</title>
- <para>TreeCache has implemented a LRU eviction policy,
+ <para>
<literal>org.jboss.cache.eviction.LRUPolicy</literal>
- , that controls
- both the node lifetime and age. This policy guarantees O(n) = 1 for
+ controls both the node lifetime and age. This policy guarantees O(n) = 1 for
adds, removals and lookups (visits). It has the following configuration
parameters:
</para>
<itemizedlist>
+ <listitem><literal>maxNodes</literal> - This is the maximum number of nodes allowed in this region. 0 denotes no limit.</listitem>
<listitem>
- <para>
- <literal>wakeUpIntervalSeconds</literal>
- . This is the interval
- (in seconds) to process the node events and also to perform sweeping
- for the size limit and age-out nodes.
- </para>
+ <literal>timeToLiveSeconds</literal> - Time to idle (in seconds) before the node is swept away. 0 denotes no limit.
</listitem>
<listitem>
- <para>
- <literal>Region</literal>
- . Region is a group of nodes that
- possess the same eviction policy, e.g., same expired time. In
- TreeCache, region is denoted by a fqn, e.g.,
- <literal>/company/personnel</literal>
- , and it is recursive. In
- specifying the region, the order is important. For example, if
- <literal>/org/jboss/test</literal>
- is specified before
- <literal>/org/jboss/test/data</literal>
- , then any node under
- <literal>/org/jboss/test/data</literal>
- belongs to the first region
- rather than the second. Note also that whenever eviction policy is
- activated, there should always be a
- <literal>/_default_</literal>
- region which covers all the eviction policies not specified by the
- user. In addition, the region configuration is not programmable,
- i.e., all the policies have to be specified via XML
- configuration.
- <itemizedlist>
- <listitem>
- <para>
- <literal>maxNodes</literal>
- . This is the maximum number
- of nodes allowed in this region. 0 denotes no limit.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>timeToLiveSeconds</literal>
- . Time to idle (in
- seconds) before the node is swept away. 0 denotes no
- limit.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>maxAgeSeconds</literal>
- . Time an object should
- exist in TreeCache (in seconds) regardless of idle time before
- the node is swept away. 0 denotes no limit.
- </para>
- </listitem>
- </itemizedlist>
- </para>
+ <literal>maxAgeSeconds</literal> - Lifespan of a node (in seconds) regardless of idle time before the node is swept away. 0 denotes no limit.
</listitem>
</itemizedlist>
-
- <para>Please see the above section for an example.</para>
</section>
<section>
- <title>TreeCache FIFO eviction policy implementation</title>
+ <title>FIFOPolicy - First In, First Out</title>
- <para>TreeCache has implemented a FIFO eviction policy,
+ <para>
<literal>org.jboss.cache.eviction.FIFOPolicy</literal>
- , that will
- control the eviction in a proper first in first out order. This policy
+ controls the eviction in a proper first in first out order. This policy
guarantees O(n) = 1 for adds, removals and lookups (visits). It has the
following configuration parameters:
</para>
<itemizedlist>
- <listitem>
- <para>
- <literal>wakeUpIntervalSeconds</literal>
- . This is the interval
- (in seconds) to process the node events and also to perform sweeping
- for the size limit and age-out nodes.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>Region</literal>
- . Region is a group of nodes that
- possess the same eviction policy, e.g., same expired time. In
- TreeCache, region is denoted by a fqn, e.g.,
- <literal>/company/personnel</literal>
- , and it is recursive. In
- specifying the region, the order is important. For example, if
- <literal>/org/jboss/test</literal>
- is specified before
- <literal>/org/jboss/test/data</literal>
- , then any node under
- <literal>/org/jboss/test/data</literal>
- belongs to the first region
- rather than the second. Note also that whenever eviction policy is
- activated, there should always be a
- <literal>/_default_</literal>
- region which covers all the eviction policies not specified by the
- user. In addition, the region configuration is not programmable,
- i.e., all the policies have to be specified via XML
- configuration.
- <itemizedlist>
- <listitem>
- <para>
- <literal>maxNodes</literal>
- . This is the maximum number
- of nodes allowed in this region. Any integer less than or
- equal to 0 will throw an exception when the policy provider is
- being configured for use.
- </para>
- </listitem>
+ <listitem><literal>maxNodes</literal> - This is the maximum number of nodes allowed in this region. 0 denotes no limit.</listitem>
</itemizedlist>
- </para>
- </listitem>
- </itemizedlist>
-
- <para>Please read the above section for an example.</para>
</section>
+
<section>
- <title>TreeCache MRU eviction policy implementation</title>
+ <title>MRUPolicy - Most Recently Used</title>
- <para>TreeCache has implemented a MRU eviction policy,
+ <para>
<literal>org.jboss.cache.eviction.MRUPolicy</literal>
- , that will control
+ controls
the eviction in based on most recently used algorithm. The most recently
used nodes will be the first to evict with this policy. This policy
guarantees O(n) = 1 for adds, removals and lookups (visits). It has the
@@ -525,61 +142,16 @@
</para>
<itemizedlist>
- <listitem>
- <para>
- <literal>wakeUpIntervalSeconds</literal>
- . This is the interval
- (in seconds) to process the node events and also to perform sweeping
- for the size limit and age-out nodes.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>Region</literal>
- . Region is a group of nodes that
- possess the same eviction policy, e.g., same expired time. In
- TreeCache, region is denoted by a fqn, e.g.,
- <literal>/company/personnel</literal>
- , and it is recursive. In
- specifying the region, the order is important. For example, if
- <literal>/org/jboss/test</literal>
- is specified before
- <literal>/org/jboss/test/data</literal>
- , then any node under
- <literal>/org/jboss/test/data</literal>
- belongs to the first region
- rather than the second. Note also that whenever eviction policy is
- activated, there should always be a
- <literal>/_default_</literal>
- region which covers all the eviction policies not specified by the
- user. In addition, the region configuration is not programmable,
- i.e., all the policies have to be specified via XML
- configuration.
- <itemizedlist>
- <listitem>
- <para>
- <literal>maxNodes</literal>
- . This is the maximum number
- of nodes allowed in this region. Any integer less than or
- equal to 0 will throw an exception when the policy provider is
- being configured for use.
- </para>
- </listitem>
+ <listitem><literal>maxNodes</literal> - This is the maximum number of nodes allowed in this region. 0 denotes no limit.</listitem>
</itemizedlist>
- </para>
- </listitem>
- </itemizedlist>
-
- <para>Please read the above section for an example.</para>
</section>
<section>
- <title>TreeCache LFU eviction policy implementation</title>
+ <title>LFUPolicy - Least Frequently Used</title>
- <para>TreeCache has implemented a LFU eviction policy,
+ <para>
<literal>org.jboss.cache.eviction.LFUPolicy</literal>
- , that will control
+ controls
the eviction in based on least frequently used algorithm. The least
frequently used nodes will be the first to evict with this policy. Node
usage starts at 1 when a node is first added. Each time it is visted,
@@ -596,80 +168,28 @@
</para>
<itemizedlist>
- <listitem>
- <para>
- <literal>wakeUpIntervalSeconds</literal>
- . This is the interval
- (in seconds) to process the node events and also to perform sweeping
- for the size limit and age-out nodes.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>Region</literal>
- . Region is a group of nodes that
- possess the same eviction policy, e.g., same expired time. In
- TreeCache, region is denoted by a fqn, e.g.,
- <literal>/company/personnel</literal>
- , and it is recursive. In
- specifying the region, the order is important. For example, if
- <literal>/org/jboss/test</literal>
- is specified before
- <literal>/org/jboss/test/data</literal>
- , then any node under
- <literal>/org/jboss/test/data</literal>
- belongs to the first region
- rather than the second. Note also that whenever eviction policy is
- activated, there should always be a
- <literal>/_default_</literal>
- region which covers all the eviction policies not specified by the
- user. In addition, the region configuration is not programmable,
- i.e., all the policies have to be specified via XML
- configuration.
- <itemizedlist>
- <listitem>
- <para>
- <literal>maxNodes</literal>
- . This is the maximum number
- of nodes allowed in this region. A value of 0 for maxNodes
- means that there is no upper bound for the configured cache
- region.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>minNodes</literal>
- . This is the minimum number
- of nodes allowed in this region. This value determines what
+ <listitem><literal>maxNodes</literal> - This is the maximum number of nodes allowed in this region. 0 denotes no limit.</listitem>
+ <listitem><literal>minNodes</literal> - This is the minimum number of nodes allowed in this region. This value determines what
the eviction queue should prune down to per pass. e.g. If
minNodes is 10 and the cache grows to 100 nodes, the cache is
pruned down to the 10 most frequently used nodes when the
eviction timer makes a pass through the eviction
- algorithm.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
+ algorithm.</listitem>
+
</itemizedlist>
- <para>Please read the above section for an example.</para>
</section>
<section>
- <title>TreeCache expiration eviction policy implementation</title>
+ <title>ExpirationPolicy</title>
<para>
- TreeCache has implemented a per-node expiration and eviction
- policy,
<literal>org.jboss.cache.eviction.ExpirationPolicy</literal>
- ,
+ is a policy
that evicts nodes based on an absolute expiration time. The
expiration time is indicated using the
<literal>org.jboss.cache.Node.put()</literal>
- method, using a key String
+ method, using a String key
<literal>expiration</literal>
and the absolute time as a
<literal>java.lang.Long</literal>
@@ -682,7 +202,7 @@
<para>
This policy guarantees O(n) = 1 for adds and removals.
Internally, a sorted set (TreeSet) containing the expiration
- time and FQN of the nodes is stored, which essentially
+ time and Fqn of the nodes is stored, which essentially
functions as a heap.
</para>
@@ -692,58 +212,33 @@
<itemizedlist>
<listitem>
- <para>
- <literal>wakeUpIntervalSeconds</literal>
- . This is the interval
- (in seconds) to process the node events and also to perform removal
- for expired nodes and check the size limit.
- </para>
- </listitem>
-
- <listitem>
- <para>
<literal>expirationKeyName</literal>
- . This is the Node key name used
+ - This is the Node key name used
in the eviction algorithm. The configuration default is
- <literal>expiration</literal>
- .
- </para>
+ <literal>expiration</literal>.
</listitem>
+ <listitem><literal>maxNodes</literal> - This is the maximum number of nodes allowed in this region. 0 denotes no limit.</listitem>
- <listitem>
- <para>
- <literal>Region</literal>
- . Region is a group of nodes that
- possess this eviction policy.
- <itemizedlist>
- <listitem>
- <para>
- <literal>maxNodes</literal>
- . This is the maximum number
- of nodes allowed in this region. If the number of nodes for
- a region exceeds this amount, then eviction will occur first for
- the soonest to expire nodes.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
</itemizedlist>
<para>
The following listing shows how the expiration date is indicated and how the
policy is applied:
<programlisting>
- <![CDATA[
- Cache cache;
+<![CDATA[
+ Cache cache = DefaultCacheFactory.createCache();
Fqn fqn1 = Fqn.fromString("/node/1");
Long future = new Long(System.currentTimeMillis() + 2000);
- cache.put(fqn1, ExpirationConfiguration.EXPIRATION_KEY, future);
- assertTrue(cache.get(fqn1) != null);
+
+ // sets the expiry time for a node
+ cache.getRoot().addChild(fqn1).put(ExpirationConfiguration.EXPIRATION_KEY, future);
+
+ assertTrue(cache.getRoot().hasChild(fqn1));
Thread.sleep(5000);
+
// after 5 seconds, expiration completes
- assertTrue(cache.get(fqn1) == null);
- ]]>
+ assertFalse(cache.getRoot().hasChild(fqn1));
+]]>
</programlisting>
Note that the expiration time of nodes is only checked when the
region manager wakes up every
@@ -752,5 +247,124 @@
may happen a few seconds later than indicated.
</para>
</section>
+ </section>
+
+ <section>
+ <title>Writing Your Own Eviction Policies</title>
+ <section>
+ <title>Eviction Policy Plugin Design</title>
+
+ <para>The design of the JBoss Cache eviction policy framework is based
+ on an <literal>EvictionInterceptor</literal> to handle cache events and relay them back to the eviction
+ policies. During the cache start up, an <literal>EvictionInterceptor</literal> will be added to the cache
+ interceptor stack if the eviction policy is specified.
+ Then whenever a node is added, removed, evicted, or visited, the
+ <literal>EvictionInterceptor</literal> will maintain state statistics and
+ information will be relayed to each individual eviction region.
+ </para>
+
+ <para>
+ There is a single eviction thread (timer) that will run at a
+ configured interval. This thread will make calls into each of the policy
+ providers and inform it of any aggregated adds,
+ removes and visits (gets) events to the cache during the configured interval.
+ The eviction thread is responsible for kicking off the eviction policy
+ processing (a single pass) for each configured eviction cache
+ region.
+ </para>
+ </section>
+ <section>
+ <title>Interfaces to implement</title>
+ <para>In order to implement an eviction policy, the following interfaces
+ must be implemented:
+ <itemizedlist>
+ <listitem><literal>org.jboss.cache.eviction.EvictionPolicy</literal></listitem>
+ <listitem><literal>org.jboss.cache.eviction.EvictionAlgorithm</literal></listitem>
+ <listitem><literal>org.jboss.cache.eviction.EvictionQueue</literal></listitem>
+ <listitem><literal>org.jboss.cache.eviction.EvictionConfiguration</literal></listitem>
+ </itemizedlist>
+ When compounded
+ together, each of these interface implementations define all the
+ underlying mechanics necessary for a complete eviction policy
+ implementation.
+ </para>
+
+ <figure>
+ <title>TreeCache eviction UML Diagram</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/EvictionUML.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+
+ <para>
+ <emphasis>Note that:</emphasis>
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The EvictionConfiguration class <literal>parseXMLConfig(Element)</literal>
+ method expects only the DOM element pertaining to the region the
+ policy is being configured for.
+ </para>
+ </listitem>
+ <listitem>
+ <para>The EvictionConfiguration implementation should maintain
+ getter and setter methods for configured properties pertaining to
+ the policy used on a given cache region. (e.g. for <literal>LRUConfiguration</literal>
+ there is a <literal>int getMaxNodes()</literal> and a <literal>setMaxNodes(int)</literal>)
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Alternatively, the implementation of a new eviction policy
+ provider can be simplified by extending <literal>BaseEvictionPolicy</literal> and
+ <literal>BaseEvictionAlgorithm</literal>. Or for properly sorted EvictionAlgorithms (sorted
+ in eviction order - see <literal>LFUAlgorithm</literal>) extending
+ <literal>BaseSortedEvictionAlgorithm</literal> and implementing <literal>SortedEvictionQueue</literal> takes
+ care of most of the common functionality available in a set of eviction
+ policy provider classes
+ </para>
+
+
+ <para>
+ <emphasis>Note that:</emphasis>
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The <literal>BaseEvictionAlgorithm</literal> class maintains a processing
+ structure. It will process the ADD, REMOVE, and VISIT events queued
+ by the region first. It also maintains an collection of
+ items that were not properly evicted during the last go around
+ because of held locks. That list is pruned. Finally, the
+ EvictionQueue itself is pruned for entries that should be evicted
+ based upon the configured eviction rules for the region.
+ </para>
+ </listitem>
+ <listitem>
+ <para>The <literal>BaseSortedEvictionAlgorithm</literal> class will maintain a boolean
+ through the algorithm processing that will determine if any new
+ nodes were added or visited. This allows the Algorithm to determine
+ whether to resort the eviction queue items (in first to evict order)
+ or to skip the potentially expensive sorting if there have been no
+ changes to the cache in this region.
+ </para>
+ </listitem>
+ <listitem>
+ <para>The <literal>SortedEvictionQueue</literal> interface defines the contract used by
+ the <literal>BaseSortedEvictionAlgorithm</literal> abstract class that is used to
+ resort the underlying queue. Again, the queue sorting should be
+ sorted in first to evict order. The first entry in the list should
+ evict before the last entry in the queue. The last entry in the
+ queue should be the last entry that will require eviction.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
</chapter>
\ No newline at end of file
More information about the jboss-cvs-commits
mailing list