javax.jdo

Interface JDOQLTypedQuery<T>

Type Parameters:

T - candidate type for this query

All Superinterfaces:

AutoCloseable, Closeable, Serializable

public interface JDOQLTypedQuery<T>
extends Serializable, Closeable

Interface for a type-safe refactorable JDOQL query, using a fluent API, based around expressions. Note that a JDOQLTypedQuery only supports named parameters, and the values of these parameters should be set using the relevant setter methods prior to execution, and that the values for the parameters will only be retained until the subsequent query execution.

Field Summary

Fields

Modifier and Type	Field and Description
static String	QUERY_CLASS_PREFIX

Method Summary

Modifier and Type	Method and Description
void	cancel(Thread thread) Method to cancel an executing query in the specified thread.
void	cancelAll() Method to cancel any executing queries.
PersistableExpression<T>	candidate() Method to return an expression for the candidate of the query.
CharacterExpression	characterParameter(String name) Method to return a character parameter for the query.
void	close(Object result) Method to close the specified query result.
void	closeAll() Method to close all query results from this query.
CollectionExpression<?,?>	collectionParameter(String name) Method to return a collection parameter for the query.
default <E> CollectionExpression<Collection<E>,E>	collectionParameter(String name, Class<E> elementType) Method to return a collection parameter for the query.
JDOQLTypedQuery<T>	datastoreReadTimeoutMillis(Integer interval) Set the datastore read timeout (millis).
JDOQLTypedQuery<T>	datastoreWriteTimeoutMillis(Integer interval) Set the datastore write timeout (millis).
DateExpression	dateParameter(String name) Method to return a date parameter for the query.
DateTimeExpression	datetimeParameter(String name) Method to return a datetime parameter for the query.
long	deletePersistentAll() Method to execute the query deleting the affected instances.
JDOQLTypedQuery<T>	excludeSubclasses() Method to remove subclasses (of the candidate) from the query
List<T>	executeList() Method to execute the query where there are (potentially) multiple rows and we are returning the candidate type.
List<Object>	executeResultList() Method to execute the query where there are (potentially) multiple rows and we have a result defined but no result class.
<R> List<R>	executeResultList(Class<R> resultCls) Method to execute the query where there are (potentially) multiple rows and we are returning either the result type.
Object	executeResultUnique() Method to execute the query where there is a single row and we have a result defined but no result class.
<R> R	executeResultUnique(Class<R> resultCls) Method to execute the query where there is a single row and we are returning either the result type.
T	executeUnique() Method to execute the query where there is a single row and we are returning the candidate type.
JDOQLTypedQuery<T>	extension(String key, Object value) Specify an extension for this query.
JDOQLTypedQuery<T>	extensions(Map values) Specify a map of extensions for this query.
JDOQLTypedQuery<T>	filter(BooleanExpression expr) Method to set the filter of the query.
Integer	getDatastoreReadTimeoutMillis() Get the effective timeout setting for read operations.
Integer	getDatastoreWriteTimeoutMillis() Get the effective timeout setting for write operations.
FetchPlan	getFetchPlan() Accessor for the FetchPlan for this query
boolean	getIgnoreCache() Get the ignoreCache option setting.
PersistenceManager	getPersistenceManager() Accessor for the PersistenceManager for this query
Boolean	getSerializeRead() Return the current value of the serializeRead property.
JDOQLTypedQuery<T>	groupBy(Expression<?>... exprs) Method to set the grouping(s) for the query.
JDOQLTypedQuery<T>	having(Expression<?> expr) Method to set the having clause of the query.
<V> IfThenElseExpression<V>	ifThen(BooleanExpression cond, V thenValue) Method to return an "IF (...) ...
<V> IfThenElseExpression<V>	ifThen(Class<V> type, BooleanExpression cond, Expression<V> thenValueExpr) Method to return an "IF (...) ...
<V> IfThenElseExpression<V>	ifThenElse(BooleanExpression cond, Expression<V> thenValueExpr, V elseValue) Method to return an "IF (...) ...
<V> IfThenElseExpression<V>	ifThenElse(BooleanExpression cond, V thenValue, Expression<V> elseValueExpr) Method to return an "IF (...) ...
<V> IfThenElseExpression<V>	ifThenElse(BooleanExpression cond, V thenValue, V elseValue) Method to return an "IF (...) ...
<V> IfThenElseExpression<V>	ifThenElse(Class<V> type, BooleanExpression cond, Expression<V> thenValueExpr, Expression<V> elseValueExpr) Method to return an "IF (...) ...
JDOQLTypedQuery<T>	ignoreCache(boolean flag) Set whether we to ignore the cache with this query.
JDOQLTypedQuery<T>	includeSubclasses() Method to include subclasses (of the candidate) to the query
boolean	isUnmodifiable() The unmodifiable flag, when set, disallows further modification of the query, except for specifying the range, result class, and ignoreCache option.
ListExpression<?,?>	listParameter(String name) Method to return a list parameter for the query.
default <E> ListExpression<List<E>,E>	listParameter(String name, Class<E> elementType) Method to return a list parameter for the query.
MapExpression<?,?,?>	mapParameter(String name) Method to return a map parameter for the query.
default <K,V> MapExpression<Map<K,V>,K,V>	mapParameter(String name, Class<K> keyType, Class<V> valueType) Method to return a map parameter for the query.
NumericExpression<?>	numericParameter(String name) Method to return a numeric parameter for the query.
default <N> NumericExpression<N>	numericParameter(String name, Class<N> type) Method to return a numeric parameter for the query.
JDOQLTypedQuery<T>	orderBy(OrderExpression<?>... orderExprs) Method to set the ordering of the query.
<P> Expression<P>	parameter(String name, Class<P> type) Method to return a parameter for the query.
JDOQLTypedQuery<T>	range(Expression<?> paramLowerInclExpr, Expression<?> paramUpperExclExpr) Method to set the range of any required results, using parameters (expressions).
JDOQLTypedQuery<T>	range(long lowerIncl, long upperExcl) Method to set the range of any required results, using long values.
JDOQLTypedQuery<T>	range(NumericExpression<?> lowerInclExpr, NumericExpression<?> upperExclExpr) Method to set the range of any required results, using expressions.
JDOQLTypedQuery<T>	result(boolean distinct, Expression<?>... exprs) Method to set the result of the query.
JDOQLTypedQuery<T>	saveAsNamedQuery(String name) Save the query, as it is currently defined, as a named query under the specified name.
JDOQLTypedQuery<T>	serializeRead(Boolean serialize) Set whether we to lock all objects read by this query.
JDOQLTypedQuery<T>	setCandidates(Collection<T> candidates) Method to set the candidates to use over which we are querying.
JDOQLTypedQuery<T>	setParameter(Expression<?> paramExpr, Object value) Method to set a parameter value for the specified (parameter) expression when executing the query.
JDOQLTypedQuery<T>	setParameter(String paramName, Object value) Method to set the value for a named parameter for use when executing the query.
JDOQLTypedQuery<T>	setParameters(Map<String,?> namedParamMap) Method to set the named parameters on this query prior to execution.
StringExpression	stringParameter(String name) Method to return a string parameter for the query.
<S> JDOQLTypedSubquery<S>	subquery(Class<S> candidate, String candidateAlias) Method to return a subquery for use in this query.
<E> JDOQLTypedSubquery<E>	subquery(CollectionExpression<Collection<E>,E> candidateCollection, Class<E> candidate, String candidateAlias) Method to return a correlated subquery for use in this query.
JDOQLTypedSubquery<T>	subquery(String candidateAlias) Method to return a subquery for use in this query using the same candidate class as this query.
TimeExpression	timeParameter(String name) Method to return a time parameter for the query.
String	toString() Method to return the equivalent String form of this query (if applicable for the query language).
JDOQLTypedQuery<T>	unmodifiable() Set to make this query unmodifiable hereafter.
<V> Expression<V>	variable(String name, Class<V> type) Method to return a variable for this query.

Methods inherited from interface java.io.Closeable

close

Field Detail

QUERY_CLASS_PREFIX

static final String QUERY_CLASS_PREFIX

See Also:

Constant Field Values

Method Detail

candidate

PersistableExpression<T> candidate()

Method to return an expression for the candidate of the query. Cast the returned expression to the candidate "Q" type to be able to call methods on it. This calls the method "Q{type}.candidate(null)" The preference is to use the "Q{type}.candidate()" method for real type-safe handling.

Returns:

Expression for the candidate

parameter

<P> Expression<P> parameter(String name,
                            Class<P> type)

Method to return a parameter for the query. Cast the returned parameter to the right type to be able to call methods on it. The preference is to use the "xxxParameter(String)" methods for real type-safe handling.

Type Parameters:

P - type for the parameter

Parameters:

name - Name of the parameter

type - Java type of the parameter

Returns:

Expression for the parameter

stringParameter

StringExpression stringParameter(String name)

Method to return a string parameter for the query.

Parameters:

name - Name of the parameter

Returns:

StringExpression for the parameter

characterParameter

CharacterExpression characterParameter(String name)

Method to return a character parameter for the query.

Parameters:

name - Name of the parameter

Returns:

Expression for the parameter

numericParameter

NumericExpression<?> numericParameter(String name)

Method to return a numeric parameter for the query.

Parameters:

name - Name of the parameter

Returns:

NumericExpression for the parameter

numericParameter

default <N> NumericExpression<N> numericParameter(String name,
                                                  Class<N> type)

Method to return a numeric parameter for the query.

Type Parameters:

N - Type for the numeric parameter

Parameters:

name - Name of the parameter

type - Type of the numeric parameter

Returns:

NumericExpression for the parameter

dateParameter

DateExpression dateParameter(String name)

Method to return a date parameter for the query.

Parameters:

name - Name of the parameter

Returns:

Expression for the parameter

timeParameter

TimeExpression timeParameter(String name)

Method to return a time parameter for the query.

Parameters:

name - Name of the parameter

Returns:

Expression for the parameter

datetimeParameter

DateTimeExpression datetimeParameter(String name)

Method to return a datetime parameter for the query.

Parameters:

name - Name of the parameter

Returns:

Expression for the parameter

collectionParameter

CollectionExpression<?,?> collectionParameter(String name)

Method to return a collection parameter for the query.

Parameters:

name - Name of the parameter

Returns:

Expression for the parameter

collectionParameter

default <E> CollectionExpression<Collection<E>,E> collectionParameter(String name,
                                                                      Class<E> elementType)

Method to return a collection parameter for the query.

Type Parameters:

E - Element type for the collection parameter

Parameters:

name - Name of the parameter

elementType - Element type of the collection parameter

Returns:

Expression for the parameter

mapParameter

MapExpression<?,?,?> mapParameter(String name)

Method to return a map parameter for the query.

Parameters:

name - Name of the parameter

Returns:

Expression for the parameter

mapParameter

default <K,V> MapExpression<Map<K,V>,K,V> mapParameter(String name,
                                                       Class<K> keyType,
                                                       Class<V> valueType)

Method to return a map parameter for the query.

Type Parameters:

K - Key type for the map parameter

V - Value type for the map parameter

Parameters:

name - Name of the parameter

keyType - Key type of the map parameter

valueType - Value type of the map parameter

Returns:

Expression for the parameter

listParameter

ListExpression<?,?> listParameter(String name)

Method to return a list parameter for the query.

Parameters:

name - Name of the parameter

Returns:

Expression for the parameter

listParameter

default <E> ListExpression<List<E>,E> listParameter(String name,
                                                    Class<E> elementType)

Method to return a list parameter for the query.

Type Parameters:

E - Element type for the list parameter

Parameters:

name - Name of the parameter

elementType - Element type of the list parameter

Returns:

Expression for the parameter

variable

<V> Expression<V> variable(String name,
                           Class<V> type)

Method to return a variable for this query. Cast the returned variable to the right type to be able to call methods on it.

Type Parameters:

V - type for the variable

Parameters:

name - Name of the variable

type - Type of the variable

Returns:

Expression for the variable

setCandidates

JDOQLTypedQuery<T> setCandidates(Collection<T> candidates)

Method to set the candidates to use over which we are querying. If no candidates are set then the query is performed on the datastore.

Parameters:

candidates - The candidates

Returns:

The query

excludeSubclasses

JDOQLTypedQuery<T> excludeSubclasses()

Method to remove subclasses (of the candidate) from the query

Returns:

The query

includeSubclasses

JDOQLTypedQuery<T> includeSubclasses()

Method to include subclasses (of the candidate) to the query

Returns:

The query

filter

JDOQLTypedQuery<T> filter(BooleanExpression expr)

Method to set the filter of the query.

Parameters:

expr - Filter expression

Returns:

The query

ifThenElse

<V> IfThenElseExpression<V> ifThenElse(Class<V> type,
                                       BooleanExpression cond,
                                       Expression<V> thenValueExpr,
                                       Expression<V> elseValueExpr)

Method to return an "IF (...) ... ELSE ..." expression for use in this query.

Type Parameters:

V - type for the IfThenElseExpression

Parameters:

type - The type returned by the IfElse.

cond - The if condition

thenValueExpr - Expression for value to return when the if expression is met

elseValueExpr - Expression for value to return when the if expression is not met

Returns:

The IfThenElse expression

ifThenElse

<V> IfThenElseExpression<V> ifThenElse(BooleanExpression cond,
                                       V thenValue,
                                       Expression<V> elseValueExpr)

Method to return an "IF (...) ... ELSE ..." expression for use in this query.

Type Parameters:

V - type for the IfThenElseExpression

Parameters:

cond - The if condition

thenValue - Value to return when the if expression is met

elseValueExpr - Expression to return when the if expression is not met

Returns:

The IfThenElse expression

ifThenElse

<V> IfThenElseExpression<V> ifThenElse(BooleanExpression cond,
                                       Expression<V> thenValueExpr,
                                       V elseValue)

Method to return an "IF (...) ... ELSE ..." expression for use in this query.

Type Parameters:

V - type for the IfThenElseExpression

Parameters:

cond - The if condition

thenValueExpr - Expression to return when the if expression is met

elseValue - Value to return when the if expression is not met

Returns:

The IfThenElse expression

ifThenElse

<V> IfThenElseExpression<V> ifThenElse(BooleanExpression cond,
                                       V thenValue,
                                       V elseValue)

Method to return an "IF (...) ... ELSE ..." expression for use in this query.

Type Parameters:

V - type for the IfThenElseExpression

Parameters:

cond - The if condition

thenValue - Value to return when the if expression is met

elseValue - Value to return when the if expression is not met

Returns:

The IfThenElse expression

ifThen

<V> IfThenElseExpression<V> ifThen(Class<V> type,
                                   BooleanExpression cond,
                                   Expression<V> thenValueExpr)

Method to return an "IF (...) ... ELSE ..." expression for use in this query.

Type Parameters:

V - type for the IfThenElseExpression

Parameters:

type - The type returned by the IfElse.

cond - The if condition

thenValueExpr - Expression for value to return when the if expression is met

Returns:

The IfThenElse expression

ifThen

<V> IfThenElseExpression<V> ifThen(BooleanExpression cond,
                                   V thenValue)

Method to return an "IF (...) ... ELSE ..." expression for use in this query.

Type Parameters:

V - type for the IfThenElseExpression

Parameters:

cond - The if condition

thenValue - Value to return when the if expression is met

Returns:

The IfThenElse expression

groupBy

JDOQLTypedQuery<T> groupBy(Expression<?>... exprs)

Method to set the grouping(s) for the query.

Parameters:

exprs - Grouping expression(s)

Returns:

The query

having

JDOQLTypedQuery<T> having(Expression<?> expr)

Method to set the having clause of the query.

Parameters:

expr - Having expression

Returns:

The query

orderBy

JDOQLTypedQuery<T> orderBy(OrderExpression<?>... orderExprs)

Method to set the ordering of the query.

Parameters:

orderExprs - Ordering expression(s)

Returns:

The query

result

JDOQLTypedQuery<T> result(boolean distinct,
                          Expression<?>... exprs)

Method to set the result of the query.

Parameters:

distinct - Whether results are distinct

exprs - The result expressions

Returns:

The query

range

JDOQLTypedQuery<T> range(NumericExpression<?> lowerInclExpr,
                         NumericExpression<?> upperExclExpr)

Method to set the range of any required results, using expressions.

Parameters:

lowerInclExpr - The position of the first result (inclusive)

upperExclExpr - The position of the last result (exclusive)

Returns:

The query

range

JDOQLTypedQuery<T> range(long lowerIncl,
                         long upperExcl)

Method to set the range of any required results, using long values.

Parameters:

lowerIncl - The position of the first result (inclusive)

upperExcl - The position of the last result (exclusive)

Returns:

The query

range

JDOQLTypedQuery<T> range(Expression<?> paramLowerInclExpr,
                         Expression<?> paramUpperExclExpr)

Method to set the range of any required results, using parameters (expressions).

Parameters:

paramLowerInclExpr - Expression for a parameter defining the position of the first result (inclusive)

paramUpperExclExpr - Expression for a parameter defining the position of the last result (exclusive)

Returns:

The query

subquery

JDOQLTypedSubquery<T> subquery(String candidateAlias)

Method to return a subquery for use in this query using the same candidate class as this query. To obtain the expression for the subquery to link it back to this query, call "result(...)" on the subquery.

Parameters:

candidateAlias - Alias for the candidate

Returns:

The subquery

subquery

<S> JDOQLTypedSubquery<S> subquery(Class<S> candidate,
                                   String candidateAlias)

Method to return a subquery for use in this query. To obtain the expression for the subquery to link it back to this query, call "result(...)" on the subquery.

Type Parameters:

S - Candidate type for subquery

Parameters:

candidate - Candidate for the subquery

candidateAlias - Alias for the candidate

Returns:

The subquery

subquery

<E> JDOQLTypedSubquery<E> subquery(CollectionExpression<Collection<E>,E> candidateCollection,
                                   Class<E> candidate,
                                   String candidateAlias)

Method to return a correlated subquery for use in this query. The candidate collection of the subquery is defined using a collection relationship of the outer query. To obtain the expression for the subquery to link it back to this query, call "result(...)" on the subquery.

Type Parameters:

E - Candidate type for subquery

Parameters:

candidateCollection - Expression defining the candidate collection for the subquery

candidate - Candidate for the subquery

candidateAlias - Alias for the candidate

Returns:

The subquery

setParameters

JDOQLTypedQuery<T> setParameters(Map<String,?> namedParamMap)

Method to set the named parameters on this query prior to execution. All parameter values specified in this method will only be retained until the subsequent query execution.

Parameters:

namedParamMap - The map of parameter values keyed by their names.

Returns:

This query

setParameter

JDOQLTypedQuery<T> setParameter(Expression<?> paramExpr,
                                Object value)

Method to set a parameter value for the specified (parameter) expression when executing the query. All parameter values specified in this method will only be retained until the subsequent query execution.

Parameters:

paramExpr - Expression defining the parameter

value - The value

Returns:

The query

setParameter

JDOQLTypedQuery<T> setParameter(String paramName,
                                Object value)

Method to set the value for a named parameter for use when executing the query. All parameter values specified in this method will only be retained until the subsequent query execution.

Parameters:

paramName - Parameter name

value - The value

Returns:

The query

executeList

List<T> executeList()

Method to execute the query where there are (potentially) multiple rows and we are returning the candidate type. Any parameters required should be set prior to calling this method, using one of the setParameter methods.

Calling this method with a result being specified will result in JDOUserException being thrown.

Returns:

The results

executeUnique

T executeUnique()

Method to execute the query where there is a single row and we are returning the candidate type. Any parameters required should be set prior to calling this method, using one of the setParameter methods.

Calling this method with a result being specified will result in JDOUserException being thrown.

Returns:

The result

executeResultList

<R> List<R> executeResultList(Class<R> resultCls)

Method to execute the query where there are (potentially) multiple rows and we are returning either the result type. Any parameters required should be set prior to calling this method, using one of the setParameters methods.

Calling this method with no result being specified will result in JDOUserException being thrown.

Type Parameters:

R - result type

Parameters:

resultCls - Result class

Returns:

The results

executeResultUnique

<R> R executeResultUnique(Class<R> resultCls)

Method to execute the query where there is a single row and we are returning either the result type. Any parameters required should be set prior to calling this method, using one of the setParameter methods.

Calling this method with no result being specified will result in JDOUserException being thrown.

Type Parameters:

R - result type

Parameters:

resultCls - Result class

Returns:

The result

executeResultList

List<Object> executeResultList()

Method to execute the query where there are (potentially) multiple rows and we have a result defined but no result class. Any parameters required should be set prior to calling this method, using one of the setParameter methods.

Calling this method with no result being specified will result in JDOUserException being thrown.

Returns:

The results

executeResultUnique

Object executeResultUnique()

Method to execute the query where there is a single row and we have a result defined but no result class. Any parameters required should be set prior to calling this method, using one of the setParameters methods.

Calling this method with no result being specified will result in JDOUserException being thrown.

Returns:

The results

deletePersistentAll

long deletePersistentAll()

Method to execute the query deleting the affected instances. Any parameters required should be set prior to calling this method, using one of the setParameter methods.

Returns:

The number of objects deleted

getDatastoreReadTimeoutMillis

Integer getDatastoreReadTimeoutMillis()

Get the effective timeout setting for read operations. If the timeout has not been set on this query explicitly, the effective datastore read timeout value from the persistence manager is returned.

Returns:

the effective timeout setting (milliseconds).

See Also:

PersistenceManager.setDatastoreReadTimeoutMillis(Integer)

datastoreReadTimeoutMillis

JDOQLTypedQuery<T> datastoreReadTimeoutMillis(Integer interval)

Set the datastore read timeout (millis).

Parameters:

interval - The interval

Returns:

This query

getDatastoreWriteTimeoutMillis

Integer getDatastoreWriteTimeoutMillis()

Get the effective timeout setting for write operations. If the timeout has not been set on this query explicitly, the effective datastore write timeout value from the persistence manager is returned.

Returns:

the effective timeout setting (milliseconds).

See Also:

PersistenceManager.setDatastoreWriteTimeoutMillis(Integer)

datastoreWriteTimeoutMillis

JDOQLTypedQuery<T> datastoreWriteTimeoutMillis(Integer interval)

Set the datastore write timeout (millis).

Parameters:

interval - The interval

Returns:

This query

getSerializeRead

Boolean getSerializeRead()

Return the current value of the serializeRead property.

Returns:

the value of the serializeRead property

serializeRead

JDOQLTypedQuery<T> serializeRead(Boolean serialize)

Set whether we to lock all objects read by this query.

Parameters:

serialize - Whether to lock

Returns:

This query

isUnmodifiable

boolean isUnmodifiable()

The unmodifiable flag, when set, disallows further modification of the query, except for specifying the range, result class, and ignoreCache option.

Returns:

the current setting of the flag

unmodifiable

JDOQLTypedQuery<T> unmodifiable()

Set to make this query unmodifiable hereafter.

Returns:

This query

getIgnoreCache

boolean getIgnoreCache()

Get the ignoreCache option setting.

Returns:

the ignoreCache option setting.

ignoreCache

JDOQLTypedQuery<T> ignoreCache(boolean flag)

Set whether we to ignore the cache with this query.

Parameters:

flag - Whether to ignore the cache

Returns:

This query

extension

JDOQLTypedQuery<T> extension(String key,
                             Object value)

Specify an extension for this query.

Parameters:

key - The extension key

value - The extension value

Returns:

This query

extensions

JDOQLTypedQuery<T> extensions(Map values)

Specify a map of extensions for this query.

Parameters:

values - The extension map of keys and values

Returns:

This query

saveAsNamedQuery

JDOQLTypedQuery<T> saveAsNamedQuery(String name)

Save the query, as it is currently defined, as a named query under the specified name. If a named query already exists under this name (either defined in metadata, or previously saved) then it will be overwritten.

Parameters:

name - Name to save it under.

Returns:

This query

getPersistenceManager

PersistenceManager getPersistenceManager()

Accessor for the PersistenceManager for this query

Returns:

The PersistenceManager

getFetchPlan

FetchPlan getFetchPlan()

Accessor for the FetchPlan for this query

Returns:

The FetchPlan

cancelAll

void cancelAll()

Method to cancel any executing queries. If the underlying datastore doesn't support cancellation of queries this will throw JDOUnsupportedOptionException. If the cancellation fails (e.g in the underlying datastore) then this will throw a JDOException.

cancel

void cancel(Thread thread)

Method to cancel an executing query in the specified thread. If the underlying datastore doesn't support cancellation of queries this will throw JDOUnsupportedOptionException. If the cancellation fails (e.g in the underlying datastore) then this will throw a JDOException.

Parameters:

thread - The thread to cancel

close

void close(Object result)

Method to close the specified query result.

Parameters:

result - The result

closeAll

void closeAll()

Method to close all query results from this query.

toString

String toString()

Method to return the equivalent String form of this query (if applicable for the query language).

Overrides:

toString in class Object

Returns:

The single-string form of this query