org.objectweb.cjdbc.controller.cache.result
Class AbstractResultCache

java.lang.Object
  org.objectweb.cjdbc.controller.cache.result.AbstractResultCache

All Implemented Interfaces:

XmlComponent

Direct Known Subclasses:

ResultCache

public abstract class AbstractResultCache

extends java.lang.Object

implements XmlComponent

This class defines the minimal functionnalities that a request cache must provide.

Only read requests (SELECTs) can be cached, there is no sense to cache writes as they do not provide any result to cache. However, the cache must be notified of the write queries in order to maintain cache coherency.

Version:

1.0

Author:

Emmanuel Cecchet , Nicolas Modrzyk

Field Summary

protected static Trace	logger Logger instance.
protected int	parsingGranularity Parsing granularity.

Fields inherited from interface org.objectweb.cjdbc.common.xml.XmlComponent

DOCTYPE_CONTROLLER, DOCTYPE_DB, XML_VERSION

Constructor Summary

AbstractResultCache()

Method Summary

abstract void	addCachingRule(ResultCacheRule rule) Add precise management and configuration of the cache behavior.
abstract void	addToCache(SelectRequest request, ControllerResultSet result) Adds an entry request/reply to the cache.
abstract void	commit(long transactionId) Commit a transaction given its id.
abstract void	flushCache() Removes all entries from the cache.
abstract java.lang.String[][]	getCacheData() Returns the content of the cache as displayable array of array of string
abstract long	getCacheSize() Returns number of entries in the cache
abstract CacheStatistics	getCacheStatistics() Returns pointer to the stats collector
abstract java.lang.String[][]	getCacheStatsData() Returns a bunch of stats collected by the cache, such as cache hits.
abstract ResultCacheRule	getDefaultRule() Return the default cache rule
abstract AbstractResultCacheEntry	getFromCache(SelectRequest request, boolean addToPendingQueries) Gets the result to the given request from the cache.
int	getParsingGranularity() Gets the needed query parsing granularity.
java.lang.String	getXml() Get xml formatted representation of this cjdbc component
protected abstract java.lang.String	getXmlImpl() Gets information about the request cache in xml
abstract boolean	isUpdateNecessary(UpdateRequest request) Returns true if the cache does not contain the values that are given in the update statement.
void	mergeDatabaseSchema(DatabaseSchema dbs) Merge the given DatabaseSchema with the current one.
abstract void	removeFromCache(SelectRequest request) Removes an entry from the cache (both request and reply are dropped).
abstract void	removeFromPendingQueries(SelectRequest request) Removes an entry from the pending query list.
abstract void	rollback(long transactionId) Rollback a transaction given its id.
void	setDatabaseSchema(DatabaseSchema dbs) Sets the DatabaseSchema of the current virtual database.
abstract void	setDefaultRule(ResultCacheRule defaultRule) Set the default query rule
void	setParsingGranularity(int parsingGranularity) Sets the needed query parsing granularity.
abstract void	shutdown() Shutdown the result cache and all its threads.
abstract void	writeNotify(AbstractWriteRequest request) Notifies the cache that the given write request has been issued, so that cache coherency can be maintained.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

parsingGranularity

protected int parsingGranularity

Parsing granularity. Default is: ParsingGranularities.NO_PARSING.

logger

protected static Trace logger

Logger instance.

Constructor Detail

AbstractResultCache

public AbstractResultCache()

Method Detail

getParsingGranularity

public int getParsingGranularity()

Gets the needed query parsing granularity.

Returns:

needed query parsing granularity

See Also:

setParsingGranularity(int)

setParsingGranularity

public void setParsingGranularity(int parsingGranularity)

Sets the needed query parsing granularity.

Parameters:

parsingGranularity - the query parsing granularity to set

See Also:

getParsingGranularity()

setDatabaseSchema

public void setDatabaseSchema(DatabaseSchema dbs)

Sets the DatabaseSchema of the current virtual database.

Parameters:

dbs - a DatabaseSchema value

See Also:

CacheDatabaseSchema

mergeDatabaseSchema

public void mergeDatabaseSchema(DatabaseSchema dbs)

Merge the given DatabaseSchema with the current one.

Parameters:

dbs - a DatabaseSchema value

See Also:

CacheDatabaseSchema

addCachingRule

public abstract void addCachingRule(ResultCacheRule rule)

Add precise management and configuration of the cache behavior. A cache rule contains information on a query pattern and how to act if that pattern was matched.

Parameters:

rule - of action for the cache

See Also:

ResultCacheRule

getDefaultRule

public abstract ResultCacheRule getDefaultRule()

Return the default cache rule

Returns:

default query cache rule. Cannot be null

setDefaultRule

public abstract void setDefaultRule(ResultCacheRule defaultRule)

Set the default query rule

Parameters:

defaultRule - default rule to set

addToCache

public abstract void addToCache(SelectRequest request,
                                ControllerResultSet result)
                         throws CacheException

Adds an entry request/reply to the cache. Note that if the request was already in the cache, its result must be updated in any case but the request must never appear twice in the cache.

Parameters:

request - the request

result - the result corresponding to the request

Throws:

CacheException - if an error occurs

getFromCache

public abstract AbstractResultCacheEntry getFromCache(SelectRequest request,
                                                      boolean addToPendingQueries)

Gets the result to the given request from the cache.

The returned AbstractResultCacheEntry is null if the request is not present in the cache.

An invalid CacheEntry may be returned (it means that the result is null) but the already parsed query can be retrieved from the cache entry.

Parameters:

request - an SQL select request

addToPendingQueries - true if the request must be added to the pending query list on a cache miss

Returns:

the AbstractResultCacheEntry if found, else null

removeFromCache

public abstract void removeFromCache(SelectRequest request)

Removes an entry from the cache (both request and reply are dropped). The request is NOT removed from the pending query list, but it shouldn't be in this list.

Parameters:

request - a SelectRequest

removeFromPendingQueries

public abstract void removeFromPendingQueries(SelectRequest request)

Removes an entry from the pending query list.

Parameters:

request - a SelectRequest

shutdown

public abstract void shutdown()

Shutdown the result cache and all its threads.

writeNotify

public abstract void writeNotify(AbstractWriteRequest request)
                          throws CacheException

Notifies the cache that the given write request has been issued, so that cache coherency can be maintained. If the cache is distributed, this method is reponsible for broadcasting this information to other caches.

Parameters:

request - an AbstractWriteRequest value

Throws:

CacheException - if an error occurs

isUpdateNecessary

public abstract boolean isUpdateNecessary(UpdateRequest request)
                                   throws CacheException

Returns true if the cache does not contain the values that are given in the update statement.

Parameters:

request - the update request that needs to be executed

Returns:

false if the request shouldn't be executed, true otherwise.

Throws:

CacheException - if an error occurs

flushCache

public abstract void flushCache()

Removes all entries from the cache.

commit

public abstract void commit(long transactionId)
                     throws CacheException

Commit a transaction given its id.

Parameters:

transactionId - the transaction id

Throws:

CacheException - if an error occurs

rollback

public abstract void rollback(long transactionId)
                       throws CacheException

Rollback a transaction given its id.

Parameters:

transactionId - the transaction id

Throws:

CacheException - if an error occurs

getXmlImpl

protected abstract java.lang.String getXmlImpl()

Gets information about the request cache in xml

Returns:

xml formatted String containing information

getXml

public java.lang.String getXml()

Description copied from interface: XmlComponent

Get xml formatted representation of this cjdbc component

Specified by:

getXml in interface XmlComponent

Returns:

xml formatted fragment

See Also:

XmlComponent.getXml()

getCacheData

public abstract java.lang.String[][] getCacheData()
                                           throws CacheException

Returns the content of the cache as displayable array of array of string

Returns:

the data

Throws:

CacheException - if fails

getCacheStatsData

public abstract java.lang.String[][] getCacheStatsData()
                                                throws CacheException

Returns a bunch of stats collected by the cache, such as cache hits.

Returns:

the data

Throws:

CacheException - if fails to collect the data.

getCacheStatistics

public abstract CacheStatistics getCacheStatistics()

Returns pointer to the stats collector

Returns:

CacheStatistics object

getCacheSize

public abstract long getCacheSize()

Returns number of entries in the cache

Returns:

integer value representing the total number of entries