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

[Elias Ross]

  User: genman  
  Date: 07/01/09 19:10:46

  Modified:    docs/TreeCache/en/modules  eviction_policies.xml
  Log:
  JBCACHE-880 - Add documention/examples for this policy
  
  Revision  Changes    Path
  1.9       +80 -0     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.8
  retrieving revision 1.9
  diff -u -b -r1.8 -r1.9
  --- eviction_policies.xml	14 Nov 2006 14:17:12 -0000	1.8
  +++ eviction_policies.xml	10 Jan 2007 00:10:46 -0000	1.9
  @@ -1210,4 +1210,84 @@
   
         <para>Please read the above section for an example.</para>
       </section>
  +    
  +    <section>
  +      <title>TreeCache expiration eviction policy implementation</title>
  +
  +      <para>
  +      	TreeCache has implemented a per-node expiration and eviction
  +      	policy,
  +      	<literal>org.jboss.cache.eviction.ExpirationPolicy</literal>,
  +      	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
  +      	<literal>expiration</literal>
  +      	and the absolute time as a
  +      	<literal>java.lang.Long</literal>
  +      	object, with a value indicated as milliseconds past midnight
  +      	January 1st, 1970 UTC (the same relative time as provided by
  +      	<literal>java.lang.System.currentTimeMillis()</literal>).
  +      </para>
  +
  +      <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
  +      	functions as a heap.
  +      </para>
  +
  +      <para>
  +      	This policy 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 removal
  +          for expired nodes and check the size limit.</para>
  +        </listitem>
  +
  +        <listitem>
  +          <para>
  +          	<literal>expirationKeyName</literal>. This is the Node key name used
  +          in the eviction algorithm. The configuration default is
  +          <literal>expiration</literal>.
  +          </para>
  +        </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>
  +      		Cache cache;
  +      		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);
  +			Thread.sleep(5000);
  +			// after 5 seconds, expiration completes
  +			assertTrue(cache.get(fqn1) == null);
  +      	</programlisting>
  +      	Note that the expiration time of nodes is only checked when the
  +      	region manager wakes up every
  +      	<literal>wakeUpIntervalSeconds</literal>, so eviction
  +      	may happen a few seconds later than indicated.
  +      </para>
  +    </section>
  +
     </chapter>
  \ No newline at end of file