io.ebean.QueryIterator Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of ebean-api Show documentation

ebean api

There is a newer version: 15.8.0

package io.ebean;

import java.util.Iterator;

/**
 * Used to provide iteration over query results.
 * 
 * This can be used when you want to process a very large number of results and
 * means that you don't have to hold all the results in memory at once (unlike
 * findList(), findSet() etc where all the beans are held in the List or Set
 * etc).
 * 
 * 
 * Note that findIterate (and findEach and findEachWhile) uses a "per graph"
 * persistence context scope and adjusts jdbc fetch buffer size for large
 * queries. As such it is better to use findList for small queries.
 * 
 * 
 * Remember that with {@link QueryIterator} you must call {@link QueryIterator#close()}
 * when you have finished iterating the results. Use "try with resources" or ensure it
 * is closed in a finally block.
 * 
 * Try finally style
 * {@code
 *
 *  Query query = database.find(Customer.class)
 *     .where().gt("id", 0)
 *     .order("id")
 *     .setMaxRows(2);
 *
 *  QueryIterator it = query.findIterate();
 *  try {
 *    while (it.hasNext()) {
 *      Customer customer = it.next();
 *      // do something with customer ...
 *    }
 *  } finally {
 *    // close the underlying resources
 *    it.close();
 *  }
 *
 * }
 * 
 * 
Try with resources style
 * {@code
 *
 *  // try with resources
 *  try (QueryIterator it = query.findIterate()) {
 *    while (it.hasNext()) {
 *      Customer customer = it.next();
 *      // do something with customer ...
 *    }
 *  }
 *
 * }
 *
 * @param  the type of entity bean in the iteration
 */
public interface QueryIterator extends Iterator, AutoCloseable {

  /**
   * Returns true if the iteration has more elements.
   */
  @Override
  boolean hasNext();

  /**
   * Returns the next element in the iteration.
   */
  @Override
  T next();

  /**
   * Close the underlying resources held by this iterator.
   */
  @Override
  void close();
}