datastore: Update AllocateIDs to take keys.

datastore: Update AllocateIDs to take keys.

Update the Datastore's AllocateIDs call to accept variadic arguments similar
to Get/Put/Delete/Exists. Structs can be supplied to populate their keys
directly, and keys or key slices can be supplied to directly allocate keys.

This adds some Key helper functions:
- SameKind, which asserts that keys reference the same kind.
- Partial, which returns a partial key given a source key.
- WithID, which returns a derivative key with the specified ID.
- NewIncompleteKeys, which allocates a slice of incomplete keys given a kind.

BUG=

Committed: https://github.com/luci/gae/commit/a212da0491a31a03fb1e9fb21a328ac1dc72354c

[dnj (Google), 2016-05-24 17:57:44]

dnj@google.com changed reviewers:
+ dnj@google.com, iannucci@chromium.org

[dnj (Google), 2016-05-24 17:57:45]

PTAL.

iannucci@: This is in response to your comment in my cloud datastore CL that
this method should be updated to take keys.

https://chromiumcodereview.appspot.com/2007123002/diff/1/impl/dummy/dummy.go
File impl/dummy/dummy.go (left):

https://chromiumcodereview.appspot.com/2007123002/diff/1/impl/dummy/dummy.go#...
impl/dummy/dummy.go:86: func (ds) NewQuery(string) datastore.Query              
              { panic(ni()) }
(This isn't an interface method, so isn't used. golint rightfully complains that
this method copies ds.Query, which copies a lock, so I am removing it).

[dnj, 2016-05-31 06:58:10]

Description was changed from

==========
datastore: Update AllocateIDs to take keys.

Update the Datastore's AllocateIDs call to accept incomplete keys and
return populated keys. This brings it closer in line with Cloud
Datastore's AllocateIDs API, and removes the requirement that the
allocated IDs must be contiguous.

This adds some helper functions, namely SameKind, which asserts that two
keys reference the same kind, and NewIncompleteKeys, which allocates
slices of homogenous incomplete keys.

BUG=
==========

to

==========
datastore: Update AllocateIDs to take keys.

Update the Datastore's AllocateIDs call to accept variadic arguments similar
to Get/Put/Delete/Exists. Structs can be supplied to populate their keys
directly, and keys or key slices can be supplied to directly allocate keys.

This adds some Key helper functions:
- SameKind, which asserts that keys reference the same kind.
- Partial, which returns a partial key given a source key.
- WithID, which returns a derivative key with the specified ID.
- NewIncompleteKeys, which allocates a slice of incomplete keys given a kind.

BUG=
==========

[dnj, 2016-05-31 17:16:12]

PTAL! I have updated this per our discussions. It now takes a variadic set of
arguments like Get/Exists/Delete/Put, and populates key slices. It also handles
multiple entity types.

I need to add a few more tests, namely:
- test multiple entity types vs. impl/memory and impl/prod
- test failure cases, e.g., string IDs, "$gae,1"-style fixed IDs, etc.

The majority of the stuff works nicely though.

[iannucci, 2016-06-14 01:46:04]

awesome :) lgtm w/ nits

https://chromiumcodereview.appspot.com/2007123002/diff/40001/impl/memory/data...
File impl/memory/datastore_data.go (right):

https://chromiumcodereview.appspot.com/2007123002/diff/40001/impl/memory/data...
impl/memory/datastore_data.go:264: return -1, errors.New("disableSpecialEntities
is true so allocateIDs is disabled")
0 is an invalid id, this shouldn't need to be -1.

https://chromiumcodereview.appspot.com/2007123002/diff/40001/service/datastor...
File service/datastore/interface.go (right):

https://chromiumcodereview.appspot.com/2007123002/diff/40001/service/datastor...
service/datastore/interface.go:42: //	- *Key to populate a partial-valid key.
how can this work? Does it modify the Key in place? []*Key works because the
original slot can be written to with a new *Key. Otherwise a *Key is considered
to be immutable.

https://chromiumcodereview.appspot.com/2007123002/diff/40001/service/datastor...
File service/datastore/key.go (right):

https://chromiumcodereview.appspot.com/2007123002/diff/40001/service/datastor...
service/datastore/key.go:423: func (k *Key) SameKind(other *Key) (ret bool) {
This terminology is misleading. Kind means something else for Keys.
IncompleteEqual would be (maybe) clearer. e.g. 'if these were both incomplete
keys, would they be equal?'

https://chromiumcodereview.appspot.com/2007123002/diff/40001/service/datastor...
service/datastore/key.go:446: func (k *Key) Partial() *Key {
RemoveID? WithoutID?

https://chromiumcodereview.appspot.com/2007123002/diff/40001/service/datastor...
service/datastore/key.go:453: // WithID returns a key with the same kind as k,
but with the specified string
kind here is also confusing for the same reason.

https://chromiumcodereview.appspot.com/2007123002/diff/40001/service/datastor...
File service/datastore/raw_interface.go (right):

https://chromiumcodereview.appspot.com/2007123002/diff/40001/service/datastor...
service/datastore/raw_interface.go:113: AllocateIDs(keys []*Key, cb PutMultiCB)
error
maybe PutMultiCB should be renamed? Or duplicated and redocumented?

[dnj (Google), 2016-06-14 04:24:18]

Updated, cleaned up. PTAL for sanity when you get the chance.

https://chromiumcodereview.appspot.com/2007123002/diff/40001/impl/memory/data...
File impl/memory/datastore_data.go (right):

https://chromiumcodereview.appspot.com/2007123002/diff/40001/impl/memory/data...
impl/memory/datastore_data.go:264: return -1, errors.New("disableSpecialEntities
is true so allocateIDs is disabled")
On 2016/06/14 01:46:04, iannucci wrote:
> 0 is an invalid id, this shouldn't need to be -1.

Done.

https://chromiumcodereview.appspot.com/2007123002/diff/40001/service/datastor...
File service/datastore/interface.go (right):

https://chromiumcodereview.appspot.com/2007123002/diff/40001/service/datastor...
service/datastore/interface.go:42: //	- *Key to populate a partial-valid key.
On 2016/06/14 01:46:04, iannucci wrote:
> how can this work? Does it modify the Key in place? []*Key works because the
> original slot can be written to with a new *Key. Otherwise a *Key is
considered
> to be immutable.

Oh good point. Crap, okay, I'll remove this option.

https://chromiumcodereview.appspot.com/2007123002/diff/40001/service/datastor...
File service/datastore/key.go (right):

https://chromiumcodereview.appspot.com/2007123002/diff/40001/service/datastor...
service/datastore/key.go:423: func (k *Key) SameKind(other *Key) (ret bool) {
On 2016/06/14 01:46:04, iannucci wrote:
> This terminology is misleading. Kind means something else for Keys.
> IncompleteEqual would be (maybe) clearer. e.g. 'if these were both incomplete
> keys, would they be equal?'

Done.

https://chromiumcodereview.appspot.com/2007123002/diff/40001/service/datastor...
service/datastore/key.go:446: func (k *Key) Partial() *Key {
On 2016/06/14 01:46:04, iannucci wrote:
> RemoveID? WithoutID?

I changed "Incomplete" to "IsIncomplete" (asking question), and this to
"Incomplete".

https://chromiumcodereview.appspot.com/2007123002/diff/40001/service/datastor...
service/datastore/key.go:453: // WithID returns a key with the same kind as k,
but with the specified string
On 2016/06/14 01:46:04, iannucci wrote:
> kind here is also confusing for the same reason.

Done.

[dnj (Google), 2016-07-01 01:52:01]

The CQ bit was checked by dnj@google.com

[dnj (Google), 2016-07-01 01:52:02]

The patchset sent to the CQ was uploaded after l-g-t-m from
iannucci@chromium.org
Link to the patchset: https://chromiumcodereview.appspot.com/2007123002/#ps60001
(title: "Rebase, comments.")

[commit-bot: I haz the power, 2016-07-01 01:52:03]

CQ is trying da patch. Follow status at
 
https://chromium-cq-status.appspot.com/v2/patch-status/codereview.chromium.or...

[commit-bot: I haz the power, 2016-07-01 01:58:33]

Description was changed from

==========
datastore: Update AllocateIDs to take keys.

Update the Datastore's AllocateIDs call to accept variadic arguments similar
to Get/Put/Delete/Exists. Structs can be supplied to populate their keys
directly, and keys or key slices can be supplied to directly allocate keys.

This adds some Key helper functions:
- SameKind, which asserts that keys reference the same kind.
- Partial, which returns a partial key given a source key.
- WithID, which returns a derivative key with the specified ID.
- NewIncompleteKeys, which allocates a slice of incomplete keys given a kind.

BUG=
==========

to

==========
datastore: Update AllocateIDs to take keys.

Update the Datastore's AllocateIDs call to accept variadic arguments similar
to Get/Put/Delete/Exists. Structs can be supplied to populate their keys
directly, and keys or key slices can be supplied to directly allocate keys.

This adds some Key helper functions:
- SameKind, which asserts that keys reference the same kind.
- Partial, which returns a partial key given a source key.
- WithID, which returns a derivative key with the specified ID.
- NewIncompleteKeys, which allocates a slice of incomplete keys given a kind.

BUG=

Committed:
https://github.com/luci/gae/commit/a212da0491a31a03fb1e9fb21a328ac1dc72354c
==========

[commit-bot: I haz the power, 2016-07-01 01:58:34]

Committed patchset #4 (id:60001) as
https://github.com/luci/gae/commit/a212da0491a31a03fb1e9fb21a328ac1dc72354c