Debian Codegraph @

closure-library/closure/goog/db/indexeddb.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 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);