Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<h2>Overview</h2>

<p>This module provides an implementation of a feature cache.</p>

<p>It started out as a Google Summer of Code project:</p>
<ul>
	<li><a href="http://docs.codehaus.org/display/GEOTOOLS/SoC+2007+Caching+data">http://docs.codehaus.org/display/GEOTOOLS/SoC+2007+Caching+data</a></li>
	<li><a class="confluence-link" href="/display/GEOTOOLS/SoC+2007+Caching+data" data-linked-resource-id="79349" data-linked-resource-type="page" data-linked-resource-default-alias="SoC 2007 Caching data" data-base-url="http://docs.codehaus.org">SoC 2007 Caching data</a> for more info</li>
</ul>

<p>It has since been revived to be used in a WFS caching datastore for uDig.</p>

<h2>Class Diagram</h2>

<p><img class="confluence-embedded-image confluence-thumbnail" src="/download/thumbnails/231080212/cachingclassdiagram.png?version=1&amp;modificationDate=1369509256857" data-image-src="/download/attachments/231080212/cachingclassdiagram.png?version=1&amp;modificationDate=1369509256857" data-linked-resource-id="231376271" data-linked-resource-type="attachment" data-linked-resource-default-alias="cachingclassdiagram.png" data-base-url="http://docs.codehaus.org" data-linked-resource-container-id="231080212" title="null > cachingclassdiagram.png"> </p>

<h5>Feature Cache Implementations</h5>

<p>There are currently two implementations of feature cache:</p>

<p><strong>GridFeatureCache</strong></p>
<ul>
	<li>This was the initial implementation for the FeatureCache.</li>
	<li>Based on using a GridSpatialIndex (see below).</li>
	<li>It blocks the entire cache while collecting features from the original feature source and saving them to cache.</li>
	<li>When features are requested the features from the cache and the source are combined into a single in-memory feature collection and returned.</li>
	<li>Feature Cache has a maximum number of features which can be stored in it.  If this limit is reached then items are evicted from the cache. (If this limit is set to Integer.MAX_VALUE then all features are cached).</li>
</ul>

<p><strong>StreamingGridFeatureCache</strong></p>
<ul>
	<li>This implementation improved on the initial GridFeatureCache.</li>
	<li>Only the nodes which are currently being read or written to are locked.  This allows multiple threads to be reading/writing from the cache at the same time.</li>
	<li>When features are requested the request returns a FeatureCollection that only reads the features as they are requested.  (No in-memory feature collections are used).  This FeatureCollection is also responsible for caching the features as they are read from the feature source.</li>
</ul>

<h5>Spatial Index Implementations</h5>

<p> <strong>GridSpatialIndex</strong></p>
<ul>
	<li>Currently this is the only spatial index implementation.</li>
	<li>This index works by building a grid the encompasses the bounds of the feature source dataset (or the bounds provided by the user).  The size of the index (number of grid cells) is user customizable.</li>
	<li>Each grid cell (Node) contains a collection of data as well as a state (valid or not valid).  Valid nodes are nodes which have all there data (or are in the process of writing data to them).  Invalid nodes are nodes whose data has not yet been cached.</li>
	<li>Features are added to all nodes they intersect which one exception - if a feature intersects more than 4 nodes the feature is added to the &quot;root&quot; node.</li>
</ul>

<ul>
	<li>Statistics are kept about the number of items in the cache; the access and evictions.</li>
</ul>

<h5>Eviction Policy</h5>

<p><strong>LRUEvictionPolicy</strong></p>
<ul>
	<li> Evicts nodes based on the Least-Recently-Used policy.  Note that nodes that are currently locked for reading/writing are not evictable.</li>
</ul>

<h5>Storage Implementations</h5>

<p>There are currently three storage implementations:</p>

<p><strong>MemoryStore</strong></p>
<ul>
	<li>Stores all data in memory.</li>
</ul>

<p><strong>DiskStore</strong></p>
<ul>
	<li>Stores index to disk.  </li>
	<li>Two files are used - one file to store the nodes in pages; another file to store the page index.</li>
	<li>Each time a node is accessed it is written/read from disk.</li>
</ul>

<p><strong>BufferedDiskStore</strong></p>
<ul>
	<li>Extension to the DiskStore that &quot;caches&quot; the nodes so the are not constantly accessing the disk.</li>
</ul>

<h2>Usage</h2>

<p>So you have a feature source that you want to cache . . .</p>

<p>A FeatureCache can be made using:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
 FeatureCache cachingFS = new StreamingGridFeatureCache(featureSource, indexcapacity, featurecapacity, storage);
</pre></td></tr></table>
<ul>
	<li>featureSource - the original feature source</li>
	<li>indexcapacity - the desired size of the index (in the case of the grid spatial index this is the total number of grid cells)</li>
	<li>featurecapacity - the maximum number of features that can be stored in the cache.  Integer.MAX_VALUE will cache all features</li>
	<li>storage - the store to use for the cache
<br class="atl-forced-newline" /></li>
</ul>

<p>The above constructor makes use of the bounds of the featureSource for determing the bounds of the cache.  If you wish to provide your own bounds for the cache you can do so using the following:<br class="atl-forced-newline" /></p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
FeatureCache cachingFS = new StreamingGridFeatureCache(featureSource, bounds, indexcapacity, featurecapacity, storage);
</pre></td></tr></table>
<p><strong>Re-using the</strong> <strong>Cache</strong></p>

<p>A cache store can be re-used and providing the feature types are the same the features from the store will be used.  For example if you are using this within uDig; cache a bunch of WFS features; restart uDig; the feature cache will still be used to serve up features.</p>

<p><strong>Clearing the Cache</strong></p>

<p>Currently there is no policy for checking if features in the cache are valid.  Features in the cache do not expire.  However the feature cache does listen to feature events and if a feature is added or removed from the cache the nodes that correspond to that feature event are invalidated and cleared.  (Thus next time features from those nodes are requested it will pass the request along to the original feature source). </p>

<p>The cache can be cleared manually using:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
FeatureCache.clear()
</pre></td></tr></table>
<p><br class="atl-forced-newline" />
<br class="atl-forced-newline" /></p>