Debian Codegraph @

closure-library/closure/goog/db/objectstore.js

raw
1 // Copyright 2011 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview Wrapper for an IndexedDB object store.
17 *
18 */
19
20
21 goog.provide('goog.db.ObjectStore');
22
23 goog.require('goog.async.Deferred');
24 goog.require('goog.db.Cursor');
25 goog.require('goog.db.Error');
26 goog.require('goog.db.Index');
27 goog.require('goog.db.KeyRange');
28 goog.require('goog.debug');
29 goog.require('goog.events');
30
31
32
33 /**
34 * Creates an IDBObjectStore wrapper object. Object stores have methods for
35 * storing and retrieving records, and are accessed through a transaction
36 * object. They also have methods for creating indexes associated with the
37 * object store. They can only be created when setting the version of the
38 * database. Should not be created directly, access object stores through
39 * transactions.
40 * @see goog.db.UpgradeNeededCallback
41 * @see goog.db.Transaction#objectStore
42 *
43 * @param {!IDBObjectStore} store The backing IndexedDb object.
44 * @constructor
45 * @final
46 *
47 * TODO(arthurhsu): revisit msg in exception and errors in this class. In newer
48 * Chrome (v22+) the error/request come with a DOM error string that is
49 * already very descriptive.
50 */
51 goog.db.ObjectStore = function(store) {
52 /**
53 * Underlying IndexedDB object store object.
54 *
55 * @type {!IDBObjectStore}
56 * @private
57 */
58 this.store_ = store;
59 };
60
61
62 /**
63 * @return {string} The name of the object store.
64 */
65 goog.db.ObjectStore.prototype.getName = function() {
66 return this.store_.name;
67 };
68
69
70 /**
71 * Helper function for put and add.
72 *
73 * @param {string} fn Function name to call on the object store.
74 * @param {string} msg Message to give to the error.
75 * @param {*} value Value to insert into the object store.
76 * @param {IDBKeyType=} opt_key The key to use.
77 * @return {!goog.async.Deferred} The resulting deferred request.
78 * @private
79 */
80 goog.db.ObjectStore.prototype.insert_ = function(fn, msg, value, opt_key) {
81 // TODO(user): refactor wrapping an IndexedDB request in a Deferred by
82 // creating a higher-level abstraction for it (mostly affects here and
83 // goog.db.Index)
84 var d = new goog.async.Deferred();
85 var request;
86 try {
87 // put or add with (value, undefined) throws an error, so we need to check
88 // for undefined ourselves
89 if (opt_key) {
90 request = this.store_[fn](value, opt_key);
91 } else {
92 request = this.store_[fn](value);
93 }
94 } catch (ex) {
95 msg += goog.debug.deepExpose(value);
96 if (opt_key) {
97 msg += ', with key ' + goog.debug.deepExpose(opt_key);
98 }
99 d.errback(goog.db.Error.fromException(ex, msg));
100 return d;
101 }
102 request.onsuccess = function(ev) {
103 d.callback(ev.target.result);
104 };
105 request.onerror = function(ev) {
106 msg += goog.debug.deepExpose(value);
107 if (opt_key) {
108 msg += ', with key ' + goog.debug.deepExpose(opt_key);
109 }
110 d.errback(goog.db.Error.fromRequest(ev.target, msg));
111 };
112 return d;
113 };
114
115
116 /**
117 * Adds an object to the object store. Replaces existing objects with the
118 * same key.
119 *
120 * @param {*} value The value to put.
121 * @param {IDBKeyType=} opt_key The key to use. Cannot be used if the
122 * keyPath was specified for the object store. If the keyPath was not
123 * specified but autoIncrement was not enabled, it must be used.
124 * @return {!goog.async.Deferred} The deferred put request.
125 */
126 goog.db.ObjectStore.prototype.put = function(value, opt_key) {
127 return this.insert_(
128 'put', 'putting into ' + this.getName() + ' with value', value, opt_key);
129 };
130
131
132 /**
133 * Adds an object to the object store. Requires that there is no object with
134 * the same key already present.
135 *
136 * @param {*} value The value to add.
137 * @param {IDBKeyType=} opt_key The key to use. Cannot be used if the
138 * keyPath was specified for the object store. If the keyPath was not
139 * specified but autoIncrement was not enabled, it must be used.
140 * @return {!goog.async.Deferred} The deferred add request.
141 */
142 goog.db.ObjectStore.prototype.add = function(value, opt_key) {
143 return this.insert_(
144 'add', 'adding into ' + this.getName() + ' with value ', value, opt_key);
145 };
146
147
148 /**
149 * Removes an object from the store. No-op if there is no object present with
150 * the given key.
151 *
152 * @param {IDBKeyType|!goog.db.KeyRange} keyOrRange The key or range to remove
153 * objects under.
154 * @return {!goog.async.Deferred} The deferred remove request.
155 */
156 goog.db.ObjectStore.prototype.remove = function(keyOrRange) {
157 var d = new goog.async.Deferred();
158 var request;
159 try {
160 request = this.store_['delete'](
161 keyOrRange instanceof goog.db.KeyRange ? keyOrRange.range() :
162 keyOrRange);
163 } catch (err) {
164 var msg = 'removing from ' + this.getName() + ' with key ' +
165 goog.debug.deepExpose(keyOrRange);
166 d.errback(goog.db.Error.fromException(err, msg));
167 return d;
168 }
169 request.onsuccess = function(ev) { d.callback(); };
170 var self = this;
171 request.onerror = function(ev) {
172 var msg = 'removing from ' + self.getName() + ' with key ' +
173 goog.debug.deepExpose(keyOrRange);
174 d.errback(goog.db.Error.fromRequest(ev.target, msg));
175 };
176 return d;
177 };
178
179
180 /**
181 * Gets an object from the store. If no object is present with that key
182 * the result is {@code undefined}.
183 *
184 * @param {IDBKeyType} key The key to look up.
185 * @return {!goog.async.Deferred} The deferred get request.
186 */
187 goog.db.ObjectStore.prototype.get = function(key) {
188 var d = new goog.async.Deferred();
189 var request;
190 try {
191 request = this.store_.get(key);
192 } catch (err) {
193 var msg = 'getting from ' + this.getName() + ' with key ' +
194 goog.debug.deepExpose(key);
195 d.errback(goog.db.Error.fromException(err, msg));
196 return d;
197 }
198 request.onsuccess = function(ev) { d.callback(ev.target.result); };
199 var self = this;
200 request.onerror = function(ev) {
201 var msg = 'getting from ' + self.getName() + ' with key ' +
202 goog.debug.deepExpose(key);
203 d.errback(goog.db.Error.fromRequest(ev.target, msg));
204 };
205 return d;
206 };
207
208
209 /**
210 * Gets all objects from the store and returns them as an array.
211 *
212 * @param {!goog.db.KeyRange=} opt_range The key range. If undefined iterates
213 * over the whole object store.
214 * @param {!goog.db.Cursor.Direction=} opt_direction The direction. If undefined
215 * moves in a forward direction with duplicates.
216 * @return {!goog.async.Deferred} The deferred getAll request.
217 */
218 goog.db.ObjectStore.prototype.getAll = function(opt_range, opt_direction) {
219 var d = new goog.async.Deferred();
220 var cursor;
221 try {
222 cursor = this.openCursor(opt_range, opt_direction);
223 } catch (err) {
224 d.errback(err);
225 return d;
226 }
227
228 var result = [];
229 goog.events.listen(cursor, goog.db.Cursor.EventType.NEW_DATA, function() {
230 result.push(cursor.getValue());
231 cursor.next();
232 });
233
234 goog.events.listenOnce(
235 cursor,
236 [goog.db.Cursor.EventType.ERROR, goog.db.Cursor.EventType.COMPLETE],
237 function(evt) {
238 cursor.dispose();
239 if (evt.type == goog.db.Cursor.EventType.COMPLETE) {
240 d.callback(result);
241 } else {
242 d.errback();
243 }
244 });
245 return d;
246 };
247
248
249 /**
250 * Gets an object from the store. If no object is present with that key
251 * the result is {@code undefined}.
252 *
253 * @return {!goog.async.Deferred} The deferred getAllKeys request.
254 */
255 goog.db.ObjectStore.prototype.getAllKeys = function() {
256 var d = new goog.async.Deferred();
257 var request;
258 try {
259 request = this.store_.getAllKeys();
260 } catch (err) {
261 var msg = 'getting all keys from ' + this.getName();
262 d.errback(goog.db.Error.fromException(err, msg));
263 return d;
264 }
265 request.onsuccess = function(ev) {
266 d.callback(ev.target.result);
267 };
268 var self = this;
269 request.onerror = function(ev) {
270 var msg = 'getting all keys from ' + self.getName();
271 d.errback(goog.db.Error.fromRequest(ev.target, msg));
272 };
273 return d;
274 };
275
276
277 /**
278 * Opens a cursor over the specified key range. Returns a cursor object which is
279 * able to iterate over the given range.
280 *
281 * Example usage:
282 *
283 * <code>
284 * var cursor = objectStore.openCursor(goog.db.Range.bound('a', 'c'));
285 *
286 * var key = goog.events.listen(
287 * cursor, goog.db.Cursor.EventType.NEW_DATA, function() {
288 * // Do something with data.
289 * cursor.next();
290 * });
291 *
292 * goog.events.listenOnce(
293 * cursor, goog.db.Cursor.EventType.COMPLETE, function() {
294 * // Clean up listener, and perform a finishing operation on the data.
295 * goog.events.unlistenByKey(key);
296 * });
297 * </code>
298 *
299 * @param {!goog.db.KeyRange=} opt_range The key range. If undefined iterates
300 * over the whole object store.
301 * @param {!goog.db.Cursor.Direction=} opt_direction The direction. If undefined
302 * moves in a forward direction with duplicates.
303 * @return {!goog.db.Cursor} The cursor.
304 * @throws {goog.db.Error} If there was a problem opening the cursor.
305 */
306 goog.db.ObjectStore.prototype.openCursor = function(opt_range, opt_direction) {
307 return goog.db.Cursor.openCursor(this.store_, opt_range, opt_direction);
308 };
309
310
311 /**
312 * Deletes all objects from the store.
313 *
314 * @return {!goog.async.Deferred} The deferred clear request.
315 */
316 goog.db.ObjectStore.prototype.clear = function() {
317 var msg = 'clearing store ' + this.getName();
318 var d = new goog.async.Deferred();
319 var request;
320 try {
321 request = this.store_.clear();
322 } catch (err) {
323 d.errback(goog.db.Error.fromException(err, msg));
324 return d;
325 }
326 request.onsuccess = function(ev) { d.callback(); };
327 request.onerror = function(ev) {
328 d.errback(goog.db.Error.fromRequest(ev.target, msg));
329 };
330 return d;
331 };
332
333
334 /**
335 * Creates an index in this object store. Can only be called inside a
336 * {@link goog.db.UpgradeNeededCallback}.
337 *
338 * @param {string} name Name of the index to create.
339 * @param {string|!Array<string>} keyPath Attribute or array of attributes to
340 * index on.
341 * @param {!Object=} opt_parameters Optional parameters object. The only
342 * available option is unique, which defaults to false. If unique is true,
343 * the index will enforce that there is only ever one object in the object
344 * store for each unique value it indexes on.
345 * @return {!goog.db.Index} The newly created, wrapped index.
346 * @throws {goog.db.Error} In case of an error creating the index.
347 */
348 goog.db.ObjectStore.prototype.createIndex = function(
349 name, keyPath, opt_parameters) {
350 try {
351 return new goog.db.Index(
352 this.store_.createIndex(name, keyPath, opt_parameters));
353 } catch (ex) {
354 var msg = 'creating new index ' + name + ' with key path ' + keyPath;
355 throw goog.db.Error.fromException(ex, msg);
356 }
357 };
358
359
360 /**
361 * Gets an index.
362 *
363 * @param {string} name Name of the index to fetch.
364 * @return {!goog.db.Index} The requested wrapped index.
365 * @throws {goog.db.Error} In case of an error getting the index.
366 */
367 goog.db.ObjectStore.prototype.getIndex = function(name) {
368 try {
369 return new goog.db.Index(this.store_.index(name));
370 } catch (ex) {
371 var msg = 'getting index ' + name;
372 throw goog.db.Error.fromException(ex, msg);
373 }
374 };
375
376
377 /**
378 * Deletes an index from the object store. Can only be called inside a
379 * {@link goog.db.UpgradeNeededCallback}.
380 *
381 * @param {string} name Name of the index to delete.
382 * @throws {goog.db.Error} In case of an error deleting the index.
383 */
384 goog.db.ObjectStore.prototype.deleteIndex = function(name) {
385 try {
386 this.store_.deleteIndex(name);
387 } catch (ex) {
388 var msg = 'deleting index ' + name;
389 throw goog.db.Error.fromException(ex, msg);
390 }
391 };
392
393
394 /**
395 * Gets number of records within a key range.
396 *
397 * @param {!goog.db.KeyRange=} opt_range The key range. If undefined, this will
398 * count all records in the object store.
399 * @return {!goog.async.Deferred} The deferred number of records.
400 */
401 goog.db.ObjectStore.prototype.count = function(opt_range) {
402 var d = new goog.async.Deferred();
403
404 try {
405 var range = opt_range ? opt_range.range() : null;
406 var request = this.store_.count(range);
407 request.onsuccess = function(ev) { d.callback(ev.target.result); };
408 var self = this;
409 request.onerror = function(ev) {
410 d.errback(goog.db.Error.fromRequest(ev.target, self.getName()));
411 };
412 } catch (ex) {
413 d.errback(goog.db.Error.fromException(ex, this.getName()));
414 }
415
416 return d;
417 };