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 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:

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

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

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

    • 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