Source

oscache / docs / configuration.html

Full commit
<html>
<head>
<title>OSCache Configuration Guide</title>
</head>
<body bgcolor="#FFFFFF">
<p>This guide only covers the configuration of OSCache by using the <code>oscache.properties</code> file.
  To see how to install OSCache and where to place the <code>oscache.properties</code> file, see the
  <a href="install.html">Installation Guide</a>.</p>

The following properties are able to be set in the <code>oscache.properties</code> file:

<h3>cache.memory</h3>
<p>Valid values are <code>true</code> or <code>false</code>, with <code>true</code> being the default value.
If you want to disable memory caching, just comment out or remove this line.</p>
<p>Note: disabling memory AND disk caching is possible but fairly stupid ;)</p>

<h3>cache.capacity</h3>
<p>The maximum number of items that a cache will hold. By default the capacity is unlimited - the cache will
never remove any items. Negative values will also be treated as meaning unlimited capacity.</p>

<h3>cache.algorithm</h3>
<p>The default cache algorithm to use. Note that in order to use an algorithm the cache size must also
be specified. If the cache size is not specified, the cache algorithm will be Unlimited cache regardless
of the value of this property. If you specify a size but not an algorithm, the cache algorithm used will be
<code>com.opensymphony.oscache.base.algorithm.LRUCache</code>.</p>
<p>OSCache currently comes with three algorithms:
<ul>
  <li><code>com.opensymphony.oscache.base.algorithm.LRUCache</code> - Least Recently Used. This is the
  default when a <code>cache.capacity</code> is set.</li>
  <li><code>com.opensymphony.oscache.base.algorithm.FIFOCache</code> - First In First Out.</li>
  <li><code>com.opensymphony.oscache.base.algorithm.UnlimitedCache</code> - Content that is added to
  the cache will never be discarded. This is the default when no value is set for the <code>cache.capacity</code>
  property.</li>
</ul>
</p>

<h3>cache.blocking</h3>
<p>When a request is made for a stale cache entry, it is possible that another thread is already in the process
of rebuilding that entry. This setting specifies how OSCache handles the subsequent 'non-building' threads. The
default behaviour (<code>cache.blocking=false</code>) is to serve the old content to subsequent threads until the
cache entry has been updated. This provides the best performance (at the cost of serving slightly stale data).
When blocking is enabled, threads will instead block until the new cache entry is ready to be served.
Once the new entry is put in the cache the blocked threads will be restarted and given the new entry.</p>
<p>Note that <em>even if blocking is disabled</em>, when there is no stale data available to be served threads
will block until the data is added to the cache by the thread that is responsible for building the data.</p>

<h3>cache.unlimited.disk</h3>
<p>Indicates whether the disk cache should be treated as unlimited or not. The default value is
<code>false</code>.</p>

<h3>cache.persistence.class</h3>
<p>Specifies the class to use for persisting cache entries. This class must implement the <code>PersistenceListener</code>
interface. OSCache comes with an implementation that provides filesystem based persistence. Set this property
to <code>com.opensymphony.oscache.plugins.diskpersistence.DiskPersistenceListener</code> to enable this
implementation. By specifying your own class here you should be able to persist cache data using say JDBC or LDAP.</p>
<p>The <code>DiskPersistenceListener</code> class requires the following extra configuration property to be
set:
<blockquote>
<h3>cache.path</h3>
<p>This specifies the directory on disk where caches will be stored. The directory will be created if it
doesn't already exist, but remember that OSCache must have permission to write to this location.</p>
<p>Note: for Windows machines, the backslash character '\' needs to be escaped. ie in Windows:</p>
<p><code>cache.path=c:\\myapp\\cache</code></p>
<p>or *ix:</p>
<p><code>cache.path=/opt/myapp/cache</code></p>
</blockquote>

<h3>cache.event.listeners</h3>
<p>This takes a comma-delimited list of fully-qualified class names. Each class in the list <em>must</em>
implement one (or more) of the following interfaces:
<ul>
  <li><b>CacheEntryEventListener</b> - Receives cache add/update/flush and remove events.</li>
  <li><b>CacheMapAccessEventListener</b> - Receives cache access events. This allows you to keep statistical
  information to track how effectively the cache is working.</li>
</ul>
No listeners are configured by default, however some ship with OSCache that you may wish to enable:
<ul>
  <li><b>com.opensymphony.oscache.plugins.clustersupport.BroadcastingCacheEventListener</b>
    - provides clustering support for OSCache. Enabling this will cause cache flush events to be broadcast to
    other instances of OSCache running on your LAN. See <a href="clustering.html">Clustering OSCache</a> for
    further information about this event listener.</li>
  <li><b>com.opensymphony.oscache.extra.CacheEntryEventListenerImpl</b> - a simple listener implementation
    that maintains a running count of all of the entry events that occur during a cache's lifetime.</li>
  <li><b>com.opensymphony.oscache.extra.CacheMapAccessEventListenerImpl</b> - a simple listener implementation
    that keeps count of all the cache map events (cache hits and misses, and stale hits) that occur on a cache
    instance.</li>
</ul>
It is also of course quite straightforward to write your own event listener. See the
<a href="api">JavaDoc API</a> for further details.</p>

<h3>cache.key</h3>
<p>This is the key that will be used by the ServletCacheAdministrator (and hence the custom tags) to
store the cache object in the application and session scope. The default value when this property is
not specified is <code>"__oscache_cache"</code>. If you want to access this default value in your code,
it is available as <code>com.opensymphony.oscache.base.Const.DEFAULT_CACHE_KEY</code>.</p>

<h3>cache.use.host.domain.in.key</h3>
<p>If your server is configured with multiple hosts, you may wish to add host name information to
automatically generated cache keys. If so, set this property to <code>true</code>. The default value
is <code>false</code>.</p>

<h3>Additional Properties</h3>

<p>In additon to the above basic options, any other properties that are specified in this file will still be
loaded and can be made available to your event handlers. For example, the <code>JavaGroupsBroadcastingListener</code>
supports the following additional properties:</p>

<p><b>cache.cluster.multicast.ip</b></p>
<p>The multicast IP to use for this cache cluster. Defaults to <code>231.12.21.132</code>.

<p><b>cache.cluster.properties</b></p>
<p>Specifies additional configuration options for the clustering. The default setting is</p>
<p><pre>UDP(mcast_addr=231.12.21.132;mcast_port=45566;ip_ttl=32;mcast_send_buf_size=150000;mcast_recv_buf_size=80000)
:PING(timeout=2000;num_initial_members=3)
:MERGE2(min_interval=5000;max_interval=10000)
:FD_SOCK:VERIFY_SUSPECT(timeout=1500)
:pbcast.NAKACK(gc_lag=50;retransmit_timeout=300,600,1200,2400,4800)
:pbcast.STABLE(desired_avg_gossip=20000)
:UNICAST(timeout=5000)
:FRAG(frag_size=8096;down_thread=false;up_thread=false)
:pbcast.GMS(join_timeout=5000;join_retry_timeout=2000;shun=false;print_local_addr=true)</pre></p>

<p>See the <a href="clustering.html">Clustering OSCache</a> documentation for further details on the above
two properties.</p>
</body>
</html>