001package com.avaje.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 * 
021 * <pre>{@code
022 *  // create a query to find all orders
023 * Query<Order> query = Ebean.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 * 
039 * if (!futureList.isCancelled()){
040 *      // wait for the query to finish and return the list
041 *      List<Order> list = futureList.get();
042 *      ...
043 * }
044 * 
045 * }</pre>
046 */
047public interface FutureList<T> extends Future<List<T>> {
048
049  /**
050   * Return the query that is being executed by a background thread.
051   */
052  Query<T> getQuery();
053
054  /**
055   * Same as {@link #get()} but wraps InterruptedException and ExecutionException in the
056   * unchecked PersistenceException.
057   *
058   * @return The query list result
059   *
060   * @throws PersistenceException when a InterruptedException or ExecutionException occurs.
061   */
062  List<T> getUnchecked();
063
064  /**
065   * Same as {@link #get(long, java.util.concurrent.TimeUnit)} but wraps InterruptedException
066   * and ExecutionException in the unchecked PersistenceException.
067   *
068   * @return The query list result
069   *
070   * @throws TimeoutException if the wait timed out
071   * @throws PersistenceException if a InterruptedException or ExecutionException occurs.
072   */
073  List<T> getUnchecked(long timeout, TimeUnit unit) throws TimeoutException;
074
075}