001package io.ebean;
002
003import javax.persistence.PersistenceException;
004import java.util.List;
005import java.util.concurrent.Future;
006import java.util.concurrent.TimeUnit;
007import java.util.concurrent.TimeoutException;
008
009/**
010 * FutureList represents the result of a background query execution that will
011 * return a list of entities.
012 * <p>
013 * It extends the java.util.concurrent.Future with the ability to cancel the
014 * query, check if it is finished and get the resulting list waiting for the
015 * query to finish (ie. the standard features of java.util.concurrent.Future).
016 * </p>
017 * <p>
018 * A simple example:
019 * </p>
020 * <pre>{@code
021 *
022 *  // create a query to find all orders
023 * Query<Order> query = DB.find(Order.class);
024 *
025 *  // execute the query in a background thread
026 *  // immediately returning the futureList
027 * FutureList<Order> futureList = query.findFutureList();
028 *
029 *  // do something else ...
030 *
031 * if (!futureList.isDone()){
032 *      // we can cancel the query execution. This will cancel
033 * // the underlying query if that is supported by the JDBC
034 * // driver and database
035 *      futureList.cancel(true);
036 * }
037 *
038 * if (!futureList.isCancelled()){
039 *      // wait for the query to finish and return the list
040 *      List<Order> list = futureList.get();
041 *      ...
042 * }
043 *
044 * }</pre>
045 */
046public interface FutureList<T> extends Future<List<T>> {
047
048  /**
049   * Return the query that is being executed by a background thread.
050   */
051  Query<T> getQuery();
052
053  /**
054   * Same as {@link #get()} but wraps InterruptedException and ExecutionException in the
055   * unchecked PersistenceException.
056   *
057   * @return The query list result
058   * @throws PersistenceException when a InterruptedException or ExecutionException occurs.
059   */
060  List<T> getUnchecked();
061
062  /**
063   * Same as {@link #get(long, java.util.concurrent.TimeUnit)} but wraps InterruptedException
064   * and ExecutionException in the unchecked PersistenceException.
065   *
066   * @return The query list result
067   * @throws TimeoutException     if the wait timed out
068   * @throws PersistenceException if a InterruptedException or ExecutionException occurs.
069   */
070  List<T> getUnchecked(long timeout, TimeUnit unit) throws TimeoutException;
071
072}