001package io.ebean;
002
003import java.util.Iterator;
004
005/**
006 * Used to provide iteration over query results.
007 * <p>
008 * This can be used when you want to process a very large number of results and
009 * means that you don't have to hold all the results in memory at once (unlike
010 * findList(), findSet() etc where all the beans are held in the List or Set
011 * etc).
012 * </p>
013 * <p>
014 * Note that findIterate (and findEach and findEachWhile) uses a "per graph"
015 * persistence context scope and adjusts jdbc fetch buffer size for large
016 * queries. As such it is better to use findList for small queries.
017 * </p>
018 * <p>
019 * Remember that with {@link QueryIterator} you must call {@link QueryIterator#close()}
020 * when you have finished iterating the results. Use "try with resources" or ensure it
021 * is closed in a finally block.
022 * </p>
023 * <h3>Try finally style</h3>
024 * <pre>{@code
025 *
026 *  Query<Customer> query = server.find(Customer.class)
027 *     .where().gt("id", 0)
028 *     .orderBy("id")
029 *     .setMaxRows(2);
030 *
031 *  QueryIterator<Customer> it = query.findIterate();
032 *  try {
033 *    while (it.hasNext()) {
034 *      Customer customer = it.next();
035 *      // do something with customer ...
036 *    }
037 *  } finally {
038 *    // close the underlying resources
039 *    it.close();
040 *  }
041 *
042 * }</pre>
043 * <p>
044 * <h3>Try with resources style</h3>
045 * <pre>{@code
046 *
047 *  // try with resources
048 *  try (QueryIterator<Customer> it = query.findIterate()) {
049 *    while (it.hasNext()) {
050 *      Customer customer = it.next();
051 *      // do something with customer ...
052 *    }
053 *  }
054 *
055 * }</pre>
056 *
057 * @param <T> the type of entity bean in the iteration
058 */
059public interface QueryIterator<T> extends Iterator<T>, java.io.Closeable {
060
061  /**
062   * Returns <tt>true</tt> if the iteration has more elements.
063   */
064  @Override
065  boolean hasNext();
066
067  /**
068   * Returns the next element in the iteration.
069   */
070  @Override
071  T next();
072
073  /**
074   * Remove is not allowed.
075   */
076  @Override
077  void remove();
078
079  /**
080   * Close the underlying resources held by this iterator.
081   */
082  @Override
083  void close();
084}