Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(508)

Side by Side Diff: service/datastore/interface.go

Issue 1259593005: Add 'user friendly' datastore API. (Closed) Base URL: https://github.com/luci/gae.git@master
Patch Set: more docs Created 5 years, 4 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
« no previous file with comments | « service/datastore/datastore_test.go ('k') | service/datastore/multiarg.go » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
(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 }
OLDNEW
« no previous file with comments | « service/datastore/datastore_test.go ('k') | service/datastore/multiarg.go » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698