[jboss-cvs] JBossCache/docs/TreeCache/en/modules ...

[Ben Wang]

  User: bwang   
  Date: 06/10/10 00:12:27

  Modified:    docs/TreeCache/en/modules  eviction_policies.xml
  Log:
  Progrmmatic eviction policy update
  
  Revision  Changes    Path
  1.5       +49 -9     JBossCache/docs/TreeCache/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/TreeCache/en/modules/eviction_policies.xml,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -b -r1.4 -r1.5
  --- eviction_policies.xml	10 Jul 2006 14:50:02 -0000	1.4
  +++ eviction_policies.xml	10 Oct 2006 04:12:27 -0000	1.5
  @@ -1,18 +1,21 @@
   <chapter id="eviction_policies">
       <title>Eviction Policies</title>
   
  -    <para>Eviction policies specify the behavior of a node residing inside the
  -    cache, e.g., life time and maximum numbers allowed.  Memory constraints on servers mean caches cannot grow indefinitely, so policies need to be in place to restrict the size of the cache in memory.</para>
  +    <para>Eviction policies specify the living behavior of a node residing inside the
  +    cache, e.g., life time and maximum numbers allowed.
  +       Memory constraints on servers mean cache cannot grow indefinitely, so policies
  +       need to be in place to restrict the size of the cache in memory.</para>
   
       <section>
         <title>Eviction Policy Plugin</title>
   
         <para>The design of the JBoss Cache eviction policy framework is based
  -      on the loosely coupled observable pattern (albeit still synchronous)
  -      where the eviction region manager will register a <literal>TreeCacheListener</literal> to
  -      handle cache events and relay them back to the eviction policies.
  -      Whenever a cached node is added, removed, evicted, or visited, the
  -      eviction registered <literal>TreeCacheListener</literal> will maintain state statistics and
  +      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
  @@ -21,8 +24,8 @@
   
         <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 <literal>TreeCacheListener</literal> aggregated adds,
  -      removes and visits (gets) to the cache during the configured interval.
  +      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>
  @@ -807,6 +810,12 @@
         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>
  @@ -904,6 +913,9 @@
            &lt;/config&gt;
         &lt;/attribute&gt;
          </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
  @@ -922,6 +934,34 @@
            ((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>
  +         // cache needs to be started first
  +         cache_.start();
  +
  +         // region name is ignored here.
  +         String xml = "&lt;region name="/dummy"&gt;" +
  +               "&lt;attribute name="maxNodes"&gt;10000&lt;/attribute&gt;" +
  +               "&lt;attribute name="timeToLiveSeconds"&gt;4&lt;/attribute&gt;" +
  +               "&lt;/region&gt;";
  +         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>
  +         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>