#219 - Update PagedList javadoc - enable foreground query for getTotalRowCount() when loadRowCount() has not been used

src/main/java/com/avaje/ebean/PagedList.java

@@ -16,7 +16,44 @@ import java.util.concurrent.Future;
  * the query. This translates into SQL that uses limit offset, rownum or row_number function to
  * limit the result set.
  * </p>
- * 
+ *
+ * <h4>Example: typical use including total row count</h4>
+ * <pre>{@code
+ *
+ *     // We want to find the first 100 new orders
+ *     //  ... 0 means first page
+ *     //  ... page size is 100
+ *
+ *     PagedList<Order> pagedList
+ *       = ebeanServer.find(Order.class)
+ *       .where().eq("status", Order.Status.NEW)
+ *       .order().asc("id")
+ *       .findPagedList(0, 100);
+ *
+ *     // 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<Order> orders = pagedList.getList();
+ *
+ *     // get the total row count (from the future)
+ *     int totalRowCount = pagedList.getTotalRowCount();
+ *
+ * }</pre>
+ *
+ * <h4>Example: No total row count required</h4>
+ * <pre>{@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<Order> orders = pagedList.getList();
+ *
+ * }</pre>
+ *
  * @param <T>
  *          the entity bean type
  * 
@@ -26,12 +63,53 @@ public interface PagedList<T> {
 
   /**
    * Initiate the loading of the total row count in the background.
+   * <pre>{@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<Order> orders = pagedList.getList();
+   *
+   *     // get the total row count (from the future)
+   *     int totalRowCount = pagedList.getTotalRowCount();
+   *
+   * }</pre>
+   *
+   * <p>
+   * 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).
+   * </p>
    */
   public void loadRowCount();
 
   /**
    * Return the Future row count. You might get this if you wish to cancel the total row count query
-   * or specify a timeout for that query.
+   * or specify a timeout for the row count query.
+   * <p>
+   * The loadRowCount() & getTotalRowCount() methods internally make use of this getFutureRowCount() method.
+   * Generally I expect people to prefer loadRowCount() & getTotalRowCount() over getFutureRowCount().
+   * </p>
+   * <pre>{@code
+   *
+   *     // initiate the row count query in the background thread
+   *     Future<Integer> rowCount = pagedList.getFutureRowCount();
+   *
+   *     // fetch and return the list in the foreground thread
+   *     List<Order> 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();
+   *
+   * }</pre>
    */
   public Future<Integer> getFutureRowCount();
 
@@ -42,11 +120,37 @@ public interface PagedList<T> {
 
   /**
    * Return the total row count for all pages.
+   * <p>
+   * 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.
+   * </p>
+   * <p>
+   * 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.
+   * </p>
+   * <pre>{@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<Order> orders = pagedList.getList();
+   *
+   *     // get the total row count (which was being executed
+   *     // in a background thread if loadRowCount() was used)
+   *     int totalRowCount = pagedList.getTotalRowCount();
+   *
+   * }</pre>
    */
   public int getTotalRowCount();
 
   /**
    * Return the total number of pages based on the page size and total row count.
+   * <p>
+   * 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.
+   * </p>
    */
   public int getTotalPageCount();
 
@@ -57,6 +161,10 @@ public interface PagedList<T> {
 
   /**
    * Return true if there is a next page.
+   * <p>
+   * 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.
+   * </p>
    */
   public boolean hasNext();
 
@@ -68,7 +176,11 @@ public interface PagedList<T> {
   /**
    * 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.
-   * 
+   * <p>
+   * 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.
+   * </p>
+   *
    * @param to
    *          String to put between the first and last row
    * @param of

src/main/java/com/avaje/ebeaninternal/server/query/LimitOffsetPagedList.java

@@ -28,6 +28,8 @@ public class LimitOffsetPagedList<T> implements PagedList<T> {
 
   private final Monitor monitor = new Monitor();
 
+  private int foregroundTotalRowCount = -1;
+
   private Future<Integer> futureRowCount;
 
   private List<T> list;
@@ -51,13 +53,12 @@ public class LimitOffsetPagedList<T> implements PagedList<T> {
       return futureRowCount;
     }
   }
-  
+
   public List<T> getList() {
     synchronized (monitor) {
       if (list == null) {
         query.setFirstRow(pageIndex * pageSize);
         query.setMaxRows(pageSize);
-
         list = server.findList(query, null);
       }
       return list;
@@ -75,10 +76,21 @@ public class LimitOffsetPagedList<T> implements PagedList<T> {
   }
 
   public int getTotalRowCount() {
-    try {
-      return getFutureRowCount().get();
-    } catch (Exception e) {
-      throw new PersistenceException(e);
+    synchronized (monitor) {
+      if (futureRowCount != null) {
+        try {
+          // background query already initiated so get it with a wait
+          return futureRowCount.get();
+        } catch (Exception e) {
+          throw new PersistenceException(e);
+        }
+      }
+      // already fetched?
+      if (foregroundTotalRowCount > -1) return foregroundTotalRowCount;
+
+      // just using foreground thread
+      foregroundTotalRowCount = server.findRowCount(query, null);
+      return foregroundTotalRowCount;
     }
   }