Package 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.

    • 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

      • selectAll

        <U> JinqStream<U> selectAll​(JinqStream.Join<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. Unlike a normal select(), this method allows you to return a stream of elements. The stream elements will all be added to the final stream. 
         JinqStream<Country> stream = ...;
 JinqStream<City> result = stream.selectAll(c -> JinqStream.from(c.getCities()));
        Parameters:
        select - function applied to the elements of the stream. When passed an element from the stream, the function should return a stream of new values that will be flattened and placed in the new stream
        Returns:
        a new stream that uses only the new rewritten stream elements
        See Also:
        select(Select)

      • selectAllList

        <U> JinqStream<U> selectAllList​(JinqStream.JoinToIterable<T,​U> select)
        A variant of selectAll() that can be used if you want to join to a collection without the trouble of converting it to a JinqStream first. 
         JinqStream<Country> stream = ...;
 JinqStream<City> result = stream.selectAll(c -> c.getCities());
        Parameters:
        select - function applied to the elements of the stream. When passed an element from the stream, the function should return a collection of new values that will be flattened and placed in the new stream
        Returns:
        a new stream that uses only the new rewritten stream elements
        See Also:
        selectAll(Join)

      • 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

      • 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.leftOuterJoin(c -> JinqStream.from(c.getMountain()));
 JinqStream<Pair<Country, Mountain>> result = 
    stream.leftOuterJoin(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)

      • leftOuterJoin

        <U> JinqStream<Pair<T,​U>> leftOuterJoin​(JinqStream.JoinWithSource<T,​U> join,
                                              JinqStream.WhereForOn<T,​U> on)
        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. 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 and an ON clause can be specified that will determine which elements from the two streams will be joined together. 
         JinqStream<Country> stream = ...;
 JinqStream<Pair<Country, Mountain>> result = 
    stream.leftOuterJoin(
            (c, source) -> source.stream(Mountain.class), 
            (country, mountain) -> country.getName().equals(mountain.getCountry()));
        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.
        on - this is a comparison function that returns true if the elements from the two streams should be joined together. It is similar to a standard where() clause except that the elements from the two streams are passed in as separate parameters for convenience (as opposed to being passed in as a pair)
        Returns:
        a new stream with the paired up elements
        See Also:
        leftOuterJoin(Join)

      • crossJoin

        <U> JinqStream<Pair<T,​U>> crossJoin​(JinqStream<U> join)
        Performs a full cross-join of the elements of two streams.
        Parameters:
        join - other stream to perform the cross join with
        Returns:
        a new stream where each element of the stream is paired up with each element of the join stream

      • 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.

      • 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

      • 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 birthdayOfOldest = stream.min(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 elements 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

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

      • findOne

        java.util.Optional<T> findOne()
        A convenience method for getting the contents of a stream when it contains 0 or 1 values. If the stream contains more than one value, an exception will be thrown. It cannot be used in subqueries.
        Returns:
        an Optional with the single element contained in the stream or an empty Optional if the stream is empty
        Throws:
        java.util.NoSuchElementException - stream contains more than one element
        See Also:
        Stream.findFirst()

      • findFirst

        default java.util.Optional<T> findFirst()
        A convenience method for limiting the stream to one element and then returning that element as an Optional. It cannot be used in subqueries.
        Specified by:
        findFirst in interface java.util.stream.Stream<T>
        See Also:
        Stream.findFirst()

      • exists

        default boolean exists()
        This method checks if a query/stream returns any results or not. It is supposed to be used for generating EXISTS subqueries in larger queries, but a default implementation is provided in case the method is used outside of that context.

      • 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.