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

20

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

23
goog.require('goog.db.Error');
24
goog.require('goog.db.ObjectStore');
25
goog.require('goog.db.Transaction');
26
goog.require('goog.events.Event');
27
goog.require('goog.events.EventHandler');
28
goog.require('goog.events.EventTarget');
29

30

31

32
/**
33
 * Creates an IDBDatabase wrapper object. The database object has methods for
34
 * setting the version to change the structure of the database and for creating
35
 * transactions to get or modify the stored records. Should not be created
36
 * directly, call {@link goog.db.openDatabase} to set up the connection.
37
 *
38
 * @param {!IDBDatabase} db Underlying IndexedDB database object.
39
 * @constructor
40
 * @extends {goog.events.EventTarget}
41
 * @final
42
 */
43
goog.db.IndexedDb = function(db) {
44
  goog.db.IndexedDb.base(this, 'constructor');
45

46
  /**
47
   * Underlying IndexedDB database object.
48
   *
49
   * @type {!IDBDatabase}
50
   * @private
51
   */
52
  this.db_ = db;
53

54
  /**
55
   * Internal event handler that listens to IDBDatabase events.
56
   * @type {!goog.events.EventHandler<!goog.db.IndexedDb>}
57
   * @private
58
   */
59
  this.eventHandler_ = new goog.events.EventHandler(this);
60

61
  this.eventHandler_.listen(
62
      this.db_, goog.db.IndexedDb.EventType.ABORT,
63
      goog.bind(this.dispatchEvent, this, goog.db.IndexedDb.EventType.ABORT));
64
  this.eventHandler_.listen(
65
      this.db_, goog.db.IndexedDb.EventType.ERROR, this.dispatchError_);
66
  this.eventHandler_.listen(
67
      this.db_, goog.db.IndexedDb.EventType.VERSION_CHANGE,
68
      this.dispatchVersionChange_);
69
  this.eventHandler_.listen(
70
      this.db_, goog.db.IndexedDb.EventType.CLOSE,
71
      goog.bind(this.dispatchEvent, this, goog.db.IndexedDb.EventType.CLOSE));
72
};
73
goog.inherits(goog.db.IndexedDb, goog.events.EventTarget);
74

75

76
/**
77
 * True iff the database connection is open.
78
 *
79
 * @type {boolean}
80
 * @private
81
 */
82
goog.db.IndexedDb.prototype.open_ = true;
83

84

85
/**
86
 * Dispatches a wrapped error event based on the given event.
87
 *
88
 * @param {Event} ev The error event given to the underlying IDBDatabase.
89
 * @private
90
 */
91
goog.db.IndexedDb.prototype.dispatchError_ = function(ev) {
92
  this.dispatchEvent({
93
    type: goog.db.IndexedDb.EventType.ERROR,
94
    errorCode: /** @type {IDBRequest} */ (ev.target).error.severity
95
  });
96
};
97

98

99
/**
100
 * Dispatches a wrapped version change event based on the given event.
101
 *
102
 * @param {Event} ev The version change event given to the underlying
103
 *     IDBDatabase.
104
 * @private
105
 */
106
goog.db.IndexedDb.prototype.dispatchVersionChange_ = function(ev) {
107
  this.dispatchEvent(
108
      new goog.db.IndexedDb.VersionChangeEvent(ev.oldVersion, ev.newVersion));
109
};
110

111

112
/**
113
 * Closes the database connection. Metadata queries can still be made after this
114
 * method is called, but otherwise this wrapper should not be used further.
115
 */
116
goog.db.IndexedDb.prototype.close = function() {
117
  if (this.open_) {
118
    this.db_.close();
119
    this.open_ = false;
120
  }
121
};
122

123

124
/**
125
 * @return {boolean} Whether a connection is open and the database can be used.
126
 */
127
goog.db.IndexedDb.prototype.isOpen = function() {
128
  return this.open_;
129
};
130

131

132
/**
133
 * @return {string} The name of this database.
134
 */
135
goog.db.IndexedDb.prototype.getName = function() {
136
  return this.db_.name;
137
};
138

139

140
/**
141
 * @return {number} The current database version.
142
 */
143
goog.db.IndexedDb.prototype.getVersion = function() {
144
  // TODO(bradfordcsmith): drop Number() call once closure compiler's externs
145
  // are updated
146
  return Number(this.db_.version);
147
};
148

149

150
/**
151
 * @return {DOMStringList} List of object stores in this database.
152
 */
153
goog.db.IndexedDb.prototype.getObjectStoreNames = function() {
154
  return this.db_.objectStoreNames;
155
};
156

157

158
/**
159
 * Creates an object store in this database. Can only be called inside a
160
 * {@link goog.db.UpgradeNeededCallback}.
161
 *
162
 * @param {string} name Name for the new object store.
163
 * @param {!IDBObjectStoreParameters=} opt_params Options object.
164
 *     The available options are:
165
 *     keyPath, which is a string and determines what object attribute
166
 *     to use as the key when storing objects in this object store; and
167
 *     autoIncrement, which is a boolean, which defaults to false and determines
168
 *     whether the object store should automatically generate keys for stored
169
 *     objects. If keyPath is not provided and autoIncrement is false, then all
170
 *     insert operations must provide a key as a parameter.
171
 * @return {!goog.db.ObjectStore} The newly created object store.
172
 * @throws {goog.db.Error} If there's a problem creating the object store.
173
 */
174
goog.db.IndexedDb.prototype.createObjectStore = function(name, opt_params) {
175
  try {
176
    return new goog.db.ObjectStore(
177
        this.db_.createObjectStore(name, opt_params));
178
  } catch (ex) {
179
    throw goog.db.Error.fromException(ex, 'creating object store ' + name);
180
  }
181
};
182

183

184
/**
185
 * Deletes an object store. Can only be called inside a
186
 * {@link goog.db.UpgradeNeededCallback}.
187
 *
188
 * @param {string} name Name of the object store to delete.
189
 * @throws {goog.db.Error} If there's a problem deleting the object store.
190
 */
191
goog.db.IndexedDb.prototype.deleteObjectStore = function(name) {
192
  try {
193
    this.db_.deleteObjectStore(name);
194
  } catch (ex) {
195
    throw goog.db.Error.fromException(ex, 'deleting object store ' + name);
196
  }
197
};
198

199

200
/**
201
 * Creates a new transaction.
202
 *
203
 * @param {!Array<string>} storeNames A list of strings that contains the
204
 *     transaction's scope, the object stores that this transaction can operate
205
 *     on.
206
 * @param {goog.db.Transaction.TransactionMode=} opt_mode The mode of the
207
 *     transaction. If not present, the default is READ_ONLY.
208
 * @return {!goog.db.Transaction} The wrapper for the newly created transaction.
209
 * @throws {goog.db.Error} If there's a problem creating the transaction.
210
 */
211
goog.db.IndexedDb.prototype.createTransaction = function(storeNames, opt_mode) {
212
  try {
213
    // IndexedDB on Chrome 22+ requires that opt_mode not be passed rather than
214
    // be explicitly passed as undefined.
215
    var transaction = opt_mode ? this.db_.transaction(storeNames, opt_mode) :
216
                                 this.db_.transaction(storeNames);
217
    return new goog.db.Transaction(transaction, this);
218
  } catch (ex) {
219
    throw goog.db.Error.fromException(ex, 'creating transaction');
220
  }
221
};
222

223

224
/** @override */
225
goog.db.IndexedDb.prototype.disposeInternal = function() {
226
  goog.db.IndexedDb.base(this, 'disposeInternal');
227
  this.eventHandler_.dispose();
228
};
229

230

231
/**
232
 * Event types fired by a database.
233
 *
234
 * @enum {string} The event types for the web socket.
235
 */
236
goog.db.IndexedDb.EventType = {
237

238
  /**
239
   * Fired when a transaction is aborted and the event bubbles to its database.
240
   */
241
  ABORT: 'abort',
242

243
  /**
244
   * Fired when the database connection is forcibly closed by the browser,
245
   * without an explicit call to IDBDatabase#close. This behavior is not in the
246
   * spec yet but will be added since it is necessary, see
247
   * https://www.w3.org/Bugs/Public/show_bug.cgi?id=22540.
248
   */
249
  CLOSE: 'close',
250

251
  /**
252
   * Fired when a transaction has an error.
253
   */
254
  ERROR: 'error',
255

256
  /**
257
   * Fired when someone (possibly in another window) is attempting to modify the
258
   * structure of the database. Since a change can only be made when there are
259
   * no active database connections, this usually means that the database should
260
   * be closed so that the other client can make its changes.
261
   */
262
  VERSION_CHANGE: 'versionchange'
263
};
264

265

266

267
/**
268
 * Event representing a (possibly attempted) change in the database structure.
269
 *
270
 * At time of writing, no Chrome versions support oldVersion or newVersion. See
271
 * http://crbug.com/153122.
272
 *
273
 * @param {number} oldVersion The previous version of the database.
274
 * @param {number} newVersion The version the database is being or has been
275
 *     updated to.
276
 * @constructor
277
 * @extends {goog.events.Event}
278
 * @final
279
 */
280
goog.db.IndexedDb.VersionChangeEvent = function(oldVersion, newVersion) {
281
  goog.db.IndexedDb.VersionChangeEvent.base(
282
      this, 'constructor', goog.db.IndexedDb.EventType.VERSION_CHANGE);
283

284
  /**
285
   * The previous version of the database.
286
   * @type {number}
287
   */
288
  this.oldVersion = oldVersion;
289

290
  /**
291
   * The version the database is being or has been updated to.
292
   * @type {number}
293
   */
294
  this.newVersion = newVersion;
295
};
296
goog.inherits(goog.db.IndexedDb.VersionChangeEvent, goog.events.Event);
297

298