Debian Codegraph @

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

raw
1 // Copyright 2012 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 a IndexedDB cursor.
17 *
18 */
19
20
21 goog.provide('goog.db.Cursor');
22
23 goog.require('goog.async.Deferred');
24 goog.require('goog.db.Error');
25 goog.require('goog.db.KeyRange');
26 goog.require('goog.debug');
27 goog.require('goog.events.EventTarget');
28
29
30
31 /**
32 * Creates a new IDBCursor wrapper object. Should not be created directly,
33 * access cursor through object store.
34 * @see goog.db.ObjectStore#openCursor
35 *
36 * @constructor
37 * @extends {goog.events.EventTarget}
38 * @final
39 */
40 goog.db.Cursor = function() {
41 goog.db.Cursor.base(this, 'constructor');
42 };
43 goog.inherits(goog.db.Cursor, goog.events.EventTarget);
44
45
46 /**
47 * Underlying IndexedDB cursor object.
48 *
49 * @type {IDBCursor}
50 * @private
51 */
52 goog.db.Cursor.prototype.cursor_ = null;
53
54
55 /**
56 * Advances the cursor to the next position along its direction. When new data
57 * is available, the NEW_DATA event will be fired. If the cursor has reached the
58 * end of the range it will fire the COMPLETE event. If opt_key is specified it
59 * will advance to the key it matches in its direction.
60 *
61 * This wraps the native #continue method on the underlying object.
62 *
63 * @param {IDBKeyType=} opt_key The optional key to advance to.
64 */
65 goog.db.Cursor.prototype.next = function(opt_key) {
66 if (opt_key) {
67 this.cursor_['continue'](opt_key);
68 } else {
69 this.cursor_['continue']();
70 }
71 };
72
73
74 /**
75 * Updates the value at the current position of the cursor in the object store.
76 * If the cursor points to a value that has just been deleted, a new value is
77 * created.
78 *
79 * @param {*} value The value to be stored.
80 * @return {!goog.async.Deferred} The resulting deferred request.
81 */
82 goog.db.Cursor.prototype.update = function(value) {
83 var msg = 'updating via cursor with value ';
84 var d = new goog.async.Deferred();
85 var request;
86
87 try {
88 request = this.cursor_.update(value);
89 } catch (err) {
90 msg += goog.debug.deepExpose(value);
91 d.errback(goog.db.Error.fromException(err, msg));
92 return d;
93 }
94 request.onsuccess = function(ev) { d.callback(); };
95 request.onerror = function(ev) {
96 msg += goog.debug.deepExpose(value);
97 d.errback(goog.db.Error.fromRequest(ev.target, msg));
98 };
99 return d;
100 };
101
102
103 /**
104 * Deletes the value at the cursor's position, without changing the cursor's
105 * position. Once the value is deleted, the cursor's value is set to null.
106 *
107 * @return {!goog.async.Deferred} The resulting deferred request.
108 */
109 goog.db.Cursor.prototype.remove = function() {
110 var msg = 'deleting via cursor';
111 var d = new goog.async.Deferred();
112 var request;
113
114 try {
115 request = this.cursor_['delete']();
116 } catch (err) {
117 d.errback(goog.db.Error.fromException(err, msg));
118 return d;
119 }
120 request.onsuccess = function(ev) { d.callback(); };
121 request.onerror = function(ev) {
122 d.errback(goog.db.Error.fromRequest(ev.target, msg));
123 };
124 return d;
125 };
126
127
128 /**
129 * @return {*} The value for the value at the cursor's position. Undefined
130 * if no current value, or null if value has just been deleted.
131 */
132 goog.db.Cursor.prototype.getValue = function() {
133 return this.cursor_['value'];
134 };
135
136
137 /**
138 * @return {IDBKeyType} The key for the value at the cursor's position. If
139 * the cursor is outside its range, this is undefined.
140 */
141 goog.db.Cursor.prototype.getKey = function() {
142 return this.cursor_.key;
143 };
144
145
146 /**
147 * Opens a value cursor from IDBObjectStore or IDBIndex over the specified key
148 * range. Returns a cursor object which is able to iterate over the given range.
149 * @param {!(IDBObjectStore|IDBIndex)} source Data source to open cursor.
150 * @param {!goog.db.KeyRange=} opt_range The key range. If undefined iterates
151 * over the whole data source.
152 * @param {!goog.db.Cursor.Direction=} opt_direction The direction. If undefined
153 * moves in a forward direction with duplicates.
154 * @return {!goog.db.Cursor} The cursor.
155 * @throws {goog.db.Error} If there was a problem opening the cursor.
156 */
157 goog.db.Cursor.openCursor = function(source, opt_range, opt_direction) {
158 var cursor = new goog.db.Cursor();
159 var request;
160
161 try {
162 var range = opt_range ? opt_range.range() : null;
163 if (opt_direction) {
164 request = source.openCursor(range, opt_direction);
165 } else {
166 request = source.openCursor(range);
167 }
168 } catch (ex) {
169 cursor.dispose();
170 throw goog.db.Error.fromException(ex, source.name);
171 }
172 request.onsuccess = function(e) {
173 cursor.cursor_ = e.target.result || null;
174 if (cursor.cursor_) {
175 cursor.dispatchEvent(goog.db.Cursor.EventType.NEW_DATA);
176 } else {
177 cursor.dispatchEvent(goog.db.Cursor.EventType.COMPLETE);
178 }
179 };
180 request.onerror = function(e) {
181 cursor.dispatchEvent(goog.db.Cursor.EventType.ERROR);
182 };
183 return cursor;
184 };
185
186
187 /**
188 * Possible cursor directions.
189 * @see http://www.w3.org/TR/IndexedDB/#idl-def-IDBCursor
190 *
191 * @enum {string}
192 */
193 goog.db.Cursor.Direction = {
194 NEXT: 'next',
195 NEXT_NO_DUPLICATE: 'nextunique',
196 PREV: 'prev',
197 PREV_NO_DUPLICATE: 'prevunique'
198 };
199
200
201 /**
202 * Event types that the cursor can dispatch. COMPLETE events are dispatched when
203 * a cursor is depleted of values, a NEW_DATA event if there is new data
204 * available, and ERROR if an error occurred.
205 *
206 * @enum {string}
207 */
208 goog.db.Cursor.EventType = {
209 COMPLETE: 'c',
210 ERROR: 'e',
211 NEW_DATA: 'n'
212 };