org.jinq.orm.stream

Interface JinqStream<T>

Type Parameters:

T - type of object that is being processed by the stream

All Superinterfaces:

java.lang.AutoCloseable, java.util.stream.BaseStream<T,java.util.stream.Stream<T>>, java.util.stream.Stream<T>

All Known Implementing Classes:

NonQueryJinqStream, QueryJinqStream

public interface JinqStream<T>
extends java.util.stream.Stream<T>

The JinqStream is a normal Java 8 stream extended with extra methods. These extra methods are needed because:

• They can be more easily analyzed by Jinq
• They provide extra functionality that more closely mirrors database query functionality
• They have names that are derived from database query syntax instead of names derived from functional programming syntax

Programmers typically get access to JinqStreams through a JinqStream provider. For example, the org.jinq.jpa.JinqJPAStreamProvider is able to create streams of JPA entities from a database. It is also possible to create JinqStreams from collections and single objects.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	JinqStream.AggregateGroup<W,U,V>
static interface	JinqStream.AggregateSelect<U,V>
static interface	JinqStream.CollectBigDecimal<U>
static interface	JinqStream.CollectBigInteger<U>
static interface	JinqStream.CollectComparable<U,V extends java.lang.Comparable<V>>
static interface	JinqStream.CollectDouble<U>
static interface	JinqStream.CollectInteger<U>
static interface	JinqStream.CollectLong<U>
static interface	JinqStream.CollectNumber<U,V extends java.lang.Number & java.lang.Comparable<V>>
static interface	JinqStream.Join<U,V>
static interface	JinqStream.JoinWithSource<U,V>
static interface	JinqStream.Select<U,V>
static interface	JinqStream.SelectWithSource<U,V>
static interface	JinqStream.Where<U,E extends java.lang.Exception>
static interface	JinqStream.WhereWithSource<U,E extends java.lang.Exception>

Nested classes/interfaces inherited from interface java.util.stream.Stream

java.util.stream.Stream.Builder<T>

Method Summary

Modifier and Type	Method and Description
<U,V> Pair<U,V>	aggregate(JinqStream.AggregateSelect<T,U> aggregate1, JinqStream.AggregateSelect<T,V> aggregate2) Calculates more than one aggregate function over the elements of the stream.
<U,V,W> Tuple3<U,V,W>	aggregate(JinqStream.AggregateSelect<T,U> aggregate1, JinqStream.AggregateSelect<T,V> aggregate2, JinqStream.AggregateSelect<T,W> aggregate3)
<U,V,W,X> Tuple4<U,V,W,X>	aggregate(JinqStream.AggregateSelect<T,U> aggregate1, JinqStream.AggregateSelect<T,V> aggregate2, JinqStream.AggregateSelect<T,W> aggregate3, JinqStream.AggregateSelect<T,X> aggregate4)
<U,V,W,X,Y> Tuple5<U,V,W,X,Y>	aggregate(JinqStream.AggregateSelect<T,U> aggregate1, JinqStream.AggregateSelect<T,V> aggregate2, JinqStream.AggregateSelect<T,W> aggregate3, JinqStream.AggregateSelect<T,X> aggregate4, JinqStream.AggregateSelect<T,Y> aggregate5)
<V extends java.lang.Number & java.lang.Comparable<V>> java.lang.Double	avg(JinqStream.CollectNumber<T,V> aggregate) Finds the average of the element of a stream.
long	count() Counts the elements in the stream.
JinqStream<T>	distinct()
static <U> JinqStream<U>	from(java.util.Collection<U> collection) Easy way to get a JinqStream from a collection.
java.lang.String	getDebugQueryString() Returns the query that Jinq will send to the database to generate the values of the stream.
java.util.Collection<java.lang.Throwable>	getExceptions() Deprecated.
T	getOnlyValue() If the stream contains only a single value, this method will return that value.
<U,V> JinqStream<Pair<U,V>>	group(JinqStream.Select<T,U> select, JinqStream.AggregateGroup<U,T,V> aggregate) Groups together elements from the stream that share a common key.
<U,V,W> JinqStream<Tuple3<U,V,W>>	group(JinqStream.Select<T,U> select, JinqStream.AggregateGroup<U,T,V> aggregate1, JinqStream.AggregateGroup<U,T,W> aggregate2) Calculates two aggregate values instead of one aggregate value for grouped stream elements.
<U,V,W,X> JinqStream<Tuple4<U,V,W,X>>	group(JinqStream.Select<T,U> select, JinqStream.AggregateGroup<U,T,V> aggregate1, JinqStream.AggregateGroup<U,T,W> aggregate2, JinqStream.AggregateGroup<U,T,X> aggregate3) Calculates three aggregate values instead of one aggregate value for grouped stream elements.
<U,V,W,X,Y> JinqStream<Tuple5<U,V,W,X,Y>>	group(JinqStream.Select<T,U> select, JinqStream.AggregateGroup<U,T,V> aggregate1, JinqStream.AggregateGroup<U,T,W> aggregate2, JinqStream.AggregateGroup<U,T,X> aggregate3, JinqStream.AggregateGroup<U,T,Y> aggregate4) Calculates four aggregate values instead of one aggregate value for grouped stream elements.
<U> JinqStream<Pair<T,U>>	join(JinqStream.Join<T,U> join) Pairs up each entry of the stream with a stream of related elements.
<U> JinqStream<Pair<T,U>>	join(JinqStream.JoinWithSource<T,U> join) Pairs up each entry of the stream with a stream of related elements.
<U> JinqStream<Pair<T,U>>	leftOuterJoin(JinqStream.Join<T,U> join) Pairs up each entry of the stream with a stream of related elements.
JinqStream<T>	limit(long n)
<V extends java.lang.Comparable<V>> V	max(JinqStream.CollectComparable<T,V> aggregate) Finds the largest or maximum element of a stream.
<V extends java.lang.Comparable<V>> V	min(JinqStream.CollectComparable<T,V> aggregate) Finds the smallest or minimum element of a stream.
static <U> JinqStream<U>	of(U value) Creates a JinqStream containing a single object.
void	propagateException(java.lang.Object source, java.lang.Throwable exception) Deprecated.
<U> JinqStream<U>	select(JinqStream.Select<T,U> select) Transforms the elements in the stream.
<U> JinqStream<U>	select(JinqStream.SelectWithSource<T,U> select) Transforms the elements in the stream.
JinqStream<T>	setHint(java.lang.String name, java.lang.Object value) Sets a hint on the stream for how the query should be executed
JinqStream<T>	skip(long n)
<V extends java.lang.Comparable<V>> JinqStream<T>	sortedBy(JinqStream.CollectComparable<T,V> sortField) Sorts the elements of a stream in ascending order based on the value returned.
<V extends java.lang.Comparable<V>> JinqStream<T>	sortedDescendingBy(JinqStream.CollectComparable<T,V> sortField) Sorts the elements of a stream in descending order based on the value returned.
java.math.BigDecimal	sumBigDecimal(JinqStream.CollectBigDecimal<T> aggregate)
java.math.BigInteger	sumBigInteger(JinqStream.CollectBigInteger<T> aggregate)
java.lang.Double	sumDouble(JinqStream.CollectDouble<T> aggregate)
java.lang.Long	sumInteger(JinqStream.CollectInteger<T> aggregate) Calculates a sum over the elements of a stream.
java.lang.Long	sumLong(JinqStream.CollectLong<T> aggregate)
java.util.List<T>	toList() Convenience method that collects the stream contents into a List.
<E extends java.lang.Exception> JinqStream<T>	where(JinqStream.Where<T,E> test) Filters the elements of the stream.
<E extends java.lang.Exception> JinqStream<T>	where(JinqStream.WhereWithSource<T,E> test) Filters the elements of the stream.

Methods inherited from interface java.util.stream.Stream

allMatch, anyMatch, builder, collect, collect, concat, empty, filter, findAny, findFirst, flatMap, flatMapToDouble, flatMapToInt, flatMapToLong, forEach, forEachOrdered, generate, iterate, map, mapToDouble, mapToInt, mapToLong, max, min, noneMatch, peek, reduce, reduce, reduce, sorted, sorted, toArray, toArray

Methods inherited from interface java.util.stream.BaseStream

close, isParallel, iterator, onClose, parallel, sequential, spliterator, unordered

Method Detail

where

<E extends java.lang.Exception> JinqStream<T> where(JinqStream.Where<T,E> test)

Filters the elements of the stream.

  JinqStream<Customer> stream = ...;
 JinqStream<Customer> result = stream.where(c -> c.getName().equals("Alice"));
 
 

Parameters:

test - function applied to the elements of the stream. When passed an element from the stream, the function should return true if the element should be kept. if the function returns false, the element is discarded.

Returns:

a new stream that returns only the elements satisfying the filter

where

<E extends java.lang.Exception> JinqStream<T> where(JinqStream.WhereWithSource<T,E> test)

Filters the elements of the stream. This version allows the filter function to take a second parameter with an InQueryStreamSource. This lets the function create new streams of elements that it can use in subqueries.

Parameters:

test - function applied to each element of the stream. The function is passed an element from the stream as well as an InQueryStreamSource. The function should return true if the element should be kept. if the function returns false, the element is discarded.

Returns:

a new stream that returns only the elements satisfying the filter

See Also:

where(Where)

select

<U> JinqStream<U> select(JinqStream.Select<T,U> select)

Transforms the elements in the stream. The method allows you to rewrite each element from the stream, so that they contain only certain fields or to do some calculation based on the values of the fields.

  JinqStream<Customer> stream = ...;
 JinqStream<String> result = stream.select(c -> c.getName());
 
 

Parameters:

select - function applied to the elements of the stream. When passed an element from the stream, the function should return a new value that should be used instead of the element in the stream.

Returns:

a new stream that uses only the new rewritten stream elements

select

<U> JinqStream<U> select(JinqStream.SelectWithSource<T,U> select)

Transforms the elements in the stream. This version also passes an InQueryStreamSource to the select function so that the function can create new streams of elements to use in subqueries.

See Also:

select(Select)

join

<U> JinqStream<Pair<T,U>> join(JinqStream.Join<T,U> join)

Pairs up each entry of the stream with a stream of related elements.

  JinqStream<Country> stream = ...;
 JinqStream<Pair<Country, City>> result = 
    stream.join(c -> JinqStream.from(c.getCities()));
 
 

Parameters:

join - function applied to the elements of the stream. When passed an element from the stream, the function should return a stream of values that should be paired up with that stream element.

Returns:

a new stream with the paired up elements

join

<U> JinqStream<Pair<T,U>> join(JinqStream.JoinWithSource<T,U> join)

Pairs up each entry of the stream with a stream of related elements. This version also passes an InQueryStreamSource to the join function so that the function can join elements with unrelated streams of entities from a database.

See Also:

join(Join)

leftOuterJoin

<U> JinqStream<Pair<T,U>> leftOuterJoin(JinqStream.Join<T,U> join)

Pairs up each entry of the stream with a stream of related elements. Uses a left outer join during the pairing up process, so even if an element is not joined with anything, a pair will still be created in the output stream consisting of the element paired with null.

  JinqStream<Country> stream = ...;
 JinqStream<Pair<Country, Mountain>> result = 
    stream.join(c -> JinqStream.from(c.getMountain()));
 JinqStream<Pair<Country, Mountain>> result = 
    stream.join(c -> JinqStream.of(c.getHighestMountain()));
 
 

Parameters:

join - function applied to the elements of the stream. When passed an element from the stream, the function should return a stream of values that should be paired up with that stream element. The function must use a JPA association or navigational link as the base for the stream returned. Both singular or plural associations are allowed.

Returns:

a new stream with the paired up elements

See Also:

join(Join)

group

<U,V> JinqStream<Pair<U,V>> group(JinqStream.Select<T,U> select,
                                  JinqStream.AggregateGroup<U,T,V> aggregate)

Groups together elements from the stream that share a common key. Aggregates can then be calculated over the elements in each group.

  JinqStream<City> stream = ...;
 JinqStream<Pair<String, Long>> result = 
    stream.group(c -> c.getCountry(), (key, cities) -> cities.count());
 
 

Parameters:

select - function applied to each element of the stream that returns the key to be used to group elements together

aggregate - function applied to each group and calculates an aggregate value over the group. The function is passed the key for the group and a JinqStream of elements contained inside that group. It should return the aggregate value calculated for that group.

Returns:

a new stream containing a tuple for each group. The tuple contains the key for the group and any calculated aggregate values.

group

<U,V,W> JinqStream<Tuple3<U,V,W>> group(JinqStream.Select<T,U> select,
                                        JinqStream.AggregateGroup<U,T,V> aggregate1,
                                        JinqStream.AggregateGroup<U,T,W> aggregate2)

Calculates two aggregate values instead of one aggregate value for grouped stream elements.

See Also:

group(Select, AggregateGroup)

group

<U,V,W,X> JinqStream<Tuple4<U,V,W,X>> group(JinqStream.Select<T,U> select,
                                            JinqStream.AggregateGroup<U,T,V> aggregate1,
                                            JinqStream.AggregateGroup<U,T,W> aggregate2,
                                            JinqStream.AggregateGroup<U,T,X> aggregate3)

Calculates three aggregate values instead of one aggregate value for grouped stream elements.

See Also:

group(Select, AggregateGroup)

group

<U,V,W,X,Y> JinqStream<Tuple5<U,V,W,X,Y>> group(JinqStream.Select<T,U> select,
                                                JinqStream.AggregateGroup<U,T,V> aggregate1,
                                                JinqStream.AggregateGroup<U,T,W> aggregate2,
                                                JinqStream.AggregateGroup<U,T,X> aggregate3,
                                                JinqStream.AggregateGroup<U,T,Y> aggregate4)

Calculates four aggregate values instead of one aggregate value for grouped stream elements.

See Also:

group(Select, AggregateGroup)

sumInteger

java.lang.Long sumInteger(JinqStream.CollectInteger<T> aggregate)

Calculates a sum over the elements of a stream. Different sum methods are provided for calculating the sum of integer, long, double, BigDecimal, and BigInteger values.

  JinqStream<City> stream = ...;
 long totalPopulation = stream.sumInteger(c -> c.getPopulation()); 
 
 

Parameters:

aggregate - function applied to each element of the stream. When passed an element of the stream, it should return the value that should be added to the sum.

Returns:

the sum of the values returned by the function

sumLong

java.lang.Long sumLong(JinqStream.CollectLong<T> aggregate)

See Also:

sumInteger(CollectInteger)

sumDouble

java.lang.Double sumDouble(JinqStream.CollectDouble<T> aggregate)

See Also:

sumInteger(CollectInteger)

sumBigDecimal

java.math.BigDecimal sumBigDecimal(JinqStream.CollectBigDecimal<T> aggregate)

See Also:

sumInteger(CollectInteger)

sumBigInteger

java.math.BigInteger sumBigInteger(JinqStream.CollectBigInteger<T> aggregate)

See Also:

sumInteger(CollectInteger)

max

<V extends java.lang.Comparable<V>> V max(JinqStream.CollectComparable<T,V> aggregate)

Finds the largest or maximum element of a stream.

  JinqStream<Student> stream = ...;
 Date birthdayOfYoungest = stream.max(s -> s.getBirthday()); 
 
 

Parameters:

aggregate - function applied to each element of the stream. When passed an element of the stream, it should return the value that should be compared.

Returns:

the maximum of the values returned by the function

min

<V extends java.lang.Comparable<V>> V min(JinqStream.CollectComparable<T,V> aggregate)

Finds the smallest or minimum element of a stream.

  JinqStream<Student> stream = ...;
 Date birthdayOfYoungest = stream.max(s -> s.getBirthday()); 
 
 

Parameters:

aggregate - function applied to each element of the stream. When passed an element of the stream, it should return the value that should be compared.

Returns:

the minimum of the values returned by the function

See Also:

max(CollectComparable)

avg

<V extends java.lang.Number & java.lang.Comparable<V>> java.lang.Double avg(JinqStream.CollectNumber<T,V> aggregate)

Finds the average of the element of a stream.

  JinqStream<Student> stream = ...;
 double averageAge = stream.avg(s -> s.getage()); 
 
 

Parameters:

aggregate - function applied to each element of the stream. When passed an element of the stream, it should return the value that should be included in the average

Returns:

the average of the values returned by the function

aggregate

<U,V> Pair<U,V> aggregate(JinqStream.AggregateSelect<T,U> aggregate1,
                          JinqStream.AggregateSelect<T,V> aggregate2)

Calculates more than one aggregate function over the elements of the stream.

  JinqStream<City> stream = ...;
 Pair<Long, Long> result = stream.aggregate(
    c -> c.sumInteger(c.getPopulation()),
    c -> c.count()); 
 
 

Parameters:

aggregate1 - a function that takes a stream and returns the first calculated aggregate value for the stream

aggregate2 - a function that takes a stream and returns a second calculated aggregate value for the stream

Returns:

a tuple of the calculated aggregate values

aggregate

<U,V,W> Tuple3<U,V,W> aggregate(JinqStream.AggregateSelect<T,U> aggregate1,
                                JinqStream.AggregateSelect<T,V> aggregate2,
                                JinqStream.AggregateSelect<T,W> aggregate3)

See Also:

aggregate(AggregateSelect, AggregateSelect)

aggregate

<U,V,W,X> Tuple4<U,V,W,X> aggregate(JinqStream.AggregateSelect<T,U> aggregate1,
                                    JinqStream.AggregateSelect<T,V> aggregate2,
                                    JinqStream.AggregateSelect<T,W> aggregate3,
                                    JinqStream.AggregateSelect<T,X> aggregate4)

See Also:

aggregate(AggregateSelect, AggregateSelect)

aggregate

<U,V,W,X,Y> Tuple5<U,V,W,X,Y> aggregate(JinqStream.AggregateSelect<T,U> aggregate1,
                                        JinqStream.AggregateSelect<T,V> aggregate2,
                                        JinqStream.AggregateSelect<T,W> aggregate3,
                                        JinqStream.AggregateSelect<T,X> aggregate4,
                                        JinqStream.AggregateSelect<T,Y> aggregate5)

See Also:

aggregate(AggregateSelect, AggregateSelect)

sortedBy

<V extends java.lang.Comparable<V>> JinqStream<T> sortedBy(JinqStream.CollectComparable<T,V> sortField)

Sorts the elements of a stream in ascending order based on the value returned. The sort is stable, so it is possible to sort the stream multiple times in order to have multiple sort keys. The last sort becomes the primary sort key, and earlier sorts become lesser keys.

Parameters:

sortField - function applied to each element of the stream. When passed an element of the stream, it should return the value that should be used as the sorting value of the element

Returns:

sorted stream

sortedDescendingBy

<V extends java.lang.Comparable<V>> JinqStream<T> sortedDescendingBy(JinqStream.CollectComparable<T,V> sortField)

Sorts the elements of a stream in descending order based on the value returned.

Parameters:

sortField - function applied to each element of the stream. When passed an element of the stream, it should return the value that should be used as the sorting value of the element

Returns:

sorted stream

See Also:

sortedBy(CollectComparable)

skip

JinqStream<T> skip(long n)

Specified by:

skip in interface java.util.stream.Stream<T>

limit

JinqStream<T> limit(long n)

Specified by:

limit in interface java.util.stream.Stream<T>

distinct

JinqStream<T> distinct()

Specified by:

distinct in interface java.util.stream.Stream<T>

count

long count()

Counts the elements in the stream. If the stream contains only a single field of data (i.e. not a tuple) as derived from a database query, then the count will be of non-NULL elements only. If the stream contains more than one field of data (i.e. a tuple) or if the stream is streaming in-memory data, then the count will include NULL values.

Specified by:

count in interface java.util.stream.Stream<T>

See Also:

Stream.count()

getOnlyValue

T getOnlyValue()

If the stream contains only a single value, this method will return that value. This method is convenient for getting the results of queries that contain only a single value. It is also useful in subqueries.

Returns:

the single element contained in the stream

Throws:

java.util.NoSuchElementException - stream contains zero or more than one element

toList

java.util.List<T> toList()

Convenience method that collects the stream contents into a List.

Returns:

a list of all the elements from the stream

getDebugQueryString

java.lang.String getDebugQueryString()

Returns the query that Jinq will send to the database to generate the values of the stream.

Returns:

the database query string or null if Jinq cannot find a database query equivalent to the contents of the stream.

propagateException

@Deprecated
void propagateException(java.lang.Object source,
                                    java.lang.Throwable exception)

Deprecated.

Used for recording an exception that occurred during processing somewhere in the stream chain.

Parameters:

source - lambda object that caused the exception (used so that if the same lambda causes multiple exceptions, only some of them need to be recorded in order to avoid memory issues)

exception - actual exception object

getExceptions

@Deprecated
java.util.Collection<java.lang.Throwable> getExceptions()

Deprecated.

setHint

JinqStream<T> setHint(java.lang.String name,
                      java.lang.Object value)

Sets a hint on the stream for how the query should be executed

Parameters:

name - name of the hint to change

value - value to assign to the hint

Returns:

a pointer to the stream, to make it easier to chain method calls on the stream

from

static <U> JinqStream<U> from(java.util.Collection<U> collection)

Easy way to get a JinqStream from a collection.

of

static <U> JinqStream<U> of(U value)

Creates a JinqStream containing a single object.

Specified by:

of in interface java.util.stream.Stream<T>