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.

  • 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

      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.
      Returns:
      results in a List.

    • 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

    • 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