Module org.dellroad.querystream.jpa

Package org.dellroad.querystream.jpa

Interface SearchValue<X,S extends jakarta.persistence.criteria.Selection<X>>

All Superinterfaces:

QueryConfigurer<jakarta.persistence.criteria.AbstractQuery<?>,X,S>, QueryStream<X,S,jakarta.persistence.criteria.AbstractQuery<?>,jakarta.persistence.criteria.CriteriaQuery<X>,jakarta.persistence.TypedQuery<X>>, SearchStream<X,S>

All Known Subinterfaces:

BooleanValue, DoubleValue, ExprValue<X,S>, FromValue<X,S>, IntValue, LongValue, PathValue<X,S>, RootValue<X>

public interface SearchValue<X,S extends jakarta.persistence.criteria.Selection<X>>
extends SearchStream<X,S>

A SearchStream that is guaranteed to return at most a single result.

Nested Class Summary

Nested classes/interfaces inherited from interface org.dellroad.querystream.jpa.QueryStream

QueryStream.Builder

Method Summary

Modifier and Type	Method	Description
SearchValue<X,S>	bind(Ref<X,? super S> ref)	Bind an unbound reference to the items in this stream.
<X2, S2 extends jakarta.persistence.criteria.Selection<X2>> SearchValue<X,S>	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.
SearchValue<X,S>	filter(jakarta.persistence.metamodel.SingularAttribute<? super X,Boolean> attribute)	Filter results using the specified boolean property.
SearchValue<X,S>	filter(Function<? super S,? extends jakarta.persistence.criteria.Expression<Boolean>> predicateBuilder)	Filter results using the boolean expression produced by the given function.
default void	ifPresent(Consumer<? super X> consumer)	Build and evaluate a JPA query based on this instance and give the returned value, if any, to the given Consumer.
default boolean	isPresent()	Build and evaluate a JPA query based on this instance and return true if a result is returned, otherwise false.
default <Y> SearchValue<Y,jakarta.persistence.criteria.Selection<Y>>	mapToSelection(Class<Y> type, Function<? super S,? extends jakarta.persistence.criteria.Selection<Y>> selectionFunction)	Map this stream into a stream whose elements are the result of applying the given function.
default X	orElse(X defaultValue)	Build and evaluate a JPA query based on this instance and return the single result, if any, otherwise the given value.
default X	orElseGet(Supplier<? extends X> supplier)	Build and evaluate a JPA query based on this instance and return the single result, if any, otherwise the value from the given Supplier.
default <T extends Throwable> X	orElseThrow(Supplier<? extends T> supplier)	Build and evaluate a JPA query based on this instance and return the single result, if any, otherwise throw an exception provided by the given Supplier.
SearchValue<X,S>	peek(Consumer<? super S> peeker)	Peek at the items in this stream.
default Optional<X>	toOptional()	Build and evaluate a JPA query based on this instance and return the single result, if any, as an Optional.
default X	value()	Build and evaluate a JPA query based on this instance and return the single result, if any.
SearchValue<X,S>	withFetchGraph(String name)	Configure a fetch graph for this query.
SearchValue<X,S>	withFlushMode(jakarta.persistence.FlushModeType flushMode)	Set the FlushModeType associated with this query.
SearchValue<X,S>	withHint(String name, Object value)	Associate a hint with this query.
SearchValue<X,S>	withHints(Map<String,Object> hints)	Associate hints with this query.
SearchValue<X,S>	withLoadGraph(String name)	Configure a load graph for this query.
SearchValue<X,S>	withLockMode(jakarta.persistence.LockModeType lockMode)	Set the LockModeType associated with this query.
SearchValue<X,S>	withParam(jakarta.persistence.Parameter<Calendar> parameter, Calendar value, jakarta.persistence.TemporalType temporalType)	Bind the value of a query parameter of type Calendar.
SearchValue<X,S>	withParam(jakarta.persistence.Parameter<Date> parameter, Date value, jakarta.persistence.TemporalType temporalType)	Bind the value of a query parameter of type Date.
<T> SearchValue<X,S>	withParam(jakarta.persistence.Parameter<T> parameter, T value)	Bind the value of a query parameter.
SearchValue<X,S>	withParams(Iterable<? extends ParamBinding<?>> params)	Associate parameter bindings with this query.

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

configure

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

getEntityManager, getFirstResult, getFlushMode, getHints, getLockMode, getMaxResults, getParams, toCriteriaQuery, toQuery

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

addRoot, allMatch, allMatch, anyMatch, anyMatch, distinct, fetch, fetch, fetch, fetch, findAny, findFirst, findSingle, flatMap, flatMap, flatMap, flatMapKeys, flatMapValues, getQueryType, getResultList, getResultStream, groupBy, groupBy, groupBy, groupByMulti, having, isEmpty, join, join, join, join, join, join, join, join, join, join, join, join, join, join, join, limit, map, map, map, map, mapToDouble, mapToDouble, mapToExpr, mapToFrom, mapToInt, mapToInt, mapToLong, mapToLong, mapToPath, mapToRef, mapToRef, mapToRef, mapToRef, mapToRoot, noneMatch, noneMatch, orderBy, orderBy, orderBy, orderBy, orderBy, orderBy, orderByMulti, skip, thenOrderBy, thenOrderBy, thenOrderBy, thenOrderBy

Method Details

value

default X value()

Build and evaluate a JPA query based on this instance and return the single result, if any.

Returns:

result of executed query

Throws:

jakarta.persistence.NoResultException - if there is no result

jakarta.persistence.NonUniqueResultException - if there is more than one result

orElse

default X orElse(X defaultValue)

Build and evaluate a JPA query based on this instance and return the single result, if any, otherwise the given value.

Parameters:

defaultValue - value to return if there is no match

Returns:

result of executed query, or defaultValue if not found

Throws:

jakarta.persistence.NonUniqueResultException - if there is more than one result

orElseThrow

default <T extends Throwable> X orElseThrow(Supplier<? extends T> supplier)
                                     throws T

Build and evaluate a JPA query based on this instance and return the single result, if any, otherwise throw an exception provided by the given Supplier.

Type Parameters:

T - exception type

Parameters:

supplier - creator of exception

Returns:

result of executed query

Throws:

T - if there is no result

jakarta.persistence.NonUniqueResultException - if there is more than one result

orElseGet

default X orElseGet(Supplier<? extends X> supplier)

Build and evaluate a JPA query based on this instance and return the single result, if any, otherwise the value from the given Supplier.

Parameters:

supplier - creator of exception

Returns:

result of executed query

Throws:

jakarta.persistence.NonUniqueResultException - if there is more than one result

IllegalArgumentException - if supplier is null

ifPresent

default void ifPresent(Consumer<? super X> consumer)

Build and evaluate a JPA query based on this instance and give the returned value, if any, to the given Consumer.

Parameters:

consumer - receives value returned by query, if any

Throws:

IllegalArgumentException - if consumer is null

jakarta.persistence.NonUniqueResultException - if there is more than one result

isPresent

default boolean isPresent()

Build and evaluate a JPA query based on this instance and return true if a result is returned, otherwise false.

Returns:

true if executed query returns a result, false otherwise

Throws:

jakarta.persistence.NonUniqueResultException - if there is more than one result

toOptional

default Optional<X> toOptional()

Build and evaluate a JPA query based on this instance and return the single result, if any, as an Optional.

Note: due to limitations of the Optional class, this method does not support returning null values; if the query returns a null value, an exception is thrown.

Returns:

the optional result of the executed query

Throws:

jakarta.persistence.NonUniqueResultException - if there is more than one result

IllegalArgumentException - if this query returns a null value

mapToSelection

default <Y>
SearchValue<Y,jakarta.persistence.criteria.Selection<Y>> mapToSelection(Class<Y> type,
 Function<? super S,? extends jakarta.persistence.criteria.Selection<Y>> selectionFunction)

Description copied from interface: SearchStream

Map this stream into a stream whose elements are the result of applying the given function.

This method provides support for multiple selection using CriteriaBuilder.array(), CriteriaBuilder.construct(), or CriteriaBuilder.tuple(). For normal single selection, typically you would use SearchStream.map() instead of this method.

Specified by:

mapToSelection in interface SearchStream<X,S extends jakarta.persistence.criteria.Selection<X>>

Type Parameters:

Y - selection type

Parameters:

type - selection type

selectionFunction - function to build selection

Returns:

mapped stream

bind

SearchValue<X,S> bind(Ref<X,? super S> ref)

Description copied from interface: QueryStream

Bind an unbound reference to the items in this stream.

Specified by:

bind in interface QueryStream<X,S extends jakarta.persistence.criteria.Selection<X>,jakarta.persistence.criteria.AbstractQuery<?>,jakarta.persistence.criteria.CriteriaQuery<X>,jakarta.persistence.TypedQuery<X>>

Specified by:

bind in interface SearchStream<X,S extends jakarta.persistence.criteria.Selection<X>>

Parameters:

ref - unbound reference

Returns:

new stream that binds ref

peek

SearchValue<X,S> peek(Consumer<? super S> peeker)

Description copied from interface: QueryStream

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

Specified by:

peek in interface QueryStream<X,S extends jakarta.persistence.criteria.Selection<X>,jakarta.persistence.criteria.AbstractQuery<?>,jakarta.persistence.criteria.CriteriaQuery<X>,jakarta.persistence.TypedQuery<X>>

Specified by:

peek in interface SearchStream<X,S extends jakarta.persistence.criteria.Selection<X>>

Parameters:

peeker - peeker into stream

Returns:

new stream that peeks into this stream

bind

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

Description copied from interface: QueryStream

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

Specified by:

bind in interface QueryStream<X,S extends jakarta.persistence.criteria.Selection<X>,jakarta.persistence.criteria.AbstractQuery<?>,jakarta.persistence.criteria.CriteriaQuery<X>,jakarta.persistence.TypedQuery<X>>

Specified by:

bind in interface SearchStream<X,S extends jakarta.persistence.criteria.Selection<X>>

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

filter

SearchValue<X,S> filter(jakarta.persistence.metamodel.SingularAttribute<? super X,Boolean> attribute)

Description copied from interface: QueryStream

Filter results using the specified boolean property.

Adds to any previously specified filters.

Specified by:

filter in interface QueryStream<X,S extends jakarta.persistence.criteria.Selection<X>,jakarta.persistence.criteria.AbstractQuery<?>,jakarta.persistence.criteria.CriteriaQuery<X>,jakarta.persistence.TypedQuery<X>>

Specified by:

filter in interface SearchStream<X,S extends jakarta.persistence.criteria.Selection<X>>

Parameters:

attribute - boolean property

Returns:

new filtered stream

filter

SearchValue<X,S> filter(Function<? super S,? extends jakarta.persistence.criteria.Expression<Boolean>> predicateBuilder)

Description copied from interface: QueryStream

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

Adds to any previously specified filters.

Specified by:

filter in interface QueryStream<X,S extends jakarta.persistence.criteria.Selection<X>,jakarta.persistence.criteria.AbstractQuery<?>,jakarta.persistence.criteria.CriteriaQuery<X>,jakarta.persistence.TypedQuery<X>>

Specified by:

filter in interface SearchStream<X,S extends jakarta.persistence.criteria.Selection<X>>

Parameters:

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

Returns:

new filtered stream

withFlushMode

SearchValue<X,S> withFlushMode(jakarta.persistence.FlushModeType flushMode)

Description copied from interface: QueryStream

Set the FlushModeType associated with this query.

Specified by:

withFlushMode in interface QueryStream<X,S extends jakarta.persistence.criteria.Selection<X>,jakarta.persistence.criteria.AbstractQuery<?>,jakarta.persistence.criteria.CriteriaQuery<X>,jakarta.persistence.TypedQuery<X>>

Specified by:

withFlushMode in interface SearchStream<X,S extends jakarta.persistence.criteria.Selection<X>>

Parameters:

flushMode - new flush mode

Returns:

new stream with the specified flush mode configured

See Also:

• Query.setFlushMode(jakarta.persistence.FlushModeType)

withLockMode

SearchValue<X,S> withLockMode(jakarta.persistence.LockModeType lockMode)

Description copied from interface: QueryStream

Set the LockModeType associated with this query.

Specified by:

withLockMode in interface QueryStream<X,S extends jakarta.persistence.criteria.Selection<X>,jakarta.persistence.criteria.AbstractQuery<?>,jakarta.persistence.criteria.CriteriaQuery<X>,jakarta.persistence.TypedQuery<X>>

Specified by:

withLockMode in interface SearchStream<X,S extends jakarta.persistence.criteria.Selection<X>>

Parameters:

lockMode - new lock mode

Returns:

new stream with the specified lock mode configured

See Also:

• Query.setLockMode(jakarta.persistence.LockModeType)

withHint

SearchValue<X,S> withHint(String name,
 Object value)

Description copied from interface: QueryStream

Associate a hint with this query.

Specified by:

withHint in interface QueryStream<X,S extends jakarta.persistence.criteria.Selection<X>,jakarta.persistence.criteria.AbstractQuery<?>,jakarta.persistence.criteria.CriteriaQuery<X>,jakarta.persistence.TypedQuery<X>>

Specified by:

withHint in interface SearchStream<X,S extends jakarta.persistence.criteria.Selection<X>>

Parameters:

name - name of hint

value - value of hint

Returns:

new stream with the specified hint configured

See Also:

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

withHints

SearchValue<X,S> withHints(Map<String,Object> hints)

Description copied from interface: QueryStream

Associate hints with this query.

Specified by:

withHints in interface QueryStream<X,S extends jakarta.persistence.criteria.Selection<X>,jakarta.persistence.criteria.AbstractQuery<?>,jakarta.persistence.criteria.CriteriaQuery<X>,jakarta.persistence.TypedQuery<X>>

Specified by:

withHints in interface SearchStream<X,S extends jakarta.persistence.criteria.Selection<X>>

Parameters:

hints - hints to add

Returns:

new stream with the specified hints added

See Also:

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

withParam

<T> SearchValue<X,S> withParam(jakarta.persistence.Parameter<T> parameter,
 T value)

Description copied from interface: QueryStream

Bind the value of a query parameter.

Replaces any previous binding of the same parameter.

Specified by:

withParam in interface QueryStream<X,S extends jakarta.persistence.criteria.Selection<X>,jakarta.persistence.criteria.AbstractQuery<?>,jakarta.persistence.criteria.CriteriaQuery<X>,jakarta.persistence.TypedQuery<X>>

Specified by:

withParam in interface SearchStream<X,S extends jakarta.persistence.criteria.Selection<X>>

Type Parameters:

T - parameter value type

Parameters:

parameter - the parameter to set

value - parameter value

Returns:

new stream with the specified parameter value set

See Also:

• Query.setParameter(Parameter, Object)

withParam

SearchValue<X,S> withParam(jakarta.persistence.Parameter<Date> parameter,
 Date value,
 jakarta.persistence.TemporalType temporalType)

Description copied from interface: QueryStream

Bind the value of a query parameter of type Date.

Replaces any previous binding of the same parameter.

Specified by:

withParam in interface QueryStream<X,S extends jakarta.persistence.criteria.Selection<X>,jakarta.persistence.criteria.AbstractQuery<?>,jakarta.persistence.criteria.CriteriaQuery<X>,jakarta.persistence.TypedQuery<X>>

Specified by:

withParam in interface SearchStream<X,S extends jakarta.persistence.criteria.Selection<X>>

Parameters:

parameter - the parameter to set

value - parameter value

temporalType - temporal type for value

Returns:

new stream with the specified parameter value set

See Also:

• Query.setParameter(Parameter, Date, TemporalType)

withParam

SearchValue<X,S> withParam(jakarta.persistence.Parameter<Calendar> parameter,
 Calendar value,
 jakarta.persistence.TemporalType temporalType)

Description copied from interface: QueryStream

Bind the value of a query parameter of type Calendar.

Replaces any previous binding of the same parameter.

Specified by:

withParam in interface QueryStream<X,S extends jakarta.persistence.criteria.Selection<X>,jakarta.persistence.criteria.AbstractQuery<?>,jakarta.persistence.criteria.CriteriaQuery<X>,jakarta.persistence.TypedQuery<X>>

Specified by:

withParam in interface SearchStream<X,S extends jakarta.persistence.criteria.Selection<X>>

Parameters:

parameter - the parameter to set

value - parameter value

temporalType - temporal type for value

Returns:

new stream with the specified parameter value set

See Also:

• Query.setParameter(Parameter, Calendar, TemporalType)

withParams

SearchValue<X,S> withParams(Iterable<? extends ParamBinding<?>> params)

Description copied from interface: QueryStream

Associate parameter bindings with this query.

Replaces any previous bindings of the same parameters.

Specified by:

withParams in interface QueryStream<X,S extends jakarta.persistence.criteria.Selection<X>,jakarta.persistence.criteria.AbstractQuery<?>,jakarta.persistence.criteria.CriteriaQuery<X>,jakarta.persistence.TypedQuery<X>>

Specified by:

withParams in interface SearchStream<X,S extends jakarta.persistence.criteria.Selection<X>>

Parameters:

params - bindings to add

Returns:

new stream with the specified parameter bindings added

See Also:

• Query.setParameter(Parameter, Object)

withLoadGraph

SearchValue<X,S> withLoadGraph(String name)

Description copied from interface: QueryStream

Configure a load graph for this query.

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

Specified by:

withLoadGraph in interface QueryStream<X,S extends jakarta.persistence.criteria.Selection<X>,jakarta.persistence.criteria.AbstractQuery<?>,jakarta.persistence.criteria.CriteriaQuery<X>,jakarta.persistence.TypedQuery<X>>

Specified by:

withLoadGraph in interface SearchStream<X,S extends jakarta.persistence.criteria.Selection<X>>

Parameters:

name - name of load graph

Returns:

new stream with the specified load graph configured

withFetchGraph

SearchValue<X,S> withFetchGraph(String name)

Description copied from interface: QueryStream

Configure a fetch graph for this query.

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

Specified by:

withFetchGraph in interface QueryStream<X,S extends jakarta.persistence.criteria.Selection<X>,jakarta.persistence.criteria.AbstractQuery<?>,jakarta.persistence.criteria.CriteriaQuery<X>,jakarta.persistence.TypedQuery<X>>

Specified by:

withFetchGraph in interface SearchStream<X,S extends jakarta.persistence.criteria.Selection<X>>

Parameters:

name - name of fetch graph

Returns:

new stream with the specified fetch graph configured