Package org.jdbi.v3.core.result

Interface ResultIterable<T>

Type Parameters:

T - iterable element type

All Superinterfaces:

Iterable<T>

All Known Subinterfaces:

BatchResultIterable<T>

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface ResultIterable<T>
extends Iterable<T>

An Iterable of values, usually mapped from a ResultSet. Generally, ResultIterables may only be traversed once.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	ResultIterable.ResultIteratorDelegate<T,R>	An implementation of ResultIterator that delegates calls to the iterator provided in the constructor.

Method Summary

Modifier and Type	Method	Description
default <R> R	collect(Collector<? super T,?,R> collector)	Collect the results into a container specified by a collector.
default <R extends Collection<? super T>> R	collectInto(Type containerType)	Collect the results into a container type.
default <R extends Collection<? super T>> R	collectInto(GenericType<R> containerType)	Collect the results into a collection type.
default List<T>	collectIntoList()	Returns results in a List.
default Set<T>	collectIntoSet()	Returns results in a Set.
default <K, V> Map<K,V>	collectToMap(Function<? super T,? extends K> keyFunction, Function<? super T,? extends V> valueFunction)	Collect the results into a Map, using the given functions to compute keys and values.
default ResultIterable<T>	filter(Predicate<? super T> predicate)	Convenience method to filter the ResultIterable by applying the specified Predicate. This method has the look and feel of Stream.filter(Predicate) without making use of streams.
default Optional<T>	findFirst()	Returns the first row in the result set, if present.
default Optional<T>	findOne()	Returns the only row in the result set, if any.
default T	findOnly()	Deprecated. use one() or findOne() instead.
default T	first()	Returns the first row in the result set.
default void	forEach(Consumer<? super T> action)
default int	forEachWithCount(Consumer<? super T> action)	Performs the specified action on each remaining element and returns the iteration i.e.
ResultIterator<T>	iterator()	Stream all the rows of the result set out with an Iterator.
default List<T>	list()	Returns results in a List using the JDK specific default implementation of List as provided by Collectors.toList().
default <R> ResultIterable<R>	map(Function<? super T,? extends R> mapper)	Returns a ResultIterable<U> derived from this ResultIterable<T>, by transforming elements using the given mapper function.
static <T> ResultIterable<T>	of(Supplier<ResultSet> resultSetSupplier, RowMapper<T> mapper, StatementContext ctx)	Returns a ResultIterable backed by the given result set supplier, mapper, and context.
static <T> ResultIterable<T>	of(ResultIterator<T> iterator)	Returns a ResultIterable backed by the given iterator.
default T	one()	Returns the only row in the result set.
default <U> U	reduce(U identity, BiFunction<U,T,U> accumulator)	Reduce the results.
default Set<T>	set()	Returns results in a Set using the JDK specific default implementation of Set as provided by Collectors.toSet().
default Stream<T>	stream()	Returns the stream of results.
default <C extends Collection<T>> C	toCollection(Supplier<C> supplier)	Collect the results into a collection object similar to Collectors.toCollection(Supplier).
default <X extends Exception> void	useIterator(IteratorConsumer<T,X> consumer)	Passes the iterator of results to the consumer.
default <X extends Exception> void	useStream(StreamConsumer<T,X> consumer)	Passes the stream of results to the consumer.
default <R, X extends Exception> R	withIterator(IteratorCallback<T,R,X> callback)	Passes the iterator of results to the callback.
default <R, X extends Exception> R	withStream(StreamCallback<T,R,X> callback)	Passes the stream of results to the callback.

Methods inherited from interface java.lang.Iterable

spliterator

Method Details

of

static <T> ResultIterable<T> of(Supplier<ResultSet> resultSetSupplier,
 RowMapper<T> mapper,
 StatementContext ctx)

Returns a ResultIterable backed by the given result set supplier, mapper, and context.

Type Parameters:

T - the mapped type

Parameters:

resultSetSupplier - result set supplier

mapper - row mapper

ctx - statement context

Returns:

the result iterable

of

static <T> ResultIterable<T> of(ResultIterator<T> iterator)

Returns a ResultIterable backed by the given iterator.

Type Parameters:

T - iterator element type

Parameters:

iterator - the result iterator

Returns:

a ResultIterable

iterator

ResultIterator<T> iterator()

Stream all the rows of the result set out with an Iterator. The Iterator must be closed to release database resources.

Specified by:

iterator in interface Iterable<T>

Returns:

the results as a streaming Iterator

useIterator

default <X extends Exception> void useIterator(IteratorConsumer<T,X> consumer)
                                        throws X

Passes the iterator of results to the consumer. Database resources owned by the query are released before this method returns.

Parameters:

consumer - a consumer which receives the iterator of results.

Throws:

X - any exception thrown by the callback

withIterator

default <R,
X extends Exception> R withIterator(IteratorCallback<T,R,X> callback)
                                         throws X

Passes the iterator of results to the callback. Database resources owned by the query are released before this method returns.

Type Parameters:

R - the type returned by the callback

Parameters:

callback - a callback which receives the iterator of results, and returns some result.

Returns:

the value returned by the callback.

Throws:

X - any exception thrown by the callback

map

default <R> ResultIterable<R> map(Function<? super T,? extends R> mapper)

Returns a ResultIterable<U> derived from this ResultIterable<T>, by transforming elements using the given mapper function.

Type Parameters:

R - Element type of the returned ResultIterable

Parameters:

mapper - function to apply to elements of this ResultIterable

Returns:

the new ResultIterable

forEach

default void forEach(Consumer<? super T> action)

Specified by:

forEach in interface Iterable<T>

forEachWithCount

default int forEachWithCount(Consumer<? super T> action)

Performs the specified action on each remaining element and returns the iteration i.e. record count.
It is often useful (e.g. for logging) to know the record count while processing result sets.

 
         int cnt = h.createQuery("select * from something").mapTo(String.class)
                    .forEachWithCount(System.out::println);
         System.out.println(cnt + " records selected");
       
  

Parameters:

action - action to apply (required)

Returns:

iteration count

Since:

3.31

one

default T one()

Returns the only row in the result set. Returns null if the row itself is null.

Returns:

the only row in the result set.

Throws:

IllegalStateException - if the result set contains zero or multiple rows

findOne

default Optional<T> findOne()

Returns the only row in the result set, if any. Returns Optional.empty() if zero rows are returned, or if the row itself is null.

Returns:

the only row in the result set, if any.

Throws:

IllegalStateException - if the result set contains multiple rows

findOnly

@Deprecated
default T findOnly()

Deprecated.

use one() or findOne() instead.

Get the only row in the result set.

Returns:

the object mapped from the singular row in the results

Throws:

IllegalStateException - if zero or multiple rows are returned

first

default T first()

Returns the first row in the result set. Returns null if the row itself is null.

Returns:

the first row in the result set.

Throws:

IllegalStateException - if zero rows are returned

findFirst

default Optional<T> findFirst()

Returns the first row in the result set, if present. Returns Optional.empty() if zero rows are returned or the first row is null.

Returns:

the first row in the result set, if present.

stream

default Stream<T> stream()

Returns the stream of results.

Note: the returned stream owns database resources, and must be closed via a call to BaseStream.close(), or by using the stream in a try-with-resources block:

 try (Stream<T> stream = query.stream()) {
   // do stuff with stream
 }
 

Returns:

the stream of results.

See Also:

• useStream(StreamConsumer)
• withStream(StreamCallback)

useStream

default <X extends Exception> void useStream(StreamConsumer<T,X> consumer)
                                      throws X

Passes the stream of results to the consumer. Database resources owned by the query are released before this method returns.

Type Parameters:

X - the exception type thrown by the callback, if any

Parameters:

consumer - a consumer which receives the stream of results.

Throws:

X - any exception thrown by the callback

withStream

default <R,
X extends Exception> R withStream(StreamCallback<T,R,X> callback)
                                       throws X

Passes the stream of results to the callback. Database resources owned by the query are released before this method returns.

Type Parameters:

R - the type returned by the callback

X - the exception type thrown by the callback, if any

Parameters:

callback - a callback which receives the stream of results, and returns some result.

Returns:

the value returned by the callback.

Throws:

X - any exception thrown by the callback

list

default List<T> list()

Returns results in a List using the JDK specific default implementation of List as provided by Collectors.toList(). The same limitations apply to the list instance returned from this method. If more control over the list type is required, use toCollection(Supplier) or see the collectIntoList() method.

Returns:

results in a List

See Also:

• collectIntoList()
• toCollection(Supplier)

set

default Set<T> set()

Returns results in a Set using the JDK specific default implementation of Set as provided by Collectors.toSet(). The same limitations apply to the set instance returned from this method. If more control over the set type is required, use toCollection(Supplier) or see the collectIntoSet() method.

Returns:

results in a Set

Since:

3.38.0

See Also:

• collectIntoSet()
• toCollection(Supplier)

collect

default <R> R collect(Collector<? super T,?,R> collector)

Collect the results into a container specified by a collector.

Type Parameters:

R - the generic type of the container

Parameters:

collector - the collector

Returns:

the container with the query result

collectToMap

default <K,
V> Map<K,V> collectToMap(Function<? super T,? extends K> keyFunction,
 Function<? super T,? extends V> valueFunction)

Collect the results into a Map, using the given functions to compute keys and values.

Type Parameters:

K - the key type

V - the value type

Parameters:

keyFunction - a function that transforms the query result to a map key

valueFunction - a function that transforms the query result to a map value

Returns:

the collected Map

Since:

3.38.0

toCollection

@Alpha
default <C extends Collection<T>> C toCollection(Supplier<C> supplier)

Collect the results into a collection object similar to Collectors.toCollection(Supplier).

Parameters:

supplier - a supplier providing a new empty Collection into which the results will be inserted

Returns:

A new collection with all results inserted

Since:

3.38.0

collectInto

@Alpha
default <R extends Collection<? super T>> R collectInto(Type containerType)

Collect the results into a container type.

Parameters:

containerType - A Type object that must describe a container type

Returns:

A new collection implementing the container type with all results inserted

Throws:

UnsupportedOperationException - if the implementation does not support this operation

Since:

3.38.0

collectInto

@Alpha
default <R extends Collection<? super T>> R collectInto(GenericType<R> containerType)

Collect the results into a collection type.

Parameters:

containerType - A GenericType object that describes a collection type

Returns:

A new collection implementing the container type with all results inserted

Throws:

UnsupportedOperationException - if the implementation does not support this operation

Since:

3.38.0

collectIntoList

@Alpha
default List<T> collectIntoList()

Returns results in a List. The implementation of the list can be changed by registering a Collector:

     jdbi.getConfig(JdbiCollectors.class).registerCollector(List.class, Collectors.toCollection(LinkedList::new));
 

or

     handle.registerCollector(List.class, Collectors.toCollection(LinkedList::new));
 

If no collector is registered, then this method behaves like list().

Returns:

results in a List

Since:

3.38.0

See Also:

• list()
• toCollection(Supplier)

collectIntoSet

@Alpha
default Set<T> collectIntoSet()

Returns results in a Set. The implementation of the set can be changed by registering a Collector:

     jdbi.getConfig(JdbiCollectors.class).registerCollector(Set.class, Collectors.toCollection(LinkedHashSet::new));
 

or

     handle.registerCollector(Set.class, Collectors.toCollection(LinkedHashSet::new));
 

If no collector is registered, then this method behaves like set().

Returns:

results in a Set

Since:

3.38.0

See Also:

• set()
• toCollection(Supplier)

reduce

default <U> U reduce(U identity,
 BiFunction<U,T,U> accumulator)

Reduce the results. Using a BiFunction<U, T, U>, repeatedly combine query results until only a single value remains.

Type Parameters:

U - the accumulator type

Parameters:

identity - the U to combine with the first result

accumulator - the function to apply repeatedly

Returns:

the final U

filter

default ResultIterable<T> filter(Predicate<? super T> predicate)

Convenience method to filter the ResultIterable by applying the specified Predicate.
This method has the look and feel of Stream.filter(Predicate) without making use of streams.

Please note that filtering takes place in Java i.e. your client code, not in the database.
Filtering inside the database will most likely be of higher performance than filtering outside, as intermediate results are loaded into Java and then discarded. Moreover, indexes that may exist in the database will not be utilized here.

Parameters:

predicate - a non-null predicate to apply to each element to determine whether it should be included in the result

Returns:

the new result iterable

Since:

3.31