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

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

All Implemented Interfaces:

XmlComponent

Direct Known Subclasses:

ResultCacheColumn, ResultCacheColumnUnique, ResultCacheDatabase, ResultCacheTable

public abstract class ResultCache

extends AbstractResultCache

This is a query cache implementation with tunable granularity.
Cache invalidation granularity can take on of the following values:

• NO_INVALIDATE: no invalidation, the cache is inconsistent and this should just be used to determine hit ratio upper bound.
• DATABASE: the cache is flushed each time the database is updated (every INSERT, UPDATE, DELETE, ... statement).
• TABLE: table granularity, entries in the cache are invalidated based on table dependencies.
• COLUMN: column granularity, entries in the cache are invalidated based on column dependencies
• COLUMN_UNIQUE: same as COLUMN except that UNIQUE queries that selects a single row based on a key are invalidated only when needed.

Version:

1.0

Author:

Emmanuel Cecchet , Julie Marguerite , Sara Bouchenak , Nicolas Modrzyk

Field Summary

private java.util.HashSet	cachingRules
protected CacheDatabaseSchema	cdbs
private ResultCacheRule	defaultRule
private java.util.ArrayList	eagerCache
private EagerCacheThread	eagerThread
private boolean	flushingCache
private AbstractResultCacheEntry	lruHead
private AbstractResultCacheEntry	lruTail
private int	maxEntries
private java.util.HashSet	pendingQueries
private long	pendingQueryTimeout Pending query timeout in ms.
private java.util.HashMap	queries
private java.util.ArrayList	relaxedCache
private RelaxedCacheThread	relaxedThread
private CacheStatistics	stats
private static boolean[]	TRUE_TRUE

Fields inherited from class org.objectweb.cjdbc.controller.cache.result.AbstractResultCache

logger, parsingGranularity

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

DOCTYPE_CONTROLLER, DOCTYPE_DB, XML_VERSION

Constructor Summary

ResultCache(int maxEntries, int pendingTimeout)
Creates a new Cache instance.

Method Summary

void	addCachingRule(ResultCacheRule rule) Add a rule for this ResultCache
void	addToCache(SelectRequest request, ControllerResultSet result) Adds an entry request/reply to the cache.
void	commit(long transactionId) Commit a transaction given its id.
void	flushCache() Removes all entries from the cache.
private CacheBehavior	getCacheBehavior(SelectRequest request) Finds the behavior of the cache with the given query skeleton.
java.lang.String[][]	getCacheData() Returns the content of the cache as displayable array of array of string
private java.lang.String	getCacheKeyFromRequest(SelectRequest request) Creates a unique cache entry key from the given request.
long	getCacheSize() Get Cache size
CacheStatistics	getCacheStatistics() Returns pointer to the stats collector
java.lang.String[][]	getCacheStatsData() Returns a bunch of stats collected by the cache, such as cache hits.
ResultCacheRule	getDefaultRule() Return the default cache rule
java.util.ArrayList	getEagerCache() Returns the eagerCache value.
AbstractResultCacheEntry	getFromCache(SelectRequest request, boolean addToPendingQueries) Gets the result to the given request from the cache.
abstract java.lang.String	getName() Retrieve the name of this cache
int	getParsingGranularity() Gets the needed query parsing granularity.
int	getPendingQueryTimeout() Returns the pending query timeout in seconds.
java.util.HashMap	getQueries() Possibly we want to access the queries in the cache for timing purposes
java.util.ArrayList	getRelaxedCache() Returns the relaxedCache value.
protected java.lang.String	getXmlImpl() Gets information about the request cache
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.
boolean[]	needInvalidate(ControllerResultSet result, UpdateRequest request) Do we need invalidation after an update request, given a ControllerResultSet.
protected abstract void	processAddToCache(AbstractResultCacheEntry qe) Process the add to cache to update implementation specific data structures.
protected abstract void	processWriteNotify(AbstractWriteRequest request) Implementation specific invalidation of the cache.
void	removeFromCache(SelectRequest request) Removes an entry from the cache (both request and reply are dropped).
void	removeFromPendingQueries(SelectRequest request) Removes an entry from the pending query list.
private void	removeOldest() Removes the oldest entry from the cache.
void	rollback(long transactionId) Rollback a transaction given its id.
void	setDatabaseSchema(DatabaseSchema dbs) Sets the DatabaseSchema of the current virtual database.
void	setDefaultRule(ResultCacheRule defaultRule) Set the default query rule
void	setPendingQueryTimeout(int pendingQueryTimeout) Sets the pending query timeout in seconds.
void	shutdown() Shutdown the result cache and all its threads.
void	writeNotify(AbstractWriteRequest request) Notifies the cache that this write request has been issued, so that cache coherency can be maintained.

Methods inherited from class org.objectweb.cjdbc.controller.cache.result.AbstractResultCache

getXml, setParsingGranularity

Methods inherited from class java.lang.Object

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

Field Detail

maxEntries

private int maxEntries

pendingQueryTimeout

private long pendingQueryTimeout

Pending query timeout in ms. Default is: 0 (wait forever).

queries

private java.util.HashMap queries

pendingQueries

private java.util.HashSet pendingQueries

cachingRules

private java.util.HashSet cachingRules

defaultRule

private ResultCacheRule defaultRule

relaxedCache

private java.util.ArrayList relaxedCache

lruHead

private AbstractResultCacheEntry lruHead

lruTail

private AbstractResultCacheEntry lruTail

cdbs

protected CacheDatabaseSchema cdbs

stats

private CacheStatistics stats

relaxedThread

private RelaxedCacheThread relaxedThread

TRUE_TRUE

private static final boolean[] TRUE_TRUE

flushingCache

private boolean flushingCache

eagerThread

private EagerCacheThread eagerThread

eagerCache

private java.util.ArrayList eagerCache

Constructor Detail

ResultCache

public ResultCache(int maxEntries,
                   int pendingTimeout)

Creates a new Cache instance.

Parameters:

maxEntries - maximum number of cache entries

pendingTimeout - pending queries timeout

Method Detail

shutdown

public void shutdown()

Shutdown the result cache and all its threads.

Specified by:

shutdown in class AbstractResultCache

getPendingQueryTimeout

public int getPendingQueryTimeout()

Returns the pending query timeout in seconds.

Returns:

the pending query timeout.

See Also:

setPendingQueryTimeout(int)

setPendingQueryTimeout

public void setPendingQueryTimeout(int pendingQueryTimeout)

Sets the pending query timeout in seconds.

Parameters:

pendingQueryTimeout - the pending query timeout to set.

See Also:

getPendingQueryTimeout()

getQueries

public java.util.HashMap getQueries()

Possibly we want to access the queries in the cache for timing purposes

Returns:

the HashMap of queries (not synchronized)

setDatabaseSchema

public void setDatabaseSchema(DatabaseSchema dbs)

Sets the DatabaseSchema of the current virtual database.

Overrides:

setDatabaseSchema in class AbstractResultCache

Parameters:

dbs - a DatabaseSchema value

See Also:

CacheDatabaseSchema

mergeDatabaseSchema

public void mergeDatabaseSchema(DatabaseSchema dbs)

Merge the given DatabaseSchema with the current one.

Overrides:

mergeDatabaseSchema in class AbstractResultCache

Parameters:

dbs - a DatabaseSchema value

See Also:

CacheDatabaseSchema

addCachingRule

public void addCachingRule(ResultCacheRule rule)

Add a rule for this ResultCache

Specified by:

addCachingRule in class AbstractResultCache

Parameters:

rule - that contains information on the action to perform for a specific query

See Also:

ResultCacheRule

getDefaultRule

public ResultCacheRule getDefaultRule()

Description copied from class: AbstractResultCache

Return the default cache rule

Specified by:

getDefaultRule in class AbstractResultCache

Returns:

default query cache rule. Cannot be null

See Also:

AbstractResultCache.getDefaultRule()

setDefaultRule

public void setDefaultRule(ResultCacheRule defaultRule)

Description copied from class: AbstractResultCache

Set the default query rule

Specified by:

setDefaultRule in class AbstractResultCache

Parameters:

defaultRule - default rule to set

See Also:

AbstractResultCache.setDefaultRule(ResultCacheRule)

getCacheBehavior

private CacheBehavior getCacheBehavior(SelectRequest request)

Finds the behavior of the cache with the given query skeleton. If the query match a pattern of a rule then we get the associated action for this, otherwise we look for the default behavior.

Parameters:

request - to get action for

Returns:

the CacheBehavior associated for this query.

getCacheKeyFromRequest

private java.lang.String getCacheKeyFromRequest(SelectRequest request)

Creates a unique cache entry key from the given request. The key is currently composed of the login name and the request SQL statement.

Parameters:

request - the request to generate the key from

Returns:

a unique cache key for this request

needInvalidate

public boolean[] needInvalidate(ControllerResultSet result,
                                UpdateRequest request)

Do we need invalidation after an update request, given a ControllerResultSet. Note that this method is meant to be used with unique queries where the ControllerResultSet is the result of a pk selection (like an Entity Bean).

Parameters:

result - that could be in the cache

request - the update we want to get updated values from

Returns:

boolean[] {needInvalidate,needToSendQuery}

addToCache

public 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, only the result is updated.

Specified by:

addToCache in class AbstractResultCache

Parameters:

request - the request

result - the result corresponding to the request

Throws:

CacheException - if an error occurs

processAddToCache

protected abstract void processAddToCache(AbstractResultCacheEntry qe)

Process the add to cache to update implementation specific data structures.

Parameters:

qe - to add to the cache.

getFromCache

public 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 AbstractResultCacheEntry may be returned (it means that the result is null) but the already parsed query can be retrieved from the cache entry.

Specified by:

getFromCache in class AbstractResultCache

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 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.

Specified by:

removeFromCache in class AbstractResultCache

Parameters:

request - a SelectRequest

removeFromPendingQueries

public void removeFromPendingQueries(SelectRequest request)

Removes an entry from the pending query list.

Specified by:

removeFromPendingQueries in class AbstractResultCache

Parameters:

request - a SelectRequest

isUpdateNecessary

public abstract boolean isUpdateNecessary(UpdateRequest request)
                                   throws CacheException

Description copied from class: AbstractResultCache

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

Specified by:

isUpdateNecessary in class AbstractResultCache

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

See Also:

AbstractResultCache.isUpdateNecessary(org.objectweb.cjdbc.common.sql.UpdateRequest)

writeNotify

public void writeNotify(AbstractWriteRequest request)
                 throws CacheException

Notifies the cache that this 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.

Specified by:

writeNotify in class AbstractResultCache

Parameters:

request - an AbstractRequest value

Throws:

CacheException - if an error occurs

processWriteNotify

protected abstract void processWriteNotify(AbstractWriteRequest request)

Implementation specific invalidation of the cache.

Parameters:

request - Write request that invalidates the cache.

flushCache

public void flushCache()

Removes all entries from the cache.

Specified by:

flushCache in class AbstractResultCache

getCacheSize

public long getCacheSize()

Get Cache size

Specified by:

getCacheSize in class AbstractResultCache

Returns:

the approximate size of the cache in bytes

removeOldest

private void removeOldest()

Removes the oldest entry from the cache.

!Warning! This method is not synchronized and should be called in the scope of a synchronized(queries)

getParsingGranularity

public int getParsingGranularity()

Gets the needed query parsing granularity.

Overrides:

getParsingGranularity in class AbstractResultCache

Returns:

needed query parsing granularity

See Also:

AbstractResultCache.setParsingGranularity(int)

getName

public abstract java.lang.String getName()

Retrieve the name of this cache

Returns:

name

commit

public void commit(long transactionId)
            throws CacheException

Commit a transaction given its id.

Specified by:

commit in class AbstractResultCache

Parameters:

transactionId - the transaction id

Throws:

CacheException - if an error occurs

rollback

public void rollback(long transactionId)
              throws CacheException

Rollback a transaction given its id.

Specified by:

rollback in class AbstractResultCache

Parameters:

transactionId - the transaction id

Throws:

CacheException - if an error occurs

getCacheData

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

Description copied from class: AbstractResultCache

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

Specified by:

getCacheData in class AbstractResultCache

Returns:

the data

Throws:

CacheException - if fails

See Also:

AbstractResultCache.getCacheData()

getCacheStatsData

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

Description copied from class: AbstractResultCache

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

Specified by:

getCacheStatsData in class AbstractResultCache

Returns:

the data

Throws:

CacheException - if fails to collect the data.

See Also:

AbstractResultCache.getCacheStatsData()

getCacheStatistics

public CacheStatistics getCacheStatistics()

Description copied from class: AbstractResultCache

Returns pointer to the stats collector

Specified by:

getCacheStatistics in class AbstractResultCache

Returns:

Returns the stats.

getEagerCache

public java.util.ArrayList getEagerCache()

Returns the eagerCache value.

Returns:

Returns the eagerCache.

getRelaxedCache

public java.util.ArrayList getRelaxedCache()

Returns the relaxedCache value.

Returns:

Returns the relaxedCache.

getXmlImpl

protected java.lang.String getXmlImpl()

Gets information about the request cache

Specified by:

getXmlImpl in class AbstractResultCache

Returns:

String containing information