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 index.
17
 *
18
 */
19

20

21
goog.provide('goog.db.Index');
22

23
goog.require('goog.async.Deferred');
24
goog.require('goog.db.Cursor');
25
goog.require('goog.db.Error');
26
goog.require('goog.db.KeyRange');
27
goog.require('goog.debug');
28

29

30

31
/**
32
 * Creates an IDBIndex wrapper object. Indexes are associated with object
33
 * stores and provide methods for looking up objects based on their non-key
34
 * properties. Should not be created directly, access through the object store
35
 * it belongs to.
36
 * @see goog.db.ObjectStore#getIndex
37
 *
38
 * @param {!IDBIndex} index Underlying IDBIndex object.
39
 * @constructor
40
 * @final
41
 */
42
goog.db.Index = function(index) {
43
  /**
44
   * Underlying IndexedDB index object.
45
   *
46
   * @type {!IDBIndex}
47
   * @private
48
   */
49
  this.index_ = index;
50
};
51

52

53
/**
54
 * @return {string} Name of the index.
55
 */
56
goog.db.Index.prototype.getName = function() {
57
  return this.index_.name;
58
};
59

60

61
/**
62
 * @return {*} Key path of the index.
63
 */
64
goog.db.Index.prototype.getKeyPath = function() {
65
  return this.index_.keyPath;
66
};
67

68

69
/**
70
 * @return {boolean} True if the index enforces that there is only one object
71
 *     for each unique value it indexes on.
72
 */
73
goog.db.Index.prototype.isUnique = function() {
74
  return this.index_.unique;
75
};
76

77

78
/**
79
 * Helper function for get and getKey.
80
 *
81
 * @param {string} fn Function name to call on the index to get the request.
82
 * @param {string} msg Message to give to the error.
83
 * @param {IDBKeyType} key The key to look up in the index.
84
 * @return {!goog.async.Deferred} The resulting deferred object.
85
 * @private
86
 */
87
goog.db.Index.prototype.get_ = function(fn, msg, key) {
88
  var d = new goog.async.Deferred();
89
  var request;
90
  try {
91
    request = this.index_[fn](key);
92
  } catch (err) {
93
    msg += ' with key ' + goog.debug.deepExpose(key);
94
    d.errback(goog.db.Error.fromException(err, msg));
95
    return d;
96
  }
97
  request.onsuccess = function(ev) { d.callback(ev.target.result); };
98
  request.onerror = function(ev) {
99
    msg += ' with key ' + goog.debug.deepExpose(key);
100
    d.errback(goog.db.Error.fromRequest(ev.target, msg));
101
  };
102
  return d;
103
};
104

105

106
/**
107
 * Fetches a single object from the object store. Even if there are multiple
108
 * objects that match the given key, this method will get only one of them.
109
 *
110
 * @param {IDBKeyType} key Key to look up in the index.
111
 * @return {!goog.async.Deferred} The deferred object for the given record.
112
 */
113
goog.db.Index.prototype.get = function(key) {
114
  return this.get_('get', 'getting from index ' + this.getName(), key);
115
};
116

117

118
/**
119
 * Looks up a single object from the object store and gives back the key that
120
 * it's listed under in the object store. Even if there are multiple records
121
 * that match the given key, this method returns the first.
122
 *
123
 * @param {IDBKeyType} key Key to look up in the index.
124
 * @return {!goog.async.Deferred} The deferred key for the record that matches
125
 *     the key.
126
 */
127
goog.db.Index.prototype.getKey = function(key) {
128
  return this.get_('getKey', 'getting key from index ' + this.getName(), key);
129
};
130

131

132
/**
133
 * Helper function for getAll and getAllKeys.
134
 *
135
 * @param {string} fn Function name to call on the index to get the request.
136
 * @param {string} msg Message to give to the error.
137
 * @param {IDBKeyType=} opt_key Key to look up in the index.
138
 * @return {!goog.async.Deferred} The resulting deferred array of objects.
139
 * @private
140
 */
141
goog.db.Index.prototype.getAll_ = function(fn, msg, opt_key) {
142
  // This is the most common use of IDBKeyRange. If more specific uses of
143
  // cursors are needed then a full wrapper should be created.
144
  var IDBKeyRange = goog.global.IDBKeyRange || goog.global.webkitIDBKeyRange;
145
  var d = new goog.async.Deferred();
146
  var request;
147
  try {
148
    if (opt_key) {
149
      request = this.index_[fn](IDBKeyRange.only(opt_key));
150
    } else {
151
      request = this.index_[fn]();
152
    }
153
  } catch (err) {
154
    if (opt_key) {
155
      msg += ' for key ' + goog.debug.deepExpose(opt_key);
156
    }
157
    d.errback(goog.db.Error.fromException(err, msg));
158
    return d;
159
  }
160
  var result = [];
161
  request.onsuccess = function(ev) {
162
    var cursor = ev.target.result;
163
    if (cursor) {
164
      result.push(cursor.value);
165
      cursor['continue']();
166
    } else {
167
      d.callback(result);
168
    }
169
  };
170
  request.onerror = function(ev) {
171
    if (opt_key) {
172
      msg += ' for key ' + goog.debug.deepExpose(opt_key);
173
    }
174
    d.errback(goog.db.Error.fromRequest(ev.target, msg));
175
  };
176
  return d;
177
};
178

179

180
/**
181
 * Gets all indexed objects. If the key is provided, gets all indexed objects
182
 * that match the key instead.
183
 *
184
 * @param {IDBKeyType=} opt_key Key to look up in the index.
185
 * @return {!goog.async.Deferred} A deferred array of objects that match the
186
 *     key.
187
 */
188
goog.db.Index.prototype.getAll = function(opt_key) {
189
  return this.getAll_(
190
      'openCursor', 'getting all from index ' + this.getName(), opt_key);
191
};
192

193

194
/**
195
 * Gets the keys to look up all the indexed objects. If the key is provided,
196
 * gets all records for objects that match the key instead.
197
 *
198
 * @param {IDBKeyType=} opt_key Key to look up in the index.
199
 * @return {!goog.async.Deferred} A deferred array of keys for objects that
200
 *     match the key.
201
 */
202
goog.db.Index.prototype.getAllKeys = function(opt_key) {
203
  return this.getAll_(
204
      'openKeyCursor', 'getting all keys from index ' + this.getName(),
205
      opt_key);
206
};
207

208

209
/**
210
 * Opens a cursor over the specified key range. Returns a cursor object which is
211
 * able to iterate over the given range.
212
 *
213
 * Example usage:
214
 *
215
 * <code>
216
 *  var cursor = index.openCursor(goog.db.KeyRange.bound('a', 'c'));
217
 *
218
 *  var key = goog.events.listen(
219
 *      cursor, goog.db.Cursor.EventType.NEW_DATA,
220
 *      function() {
221
 *        // Do something with data.
222
 *        cursor.next();
223
 *      });
224
 *
225
 *  goog.events.listenOnce(
226
 *      cursor, goog.db.Cursor.EventType.COMPLETE,
227
 *      function() {
228
 *        // Clean up listener, and perform a finishing operation on the data.
229
 *        goog.events.unlistenByKey(key);
230
 *      });
231
 * </code>
232
 *
233
 * @param {!goog.db.KeyRange=} opt_range The key range. If undefined iterates
234
 *     over the whole object store.
235
 * @param {!goog.db.Cursor.Direction=} opt_direction The direction. If undefined
236
 *     moves in a forward direction with duplicates.
237
 * @return {!goog.db.Cursor} The cursor.
238
 * @throws {goog.db.Error} If there was a problem opening the cursor.
239
 */
240
goog.db.Index.prototype.openCursor = function(opt_range, opt_direction) {
241
  return goog.db.Cursor.openCursor(this.index_, opt_range, opt_direction);
242
};
243

244