datastore: Add DecodeCursor to [Raw]Interface.

service/datastore/interface.go

 // Copyright 2015 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 package datastore
 
 import (
         "golang.org/x/net/context"
 )
 
@@ skipping 65 matching lines @@
         //   func(obj TYPE, getCursor CursorCB) bool
         //
         // Where TYPE is one of:
         //   - S or *S where S is a struct
         //   - P or *P where *P is a concrete type implementing PropertyLoadSaver
         //   - Key (implies a keys-only query)
         //
         // Run stops on the first error encountered.
         Run(q Query, cb interface{}) error
 
+        // DecodeCursor converts a string returned by a Cursor into a Cursor instance.
+        // It will return an error if the supplied string is not valid, or could not
+        // be decoded by the implementation.
+        DecodeCursor(string) (Cursor, error)
+
         // GetAll retrieves all of the Query results into dst.
         //
         // dst must be one of:
         //   - *[]S or *[]*S where S is a struct
-        //   - *[]P or *[]*P where *P is a concrete type implementing PropertyLoadSaver
+        //   - *[]P or *[]*P where *P is a concrete type implementing
+        //     PropertyLoadSaver
         //   - *[]Key implies a keys-only query.
         GetAll(q Query, dst interface{}) error
 
         // Get retrieves a single object from the datastore
         //
         // dst must be one of:
         //   - *S where S is a struct
         //   - *P where *P is a concrete type implementing PropertyLoadSaver
         Get(dst interface{}) error
 
@@ skipping 10 matching lines @@
 
         // Delete removes an item from the datastore.
         Delete(key Key) error
 
         // GetMulti retrieves items from the datastore.
         //
         // dst must be one of:
         //   - []S or []*S where S is a struct
         //   - []P or []*P where *P is a concrete type implementing PropertyLoadSaver
         //   - []I where I is some interface type. Each element of the slice must
-        //               be non-nil, and its underlying type must be either *S or *P.
+        //     be non-nil, and its underlying type must be either *S or *P.
         GetMulti(dst interface{}) error
 
         // PutMulti writes items to the datastore.
         //
         // src must be one of:
         //   - []S or []*S where S is a struct
         //   - []P or []*P where *P is a concrete type implementing PropertyLoadSaver
         //   - []I where i is some interface type. Each elemet of the slice must
         //     be non-nil, and its underlying type must be either *S or *P.
         //
         // If items in src resolve to Incomplete keys, PutMulti will write the
         // resolved keys back to the items in src.
         PutMulti(src interface{}) error
 
         // DeleteMulti removes items from the datastore.
         DeleteMulti(keys []Key) error
 
         // Raw returns the underlying RawInterface. The Interface and RawInterface may
         // be used interchangably; there's no danger of interleaving access to the
         // datastore via the two.
         Raw() RawInterface
 }