Module org.dellroad.querystream.jpa

Package org.dellroad.querystream.jpa

Interface QueryStream<X,S extends jakarta.persistence.criteria.Selection<X>,C extends jakarta.persistence.criteria.CommonAbstractCriteria,C2 extends C,Q extends jakarta.persistence.Query>

Type Parameters:

X - stream item type

S - criteria type for stream item

C - configured criteria API query type

C2 - final criteria API query type

Q - JPA query type

All Superinterfaces:

QueryConfigurer<C,X,S>

All Known Subinterfaces:

BooleanValue, DeleteStream<X>, DoubleStream, DoubleValue, ExprStream<X,S>, ExprValue<X,S>, FromStream<X,S>, FromValue<X,S>, IntStream, IntValue, LongStream, LongValue, PathStream<X,S>, PathValue<X,S>, RootStream<X>, RootValue<X>, SearchStream<X,S>, SearchValue<X,S>, UpdateStream<X>

public interface QueryStream<X,S extends jakarta.persistence.criteria.Selection<X>,C extends jakarta.persistence.criteria.CommonAbstractCriteria,C2 extends C,Q extends jakarta.persistence.Query>
extends QueryConfigurer<C,X,S>

Builder for JPA criteria queries, based on configuration through a Stream-like API.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static final class	QueryStream.Builder	Builder for QueryStreams, DeleteStreams, and UpdateStreams.

Method Summary

Modifier and Type	Method	Description
QueryStream<X,S,C,C2,Q>	bind(Ref<X,? super S> ref)	Bind an unbound reference to the items in this stream.
<X2, S2 extends jakarta.persistence.criteria.Selection<X2>> QueryStream<X,S,C,C2,Q>	bind(Ref<X2,? super S2> ref, Function<? super S,? extends S2> refFunction)	Bind an unbound reference to the result of applying the given function to the items in this stream.
QueryStream<X,S,C,C2,Q>	filter(jakarta.persistence.metamodel.SingularAttribute<? super X,Boolean> attribute)	Filter results using the specified boolean property.
QueryStream<X,S,C,C2,Q>	filter(Function<? super S,? extends jakarta.persistence.criteria.Expression<Boolean>> predicateBuilder)	Filter results using the boolean expression produced by the given function.
jakarta.persistence.EntityManager	getEntityManager()	Get the EntityManager associated with this instance.
int	getFirstResult()	Get the row offset associated with this query.
jakarta.persistence.FlushModeType	getFlushMode()	Get the FlushModeType associated with this query.
Map<String,Object>	getHints()	Get any hints associated with this query.
jakarta.persistence.LockModeType	getLockMode()	Get the LockModeType associated with this query.
int	getMaxResults()	Get the row limit associated with this query.
Set<ParamBinding<?>>	getParams()	Get any parameter bindings associated with this query.
QueryType<X,C,C2,Q>	getQueryType()	Get the QueryType of this instance.
QueryStream<X,S,C,C2,Q>	limit(int maxSize)	Return this stream truncated to the specified maximum length.
static QueryStream.Builder	newBuilder(jakarta.persistence.EntityManager entityManager)	Create a QueryStream.Builder that constructs QueryStreams using the given EntityManager.
QueryStream<X,S,C,C2,Q>	peek(Consumer<? super S> peeker)	Peek at the items in this stream.
QueryStream<X,S,C,C2,Q>	skip(int num)	Return this stream with the specified number of initial elements skipped.
C2	toCriteriaQuery()	Build a criteria API query based on this instance.
Q	toQuery()	Build a fully configured JPA query based on this instance.
QueryStream<X,S,C,C2,Q>	withFetchGraph(String name)	Configure a fetch graph for this query.
QueryStream<X,S,C,C2,Q>	withFlushMode(jakarta.persistence.FlushModeType flushMode)	Set the FlushModeType associated with this query.
QueryStream<X,S,C,C2,Q>	withHint(String name, Object value)	Associate a hint with this query.
QueryStream<X,S,C,C2,Q>	withHints(Map<String,Object> hints)	Associate hints with this query.
QueryStream<X,S,C,C2,Q>	withLoadGraph(String name)	Configure a load graph for this query.
QueryStream<X,S,C,C2,Q>	withLockMode(jakarta.persistence.LockModeType lockMode)	Set the LockModeType associated with this query.
QueryStream<X,S,C,C2,Q>	withParam(jakarta.persistence.Parameter<Calendar> parameter, Calendar value, jakarta.persistence.TemporalType temporalType)	Bind the value of a query parameter of type Calendar.
QueryStream<X,S,C,C2,Q>	withParam(jakarta.persistence.Parameter<Date> parameter, Date value, jakarta.persistence.TemporalType temporalType)	Bind the value of a query parameter of type Date.
<T> QueryStream<X,S,C,C2,Q>	withParam(jakarta.persistence.Parameter<T> parameter, T value)	Bind the value of a query parameter.
QueryStream<X,S,C,C2,Q>	withParams(Iterable<? extends ParamBinding<?>> params)	Associate parameter bindings with this query.

Methods inherited from interface org.dellroad.querystream.jpa.QueryConfigurer

configure

Method Details

getQueryType

QueryType<X,C,C2,Q> getQueryType()

Get the QueryType of this instance.

Returns:

associated QueryType

getEntityManager

jakarta.persistence.EntityManager getEntityManager()

Get the EntityManager associated with this instance.

Returns:

associated EntityManager

toCriteriaQuery

C2 toCriteriaQuery()

Build a criteria API query based on this instance.

Note that due to limitations of the JPA Criteria API, the returned query object lacks information that is configured on the Query object and not the CriteriaQuery object, including lock mode, hints, parameters, row offset and limit, etc.

This information can only be configured on the fully formed Query; use toQuery() instead of this method to also include that information.

Returns:

new Criteria API query corresponding to this instance

See Also:

• toQuery()

toQuery

Q toQuery()

Build a fully configured JPA query based on this instance.

Returns:

new JPA query corresponding to this instance

getFirstResult

int getFirstResult()

Get the row offset associated with this query.

Returns:

row offset, or -1 if there is none configured

See Also:

• skip(int)
• Query.setFirstResult(int)

getMaxResults

int getMaxResults()

Get the row limit associated with this query.

Returns:

row limit, or -1 if there is none configured

See Also:

• limit(int)
• Query.setMaxResults(int)

getFlushMode

jakarta.persistence.FlushModeType getFlushMode()

Get the FlushModeType associated with this query.

Returns:

flush mode, or null if none set (i.e., use EntityManager setting)

See Also:

• Query.setFlushMode(jakarta.persistence.FlushModeType)

withFlushMode

QueryStream<X,S,C,C2,Q> withFlushMode(jakarta.persistence.FlushModeType flushMode)

Set the FlushModeType associated with this query.

Parameters:

flushMode - new flush mode

Returns:

new stream with the specified flush mode configured

Throws:

IllegalArgumentException - if flushMode is null

See Also:

• Query.setFlushMode(jakarta.persistence.FlushModeType)

getLockMode

jakarta.persistence.LockModeType getLockMode()

Get the LockModeType associated with this query.

Returns:

lock mode, or null if none set

See Also:

• Query.setLockMode(jakarta.persistence.LockModeType)

withLockMode

QueryStream<X,S,C,C2,Q> withLockMode(jakarta.persistence.LockModeType lockMode)

Set the LockModeType associated with this query.

Parameters:

lockMode - new lock mode

Returns:

new stream with the specified lock mode configured

Throws:

IllegalArgumentException - if lockMode is null

See Also:

• Query.setLockMode(jakarta.persistence.LockModeType)

getHints

Map<String,Object> getHints()

Get any hints associated with this query.

Returns:

configured hints, if any, otherwise an empty map

See Also:

• Query.setHint(java.lang.String, java.lang.Object)

withHint

QueryStream<X,S,C,C2,Q> withHint(String name,
 Object value)

Associate a hint with this query.

Parameters:

name - name of hint

value - value of hint

Returns:

new stream with the specified hint configured

Throws:

IllegalArgumentException - if lockMode is null

See Also:

• Query.setHint(java.lang.String, java.lang.Object)

withHints

QueryStream<X,S,C,C2,Q> withHints(Map<String,Object> hints)

Associate hints with this query.

Parameters:

hints - hints to add

Returns:

new stream with the specified hints added

Throws:

IllegalArgumentException - if hints is null

See Also:

• Query.setHint(java.lang.String, java.lang.Object)

getParams

Set<ParamBinding<?>> getParams()

Get any parameter bindings associated with this query.

Returns:

configured parameter bindings, if any, otherwise an empty set

See Also:

• Query.setParameter(Parameter, Object)

withParam

<T> QueryStream<X,S,C,C2,Q> withParam(jakarta.persistence.Parameter<T> parameter,
 T value)

Bind the value of a query parameter.

Replaces any previous binding of the same parameter.

Type Parameters:

T - parameter value type

Parameters:

parameter - the parameter to set

value - parameter value

Returns:

new stream with the specified parameter value set

Throws:

IllegalArgumentException - if parameter is null

See Also:

• Query.setParameter(Parameter, Object)

withParam

QueryStream<X,S,C,C2,Q> withParam(jakarta.persistence.Parameter<Date> parameter,
 Date value,
 jakarta.persistence.TemporalType temporalType)

Bind the value of a query parameter of type Date.

Replaces any previous binding of the same parameter.

Parameters:

parameter - the parameter to set

value - parameter value

temporalType - temporal type for value

Returns:

new stream with the specified parameter value set

Throws:

IllegalArgumentException - if parameter or temporalType is null

See Also:

• Query.setParameter(Parameter, Date, TemporalType)

withParam

QueryStream<X,S,C,C2,Q> withParam(jakarta.persistence.Parameter<Calendar> parameter,
 Calendar value,
 jakarta.persistence.TemporalType temporalType)

Bind the value of a query parameter of type Calendar.

Replaces any previous binding of the same parameter.

Parameters:

parameter - the parameter to set

value - parameter value

temporalType - temporal type for value

Returns:

new stream with the specified parameter value set

Throws:

IllegalArgumentException - if parameter or temporalType is null

See Also:

• Query.setParameter(Parameter, Calendar, TemporalType)

withParams

QueryStream<X,S,C,C2,Q> withParams(Iterable<? extends ParamBinding<?>> params)

Associate parameter bindings with this query.

Replaces any previous bindings of the same parameters.

Parameters:

params - bindings to add

Returns:

new stream with the specified parameter bindings added

Throws:

IllegalArgumentException - if params or any contained element is null

IllegalArgumentException - if params contains duplicate bindings for the same parameter

See Also:

• Query.setParameter(Parameter, Object)

withLoadGraph

QueryStream<X,S,C,C2,Q> withLoadGraph(String name)

Configure a load graph for this query.

Equivalent to withHint("jakarta.persistence.loadgraph", name).

Parameters:

name - name of load graph

Returns:

new stream with the specified load graph configured

Throws:

IllegalArgumentException - if name is invalid

withFetchGraph

QueryStream<X,S,C,C2,Q> withFetchGraph(String name)

Configure a fetch graph for this query.

Equivalent to withHint("jakarta.persistence.fetchgraph", name).

Parameters:

name - name of fetch graph

Returns:

new stream with the specified fetch graph configured

Throws:

IllegalArgumentException - if name is invalid

bind

QueryStream<X,S,C,C2,Q> bind(Ref<X,? super S> ref)

Bind an unbound reference to the items in this stream.

Parameters:

ref - unbound reference

Returns:

new stream that binds ref

Throws:

IllegalArgumentException - if ref is already bound

IllegalArgumentException - if ref is null

bind

<X2,
S2 extends jakarta.persistence.criteria.Selection<X2>>
QueryStream<X,S,C,C2,Q> bind(Ref<X2,? super S2> ref,
 Function<? super S,? extends S2> refFunction)

Bind an unbound reference to the result of applying the given function to the items in this stream.

Type Parameters:

X2 - type of the bound value

S2 - criteria type of the bound value

Parameters:

ref - unbound reference

refFunction - function mapping this stream's Selection to the reference value

Returns:

new stream that binds ref

Throws:

IllegalArgumentException - if ref is already bound

IllegalArgumentException - if ref or refFunction is null

peek

QueryStream<X,S,C,C2,Q> peek(Consumer<? super S> peeker)

Peek at the items in this stream.

This is useful in cases where the selection can be modified, e.g., setting join ON conditions using Join.on().

Parameters:

peeker - peeker into stream

Returns:

new stream that peeks into this stream

Throws:

IllegalArgumentException - if peeker is null

filter

QueryStream<X,S,C,C2,Q> filter(Function<? super S,? extends jakarta.persistence.criteria.Expression<Boolean>> predicateBuilder)

Filter results using the boolean expression produced by the given function.

Adds to any previously specified filters.

Parameters:

predicateBuilder - function mapping this stream's item to a boolean Expression

Returns:

new filtered stream

Throws:

IllegalArgumentException - if predicateBuilder is null

filter

QueryStream<X,S,C,C2,Q> filter(jakarta.persistence.metamodel.SingularAttribute<? super X,Boolean> attribute)

Filter results using the specified boolean property.

Adds to any previously specified filters.

Parameters:

attribute - boolean property

Returns:

new filtered stream

Throws:

IllegalArgumentException - if attribute is null

limit

QueryStream<X,S,C,C2,Q> limit(int maxSize)

Return this stream truncated to the specified maximum length.

Due to limitations in the JPA Criteria API, this method is not supported on subquery streams and in general must be specified last (after any filtering, sorting, grouping, joins, etc.).

Parameters:

maxSize - maximum number of elements to return

Returns:

new truncated stream

Throws:

IllegalArgumentException - if maxSize is negative

skip

QueryStream<X,S,C,C2,Q> skip(int num)

Return this stream with the specified number of initial elements skipped.

Due to limitations in the JPA Criteria API, this method is not supported on subquery streams and in general must be specified last (after any filtering, sorting, grouping, joins, etc.).

Parameters:

num - number of elements to skip

Returns:

new elided stream

Throws:

IllegalArgumentException - if num is negative

newBuilder

static QueryStream.Builder newBuilder(jakarta.persistence.EntityManager entityManager)

Create a QueryStream.Builder that constructs QueryStreams using the given EntityManager.

Parameters:

entityManager - entity manager

Returns:

new stream builder

Throws:

IllegalArgumentException - if entityManager is null