xdocs/index.xml - turbine-fulcrum-cache - Git at Google

 <?xml version="1.0"?>
 <!--
  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.
 -->

 <document>

   <properties>
     <title>Cache Component</title>
     <author email="epugh@upstate.com">Eric Pugh</author>
     <author email="tv@apache.org">Thomas Vandahl</author>
     <author email="gk@apache.org">Georg Kallidis</author>
   </properties>

   <body>

   <section name="Overview">
     <p>
       This Service functions as a Global Cache.  A global cache is a good
       place to store items that you may need to access often but don't
       necessarily need (or want) to fetch from the database everytime.  A
       good example would be a look up table of States that you store in a
       database and use throughout your application. Since information
       about States doesn't change very often, you could store this
       information in the Global Cache and decrease the overhead of
       hitting the database everytime you need State information.
     </p>
     <p>
       There are three cache implementations
       <ul>
       	<li>GlobalCacheService,</li>
       	<li>EHCacheService (built on the EHCache project from
       		<a href="https://www.ehcache.org/">ehcache.sourceforge.net</a>, N.B. The implementation is still based on last release 2.10.9.2 of net.sf.ehcache.EHcache) and</li>
       	<li>JCSCacheService (built on the <a href="http://commons.apache.org/proper/commons-jcs/">Java Caching System</a>,
       		which was originally a part of Turbine)</li>
       </ul>
     </p>
     <p>
       It is written for use in Turbine but it can be used in any container
       compatible with Avalon's ECM container.
     </p>
   </section>
   <section name="GlobalCacheService" id="GlobalCacheService">
     <subsection name="Role Configuration">
       <source><![CDATA[
     <role
         name="org.apache.fulcrum.cache.GlobalCacheService"
         shorthand="cache"
         default-class="org.apache.fulcrum.cache.impl.DefaultGlobalCacheService"/>
       ]]></source>
     </subsection>

     <subsection name="Component Configuration">
       <table>
         <tr>
           <th>Item</th>
           <th>Datatype</th>
           <th>Cardinality</th>
           <th>Description</th>
         </tr>
         <tr>
           <td>@cacheInitialSize</td>
           <td>int</td>
           <td>[0|1]</td>
           <td>
             The initial size of the cache. The default is 20.
           </td>
         </tr>
         <tr>
           <td>@cacheCheckFrequency</td>
           <td>int</td>
           <td>[0|1]</td>
           <td>
             The cache uses a background thread to check for expired objects.
             This defines the time between two checks in seconds. The default
             is 5.
           </td>
         </tr>
       </table>
     </subsection>

     <subsection name="Component Configuration Example">
       <source><![CDATA[
     <cache cacheInitialSize="20" cacheCheckFrequency="5"/>
       ]]></source>
     </subsection>
   </section>

   <section name="EHCacheService" id="EHCacheService">

     <subsection name="Role Configuration">
       <source><![CDATA[
     <role
         name="org.apache.fulcrum.cache.GlobalCacheService"
         shorthand="ehcache"
         default-class="org.apache.fulcrum.cache.impl.EHCacheService"/>
       ]]></source>
     </subsection>

     <subsection name="Component Configuration">
       <table>
         <tr>
           <th>Item</th>
           <th>Datatype</th>
           <th>Cardinality</th>
           <th>Description</th>
         </tr>
         <tr>
           <td>cacheCheckFrequency</td>
           <td>int</td>
           <td>[0|1]</td>
           <td>
             The cache uses a background thread to check for expired objects.
             This defines the time between two checks in milliseconds. The
             default is 5000.
           </td>
         </tr>
         <tr>
           <td>cacheName</td>
           <td>String</td>
           <td>[0|1]</td>
           <td>
             The EHcache cache name to use for the cache. The default is
             <code>fulcrum</code>.
           </td>
         </tr>
         <tr>
           <td>configurationFile</td>
           <td>String</td>
           <td>[0|1]</td>
           <td>
             The the location of the EHcache configuration file.
             The default is to create a default cache withut settings.
           </td>
         </tr>
       </table>
       <p>z
         See <a href="http://commons.apache.org/proper/commons-jcs/">the JCS site</a> for more
         information about configuring JCS.
       </p>
     </subsection>

     <subsection name="Component Configuration Example">
       <source><![CDATA[
     <ehcache>
         <cacheCheckFrequency>5000</cacheCheckFrequency>
         <cacheName>fulcrum</cacheName>
         <configurationFile>ehcache.xml</configurationFile>
     </ehcache>
       ]]></source>
     </subsection>
   </section>

   <section name="JCSCacheService" id="JCSCacheService">

 	<p>
 	  The JCS cache service implements the interface <code>GlobalCacheService</code> and thus can
 	  serve as a drop-in replacement for <code>DefaultGlobalCacheService</code>. However it is
 	  possible to configure the cache behavior in much more detail to provide disk caches or lateral TCP
 	  caches for example.
 	</p>

     <subsection name="Role Configuration">
       <source><![CDATA[
     <role
         name="org.apache.fulcrum.cache.GlobalCacheService"
         shorthand="jcscache"
         default-class="org.apache.fulcrum.cache.impl.JCSCacheService"/>
       ]]></source>
     </subsection>

     <subsection name="Component Configuration">
       <table>
         <tr>
           <th>Item</th>
           <th>Datatype</th>
           <th>Cardinality</th>
           <th>Description</th>
         </tr>
         <tr>
           <td>cacheCheckFrequency</td>
           <td>int</td>
           <td>[0|1]</td>
           <td>
             The cache uses a background thread to check for expired objects.
             This defines the time between two checks in milliseconds. The
             default is 5000.
           </td>
         </tr>
         <tr>
           <td>region</td>
           <td>String</td>
           <td>[0|1]</td>
           <td>
             The JCS cache region name to use for the cache. The default is
             <code>fulcrum</code>.
             JCS will store the objects in a group named <code>default_group</code>
             in the given region.
           </td>
         </tr>
         <tr>
           <td>configurationFile</td>
           <td>String</td>
           <td>[0|1]</td>
           <td>
             The the location of the JCS configuration file. Please note that
             JCS uses a class loader to read this file, so make sure this path
             is part of your classpath. The default is <code>/cache.ccf</code>.
           </td>
         </tr>
       </table>
       <p>
         See <a href="http://jakarta.apache.org/jcs/">the JCS site</a> for more
         information about configuring JCS.
       </p>
     </subsection>

     <subsection name="Component Configuration Example">
       <source><![CDATA[
     <jcscache>
     	<cacheCheckFrequency>5000</cacheCheckFrequency>
     	<region>fulcrum</region>
     	<configurationFile>/cache.ccf</configurationFile>
     </jcscache>
       ]]></source>
     </subsection>
   </section>

   <section name="Usage">

     <source><![CDATA[
     GlobalCacheService gs = null;
     try
     {
         /*
          * Look for the item in the cache.
          * If it doesn't exist or the item is stale,
          * the cache will throw an exception.
          */
         gs = (GlobalCacheService)avalonComponentService.lookup(GlobalCacheService.ROLE)

         CachedObject obj = gs.getObject("cached_object");

         data.setMessage( data.getScreen() + " Got " +
             obj.getContents().toString() + " from global cache!" );
     }
     catch(ObjectExpiredException gone)
     {
         /*
          * Add the item to the cache.
          */
         gs.addObject("cached_object",
             new CachedObject("in_the_cache",5000));

         data.setMessage( data.getScreen() +
             " Refreshed/or added new item to" +
             " the cache! Expires in 5 seconds" );
     }
     ]]></source>

     <p>
       You can also place an expiration time on your objects so the Service will
       automatically remove them when they expire. If you don't specify an expiration
       time, the DefaultGlobalCacheService uses 5 seconds. For JCS this value depends on values set
       in the cache configuration file. To see an example, look at the
       test case <a href="xref-test/org/apache/fulcrum/cache/CacheTest.html">CacheTest</a>
     </p>

     <p>
       The cache also supports <code>RefreshableCachedObject</code>s. These objects must implement
       a <code>refresh()</code>-method which will be called every time the cache detects that the
       object is expired. This way, you can keep objects in the cache that "auto-refresh"
       asynchronously.
     </p>
   </section>

 </body>
 </document>
	<?xml version="1.0"?>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->

	<document>

	<properties>
	<title>Cache Component</title>
	<author email="epugh@upstate.com">Eric Pugh</author>
	<author email="tv@apache.org">Thomas Vandahl</author>
	<author email="gk@apache.org">Georg Kallidis</author>
	</properties>

	<body>

	<section name="Overview">
	<p>
	This Service functions as a Global Cache. A global cache is a good
	place to store items that you may need to access often but don't
	necessarily need (or want) to fetch from the database everytime. A
	good example would be a look up table of States that you store in a
	database and use throughout your application. Since information
	about States doesn't change very often, you could store this
	information in the Global Cache and decrease the overhead of
	hitting the database everytime you need State information.
	</p>
	<p>
	There are three cache implementations
	<ul>
	<li>GlobalCacheService,</li>
	<li>EHCacheService (built on the EHCache project from
	<a href="https://www.ehcache.org/">ehcache.sourceforge.net</a>, N.B. The implementation is still based on last release 2.10.9.2 of net.sf.ehcache.EHcache) and</li>
	<li>JCSCacheService (built on the <a href="http://commons.apache.org/proper/commons-jcs/">Java Caching System</a>,
	which was originally a part of Turbine)</li>
	</ul>
	</p>
	<p>
	It is written for use in Turbine but it can be used in any container
	compatible with Avalon's ECM container.
	</p>
	</section>
	<section name="GlobalCacheService" id="GlobalCacheService">
	<subsection name="Role Configuration">
	<source><![CDATA[
	<role
	name="org.apache.fulcrum.cache.GlobalCacheService"
	shorthand="cache"
	default-class="org.apache.fulcrum.cache.impl.DefaultGlobalCacheService"/>
	]]></source>
	</subsection>

	<subsection name="Component Configuration">
	<table>
	<tr>
	<th>Item</th>
	<th>Datatype</th>
	<th>Cardinality</th>
	<th>Description</th>
	</tr>
	<tr>
	<td>@cacheInitialSize</td>
	<td>int</td>
	<td>[0\|1]</td>
	<td>
	The initial size of the cache. The default is 20.
	</td>
	</tr>
	<tr>
	<td>@cacheCheckFrequency</td>
	<td>int</td>
	<td>[0\|1]</td>
	<td>
	The cache uses a background thread to check for expired objects.
	This defines the time between two checks in seconds. The default
	is 5.
	</td>
	</tr>
	</table>
	</subsection>

	<subsection name="Component Configuration Example">
	<source><![CDATA[
	<cache cacheInitialSize="20" cacheCheckFrequency="5"/>
	]]></source>
	</subsection>
	</section>

	<section name="EHCacheService" id="EHCacheService">

	<subsection name="Role Configuration">
	<source><![CDATA[
	<role
	name="org.apache.fulcrum.cache.GlobalCacheService"
	shorthand="ehcache"
	default-class="org.apache.fulcrum.cache.impl.EHCacheService"/>
	]]></source>
	</subsection>

	<subsection name="Component Configuration">
	<table>
	<tr>
	<th>Item</th>
	<th>Datatype</th>
	<th>Cardinality</th>
	<th>Description</th>
	</tr>
	<tr>
	<td>cacheCheckFrequency</td>
	<td>int</td>
	<td>[0\|1]</td>
	<td>
	The cache uses a background thread to check for expired objects.
	This defines the time between two checks in milliseconds. The
	default is 5000.
	</td>
	</tr>
	<tr>
	<td>cacheName</td>
	<td>String</td>
	<td>[0\|1]</td>
	<td>
	The EHcache cache name to use for the cache. The default is
	<code>fulcrum</code>.
	</td>
	</tr>
	<tr>
	<td>configurationFile</td>
	<td>String</td>
	<td>[0\|1]</td>
	<td>
	The the location of the EHcache configuration file.
	The default is to create a default cache withut settings.
	</td>
	</tr>
	</table>
	<p>z
	See <a href="http://commons.apache.org/proper/commons-jcs/">the JCS site</a> for more
	information about configuring JCS.
	</p>
	</subsection>

	<subsection name="Component Configuration Example">
	<source><![CDATA[
	<ehcache>
	<cacheCheckFrequency>5000</cacheCheckFrequency>
	<cacheName>fulcrum</cacheName>
	<configurationFile>ehcache.xml</configurationFile>
	</ehcache>
	]]></source>
	</subsection>
	</section>

	<section name="JCSCacheService" id="JCSCacheService">

	<p>
	The JCS cache service implements the interface <code>GlobalCacheService</code> and thus can
	serve as a drop-in replacement for <code>DefaultGlobalCacheService</code>. However it is
	possible to configure the cache behavior in much more detail to provide disk caches or lateral TCP
	caches for example.
	</p>

	<subsection name="Role Configuration">
	<source><![CDATA[
	<role
	name="org.apache.fulcrum.cache.GlobalCacheService"
	shorthand="jcscache"
	default-class="org.apache.fulcrum.cache.impl.JCSCacheService"/>
	]]></source>
	</subsection>

	<subsection name="Component Configuration">
	<table>
	<tr>
	<th>Item</th>
	<th>Datatype</th>
	<th>Cardinality</th>
	<th>Description</th>
	</tr>
	<tr>
	<td>cacheCheckFrequency</td>
	<td>int</td>
	<td>[0\|1]</td>
	<td>
	The cache uses a background thread to check for expired objects.
	This defines the time between two checks in milliseconds. The
	default is 5000.
	</td>
	</tr>
	<tr>
	<td>region</td>
	<td>String</td>
	<td>[0\|1]</td>
	<td>
	The JCS cache region name to use for the cache. The default is
	<code>fulcrum</code>.
	JCS will store the objects in a group named <code>default_group</code>
	in the given region.
	</td>
	</tr>
	<tr>
	<td>configurationFile</td>
	<td>String</td>
	<td>[0\|1]</td>
	<td>
	The the location of the JCS configuration file. Please note that
	JCS uses a class loader to read this file, so make sure this path
	is part of your classpath. The default is <code>/cache.ccf</code>.
	</td>
	</tr>
	</table>
	<p>
	See <a href="http://jakarta.apache.org/jcs/">the JCS site</a> for more
	information about configuring JCS.
	</p>
	</subsection>

	<subsection name="Component Configuration Example">
	<source><![CDATA[
	<jcscache>
	<cacheCheckFrequency>5000</cacheCheckFrequency>
	<region>fulcrum</region>
	<configurationFile>/cache.ccf</configurationFile>
	</jcscache>
	]]></source>
	</subsection>
	</section>

	<section name="Usage">

	<source><![CDATA[
	GlobalCacheService gs = null;
	try
	{
	/*
	* Look for the item in the cache.
	* If it doesn't exist or the item is stale,
	* the cache will throw an exception.
	*/
	gs = (GlobalCacheService)avalonComponentService.lookup(GlobalCacheService.ROLE)

	CachedObject obj = gs.getObject("cached_object");

	data.setMessage( data.getScreen() + " Got " +
	obj.getContents().toString() + " from global cache!" );
	}
	catch(ObjectExpiredException gone)
	{
	/*
	* Add the item to the cache.
	*/
	gs.addObject("cached_object",
	new CachedObject("in_the_cache",5000));

	data.setMessage( data.getScreen() +
	" Refreshed/or added new item to" +
	" the cache! Expires in 5 seconds" );
	}
	]]></source>

	<p>
	You can also place an expiration time on your objects so the Service will
	automatically remove them when they expire. If you don't specify an expiration
	time, the DefaultGlobalCacheService uses 5 seconds. For JCS this value depends on values set
	in the cache configuration file. To see an example, look at the
	test case <a href="xref-test/org/apache/fulcrum/cache/CacheTest.html">CacheTest</a>
	</p>

	<p>
	The cache also supports <code>RefreshableCachedObject</code>s. These objects must implement
	a <code>refresh()</code>-method which will be called every time the cache detects that the
	object is expired. This way, you can keep objects in the cache that "auto-refresh"
	asynchronously.
	</p>
	</section>

	</body>
	</document>