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
};
213

214