io.ebean.PagedList Maven / Gradle / Ivy
package io.ebean;
import java.util.List;
import java.util.concurrent.Future;
/**
* Represents a page of results.
*
* The benefit of using PagedList over just using the normal Query with
* {@link Query#setFirstRow(int)} and {@link Query#setMaxRows(int)} is that it additionally wraps
* functionality that can call {@link Query#findFutureCount()} to determine total row count,
* total page count etc.
*
*
* Internally this works using {@link Query#setFirstRow(int)} and {@link Query#setMaxRows(int)} on
* the query. This translates into SQL that uses limit offset, rownum or row_number function to
* limit the result set.
*
*
*
Example: typical use including total row count
* {@code
*
* // We want to find the first 50 new orders
* // ... so we don't really need setFirstRow(0)
*
* PagedList pagedList = DB.find(Order.class)
* .where().eq("status", Order.Status.NEW)
* .order().asc("id")
* .setFirstRow(0)
* .setMaxRows(50)
* .findPagedList();
*
* // Optional: initiate the loading of the total
* // row count in a background thread
* pagedList.loadRowCount();
*
* // fetch and return the list in the foreground thread
* List orders = pagedList.getList();
*
* // get the total row count (from the future)
* int totalRowCount = pagedList.getTotalRowCount();
*
* }
*
*
Example: No total row count required
* {@code
*
* // If you are not getting the 'first page' often
* // you do not bother getting the total row count again
* // so instead just get the page list of data
*
* // fetch and return the list in the foreground thread
* List orders = pagedList.getList();
*
* }
*
* @param the entity bean type
* @see Query#findPagedList()
*/
public interface PagedList {
/**
* Return an empty PagedList.
*/
static PagedList emptyList() {
return new EmptyPagedList<>();
}
/**
* Initiate the loading of the total row count in the background.
* {@code
*
* // initiate the loading of the total row count
* // in a background thread
* pagedList.loadRowCount();
*
* // fetch and return the list in the foreground thread
* List orders = pagedList.getList();
*
* // get the total row count (from the future)
* int totalRowCount = pagedList.getTotalRowCount();
*
* }
*
* Also note that using loadRowCount() and getTotalRowCount() rather than getFutureRowCount()
* means that exceptions ExecutionException, InterruptedException, TimeoutException are instead
* wrapped in the unchecked PersistenceException (which might be preferrable).
*
*/
void loadCount();
/**
* Return the Future row count. You might get this if you wish to cancel the total row count query
* or specify a timeout for the row count query.
*
* The loadRowCount() and getTotalRowCount() methods internally make use of this getFutureRowCount() method.
* Generally I expect people to prefer loadRowCount() and getTotalRowCount() over getFutureRowCount().
*
* {@code
*
* // initiate the row count query in the background thread
* Future rowCount = pagedList.getFutureRowCount();
*
* // fetch and return the list in the foreground thread
* List orders = pagedList.getList();
*
* // now get the total count with a timeout
* Integer totalRowCount = rowCount.get(30, TimeUnit.SECONDS);
*
* // or ge the total count without a timeout
* Integer totalRowCountViaFuture = rowCount.get();
*
* // which is actually the same as ...
* int totalRowCount = pagedList.getTotalRowCount();
*
* }
*/
Future getFutureCount();
/**
* Return the list of entities for this page.
*/
List getList();
/**
* Return the total row count for all pages.
*
* If loadRowCount() has already been called then the row count query is already executing in a background thread
* and this gets the associated Future and gets the value waiting for the future to finish.
*
*
* If loadRowCount() has not been called then this executes the find row count query and returns the result and this
* will just occur in the current thread and not use a background thread.
*
* {@code
*
* // Optional: initiate the loading of the total
* // row count in a background thread
* pagedList.loadRowCount();
*
* // fetch and return the list in the foreground thread
* List orders = pagedList.getList();
*
* // get the total row count (which was being executed
* // in a background thread if loadRowCount() was used)
* int totalRowCount = pagedList.getTotalRowCount();
*
* }
*/
int getTotalCount();
/**
* Return the total number of pages based on the page size and total row count.
*
* This method requires that the total row count has been fetched and will invoke
* the total row count query if it has not already been invoked.
*
*/
int getTotalPageCount();
/**
* Return the page size used for this query. This is the same value as maxRows used by the query.
*/
int getPageSize();
/**
* Return the index position of this page (Zero based).
*
* This is a calculated value based on firstRow/maxRows.
*
*/
int getPageIndex();
/**
* Return true if there is a next page.
*
* This method requires that the total row count has been fetched and will invoke
* the total row count query if it has not already been invoked.
*
*/
boolean hasNext();
/**
* Return true if there is a previous page.
*/
boolean hasPrev();
/**
* Helper method to return a "X to Y of Z" string for this page where X is the first row, Y the
* last row and Z the total row count.
*
* This method requires that the total row count has been fetched and will invoke
* the total row count query if it has not already been invoked.
*
*
* @param to String to put between the first and last row
* @param of String to put between the last row and the total row count
* @return String of the format XtoYofZ.
*/
String getDisplayXtoYofZ(String to, String of);
}