com.sun.jdo.api.persistence.support

Interface Query

All Superinterfaces:

Serializable

public interface Query
extends Serializable

The Query interface allows applications to obtain persistent instances from the data store. The @link PersistenceManager is the factory for Query instances. There may be many Query instances associated with a PersistenceManager. Multiple queries might be executed simultaneously by different threads, but the implementation might choose to execute them serially. In either case, the implementation must be thread safe.

There are three required elements in a Query: the class of the candidate instances, the candidate collection of instances, and the filter.

There are optional elements: parameter declarations, variable declarations, import statements, and an ordering specification.

Version:

0.1

Author:

Craig Russell

Method Summary

Modifier and Type	Method and Description
void	compile() Verify the elements of the query and provide a hint to the query to prepare and optimize an execution plan.
void	declareImports(String imports) Set the import statements to be used to identify the package name of variables or parameters.
void	declareParameters(String parameters) Set the parameter list for query execution.
void	declareVariables(String variables) Declare the unbound variables to be used in the query.
Object	execute() Execute the query and return the filtered Collection.
Object	execute(Object p1) Execute the query and return the filtered Collection.
Object	execute(Object p1, Object p2) Execute the query and return the filtered Collection.
Object	execute(Object p1, Object p2, Object p3) Execute the query and return the filtered Collection.
Object	executeWithArray(Object[] parameters) Execute the query and return the filtered Collection.
Object	executeWithMap(Map parameters) Execute the query and return the filtered Collection.
boolean	getIgnoreCache() Get the ignoreCache option setting.
PersistenceManager	getPersistenceManager() Get the PersistenceManager associated with this Query.
void	setCandidates(Collection pcs) Set the candidate Collection to query.
void	setClass(Class cls) Set the class of the candidate instances of the query.
void	setFilter(String filter) Set the filter for the query.
void	setIgnoreCache(boolean ignoreCache) Set the ignoreCache option.
void	setOrdering(String ordering) Bind the ordering declarations to the query instance.
void	setPrefetchEnabled(boolean prefetchEnabled) Sets the prefetchEnabled option.
void	setResult(String result) Set the result of the query.

Method Detail

setClass

void setClass(Class cls)

Set the class of the candidate instances of the query.

The class is a PersistenceCapable class which specifies the class of the candidates of the query. Elements of the candidate collection that are of the specified class are filtered before being put into the result Collection.

Parameters:

cls - the Class of the candidate instances.

setCandidates

void setCandidates(Collection pcs)

Set the candidate Collection to query.

Parameters:

pcs - the Candidate collection.

setFilter

void setFilter(String filter)

Set the filter for the query. The filter is a Java-like boolean expression used to select elements of the candidate Collection.

Parameters:

filter - the query filter.

declareImports

void declareImports(String imports)

Set the import statements to be used to identify the package name of variables or parameters.

Parameters:

imports - import statements separated by semicolons.

declareParameters

void declareParameters(String parameters)

Set the parameter list for query execution. The types and names of execution parameters are specified as a String separated by commas, similar to formal method declarations.

Parameters:

parameters - the list of parameters separated by commas.

declareVariables

void declareVariables(String variables)

Declare the unbound variables to be used in the query.

Parameters:

variables - the variables separated by semicolons.

setOrdering

void setOrdering(String ordering)

Bind the ordering declarations to the query instance. The ordering consists of one or more ordering declarations separated by commas. Each ordering declaration is the name of the field in the name scope of the candidate class followed by one of the following words: ascending or descending.

Parameters:

ordering - the ordering declarations separated by comma.

setResult

void setResult(String result)

Set the result of the query.

The query result is an optional keyword distinct followed by a Java expression, which tells what values are to be returned by the JDO query. If the result is not specified, then it defaults to "distinct this", which has the effect of returning the elements of the candidates that match the filter.

setPrefetchEnabled

void setPrefetchEnabled(boolean prefetchEnabled)

Sets the prefetchEnabled option. The prefetchEnabled option specifies whether prefetch of relationship fields should be enabled for this query. The prefetch is enabled by default if such fields are part of DFG. A user needs to explicitely disable prefetch for any particular query if the related instances will not be used in this transaction.

Parameters:

prefetchEnabled - the setting of the prefetchEnabled option.

setIgnoreCache

void setIgnoreCache(boolean ignoreCache)

Set the ignoreCache option. The ignoreCache option setting specifies whether the query should execute entirely in the back end, instead of in the cache.

Parameters:

ignoreCache - the setting of the ignoreCache option.

getIgnoreCache

boolean getIgnoreCache()

Get the ignoreCache option setting.

Returns:

the ignoreCache option setting.

See Also:

setIgnoreCache(boolean)

compile

void compile()

Verify the elements of the query and provide a hint to the query to prepare and optimize an execution plan.

execute

Object execute()

Execute the query and return the filtered Collection.

Returns:

the filtered Collection.

See Also:

(Object[] parameters)

execute

Object execute(Object p1)

Execute the query and return the filtered Collection.

Parameters:

p1 - the value of the first parameter declared.

Returns:

the filtered Collection.

See Also:

(Object[] parameters)

execute

Object execute(Object p1,
               Object p2)

Execute the query and return the filtered Collection.

Parameters:

p1 - the value of the first parameter declared.

p2 - the value of the second parameter declared.

Returns:

the filtered Collection.

See Also:

(Object[] parameters)

execute

Object execute(Object p1,
               Object p2,
               Object p3)

Execute the query and return the filtered Collection.

Parameters:

p1 - the value of the first parameter declared.

p2 - the value of the second parameter declared.

p3 - the value of the third parameter declared.

Returns:

the filtered Collection.

See Also:

(Object[] parameters)

executeWithMap

Object executeWithMap(Map parameters)

Execute the query and return the filtered Collection.

Parameters:

parameters - the Map containing all of the parameters.

Returns:

the filtered Collection.

See Also:

(Object[] parameters)

executeWithArray

Object executeWithArray(Object[] parameters)

Execute the query and return the filtered Collection.

The execution of the query obtains the values of the parameters and matches them against the declared parameters in order. The type of the declared parameters must match the type of the passed parameters, except that the passed parameters might need to be unwrapped to get their primitive values.

The filter, import, declared parameters, declared variables, and ordering statements are verified for consistency.

Each element in the candidate Collection is examined to see that it is assignment compatible to the Class of the query. It is then evaluated by the boolean expression of the filter. The element passes the filter if there exist unique values for all variables for which the filter expression evaluates to true.

Parameters:

parameters - the Object array with all of the parameters.

Returns:

the filtered Collection.

getPersistenceManager

PersistenceManager getPersistenceManager()

Get the PersistenceManager associated with this Query.

If this Query has no PersistenceManager return null.

Returns:

the PersistenceManager associated with this Query.