ca.uhn.cache
Interface ISemanticCache

All Known Subinterfaces:

IPreFetchingCache

All Known Implementing Classes:

ChunkBasedSemanticCache

public interface ISemanticCache

A ISemanticCache keeps rapidly available copies of data in some underlying system. Data are stored in IChunks which contain groups of data items that are likely to be requested together. Cache size and consistency with source data must be maintained by ongoing removal of old data from the cache. However the details are internal and thus not part of this interface. NOTE: This class will throw checked exception only to alert the client of situations when the requested method could not fulfill its intended semantic. For example assume we have an implementation of this interface that uses a relational backend to store the cached data, such implementation will define a new exception that inherits from CacheException named RelationalBackendNotAvailable to indicate that the relational backend couldn't be reached.

Version:

$Revision: 1.1 $ updated on $Date: 2005/01/24 22:52:08 $ by $Author: bryan_tripp $

Author:

Bryan Tripp

Method Summary

IQueryResult	get(IQuery theQuery)
java.util.Date	getEarliestCacheTime(IQuery theQuery)
void	put(IQuery theQueryScope, IQueryResult theResult)
IQuery[]	remainder(IQuery theQuery, int theMaxGroups) Given an IQuery, find a small list of new IQuery that span all the data in the original IQuery that are not present in the cache.
void	update(IQueryResult theResult) Updates semantic regions that are already in the cache with revised data.

Method Detail

remainder

public IQuery[] remainder(IQuery theQuery,
                          int theMaxGroups)
                   throws CacheException

Given an IQuery, find a small list of new IQuery that span all the data in the original IQuery that are not present in the cache. Some extra data may (i.e. data in the cache or data not requested) may be spaned. Generally there is a trade-off between extra data and number of new queries returned.

Parameters:

theQuery - parameters identifying the scope of data requested

theMaxGroups - maximum number of IQuerys returned (lower numbers will generally force more extra data to be spanned). A value of 0 means that no grouping is requested.

Returns:

the smallest query emcompassing all data that are in chunks relevant to the original query and which are not in the cache.

Throws:

CacheException - If the remainder operation could not be successfully completed.

get

public IQueryResult get(IQuery theQuery)
                 throws CacheException

Parameters:

theQuery - parameters identifying the scope of data requested

Returns:

whatever part of requested data that is available from the cache.

Throws:

CacheException - If the get operation could not be successfully completed.

put

public void put(IQuery theQueryScope,
                IQueryResult theResult)
         throws CacheException

Parameters:

theQueryScope - parameters identifying the scope of a query

theResult - the results from the underlying system that are not already in the cache (to be cached)

Throws:

CacheException - If the put operation could not be successfully completed.

getEarliestCacheTime

public java.util.Date getEarliestCacheTime(IQuery theQuery)
                                    throws CacheException

Parameters:

theQuery - parameters identifying the scope of data requested

Returns:

the earlist time at which any data matching the query was cached, or null if there are no matching data

Throws:

CacheException - if operation could not be completed successfully

update

public void update(IQueryResult theResult)
            throws CacheException

Updates semantic regions that are already in the cache with revised data. This does not change the semantic scope of the cache, but may add or alter data items. If a data item moves from one semantic region to another as a result of an update, then if both regions are cached, the changed data will replace the old data, effectively removing it from the old region. If the new region is not cached, the data will remain in the old region, until it is evicted.

Parameters:

theResult - new or changed data items for semantic regions already in the cache

Throws:

CacheException - if operation could not be completed successfully