datastore: Update AllocateIDs to take keys.

service/datastore/interface.go

 // Copyright 2015 The LUCI Authors. All rights reserved.
 // Use of this source code is governed under the Apache License, Version 2.0
 // that can be found in the LICENSE file.
 
 package datastore
 
 import (
         "golang.org/x/net/context"
 )
 
 // Interface is the 'user-friendly' interface to access the current filtered
 // datastore service implementation.
 //
 // Note that in exchange for userfriendliness, this interface ends up doing
 // a lot of reflection.
 //
 // Methods taking 'interface{}' objects describe what a valid type for that
 // interface are in the comments.
 //
 // Struct objects passed in will be converted to PropertyLoadSaver interfaces
 // using this package's GetPLS function.
 type Interface interface {
         // AllocateIDs allows you to allocate IDs from the datastore without putting
-        // any data. `incomplete` must be a PartialValid Key. If there's no error,
-        // a contiguous block of IDs of n length starting at `start` will be reserved
-        // indefinitely for the user application code for use in new keys. The
-        // appengine automatic ID generator will never automatically assign these IDs
-        // for Keys of this type.
-        AllocateIDs(incomplete *Key, n int) (start int64, err error)
+        // any data.
+        //
+        // A partial valid key will be constructed from each entity's kind and parent,
+        // if present. An allocation will then be performed against the datastore for
+        // each key, and the partial key will be populated with a unique integer ID.
+        // The resulting keys will be applied to their objects using PopulateKey. If
+        // successful, any existing ID will be destroyed.
+        //
+        // If the object is supplied that cannot accept an integer key, this method
+        // will panic.
+        //
+        // ent must be one of:
+        //      - *S where S is a struct
+        //      - *P where *P is a concrete type implementing PropertyLoadSaver
+        //      - []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.
+        //      - []*Key, to populate a slice of partial-valid keys.
+        //
+        // If an error is encountered, the returned error value will depend on the
+        // input arguments. If one argument is supplied, the result will be the
+        // encountered error type. If multiple arguments are supplied, the result will
+        // be a MultiError whose error index corresponds to the argument in which the
+        // error was encountered.
+        //
+        // If an ent argument is a slice, its error type will be a MultiError. Note
+        // that in the scenario where multiple slices are provided, this will return a
+        // MultiError containing a nested MultiError for each slice argument.
+        AllocateIDs(ent ...interface{}) error
 
         // KeyForObj extracts a key from src.
         //
         // It is the same as KeyForObjErr, except that if KeyForObjErr would have
         // returned an error, this method panics. It's safe to use if you know that
         // src statically meets the metadata constraints described by KeyForObjErr.
         KeyForObj(src interface{}) *Key
 
         // MakeKey is a convenience method for manufacturing a *Key. It should only be
         // used when elems... is known statically (e.g. in the code) to be correct.
         //
         // elems is pairs of (string, string|int|int32|int64) pairs, which correspond
         // to Kind/id pairs. Example:
         //   dstore.MakeKey("Parent", 1, "Child", "id")
         //
         // Would create the key:
         //   <current appID>:<current Namespace>:/Parent,1/Child,id
         //
         // If elems is not parsable (e.g. wrong length, wrong types, etc.) this method
         // will panic.
         MakeKey(elems ...interface{}) *Key
 
         // NewKey constructs a new key in the current appID/Namespace, using the
         // specified parameters.
         NewKey(kind, stringID string, intID int64, parent *Key) *Key
 
+        // NewIncompleteKeys allocates count incomplete keys sharing the same kind and
+        // parent. It is useful as input to AllocateIDs.
+        NewIncompleteKeys(count int, kind string, parent *Key) []*Key
+
         // NewKeyToks constructs a new key in the current appID/Namespace, using the
         // specified key tokens.
         NewKeyToks([]KeyTok) *Key
 
         // KeyForObjErr extracts a key from src.
         //
         // src must be one of:
         //   - *S, where S is a struct
         //   - a PropertyLoadSaver
         //
@@ skipping 131 matching lines @@
         //   - []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.
         //
         // NOTE: GetMulti is obsolete. The vararg-accepting Get should be used
         // instead. This is left for backwards compatibility, but will be removed from
         // this interface at some point in the future.
         GetMulti(dst interface{}) error
 
-        // Put inserts a single object into the datastore
+        // Put writes objects into the datastore.
         //
         // src must be one of:
         //      - *S, where S is a struct
         //      - *P, where *P is a concrete type implementing PropertyLoadSaver
         //      - []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.
         //
         // A *Key will be extracted from src via KeyForObj. If
@@ skipping 62 matching lines @@
 
         // Testable returns the Testable interface for the implementation, or nil if
         // there is none.
         Testable() Testable
 
         // 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
 }