Expose "unsafe" paging state API (JAVA-759).

olim7t · olim7t · commit ab4cf9a4ba4e · 2015-05-12T12:04:42.000+02:00
diff --git a/driver-core/CHANGELOG.rst b/driver-core/CHANGELOG.rst
@@ -5,6 +5,7 @@ CHANGELOG
 -------
 
 - [improvement] Use Netty's pooled ByteBufAllocator by default (JAVA-756)
+- [improvement] Expose "unsafe" paging state API (JAVA-759)
 
 
 2.0.10:
diff --git a/driver-core/src/main/java/com/datastax/driver/core/ExecutionInfo.java b/driver-core/src/main/java/com/datastax/driver/core/ExecutionInfo.java
@@ -18,6 +18,8 @@
 import java.nio.ByteBuffer;
 import java.util.List;
 
+import com.datastax.driver.core.utils.Bytes;
+
 /**
  * Basic information on the execution of a query.
  */
@@ -143,6 +145,22 @@ public PagingState getPagingState() {
         return new PagingState(this.pagingState, this.statement);
     }
 
+    /**
+     * Returns the "raw" paging state of the query.
+     *
+     * Contrary to {@link #getPagingState()}, there will be no validation when
+     * this is later reinjected into a statement.
+     *
+     * @return the paging state or null if there is no next page.
+     *
+     * @see Statement#setPagingStateUnsafe(byte[])
+     */
+    public byte[] getPagingStateUnsafe() {
+        if (this.pagingState == null)
+            return null;
+        return Bytes.getArray(this.pagingState);
+    }
+
     /**
      * Whether the cluster had reached schema agreement after the execution of this query.
      *
diff --git a/driver-core/src/main/java/com/datastax/driver/core/Statement.java b/driver-core/src/main/java/com/datastax/driver/core/Statement.java
@@ -267,8 +267,9 @@ public int getFetchSize() {
      * This will cause the next execution of this statement to fetch results from a given
      * page, rather than restarting from the beginning.
      * <p>
-     * You get the paging state from a previous execution of the statement. This is typically
-     * used to iterate in a "stateless" manner (e.g. across HTTP requests):
+     * You get the paging state from a previous execution of the statement (see
+     * {@link ExecutionInfo#getPagingState()}.
+     * This is typically used to iterate in a "stateless" manner (e.g. across HTTP requests):
      * <pre>
      * {@code
      * Statement st = new SimpleStatement("your query");
@@ -296,9 +297,17 @@ public int getFetchSize() {
      * }
      * </pre>
      * <p>
-     * Note that the paging state can only be reused between perfectly identical statements
+     * The paging state can only be reused between perfectly identical statements
      * (same query string, same bound parameters). Altering the contents of the paging state
      * or trying to set it on a different statement will cause this method to fail.
+     * <p>
+     * Note that, due to internal implementation details, the paging state is not portable
+     * across native protocol versions (see the
+     * <a href="http://datastax.github.io/java-driver/features/native_protocol">online documentation</a>
+     * for more explanations about the native protocol).
+     * This means that {@code PagingState} instances generated with an old version won't work
+     * with a higher version. If that is a problem for you, consider using the "unsafe" API (see
+     * {@link #setPagingStateUnsafe(byte[])}).
      *
      * @param pagingState the paging state to set, or {@code null} to remove any state that was
      *                    previously set on this statement.
@@ -323,6 +332,30 @@ public Statement setPagingState(PagingState pagingState) {
         return this;
     }
 
+    /**
+     * Sets the paging state.
+     * <p>
+     * Contrary to {@link #setPagingState(PagingState)}, this method takes the "raw" form of the
+     * paging state (previously extracted with {@link ExecutionInfo#getPagingStateUnsafe()}.
+     * It won't validate that this statement matches the one that the paging state was extracted from.
+     * If the paging state was altered in any way, you will get unpredictable behavior from
+     * Cassandra (ranging from wrong results to a query failure). If you decide to use this variant,
+     * it is strongly recommended to add your own validation (for example, signing the raw state with
+     * a private key).
+     *
+     * @param pagingState the paging state to set, or {@code null} to remove any state that was
+     *                    previously set on this statement.
+     * @return this {@code Statement} object.
+     */
+    public Statement setPagingStateUnsafe(byte[] pagingState) {
+        if (pagingState == null) {
+            this.pagingState = null;
+        } else {
+            this.pagingState = ByteBuffer.wrap(pagingState);
+        }
+        return this;
+    }
+
     ByteBuffer getPagingState() {
         return pagingState;
     }
diff --git a/driver-core/src/test/java/com/datastax/driver/core/PagingStateTest.java b/driver-core/src/test/java/com/datastax/driver/core/PagingStateTest.java
@@ -209,5 +209,26 @@ public void should_fail_when_setting_paging_state_on_batch_statement() {
         batch.setPagingState(emptyStatement);
     }
 
+    /**
+     * Validates that the "unsafe" paging state can be reused with the same Statement.
+     *
+     * @test_category paging
+     * @expected_result {@link ResultSet} from the query with the provided raw paging state starts from the
+     *  subsequent row from the first query.
+     */
+    @Test(groups = "short")
+    public void should_complete_when_using_unsafe_paging_state() {
+        SimpleStatement st = new SimpleStatement(String.format("SELECT v FROM test WHERE k='%s'", KEY));
+        ResultSet result = session.execute(st.setFetchSize(20));
+        int pageSize = result.getAvailableWithoutFetching();
+        byte[] savedPagingState = result.getExecutionInfo().getPagingStateUnsafe();
+
+        st = new SimpleStatement(String.format("SELECT v FROM test WHERE k='%s'", KEY));
+        result = session.execute(st.setFetchSize(20).setPagingStateUnsafe(savedPagingState));
+
+        //We have the result starting from the next page we stopped
+        assertThat(result.one().getInt("v")).isEqualTo(pageSize);
+    }
+
 }
 
diff --git a/features/paging/README.md b/features/paging/README.md
@@ -172,4 +172,46 @@ if (nextPage != null) {
 ```
 
 [result_set]:http://docs.datastax.com/en/drivers/java/2.0/com/datastax/driver/core/ResultSet.html
-[paging_state]:http://docs.datastax.com/en/drivers/java/2.0/com/datastax/driver/core/PagingState.html
+[paging_state]:http://docs.datastax.com/en/drivers/java/2.0/com/datastax/driver/core/PagingState.html
+
+Due to internal implementation details, `PagingState` instances are not
+portable across [native protocol](../native_protocol/) versions. This
+could become a problem in the following scenario:
+
+* you're using the driver 2.0.x and Cassandra 2.0.x, and therefore
+  native protocol v2;
+* a user bookmarks a link to your web service that contains a serialized
+  paging state;
+* you upgrade your server stack to use the driver 2.1.x and Cassandra
+  2.1.x, so you're now using protocol v3;
+* the user tries to reload their bookmark, but the paging state was
+  serialized with protocol v2, so trying to reuse it will fail.
+
+If this is not acceptable for you, you might want to consider the unsafe
+API described in the next section.
+
+#### Unsafe API
+
+As an alternative to the standard API, there are two methods that
+manipulate a raw `byte[]` instead of a `PagingState` object:
+
+* [ExecutionInfo#getPagingStateUnsafe()][gpsu]
+* [Statement#setPagingStateUnsafe(byte[])][spsu]
+
+These low-level methods perform no validation on their arguments;
+therefore nothing protects you from reusing a paging state that was
+generated from a different statement, or altered in any way. This could
+result in sending a corrupt paging state to Cassandra, with
+unpredictable consequences (ranging from wrong results to a query
+failure).
+
+There are two situations where you might want to use the unsafe API:
+
+* you never expose the paging state to end users and you are confident
+  that it won't get altered;
+* you want portability across protocol versions and/or you prefer
+  implementing your own validation logic (for example, signing the raw
+  state with a private key).
+
+[gpsu]: http://www.datastax.com/drivers/java/2.0/com/datastax/driver/core/ExecutionInfo.html#getPagingStateUnsafe()
+[spsu]: http://www.datastax.com/drivers/java/2.0/com/datastax/driver/core/Statement.html#setPagingStateUnsafe(byte[])
