kodo.datacache
Class CacheAwareQuery

java.lang.Object
  |
  +--kodo.datacache.CacheAwareQuery

All Implemented Interfaces:

KodoQuery, KodoQuerySPI, Query, Serializable

public class CacheAwareQuery

extends Object

implements KodoQuerySPI

A Query implementation that caches the OIDs involved in the query, and can determine whether or not the query has been dirtied.

Since:

2.5.0

See Also:

Serialized Form

Fields inherited from interface kodo.query.KodoQuery

FLUSH_FALSE, FLUSH_TRUE, FLUSH_WITH_CONNECTION

Constructor Summary

CacheAwareQuery(KodoQuery query, QueryCache cache)
Create a new CacheAwareQuery that delegates to query if no cached results are available.

Method Summary

void	abortCaching() Instructs this query to notify all CachingList objects created by it to stop caching results.
void	addAggregateListener(AggregateListener listener) Register an aggregate listener for the query.
void	addExtension(String key, Object value) JDO 2.0 Preview.
void	addFilterListener(FilterListener listener) Register a filter listener for the query.
protected Object	checkCache(QueryKey qk) Look in the query cache for a result for the given query key.
void	close(Object arg)
void	closeAll()
void	compile()
void	declareImports(String arg)
void	declareParameters(String arg)
void	declareVariables(String arg)
Object	execute()
Object	execute(Object arg)
Object	execute(Object arg0, Object arg1)
Object	execute(Object arg0, Object arg1, Object arg2)
Object	executeWithArray(Object[] args)
Object	executeWithMap(Map args)
ClassMetaData[]	getAccessPathMetaDatas() Return the classes that affect this query.
Collection	getAggregateListeners() Return the aggregate listeners added to this query, or empty collection if none.
String	getAlias() When we're returning standard candidate instances rather than a projection or aggregate, return the alias for the instances in case a result class is set.
String[]	getAliases() Return the aliases for the result expressions.
boolean[]	getAscending() Return wheher each ordering is ascending.
QueryCache	getCache() Return the QueryCache that this object is associated with.
Class	getCandidateClass() Return the class of the objects that this query will return, or null if this information is not available / not relevant.
Collection	getCandidateCollection() Return the candidate collection, or null if an extent was specified instead of a collection.
KodoExtent	getCandidateExtent() Return the candidate extent, or null if a collection was specified instead of an extent.
String[]	getDataStoreActions(Map params) Returns a description of the commands that will be sent to the datastore in order to execute this query.
KodoQuery	getDelegate() Returns the query that is being cached.
long	getEndIndex() Return the 0-based exclusive end index for the returned results, or Long.MAX_VALUE for no limit.
FetchConfiguration	getFetchConfiguration() Return the (mutable) fetch configuration for this query.
String	getFilter() Return the filter that this query has been configured with.
Collection	getFilterListeners() Return the filter listeners added to this query, or empty collection if none.
String	getGrouping() Return the grouping expression for this query.
String[]	getGroupingClauses() Return the grouping expressions.
String	getHaving() Return the having clause.
boolean	getIgnoreCache()
String[]	getImportPackages() Return the import packages.
String	getImports() Return the import declaration.
String	getLanguage() Return the language of this query.
String	getOrdering() Return the ordering expression that this query was configured with.
String[]	getOrderingClauses() Return the ordering criteria.
String	getParameters() Return the declared parameters.
org.apache.commons.collections.map.LinkedMap	getParameterTypes() Return a map of parameter name to type for this query.
PersistenceManager	getPersistenceManager()
String	getQueryString() Return a single-string representation of the query, if applicable.
String	getResult() Return the result expression set for this query.
Class	getResultClass() Returns the result class that has been set through setResultClass(java.lang.Class), or null if none.
String[]	getResultClauses() Return the result expressions.
Class[]	getResultTypes() Return the type of each result clause.
long	getStartIndex() Return the 0-based start index for the returned results.
String	getVariables() Return the declared variables.
Map	getVariableTypes() Return a map of variable name to type for this query.
boolean	hasSubclasses() Whether query results will include subclasses of the candidate class.
boolean	isAggregate() Return true if the query is an aggregate.
boolean	isDistinct() Whether the result specifies that this is a distinct query.
boolean	isQueryStringPreferred() Return true if the preferred style of query representation is with a single query string.
boolean	isUnique() The unique flag.
void	lock() Synchronize on the query's internal lock.
void	removeAggregateListener(AggregateListener listener) Remove an aggregate listener from the query.
void	removeFilterListener(FilterListener listener) Remove a filter listener from the query.
void	setCandidates(Collection arg)
void	setCandidates(Extent arg)
void	setClass(Class arg)
void	setExtensions(Map map) JDO 2.0 Preview.
void	setFilter(String arg)
void	setGrouping(String group) JDO 2.0 Preview.
void	setIgnoreCache(boolean arg)
void	setOrdering(String arg)
void	setQuery(Object query) Fill in query state from a query string or template.
void	setRange(long start, long end) JDO 2.0 Preview.
void	setResult(String result) JDO 2.0 Preview.
void	setResultClass(Class cls) JDO 2.0 Preview.
void	setUnique(boolean unique) JDO 2.0 Preview.
void	unlock() Unlock the query's internal lock.
protected Object	wrapResult(Object o, QueryKey qk) Wrap the query result in a list that will cache the values upon completion of the traversal of the underlying list.
Object	writeReplace()

Methods inherited from class java.lang.Object

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

Constructor Detail

CacheAwareQuery

public CacheAwareQuery(KodoQuery query,
                       QueryCache cache)

Create a new CacheAwareQuery that delegates to query if no cached results are available.

Method Detail

checkCache

protected Object checkCache(QueryKey qk)

Look in the query cache for a result for the given query key. Only look if this query is being executed outside a transaction or in a transaction with IgnoreCache set to true or in a transaction with IgnoreCache set to false but in which none of the classes involved in this query have been touched.

Caching is not used when using pessimistic transactions. This is because we must obtain locks on the data, and it is likely that making n trips to the database to make the locks will be slower than running the query against the database.

If KodoQuery#getQueryCacheEnabled returns false, this method returns null.

Return the list if we meet the above criteria and if a list is found for qk. Else, return null.

This implementation means that queries against the cache are of READ_COMMITTED isolation level. It'd be nice to support READ_SERIALIZABLE -- to do so, we'd just return false when in a transaction.

wrapResult

protected Object wrapResult(Object o,
                            QueryKey qk)

Wrap the query result in a list that will cache the values upon completion of the traversal of the underlying list.

This list must not register its results with the cache if one of the classes involved in this query is touched during the traversal of the query.

This method may decide not to do any caching of the query identified. For example, it might just return the supplied list if the query involves classes that are not cacheable.

getCache

public QueryCache getCache()

Return the QueryCache that this object is associated with.

abortCaching

public void abortCaching()

Instructs this query to notify all CachingList objects created by it to stop caching results. Upon invoking this method, all caching efforts are aborted, and any partial results are dropped.

getDelegate

public KodoQuery getDelegate()

Returns the query that is being cached.

writeReplace

public Object writeReplace()
                    throws ObjectStreamException

setClass

public void setClass(Class arg)

Specified by:

setClass in interface Query

setCandidates

public void setCandidates(Extent arg)

Specified by:

setCandidates in interface Query

setCandidates

public void setCandidates(Collection arg)

Specified by:

setCandidates in interface Query

setFilter

public void setFilter(String arg)

Specified by:

setFilter in interface Query

declareImports

public void declareImports(String arg)

Specified by:

declareImports in interface Query

declareParameters

public void declareParameters(String arg)

Specified by:

declareParameters in interface Query

declareVariables

public void declareVariables(String arg)

Specified by:

declareVariables in interface Query

setOrdering

public void setOrdering(String arg)

Specified by:

setOrdering in interface Query

setIgnoreCache

public void setIgnoreCache(boolean arg)

Specified by:

setIgnoreCache in interface Query

getIgnoreCache

public boolean getIgnoreCache()

Specified by:

getIgnoreCache in interface Query

compile

public void compile()

Specified by:

compile in interface Query

execute

public Object execute()

Specified by:

execute in interface Query

execute

public Object execute(Object arg)

Specified by:

execute in interface Query

execute

public Object execute(Object arg0,
                      Object arg1)

Specified by:

execute in interface Query

execute

public Object execute(Object arg0,
                      Object arg1,
                      Object arg2)

Specified by:

execute in interface Query

executeWithMap

public Object executeWithMap(Map args)

Specified by:

executeWithMap in interface Query

executeWithArray

public Object executeWithArray(Object[] args)

Specified by:

executeWithArray in interface Query

getPersistenceManager

public PersistenceManager getPersistenceManager()

Specified by:

getPersistenceManager in interface Query

close

public void close(Object arg)

Specified by:

close in interface Query

closeAll

public void closeAll()

Specified by:

closeAll in interface Query

getLanguage

public String getLanguage()

Description copied from interface: KodoQuery

Return the language of this query.

Specified by:

getLanguage in interface KodoQuery

getFetchConfiguration

public FetchConfiguration getFetchConfiguration()

Description copied from interface: KodoQuery

Return the (mutable) fetch configuration for this query.

Specified by:

getFetchConfiguration in interface KodoQuery

getFilterListeners

public Collection getFilterListeners()

Description copied from interface: KodoQuery

Return the filter listeners added to this query, or empty collection if none.

Specified by:

getFilterListeners in interface KodoQuery

addFilterListener

public void addFilterListener(FilterListener listener)

Description copied from interface: KodoQuery

Register a filter listener for the query.

Specified by:

addFilterListener in interface KodoQuery

removeFilterListener

public void removeFilterListener(FilterListener listener)

Description copied from interface: KodoQuery

Remove a filter listener from the query.

Specified by:

removeFilterListener in interface KodoQuery

getAggregateListeners

public Collection getAggregateListeners()

Description copied from interface: KodoQuery

Return the aggregate listeners added to this query, or empty collection if none.

Specified by:

getAggregateListeners in interface KodoQuery

addAggregateListener

public void addAggregateListener(AggregateListener listener)

Description copied from interface: KodoQuery

Register an aggregate listener for the query.

Specified by:

addAggregateListener in interface KodoQuery

removeAggregateListener

public void removeAggregateListener(AggregateListener listener)

Description copied from interface: KodoQuery

Remove an aggregate listener from the query.

Specified by:

removeAggregateListener in interface KodoQuery

getCandidateExtent

public KodoExtent getCandidateExtent()

Description copied from interface: KodoQuery

Return the candidate extent, or null if a collection was specified instead of an extent.

Specified by:

getCandidateExtent in interface KodoQuery

getCandidateCollection

public Collection getCandidateCollection()

Description copied from interface: KodoQuery

Return the candidate collection, or null if an extent was specified instead of a collection.

Specified by:

getCandidateCollection in interface KodoQuery

getCandidateClass

public Class getCandidateClass()

Description copied from interface: KodoQuery

Return the class of the objects that this query will return, or null if this information is not available / not relevant.

Specified by:

getCandidateClass in interface KodoQuery

hasSubclasses

public boolean hasSubclasses()

Description copied from interface: KodoQuery

Whether query results will include subclasses of the candidate class.

Specified by:

hasSubclasses in interface KodoQuery

setQuery

public void setQuery(Object query)

Description copied from interface: KodoQuerySPI

Fill in query state from a query string or template.

Specified by:

setQuery in interface KodoQuerySPI

isQueryStringPreferred

public boolean isQueryStringPreferred()

Description copied from interface: KodoQuerySPI

Return true if the preferred style of query representation is with a single query string.

Specified by:

isQueryStringPreferred in interface KodoQuerySPI

getQueryString

public String getQueryString()

Description copied from interface: KodoQuery

Return a single-string representation of the query, if applicable.

Specified by:

getQueryString in interface KodoQuery

getFilter

public String getFilter()

Description copied from interface: KodoQuery

Return the filter that this query has been configured with.

Specified by:

getFilter in interface KodoQuery

getOrdering

public String getOrdering()

Description copied from interface: KodoQuery

Return the ordering expression that this query was configured with.

Specified by:

getOrdering in interface KodoQuery

getImports

public String getImports()

Description copied from interface: KodoQuery

Return the import declaration.

Specified by:

getImports in interface KodoQuery

getParameters

public String getParameters()

Description copied from interface: KodoQuery

Return the declared parameters.

Specified by:

getParameters in interface KodoQuery

getVariables

public String getVariables()

Description copied from interface: KodoQuery

Return the declared variables.

Specified by:

getVariables in interface KodoQuery

setUnique

public void setUnique(boolean unique)

Description copied from interface: KodoQuery

JDO 2.0 Preview. Specify that the query will return only 1 result, rather than a collection. The execute method will return null if the query result size is 0.

Specified by:

setUnique in interface KodoQuery

isUnique

public boolean isUnique()

Description copied from interface: KodoQuery

The unique flag.

Specified by:

isUnique in interface KodoQuery

setResult

public void setResult(String result)

Description copied from interface: KodoQuery

JDO 2.0 Preview. Configures what type of data this query should return. If this is unset or set to null, this query will return a list of the query's candidate class. Otherwise, this query will return aggregate function results and / or individual field values (projections).

Specified by:

setResult in interface KodoQuery

Following copied from interface: kodo.query.KodoQuery

Parameters:

result - optional "distinct" keyword, followed by a comma-delimited list of fields, functions on fields, or aggregate functions to return from this query

getResult

public String getResult()

Description copied from interface: KodoQuery

Return the result expression set for this query.

Specified by:

getResult in interface KodoQuery

setResultClass

public void setResultClass(Class cls)

Description copied from interface: KodoQuery

JDO 2.0 Preview. Specify the type of object in which the result of invoking Query.execute() or one of its siblings. The behavior of this method depends the nature of the query being executed. In particular, if used in conjunction with KodoQuery.setResult(java.lang.String), the argument to this method should be Object[].class, a class with bean-like setters for each of the items listed in the result specification, or a class with a method called put with two Object arguments.

Specified by:

setResultClass in interface KodoQuery

getResultClass

public Class getResultClass()

Description copied from interface: KodoQuery

Returns the result class that has been set through KodoQuery.setResultClass(java.lang.Class), or null if none.

Specified by:

getResultClass in interface KodoQuery

setGrouping

public void setGrouping(String group)

Description copied from interface: KodoQuery

JDO 2.0 Preview. Set the grouping expressions, optionally including a "having" clause. When grouping is specified, each result expression must either be an expression contained in the grouping, or an aggregate evaluated once per group.

Specified by:

setGrouping in interface KodoQuery

Following copied from interface: kodo.query.KodoQuery

Parameters:

group - a comma-delimited list of expressions, optionally followed by the "having" keyword and a boolean expression

getGrouping

public String getGrouping()

Description copied from interface: KodoQuery

Return the grouping expression for this query.

Specified by:

getGrouping in interface KodoQuery

setRange

public void setRange(long start,
                     long end)

Description copied from interface: KodoQuery

JDO 2.0 Preview. Set the range of results to return.

Specified by:

setRange in interface KodoQuery

Following copied from interface: kodo.query.KodoQuery

Parameters:

start - 0-based inclusive start index

end - 0-based exclusive end index, or Long.MAX_VALUE for no limit

getStartIndex

public long getStartIndex()

Description copied from interface: KodoQuery

Return the 0-based start index for the returned results.

Specified by:

getStartIndex in interface KodoQuery

getEndIndex

public long getEndIndex()

Description copied from interface: KodoQuery

Return the 0-based exclusive end index for the returned results, or Long.MAX_VALUE for no limit.

Specified by:

getEndIndex in interface KodoQuery

addExtension

public void addExtension(String key,
                         Object value)

Description copied from interface: KodoQuery

JDO 2.0 Preview. Add an extension this query. Kodo recognizes the following extension keys; others will be ignored:

• kodo.FilterListener: Register a filter listener for this query; analogous to invoking KodoQuery.addFilterListener(kodo.query.FilterListener).
• kodo.AggregateListener: Register an aggregate listener for this query; analogous to invoking KodoQuery.addAggregateListener(kodo.query.AggregateListener).
• kodo.FetchPlan.<property>: Set the bean property of this query's fetch plan to the supplied value.

Specified by:

addExtension in interface KodoQuery

setExtensions

public void setExtensions(Map map)

Description copied from interface: KodoQuery

JDO 2.0 Preview. Set multiple extensions, or use null to clear extensions. This includes removing added listeners and returning fetch configuration properties to their previous values.

Specified by:

setExtensions in interface KodoQuery

Following copied from interface: kodo.query.KodoQuery

See Also:

KodoQuery.addExtension(java.lang.String, java.lang.Object)

isAggregate

public boolean isAggregate()

Description copied from interface: KodoQuerySPI

Return true if the query is an aggregate.

Specified by:

isAggregate in interface KodoQuerySPI

getDataStoreActions

public String[] getDataStoreActions(Map params)

Description copied from interface: KodoQuery

Returns a description of the commands that will be sent to the datastore in order to execute this query. This will typically be in the native query language of the database (e.g., SQL).

Specified by:

getDataStoreActions in interface KodoQuery

Following copied from interface: kodo.query.KodoQuery

Parameters:

params - the named parameter map for the query invocation

getAccessPathMetaDatas

public ClassMetaData[] getAccessPathMetaDatas()

Description copied from interface: KodoQuerySPI

Return the classes that affect this query.

Specified by:

getAccessPathMetaDatas in interface KodoQuerySPI

getImportPackages

public String[] getImportPackages()

Description copied from interface: KodoQuerySPI

Return the import packages.

Specified by:

getImportPackages in interface KodoQuerySPI

getParameterTypes

public org.apache.commons.collections.map.LinkedMap getParameterTypes()

Description copied from interface: KodoQuerySPI

Return a map of parameter name to type for this query. The returned map will iterate in the order that the parameters were declared or, if they're implicit, used.

Specified by:

getParameterTypes in interface KodoQuerySPI

getVariableTypes

public Map getVariableTypes()

Description copied from interface: KodoQuerySPI

Return a map of variable name to type for this query.

Specified by:

getVariableTypes in interface KodoQuerySPI

getOrderingClauses

public String[] getOrderingClauses()

Description copied from interface: KodoQuerySPI

Return the ordering criteria.

Specified by:

getOrderingClauses in interface KodoQuerySPI

getAscending

public boolean[] getAscending()

Description copied from interface: KodoQuerySPI

Return wheher each ordering is ascending.

Specified by:

getAscending in interface KodoQuerySPI

getResultClauses

public String[] getResultClauses()

Description copied from interface: KodoQuerySPI

Return the result expressions.

Specified by:

getResultClauses in interface KodoQuerySPI

getResultTypes

public Class[] getResultTypes()

Description copied from interface: KodoQuerySPI

Return the type of each result clause.

Specified by:

getResultTypes in interface KodoQuerySPI

getAliases

public String[] getAliases()

Description copied from interface: KodoQuerySPI

Return the aliases for the result expressions.

Specified by:

getAliases in interface KodoQuerySPI

getAlias

public String getAlias()

Description copied from interface: KodoQuerySPI

When we're returning standard candidate instances rather than a projection or aggregate, return the alias for the instances in case a result class is set.

Specified by:

getAlias in interface KodoQuerySPI

isDistinct

public boolean isDistinct()

Description copied from interface: KodoQuerySPI

Whether the result specifies that this is a distinct query.

Specified by:

isDistinct in interface KodoQuerySPI

getGroupingClauses

public String[] getGroupingClauses()

Description copied from interface: KodoQuerySPI

Return the grouping expressions.

Specified by:

getGroupingClauses in interface KodoQuerySPI

getHaving

public String getHaving()

Description copied from interface: KodoQuerySPI

Return the having clause.

Specified by:

getHaving in interface KodoQuerySPI

lock

public void lock()

Description copied from interface: KodoQuerySPI

Synchronize on the query's internal lock.

Specified by:

lock in interface KodoQuerySPI

unlock

public void unlock()

Description copied from interface: KodoQuerySPI

Unlock the query's internal lock.

Specified by:

unlock in interface KodoQuerySPI