Add 'user friendly' datastore API.

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"
+)
+
+// RunCB is the callback signature provided to Interface.Run
+//
+//   - obj is an object as specified by the proto argument of Run

[Vadim Sh., 2015/07/29 16:21:43]

consider passing a struct 

type PartialResult struct {
  Obj interface{}
  Cursor func() (...)
}

That way RunCB signatures everywhere will be simpler, e.g. no need to worry
about defining getCursor arg if you ain't going to use it. (And if some new
field is added, no need to fix all signatures everywhere).

[iannucci, 2015/08/03 03:56:31]

I tried this, but it's not really worth the extra type. The godocs are already
pretty noisy (though I have some ideas on how to fix them). If we ever add a new
thing (pretty sure we won't), we can definitely revisit the struct (or
interface) idea.

+//   - getCursor can be invoked to obtain the current cursor.
+//
+// Return true to continue iterating through the query results, or false to stop.
+type RunCB func(obj interface{}, getCursor func() (Cursor, error)) bool
+
+type Interface interface {
+        NewKey(kind, stringID string, intID int64, parent Key) Key
+
+        // NewKeyObj extracts a key from src.
+        //
+        // If there's a probjem obtaining the key, this method will panic.
+        //
+        // src must be one of:
+        //   - *S where S is a struct

[Vadim Sh., 2015/07/29 16:21:43]

struct tagged with meta-how-do-you-call-them tags? ("$id")?

Also consider renaming it to KeyForObject or something. NewKey and NewKeyObj
sound synonymous... (since obj is understood as "key object", not "key for
object").

[iannucci, 2015/08/03 03:56:32]

Done.

+        //   - a PropertyLoadSaver
+        NewKeyObj(src interface{}) Key
+
+        // NewKeyObjErr extracts a key from src.
+        //
+        // src must be one of:
+        //   - *S where S is a struct
+        //   - a PropertyLoadSaver
+        NewKeyObjErr(src interface{}) (Key, error)
+
+        DecodeKey(encoded string) (Key, error)

[Vadim Sh., 2015/07/29 16:21:43]

document?

[iannucci, 2015/08/03 03:56:32]

Done.

+        NewQuery(kind string) Query
+
+        RunInTransaction(f func(c context.Context) error, opts *TransactionOptions) error
+
+        // Run executes the given query, and calls `cb` for each successfully item.

[Vadim Sh., 2015/07/29 16:21:43]

typos: successfully item

[iannucci, 2015/08/03 03:56:32]

Done.

+        //
+        // proto is a prototype of the objects which will be passed to the callback.

[Vadim Sh., 2015/07/29 16:21:43]

It won't be written to, right?

[iannucci, 2015/08/03 03:56:32]

correct. documented.

+        // It must be of the form:
+        //   - *S where S is a struct
+        //   - *P where *P is a concrete type implementing PropertyLoadSaver
+        //   - *Key implies a keys-only query (and cb will be invoked with Key's)
+        // Run will create a new, populated instance of proto for each call of
+        // cb. Run stops on the first error encountered.
+        Run(q Query, proto interface{}, cb RunCB) 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
+        //   - *[]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
+
+        // Put inserts a single object into the datastore
+        //
+        // src must be one of:
+        //   - *S where S is a struct
+        //   - *P where *P is a concrete type implementing PropertyLoadSaver
+        //
+        // If src resolves to an Incomplete key, Put will write the

[Vadim Sh., 2015/07/29 16:21:43]

its for autogenerating ids?

[iannucci, 2015/08/03 03:56:32]

right. Incomplete specifically means `StringID == "" && IntID == 0`

+        // resolved key back to src.
+        Put(src interface{}) error
+
+        // 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.
+        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
+}
+
+// Get gets the Interface implementation from context.
+func Get(c context.Context) Interface {
+        return &datastoreImpl{GetRaw(c)}
+}