Add pagination to SafeSql

Author: fluentfuture

mug-safesql/src/main/java/com/google/mu/safesql/SafeSql.java

@@ -968,7 +968,8 @@ public <T> Optional<T> queryForOne(
   /**
    * Paginate the encapsulated query by fetching up to {@code pageSize} rows for each page.
    *
-   * <p>If {@code orderByKeys} is non-empty, the column values are used to control pagination.
+   * <p>If {@code orderByKeys} is non-empty, they refer to the columns that must uniquely identify
+   * a row. These column values are then used to control pagination.
    * For example, if {@code [groupId, timestamp]} can uniquely identify a row, the generated
    * SQL will use {@code "groupId" > ? OR ("groupId" = ? AND "timestamp" > ?)} for the next page,
    * comparing against the previous page's last row.
@@ -979,7 +980,7 @@ public <T> Optional<T> queryForOne(
    * 
    * <p>The standard SQL {@code FETCH NEXT ROWS} syntax is used for pagination.
    * If {@code orderByKeys} is empty, the paginated query will use {@code OFFSET} keyword
-   * to specify the next page offset.
+   * instead of the sort key columns to specify the next page offset.
    * 
    * <p>All column names are automatically double-quoted to avoid clashing with keywords or spaces
    * in identifiers. If your DB is case sensitive, make sure you pass in the accurate case.
@@ -1007,7 +1008,8 @@ public <T> Stream<List<T>> paginateLazily(
   /**
    * Paginate the encapsulated query by fetching up to {@code pageSize} rows for each page.
    *
-   * <p>If {@code orderByKeys} is non-empty, the column values are used to control pagination.
+   * <p>If {@code orderByKeys} is non-empty, they refer to the columns that must uniquely identify
+   * a row. These column values are then used to control pagination.
    * For example, if {@code [groupId, timestamp]} can uniquely identify a row, the generated
    * SQL will use {@code "groupId" > ? OR ("groupId" = ? AND "timestamp" > ?)} for the next page,
    * comparing against the previous page's last row.
@@ -1018,7 +1020,7 @@ public <T> Stream<List<T>> paginateLazily(
    * 
    * <p>The standard SQL {@code FETCH NEXT ROWS} syntax is used for pagination.
    * If {@code orderByKeys} is empty, the paginated query will use {@code OFFSET} keyword
-   * to specify the next page offset.
+   * instead of the sort key columns to specify the next page offset.
    * 
    * <p>All column names are automatically double-quoted to avoid clashing with keywords or spaces
    * in identifiers. If your DB is case sensitive, make sure you pass in the accurate case.
@@ -1049,7 +1051,8 @@ public <T> Stream<List<T>> paginateLazily(
   /**
    * Paginate the encapsulated query by fetching up to {@code pageSize} rows for each page.
    *
-   * <p>If {@code orderByKeys} is non-empty, the column values are used to control pagination.
+   * <p>If {@code orderByKeys} is non-empty, they refer to the columns that must uniquely identify
+   * a row. These column values are then used to control pagination.
    * For example, if {@code [groupId, timestamp]} can uniquely identify a row, the generated
    * SQL will use {@code "groupId" > ? OR ("groupId" = ? AND "timestamp" > ?)} for the next page,
    * comparing against the previous page's last row.
@@ -1060,7 +1063,7 @@ public <T> Stream<List<T>> paginateLazily(
    * 
    * <p>The standard SQL {@code FETCH NEXT ROWS} syntax is used for pagination.
    * If {@code orderByKeys} is empty, the paginated query will use {@code OFFSET} keyword
-   * to specify the next page offset.
+   * instead of the sort key columns to specify the next page offset.
    * 
    * <p>All column names are automatically double-quoted to avoid clashing with keywords or spaces
    * in identifiers. If your DB is case sensitive, make sure you pass in the accurate case.
@@ -1088,7 +1091,8 @@ public <T> Stream<List<T>> paginateLazily(
   /**
    * Paginate the encapsulated query by fetching up to {@code pageSize} rows for each page.
    *
-   * <p>If {@code orderByKeys} is non-empty, the column values are used to control pagination.
+   * <p>If {@code orderByKeys} is non-empty, they refer to the columns that must uniquely identify
+   * a row. These column values are then used to control pagination.
    * For example, if {@code [groupId, timestamp]} can uniquely identify a row, the generated
    * SQL will use {@code "groupId" > ? OR ("groupId" = ? AND "timestamp" > ?)} for the next page,
    * comparing against the previous page's last row.
@@ -1099,7 +1103,7 @@ public <T> Stream<List<T>> paginateLazily(
    * 
    * <p>The standard SQL {@code FETCH NEXT ROWS} syntax is used for pagination.
    * If {@code orderByKeys} is empty, the paginated query will use {@code OFFSET} keyword
-   * to specify the next page offset.
+   * instead of the sort key columns to specify the next page offset.
    * 
    * <p>All column names are automatically double-quoted to avoid clashing with keywords or spaces
    * in identifiers. If your DB is case sensitive, make sure you pass in the accurate case.