OLD | NEW |
(Empty) | |
| 1 // Copyright 2015 The Chromium Authors. All rights reserved. |
| 2 // Use of this source code is governed by a BSD-style license that can be |
| 3 // found in the LICENSE file. |
| 4 |
| 5 package datastore |
| 6 |
| 7 import ( |
| 8 "golang.org/x/net/context" |
| 9 ) |
| 10 |
| 11 // RunCB is the callback signature provided to Interface.Run |
| 12 // |
| 13 // - obj is an object as specified by the proto argument of Run |
| 14 // - getCursor can be invoked to obtain the current cursor. |
| 15 // |
| 16 // Return true to continue iterating through the query results, or false to stop
. |
| 17 type RunCB func(obj interface{}, getCursor func() (Cursor, error)) bool |
| 18 |
| 19 // Interface is the 'user-friendly' interface to access the current filtered |
| 20 // datastore service implementation. |
| 21 // |
| 22 // Note that in exchange for userfriendliness, this interface ends up doing |
| 23 // a lot of reflection. |
| 24 // |
| 25 // Methods taking 'interface{}' objects describe what a valid type for that |
| 26 // interface are in the comments. |
| 27 // |
| 28 // Struct objects passed in will be converted to PropertyLoadSaver interfaces |
| 29 // using this package's GetPLS function. |
| 30 type Interface interface { |
| 31 // NewKey produces a new Key with the current appid and namespace. |
| 32 NewKey(kind, stringID string, intID int64, parent Key) Key |
| 33 |
| 34 // KeyForObj extracts a key from src. |
| 35 // |
| 36 // It is the same as KeyForObjErr, except that if KeyForObjErr would hav
e |
| 37 // returned an error, this method panics. It's safe to use if you know t
hat |
| 38 // src statically meets the metadata constraints described by KeyForObjE
rr. |
| 39 KeyForObj(src interface{}) Key |
| 40 |
| 41 // KeyForObjErr extracts a key from src. |
| 42 // |
| 43 // src must be one of: |
| 44 // - *S where S is a struct |
| 45 // - a PropertyLoadSaver |
| 46 // |
| 47 // It is expected that the struct or PropertyLoadSaver exposes the |
| 48 // following metadata (as retrieved by PropertyLoadSaver.GetMeta): |
| 49 // - "key" (type: Key) - The full datastore key to use. Must not be ni
l. |
| 50 // OR |
| 51 // - "id" (type: int64 or string) - The id of the Key to create |
| 52 // - "kind" (optional, type: string) - The kind of the Key to create.
If |
| 53 // blank or not present, KeyForObjErr will extract the name of the s
rc |
| 54 // object's type. |
| 55 // - "parent" (optional, type: Key) - The parent key to use. |
| 56 // |
| 57 // If a required metadata item is missing or of the wrong type, then thi
s will |
| 58 // return an error. |
| 59 KeyForObjErr(src interface{}) (Key, error) |
| 60 |
| 61 // DecodeKey decodes a proto-encoded key. |
| 62 // |
| 63 // The encoding is defined by the appengine SDK's implementation. In |
| 64 // particular, it is a no-pad-base64-encoded protobuf. If there's an err
or |
| 65 // during the decoding process, it will be returned. |
| 66 DecodeKey(encoded string) (Key, error) |
| 67 |
| 68 // NewQuery creates a new Query object. No server communication occurs. |
| 69 NewQuery(kind string) Query |
| 70 |
| 71 // RunInTransaction runs f inside of a transaction. See the appengine SD
K's |
| 72 // documentation for full details on the behavior of transactions in the |
| 73 // datastore. |
| 74 // |
| 75 // Note that the behavior of transactions may change depending on what f
ilters |
| 76 // have been installed. It's possible that we'll end up implementing thi
ngs |
| 77 // like nested/buffered transactions as filters. |
| 78 RunInTransaction(f func(c context.Context) error, opts *TransactionOptio
ns) error |
| 79 |
| 80 // Run executes the given query, and calls `cb` for each successfully |
| 81 // retrieved item. |
| 82 // |
| 83 // proto is a prototype of the objects which will be passed to the callb
ack. |
| 84 // It will be used solely for type information, and the actual proto obj
ect |
| 85 // may be zero/nil. It must be of the form: |
| 86 // - S or *S where S is a struct |
| 87 // - P or *P where *P is a concrete type implementing PropertyLoadSave
r |
| 88 // - *Key implies a keys-only query (and cb will be invoked with Key o
bjects) |
| 89 // Run will create a new, populated instance of proto for each call of |
| 90 // cb. Run stops on the first error encountered. |
| 91 Run(q Query, proto interface{}, cb RunCB) error |
| 92 |
| 93 // GetAll retrieves all of the Query results into dst. |
| 94 // |
| 95 // dst must be one of: |
| 96 // - *[]S or *[]*S where S is a struct |
| 97 // - *[]P or *[]*P where *P is a concrete type implementing PropertyLo
adSaver |
| 98 // - *[]Key implies a keys-only query. |
| 99 GetAll(q Query, dst interface{}) error |
| 100 |
| 101 // Get retrieves a single object from the datastore |
| 102 // |
| 103 // dst must be one of: |
| 104 // - *S where S is a struct |
| 105 // - *P where *P is a concrete type implementing PropertyLoadSaver |
| 106 Get(dst interface{}) error |
| 107 |
| 108 // Put inserts a single object into the datastore |
| 109 // |
| 110 // src must be one of: |
| 111 // - *S where S is a struct |
| 112 // - *P where *P is a concrete type implementing PropertyLoadSaver |
| 113 // |
| 114 // A Key will be extracted from src via KeyForObj. If |
| 115 // KeyIncomplete(extractedKey) is true, then Put will write the resolved
(i.e. |
| 116 // automatic datastore-populated) Key back to src. |
| 117 Put(src interface{}) error |
| 118 |
| 119 // Delete removes an item from the datastore. |
| 120 Delete(key Key) error |
| 121 |
| 122 // GetMulti retrieves items from the datastore. |
| 123 // |
| 124 // dst must be one of: |
| 125 // - []S or []*S where S is a struct |
| 126 // - []P or []*P where *P is a concrete type implementing PropertyLoad
Saver |
| 127 // - []I where I is some interface type. Each element of the slice mus
t |
| 128 // be non-nil, and its underlying type must be either *S o
r *P. |
| 129 GetMulti(dst interface{}) error |
| 130 |
| 131 // PutMulti writes items to the datastore. |
| 132 // |
| 133 // src must be one of: |
| 134 // - []S or []*S where S is a struct |
| 135 // - []P or []*P where *P is a concrete type implementing PropertyLoad
Saver |
| 136 // - []I where i is some interface type. Each elemet of the slice must |
| 137 // be non-nil, and its underlying type must be either *S or *P. |
| 138 // |
| 139 // If items in src resolve to Incomplete keys, PutMulti will write the |
| 140 // resolved keys back to the items in src. |
| 141 PutMulti(src interface{}) error |
| 142 |
| 143 // DeleteMulti removes items from the datastore. |
| 144 DeleteMulti(keys []Key) error |
| 145 |
| 146 // Raw returns the underlying RawInterface. The Interface and RawInterfa
ce may |
| 147 // be used interchangably; there's no danger of interleaving access to t
he |
| 148 // datastore via the two. |
| 149 Raw() RawInterface |
| 150 } |
OLD | NEW |