Pagination Improvements

Includes integration tests and CHANGELOG.

CHANGELOG.md

@@ -1,6 +1,8 @@
 Unreleased Changes
 ------------------
 
+* Feature - Aws::Record::ItemCollection - Add the `#page` and `#last_evaluated_key` methods to `Aws::Record::ItemCollection`. This helps to support use cases where you'd like to control the result set size with the `:limit` parameter, or if you want to expose pagination capabilities to an outside caller, for example a list-type operation exposed in a web API.
+
 2.0.0 (2017-08-29)
 ------------------
 

features/searching/search.feature

@@ -130,3 +130,63 @@ Feature: Amazon DynamoDB Querying and Scanning
         }
       ]
       """
+
+  @wip
+  Scenario: Paginate Manually With Multiple Calls
+    When we call the 'scan' class method with parameter data:
+      """
+      {
+        "limit": 2
+      }
+      """
+    Then we should receive an aws-record page with 2 values from members:
+      """
+      [
+        {
+          "id": "1",
+          "count": 5,
+          "body": "First item."
+        },
+        {
+          "id": "1",
+          "count": 10,
+          "body": "Second item."
+        },
+        {
+          "id": "1",
+          "count": 15,
+          "body": "Third item."
+        },
+        {
+          "id": "2",
+          "count": 10,
+          "body": "Fourth item."
+        }
+      ]
+      """
+    When we call the 'scan' class method using the page's pagination token
+    Then we should receive an aws-record page with 2 values from members:
+      """
+      [
+        {
+          "id": "1",
+          "count": 5,
+          "body": "First item."
+        },
+        {
+          "id": "1",
+          "count": 10,
+          "body": "Second item."
+        },
+        {
+          "id": "1",
+          "count": 15,
+          "body": "Third item."
+        },
+        {
+          "id": "2",
+          "count": 10,
+          "body": "Fourth item."
+        }
+      ]
+      """

features/searching/step_definitions.rb

@@ -31,6 +31,30 @@
   @collection = @model.scan
 end
 
+When(/^we call the 'scan' class method with parameter data:$/) do |string|
+  data = JSON.parse(string, symbolize_names: true)
+  @collection = @model.scan(data)
+end
+
 When(/^we take the first member of the result collection$/) do
   @instance = @collection.first
 end
+
+Then(/^we should receive an aws\-record page with 2 values from members:$/) do |string|
+  expected = JSON.parse(string, symbolize_names: true)
+  page = @collection.page
+  @last_evaluated_key = @collection.last_evaluated_key
+  # This is definitely a hack which takes advantage of an accident in test
+  # design. In the future, we'll need to have some sort of shared collection
+  # state to cope with the fact that scan order is not guaranteed.
+  page.size == 2
+  # Results do not have guaranteed order, check each expected value individually
+  page.each do |item|
+    h = item.to_h
+    expect(expected.any? { |e| h == e }).to eq(true)
+  end
+end
+
+When(/^we call the 'scan' class method using the page's pagination token$/) do
+  @collection = @model.scan(exclusive_start_key: @last_evaluated_key)
+end