Package org.dellroad.querystream.jpa

Interface SearchStream<X,S extends Selection<X>>

Type Parameters:
X - stream item type
S - criteria type for stream item
All Superinterfaces:
QueryConfigurer<AbstractQuery<?>,X,S>, QueryStream<X,S,AbstractQuery<?>,CriteriaQuery<X>,TypedQuery<X>>
All Known Subinterfaces:
BooleanValue, 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>, SearchValue<X,S>
public interface SearchStream<X,S extends Selection<X>> extends QueryStream<X,S,AbstractQuery<?>,CriteriaQuery<X>,TypedQuery<X>>
Builder for JPA criteria search queries, based on configuration through a Stream-like API.

  • Method Details

    • getResultList

      default List<X> getResultList()
      Build and evaluate a JPA query based on this instance and return the result list.

      Delegates to TypedQuery.getResultList() and can throw any exception thrown by that method.

      Returns:
      result of executed query
      See Also:

    • getResultStream

      default Stream<X> getResultStream()
      Build and evaluate a JPA query based on this instance and return the result stream.

      Delegates to TypedQuery.getResultStream() and can throw any exception thrown by that method.

      Returns:
      result of executed query
      See Also:

    • distinct

      SearchStream<X,S> distinct()
      Suppress duplicates.
      Returns:
      a new stream with duplicates removed

    • orderBy

      SearchStream<X,S> orderBy(SingularAttribute<? super X,?> attribute, boolean asc)
      Order results using the specified property.

      Replaces any existing sort ordering.

      Parameters:
      attribute - associated property
      asc - true for ascending, false for descending
      Returns:
      a new stream with specified ordering
      Throws:
      IllegalArgumentException - if attribute is null

    • orderBy

      SearchStream<X,S> orderBy(SingularAttribute<? super X,?> attribute1, boolean asc1, SingularAttribute<? super X,?> attribute2, boolean asc2)
      Order results using the specified properties.

      Replaces any existing sort ordering.

      Parameters:
      attribute1 - associated property
      asc1 - true for attribute1 ascending, false for attribute1 descending
      attribute2 - associated property
      asc2 - true for attribute2 ascending, false for attribute2 descending
      Returns:
      a new stream with specified ordering
      Throws:
      IllegalArgumentException - if attribute1 or attribute2 is null

    • orderBy

      SearchStream<X,S> orderBy(SingularAttribute<? super X,?> attribute1, boolean asc1, SingularAttribute<? super X,?> attribute2, boolean asc2, SingularAttribute<? super X,?> attribute3, boolean asc3)
      Order results using the specified properties.

      Replaces any existing sort ordering.

      Parameters:
      attribute1 - associated property
      asc1 - true for attribute1 ascending, false for attribute1 descending
      attribute2 - associated property
      asc2 - true for attribute2 ascending, false for attribute2 descending
      attribute3 - associated property
      asc3 - true for attribute3 ascending, false for attribute3 descending
      Returns:
      a new stream with specified ordering
      Throws:
      IllegalArgumentException - if attribute1, attribute2, or attribute3 is null

    • orderBy

      SearchStream<X,S> orderBy(Ref<?,? extends Expression<?>> ref, boolean asc)
      Order results using the specified expression reference.

      Replaces any existing sort ordering.

      Parameters:
      ref - previously bound expression reference
      asc - true for ascending, false for descending
      Returns:
      a new stream with specified ordering
      Throws:
      IllegalArgumentException - if ref is null

    • orderBy

      SearchStream<X,S> orderBy(Order... orders)
      Order results using the specified Orders.

      Replaces any existing sort ordering.

      Parameters:
      orders - ordering(s), with higher precedence orderings first
      Returns:
      a new stream with specified ordering(s)
      Throws:
      IllegalArgumentException - if orders is null

    • orderBy

      SearchStream<X,S> orderBy(Function<? super S,? extends Expression<?>> orderExprFunction, boolean asc)
      Order results using the Expression produced by the given Function.

      Replaces any existing sort ordering.

      Parameters:
      orderExprFunction - Function that produces an Expression to order on given an item expression
      asc - true for ascending, false for descending
      Returns:
      a new stream with specified ordering
      Throws:
      IllegalArgumentException - if orderExprFunction is null

    • orderByMulti

      SearchStream<X,S> orderByMulti(Function<? super S,? extends List<? extends Order>> orderListFunction)
      Order results using the Order list produced by the given Function.

      Replaces any existing sort ordering.

      Parameters:
      orderListFunction - Function that produces the sort ordering given an item expression
      Returns:
      a new stream with specified ordering
      Throws:
      IllegalArgumentException - if orderListFunction is null

    • thenOrderBy

      SearchStream<X,S> thenOrderBy(SingularAttribute<? super X,?> attribute, boolean asc)
      Order results using the specified property after existing sort.

      Adds to any existing sort ordering.

      Parameters:
      attribute - associated property
      asc - true for ascending, false for descending
      Returns:
      a new stream with specified additional ordering
      Throws:
      IllegalArgumentException - if attribute is null

    • thenOrderBy

      SearchStream<X,S> thenOrderBy(Ref<?,? extends Expression<?>> ref, boolean asc)
      Order results using the specified expression reference after existing sort.

      Adds to any existing sort ordering.

      Parameters:
      ref - previously bound expression reference
      asc - true for ascending, false for descending
      Returns:
      a new stream with specified additional ordering
      Throws:
      IllegalArgumentException - if ref is null

    • thenOrderBy

      SearchStream<X,S> thenOrderBy(Order... orders)
      Order results using the specified Orders after existing sort.

      Adds to any existing sort ordering.

      Parameters:
      orders - ordering(s), with higher precedence orderings first
      Returns:
      a new stream with specified additional ordering(s)
      Throws:
      IllegalArgumentException - if orders is null

    • thenOrderBy

      SearchStream<X,S> thenOrderBy(Function<? super S,? extends Expression<?>> orderExprFunction, boolean asc)
      Order results using the Expression produced by the given Function after existing sort.

      Adds to any existing sort ordering.

      Parameters:
      orderExprFunction - Function that produces an Expression to order on given an item expression
      asc - true for ascending, false for descending
      Returns:
      a new stream with specified additional ordering
      Throws:
      IllegalArgumentException - if orderExprFunction is null

    • groupBy

      SearchStream<X,S> groupBy(Ref<?,? extends Expression<?>> ref)
      Apply grouping based on an expression reference.

      Adds to any previously specified groupings.

      Parameters:
      ref - previously bound expression reference
      Returns:
      a new stream with additional grouping
      Throws:
      IllegalArgumentException - if ref is null

    • groupBy

      SearchStream<X,S> groupBy(SingularAttribute<? super X,?> attribute)
      Apply grouping based on the specified property.

      Adds to any previously specified groupings.

      Parameters:
      attribute - associated property
      Returns:
      a new stream with additional grouping
      Throws:
      IllegalArgumentException - if attribute is null

    • groupBy

      SearchStream<X,S> groupBy(Function<? super S,? extends Expression<?>> groupFunction)
      Apply grouping based on a single expression.

      Adds to any previously specified groupings.

      Parameters:
      groupFunction - function returning an expression by which to group results
      Returns:
      a new stream with additional grouping
      Throws:
      IllegalArgumentException - if groupFunction is null

    • groupByMulti

      SearchStream<X,S> groupByMulti(Function<? super S,? extends List<Expression<?>>> groupFunction)
      Apply grouping based on a list of expressions.

      Adds to any previously specified groupings.

      Parameters:
      groupFunction - function returning a list of expressions by which to group results
      Returns:
      a new instance
      Throws:
      IllegalArgumentException - if groupFunction is null

    • having

      SearchStream<X,S> having(Function<? super S,? extends Expression<Boolean>> havingFunction)
      Add a "having" restriction.

      Adds to any previously specified "having" restrictions.

      Parameters:
      havingFunction - function returning a test to apply to grouped results
      Returns:
      a new instance
      Throws:
      IllegalArgumentException - if havingFunction is null

    • allMatch

      boolean allMatch(SingularAttribute<? super X,Boolean> attribute)
      Execute this query and return true if the given property is true for every resulting item.

      Delegates to TypedQuery.getResultStream() and can throw any exception thrown by that method.

      Parameters:
      attribute - boolean property
      Returns:
      true if all results have the given property true

    • allMatch

      boolean allMatch(Function<? super S,? extends Expression<Boolean>> predicateBuilder)
      Execute this query and return true if the predicate returned by the given function is true for every resulting item.

      Delegates to TypedQuery.getResultStream() and can throw any exception thrown by that method.

      Parameters:
      predicateBuilder - function mapping this stream's item to a boolean Expression
      Returns:
      true if all results have the computed expression true

    • anyMatch

      boolean anyMatch(SingularAttribute<? super X,Boolean> attribute)
      Execute this query and return true if any results are found for which the given property is true.

      Delegates to TypedQuery.getResultStream() and can throw any exception thrown by that method.

      Parameters:
      attribute - boolean property
      Returns:
      true if one or more results have the given property true

    • anyMatch

      boolean anyMatch(Function<? super S,? extends Expression<Boolean>> predicateBuilder)
      Execute this query and return true if any results are found for which the predicate returned by the given function is true.

      Delegates to TypedQuery.getResultStream() and can throw any exception thrown by that method.

      Parameters:
      predicateBuilder - function mapping this stream's item to a boolean Expression
      Returns:
      true if one or more results have the computed expression true

    • noneMatch

      boolean noneMatch(SingularAttribute<? super X,Boolean> attribute)
      Execute this query and return true if no results are found for which the given property is true.

      Delegates to TypedQuery.getResultStream() and can throw any exception thrown by that method.

      Parameters:
      attribute - boolean property
      Returns:
      true if no results have the given property true

    • noneMatch

      boolean noneMatch(Function<? super S,? extends Expression<Boolean>> predicateBuilder)
      Execute this query and return true if no result are found for which the predicate returned by the given function is true.

      Delegates to TypedQuery.getResultStream() and can throw any exception thrown by that method.

      Parameters:
      predicateBuilder - function mapping this stream's item to a boolean Expression
      Returns:
      true if no results have the computed expression true

    • isEmpty

      boolean isEmpty()
      Execute this query and return true if no results are found.

      Note: to perform an "exists" operation in a subquery, use ExprStream.exists().

      Delegates to TypedQuery.getResultStream() and can throw any exception thrown by that method.

      Returns:
      true if no results are found, false if one or more results are found
      See Also:

    • findAny

      SearchValue<X,S> findAny()
      Find any instance in the stream.
      Returns:
      single-valued stream containg any instance in this stream (or NULL if this stream is empty)

    • findFirst

      SearchValue<X,S> findFirst()
      Find the first instance in the stream.
      Returns:
      single-valued stream containg the first instance in this stream (or NULL if this stream is empty)

    • findSingle

      SearchValue<X,S> findSingle()
      Find the only instance in the stream or null.

      Invoke this method only when you know that the result stream contains at most one value, e.g., when searching for an object by its value in a field with a unique constraint. If the stream actually contains multiple values, then invoking any of the "single value" SearchValue methods such as value() or toOptional() will generate a NonUniqueResultException.

      Using this method is preferable to using findFirst() or findAny() for the same purpose, because it not only actually verifies the uniqueness assumption, but it also makes that assumption clearer in the code.

      Example: 

        final User user = qb.stream(User.class)
    .filter(u -> qb.equal(u.get(User_.username), username))
    .findSingle()
    .orElseThrow(NoSuchUserException::new);
      Returns:
      a single value, either the only instance in this stream or null if this stream is empty

    • addRoot

      <R> SearchStream<X,S> addRoot(Ref<R,? super Root<R>> ref, Class<R> type)
      Bind an unbound reference to a new query root that will be added to the query.

      To select the new root in a SearchStream, use SearchStream.map(), providing a Function that returns ref.

      Note that this effectively creates an unconstrained (cross product) join with the new root. Typically there would be some additional restrictions imposed (e.g., via filter()) to relate the new root to the items in the stream.

      Type Parameters:
      R - type of the new query root
      Parameters:
      ref - unbound reference
      type - type of the new query root
      Returns:
      new stream that binds ref to a new query root from type
      Throws:
      IllegalArgumentException - if ref is already bound
      IllegalArgumentException - if type or ref is null

    • map

      default <Y> PathStream<Y,Path<Y>> map(SingularAttribute<? super X,Y> attribute)
      Map this stream to an associated property.

      Unlike join(), this method allows mapping to arbitrary, non-entity properties.

      If the property is an entity, then this method works just like an inner join(). In particular, the associated entity must exist. For that reason, and also because join() returns the more specific type FromStream, join() is preferred over this method when the associated property is an entity.

      Type Parameters:
      Y - property type
      Parameters:
      attribute - associated property
      Returns:
      mapped stream

    • map

      default <Y> ExprStream<Y,Expression<Y>> map(Class<Y> type, Function<? super S,? extends Expression<Y>> exprFunction)
      Map this stream into a stream whose elements are the result of applying the given function.
      Type Parameters:
      Y - mapped expression type
      Parameters:
      type - new item type
      exprFunction - function mapping this stream's Expression to a Expression
      Returns:
      mapped stream

    • map

      default <E, C extends Collection<E>> ExprStream<C,Expression<C>> map(PluralAttribute<? super X,C,E> attribute)
      Map this stream to an associated collection property.
      Type Parameters:
      E - collection element type
      C - collection type
      Parameters:
      attribute - associated property
      Returns:
      mapped stream

    • map

      default <K, V, M extends Map<K, V>> ExprStream<M,Expression<M>> map(MapAttribute<? super X,K,V> attribute)
      Map this stream to an associated map property.
      Type Parameters:
      K - map key type
      V - map value type
      M - map type
      Parameters:
      attribute - associated property
      Returns:
      mapped stream

    • mapToExpr

      default <Y> ExprStream<Y,Expression<Y>> mapToExpr(Class<Y> type, Function<? super S,? extends Expression<Y>> exprFunction)
      Map this stream into a stream whose elements are the result of applying the given function.
      Type Parameters:
      Y - mapped target type
      Parameters:
      type - new item type
      exprFunction - function mapping this stream's Selection to an Expression
      Returns:
      mapped stream

    • mapToPath

      default <Y> PathStream<Y,Path<Y>> mapToPath(Class<Y> type, Function<? super S,? extends Path<Y>> pathFunction)
      Map this stream into a stream whose elements are the result of applying the given function.
      Type Parameters:
      Y - mapped expresssion type
      Parameters:
      type - new item type
      pathFunction - function mapping this stream's Selection to a Path
      Returns:
      mapped stream

    • mapToFrom

      default <Z, Y> FromStream<Y,From<Z,Y>> mapToFrom(Class<Y> type, Function<? super S,? extends From<Z,Y>> fromFunction)
      Map this stream into a stream whose elements are the result of applying the given function.
      Type Parameters:
      Z - mapped source type
      Y - mapped target type
      Parameters:
      type - new item type
      fromFunction - function mapping this stream's Selection to a From
      Returns:
      mapped stream

    • mapToRoot

      default <Y> RootStream<Y> mapToRoot(Class<Y> type, Function<? super S,? extends Root<Y>> rootFunction)
      Map this stream into a stream whose elements are the result of applying the given function.
      Type Parameters:
      Y - mapped target type
      Parameters:
      type - new item type
      rootFunction - function mapping this stream's Selection to a Root
      Returns:
      mapped stream

    • mapToRef

      default <Y> RootStream<Y> mapToRef(Class<Y> type, RootRef<Y> ref)
      Map this stream to a stream whose elements are bound to the supplied root reference.
      Type Parameters:
      Y - selection type
      Parameters:
      ref - previously bound root reference
      Returns:
      mapped stream

    • mapToRef

      default <Y> FromStream<Y,From<?,Y>> mapToRef(Class<Y> type, FromRef<Y> ref)
      Map this stream to a stream whose elements are bound to the supplied from reference.
      Type Parameters:
      Y - mapped target type
      Parameters:
      ref - previously bound from reference
      Returns:
      mapped stream

    • mapToRef

      default <Y> PathStream<Y,Path<Y>> mapToRef(Class<Y> type, PathRef<Y> ref)
      Map this stream to a stream whose elements are bound to the supplied path reference.
      Type Parameters:
      Y - mapped target type
      Parameters:
      ref - previously bound path reference
      Returns:
      mapped stream

    • mapToRef

      default <Y> ExprStream<Y,Expression<Y>> mapToRef(Class<Y> type, ExprRef<Y> ref)
      Map this stream to a stream whose elements are bound to the supplied expression reference.
      Type Parameters:
      Y - mapped target type
      Parameters:
      ref - previously bound expression reference
      Returns:
      mapped stream

    • mapToDouble

      default DoubleStream mapToDouble(SingularAttribute<? super X,? extends Number> attribute)
      Map this stream to an associated floating point value.
      Parameters:
      attribute - associated numerically-valued property
      Returns:
      mapped stream of doubles

    • mapToDouble

      default DoubleStream mapToDouble(Function<? super S,? extends Expression<? extends Number>> doubleExprFunction)
      Map this stream into a stream of double values that are the result of applying the given function.
      Parameters:
      doubleExprFunction - function mapping this stream's Expression to a numerical Expression
      Returns:
      mapped stream of doubles

    • mapToLong

      default LongStream mapToLong(SingularAttribute<? super X,? extends Number> attribute)
      Map this stream to an associated long value.
      Parameters:
      attribute - associated numerically-valued property
      Returns:
      mapped stream of longs

    • mapToLong

      default LongStream mapToLong(Function<? super S,? extends Expression<? extends Number>> longExprFunction)
      Map this stream into a stream of long values that are the result of applying the given function.
      Parameters:
      longExprFunction - function mapping this stream's Expression to a numerical Expression
      Returns:
      mapped stream of longs

    • mapToInt

      default IntStream mapToInt(SingularAttribute<? super X,? extends Number> attribute)
      Map this stream to an associated integer value.
      Parameters:
      attribute - associated numerically-valued property
      Returns:
      mapped stream of integers

    • mapToInt

      default IntStream mapToInt(Function<? super S,? extends Expression<? extends Number>> intExprFunction)
      Map this stream into a stream of integer values that are the result of applying the given function.
      Parameters:
      intExprFunction - function mapping this stream's Expression to a numerical Expression
      Returns:
      mapped stream of integers

    • mapToSelection

      default <Y> SearchStream<Y,Selection<Y>> mapToSelection(Class<Y> type, Function<? super S,? extends Selection<Y>> selectionFunction)
      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.

      Type Parameters:
      Y - selection type
      Parameters:
      type - selection type
      selectionFunction - function to build selection
      Returns:
      mapped stream

    • flatMap

      default <E> FromStream<E,CollectionJoin<X,E>> flatMap(CollectionAttribute<? super X,E> attribute)
      Map this stream to a stream where every item is replaced with the contents of the specified collection.
      Type Parameters:
      E - collection element type
      Parameters:
      attribute - associated collection property
      Returns:
      mapped stream

    • flatMap

      default <E> FromStream<E,ListJoin<X,E>> flatMap(ListAttribute<? super X,E> attribute)
      Map this stream to a stream where every item is replaced with the contents of the specified collection.
      Type Parameters:
      E - list element type
      Parameters:
      attribute - associated collection property
      Returns:
      mapped stream

    • flatMap

      default <E> FromStream<E,SetJoin<X,E>> flatMap(SetAttribute<? super X,E> attribute)
      Map this stream to a stream where every item is replaced with the contents of the specified collection.
      Type Parameters:
      E - set element type
      Parameters:
      attribute - associated collection property
      Returns:
      mapped stream

    • flatMapKeys

      default <K> PathStream<K,Path<K>> flatMapKeys(MapAttribute<? super X,K,?> attribute)
      Map this stream to a stream where every item is replaced with the keys of the specified map.
      Type Parameters:
      K - map key type
      Parameters:
      attribute - associated map property
      Returns:
      mapped stream

    • flatMapValues

      default <V> PathStream<V,Path<V>> flatMapValues(MapAttribute<? super X,?,V> attribute)
      Map this stream to a stream where every item is replaced with the values of the specified map.
      Type Parameters:
      V - map value type
      Parameters:
      attribute - associated map property
      Returns:
      mapped stream

    • join

      default <Y> FromStream<Y,From<X,Y>> join(SingularAttribute<? super X,Y> attribute)
      Add a singular inner join to this stream.

      Equivalent to join(attribute, JoinType.INNER).

      Type Parameters:
      Y - associated property type
      Parameters:
      attribute - associated property
      Returns:
      a new stream with specified join
      Throws:
      IllegalArgumentException - if attribute is null

    • join

      default <Y> FromStream<Y,From<X,Y>> join(SingularAttribute<? super X,Y> attribute, JoinType joinType)
      Add a singular join to this stream using the specified join type.

      Equivalent to join(attribute, JoinType.INNER, join -> null).

      Type Parameters:
      Y - associated property type
      Parameters:
      attribute - associated property
      joinType - type of join
      Returns:
      a new stream with specified join
      Throws:
      IllegalArgumentException - if either parameter is null

    • join

      default <Y> FromStream<Y,From<X,Y>> join(SingularAttribute<? super X,Y> attribute, JoinType joinType, Function<? super Join<X,Y>,? extends Expression<Boolean>> on)
      Add a singular join to this stream using the specified join type and ON condition.
      Type Parameters:
      Y - associated property type
      Parameters:
      attribute - associated property
      joinType - type of join
      on - function returning a join ON condition, or returning null for none
      Returns:
      a new stream with specified join
      Throws:
      IllegalArgumentException - if any parameter is null

    • join

      default <E> FromStream<E,CollectionJoin<X,E>> join(CollectionAttribute<? super X,E> attribute)
      Add a collection inner join to this stream.

      Equivalent to join(attribute, JoinType.INNER).

      Type Parameters:
      E - collection element type
      Parameters:
      attribute - associated property
      Returns:
      a new stream with specified join
      Throws:
      IllegalArgumentException - if attribute is null

    • join

      default <E> FromStream<E,CollectionJoin<X,E>> join(CollectionAttribute<? super X,E> attribute, JoinType joinType)
      Add a collection join to this stream using the specified join type.

      Equivalent to join(attribute, JoinType.INNER, join -> null).

      Type Parameters:
      E - collection element type
      Parameters:
      attribute - associated property
      joinType - type of join
      Returns:
      a new stream with specified join
      Throws:
      IllegalArgumentException - if either parameter is null

    • join

      default <E> FromStream<E,CollectionJoin<X,E>> join(CollectionAttribute<? super X,E> attribute, JoinType joinType, Function<? super CollectionJoin<X,E>,? extends Expression<Boolean>> on)
      Add a collection join to this stream using the specified join type and ON condition.
      Type Parameters:
      E - collection element type
      Parameters:
      attribute - associated property
      joinType - type of join
      on - function returning a join ON condition, or returning null for none
      Returns:
      a new stream with specified join
      Throws:
      IllegalArgumentException - if any parameter is null

    • join

      default <E> FromStream<E,ListJoin<X,E>> join(ListAttribute<? super X,E> attribute)
      Add a list inner join to this stream.

      Equivalent to join(attribute, JoinType.INNER).

      Type Parameters:
      E - list element type
      Parameters:
      attribute - associated property
      Returns:
      a new stream with specified join
      Throws:
      IllegalArgumentException - if attribute is null

    • join

      default <E> FromStream<E,ListJoin<X,E>> join(ListAttribute<? super X,E> attribute, JoinType joinType)
      Add a list join to this stream using the specified join type.

      Equivalent to join(attribute, JoinType.INNER, join -> null).

      Type Parameters:
      E - list element type
      Parameters:
      attribute - associated property
      joinType - type of join
      Returns:
      a new stream with specified join
      Throws:
      IllegalArgumentException - if either parameter is null

    • join

      default <E> FromStream<E,ListJoin<X,E>> join(ListAttribute<? super X,E> attribute, JoinType joinType, Function<? super ListJoin<X,E>,? extends Expression<Boolean>> on)
      Add a list join to this stream using the specified join type and ON condition.
      Type Parameters:
      E - list element type
      Parameters:
      attribute - associated property
      joinType - type of join
      on - function returning a join ON condition, or returning null for none
      Returns:
      a new stream with specified join
      Throws:
      IllegalArgumentException - if any parameter is null

    • join

      default <E> FromStream<E,SetJoin<X,E>> join(SetAttribute<? super X,E> attribute)
      Add a set inner join to this stream.

      Equivalent to join(attribute, JoinType.INNER).

      Type Parameters:
      E - set element type
      Parameters:
      attribute - associated property
      Returns:
      a new stream with specified join
      Throws:
      IllegalArgumentException - if attribute is null

    • join

      default <E> FromStream<E,SetJoin<X,E>> join(SetAttribute<? super X,E> attribute, JoinType joinType)
      Add a set join to this stream using the specified join type.

      Equivalent to join(attribute, JoinType.INNER, join -> null).

      Type Parameters:
      E - set element type
      Parameters:
      attribute - associated property
      joinType - type of join
      Returns:
      a new stream with specified join
      Throws:
      IllegalArgumentException - if either parameter is null

    • join

      default <E> FromStream<E,SetJoin<X,E>> join(SetAttribute<? super X,E> attribute, JoinType joinType, Function<? super SetJoin<X,E>,? extends Expression<Boolean>> on)
      Add a set join to this stream using the specified join type and ON condition.
      Type Parameters:
      E - set element type
      Parameters:
      attribute - associated property
      joinType - type of join
      on - function returning a join ON condition, or returning null for none
      Returns:
      a new stream with specified join
      Throws:
      IllegalArgumentException - if any parameter is null

    • join

      default <K, V> FromStream<V,MapJoin<X,K,V>> join(MapAttribute<? super X,K,V> attribute)
      Add a map inner join to this stream.

      Equivalent to join(attribute, JoinType.INNER).

      Type Parameters:
      K - map key type
      V - map value type
      Parameters:
      attribute - associated property
      Returns:
      a new stream with specified join
      Throws:
      IllegalArgumentException - if attribute is null

    • join

      default <K, V> FromStream<V,MapJoin<X,K,V>> join(MapAttribute<? super X,K,V> attribute, JoinType joinType)
      Add a map join to this stream using the specified join type.

      Equivalent to join(attribute, JoinType.INNER, join -> null).

      Type Parameters:
      K - map key type
      V - map value type
      Parameters:
      attribute - associated property
      joinType - type of join
      Returns:
      a new stream with specified join
      Throws:
      IllegalArgumentException - if either parameter is null

    • join

      default <K, V> FromStream<V,MapJoin<X,K,V>> join(MapAttribute<? super X,K,V> attribute, JoinType joinType, Function<? super MapJoin<X,K,V>,? extends Expression<Boolean>> on)
      Add a map join to this stream using the specified join type and ON condition.
      Type Parameters:
      K - map key type
      V - map value type
      Parameters:
      attribute - associated property
      joinType - type of join
      on - function returning a join ON condition, or returning null for none
      Returns:
      a new stream with specified join
      Throws:
      IllegalArgumentException - if any parameter is null

    • fetch

      SearchStream<X,S> fetch(SingularAttribute<? super X,?> attribute)
      Add a singular fetch inner join to this stream.

      Equivalent to fetch(attribute, JoinType.INNER).

      Parameters:
      attribute - associated property
      Returns:
      a new stream with specified inner fetch join
      Throws:
      IllegalArgumentException - if attribute is null

    • fetch

      SearchStream<X,S> fetch(SingularAttribute<? super X,?> attribute, JoinType joinType)
      Add a singular fetch join to this stream.

      Unlike join(), this method does not change the stream's content type. In other words, this method is used simply to pre-fetch an association, to avoid having to fetch it again later for each individual element in the stream.

      Parameters:
      attribute - associated property
      joinType - join type
      Returns:
      a new stream with specified fetch join
      Throws:
      IllegalArgumentException - if either parameter is null

    • fetch

      SearchStream<X,S> fetch(PluralAttribute<? super X,?,?> attribute)
      Add a plural fetch join to this stream.

      Equivalent to fetch(attribute, JoinType.INNER).

      Parameters:
      attribute - associated property
      Returns:
      a new stream with specified inner fetch join
      Throws:
      IllegalArgumentException - if attribute is null

    • fetch

      SearchStream<X,S> fetch(PluralAttribute<? super X,?,?> attribute, JoinType joinType)
      Add a plural fetch join to this stream.

      Unlike join(), this method does not change the stream's content type. In other words, this method is used simply to pre-fetch an association, to avoid having to fetch it again later for each individual element in the stream.

      Parameters:
      attribute - associated property
      joinType - join type
      Returns:
      a new stream with specified fetch join
      Throws:
      IllegalArgumentException - if either parameter is null

    • getQueryType

      SearchType<X> getQueryType()
      Description copied from interface: QueryStream
      Get the QueryType of this instance.
      Specified by:
      getQueryType in interface QueryStream<X,S extends Selection<X>,AbstractQuery<?>,CriteriaQuery<X>,TypedQuery<X>>
      Returns:
      associated QueryType

    • bind

      SearchStream<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 Selection<X>,AbstractQuery<?>,CriteriaQuery<X>,TypedQuery<X>>
      Parameters:
      ref - unbound reference
      Returns:
      new stream that binds ref

    • peek

      SearchStream<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 Selection<X>,AbstractQuery<?>,CriteriaQuery<X>,TypedQuery<X>>
      Parameters:
      peeker - peeker into stream
      Returns:
      new stream that peeks into this stream

    • bind

      <X2, S2 extends Selection<X2>> SearchStream<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 Selection<X>,AbstractQuery<?>,CriteriaQuery<X>,TypedQuery<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

      SearchStream<X,S> filter(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 Selection<X>,AbstractQuery<?>,CriteriaQuery<X>,TypedQuery<X>>
      Parameters:
      attribute - boolean property
      Returns:
      new filtered stream

    • filter

      SearchStream<X,S> filter(Function<? super S,? extends 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 Selection<X>,AbstractQuery<?>,CriteriaQuery<X>,TypedQuery<X>>
      Parameters:
      predicateBuilder - function mapping this stream's item to a boolean Expression
      Returns:
      new filtered stream

    • limit

      SearchStream<X,S> limit(int maxSize)
      Description copied from interface: QueryStream
      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.).

      Specified by:
      limit in interface QueryStream<X,S extends Selection<X>,AbstractQuery<?>,CriteriaQuery<X>,TypedQuery<X>>
      Parameters:
      maxSize - maximum number of elements to return
      Returns:
      new truncated stream

    • skip

      SearchStream<X,S> skip(int num)
      Description copied from interface: QueryStream
      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.).

      Specified by:
      skip in interface QueryStream<X,S extends Selection<X>,AbstractQuery<?>,CriteriaQuery<X>,TypedQuery<X>>
      Parameters:
      num - number of elements to skip
      Returns:
      new elided stream

    • withFlushMode

      SearchStream<X,S> withFlushMode(FlushModeType flushMode)
      Description copied from interface: QueryStream
      Set the FlushModeType associated with this query.
      Specified by:
      withFlushMode in interface QueryStream<X,S extends Selection<X>,AbstractQuery<?>,CriteriaQuery<X>,TypedQuery<X>>
      Parameters:
      flushMode - new flush mode
      Returns:
      new stream with the specified flush mode configured
      See Also:

    • withLockMode

      SearchStream<X,S> withLockMode(LockModeType lockMode)
      Description copied from interface: QueryStream
      Set the LockModeType associated with this query.
      Specified by:
      withLockMode in interface QueryStream<X,S extends Selection<X>,AbstractQuery<?>,CriteriaQuery<X>,TypedQuery<X>>
      Parameters:
      lockMode - new lock mode
      Returns:
      new stream with the specified lock mode configured
      See Also:

    • withHint

      SearchStream<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 Selection<X>,AbstractQuery<?>,CriteriaQuery<X>,TypedQuery<X>>
      Parameters:
      name - name of hint
      value - value of hint
      Returns:
      new stream with the specified hint configured
      See Also:

    • withHints

      SearchStream<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 Selection<X>,AbstractQuery<?>,CriteriaQuery<X>,TypedQuery<X>>
      Parameters:
      hints - hints to add
      Returns:
      new stream with the specified hints added
      See Also:

    • withParam

      <T> SearchStream<X,S> withParam(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 Selection<X>,AbstractQuery<?>,CriteriaQuery<X>,TypedQuery<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:

    • withParam

      SearchStream<X,S> withParam(Parameter<Date> parameter, Date value, 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 Selection<X>,AbstractQuery<?>,CriteriaQuery<X>,TypedQuery<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:

    • withParam

      SearchStream<X,S> withParam(Parameter<Calendar> parameter, Calendar value, 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 Selection<X>,AbstractQuery<?>,CriteriaQuery<X>,TypedQuery<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:

    • withParams

      SearchStream<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 Selection<X>,AbstractQuery<?>,CriteriaQuery<X>,TypedQuery<X>>
      Parameters:
      params - bindings to add
      Returns:
      new stream with the specified parameter bindings added
      See Also:

    • withLoadGraph

      SearchStream<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 Selection<X>,AbstractQuery<?>,CriteriaQuery<X>,TypedQuery<X>>
      Parameters:
      name - name of load graph
      Returns:
      new stream with the specified load graph configured

    • withFetchGraph

      SearchStream<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 Selection<X>,AbstractQuery<?>,CriteriaQuery<X>,TypedQuery<X>>
      Parameters:
      name - name of fetch graph
      Returns:
      new stream with the specified fetch graph configured