Debian Codegraph @

closure-library/closure/goog/db/db.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 Wrappers for the HTML5 IndexedDB. The wrappers export nearly
17 * the same interface as the standard API, but return goog.async.Deferred
18 * objects instead of request objects and use Closure events. The wrapper works
19 * and has been tested on Chrome version 22+. It may work on older Chrome
20 * versions, but they aren't explicitly supported.
21 *
22 * Example usage:
23 *
24 * <code>
25 * goog.db.openDatabase('mydb', 1, function(ev, db, tx) {
26 * db.createObjectStore('mystore');
27 * }).addCallback(function(db) {
28 * var putTx = db.createTransaction(
29 * [],
30 * goog.db.Transaction.TransactionMode.READ_WRITE);
31 * var store = putTx.objectStore('mystore');
32 * store.put('value', 'key');
33 * goog.listen(putTx, goog.db.Transaction.EventTypes.COMPLETE, function() {
34 * var getTx = db.createTransaction([]);
35 * var request = getTx.objectStore('mystore').get('key');
36 * request.addCallback(function(result) {
37 * ...
38 * });
39 * });
40 * </code>
41 *
42 */
43
44
45 goog.provide('goog.db');
46 goog.provide('goog.db.BlockedCallback');
47 goog.provide('goog.db.UpgradeNeededCallback');
48
49 goog.require('goog.asserts');
50 goog.require('goog.async.Deferred');
51 goog.require('goog.db.Error');
52 goog.require('goog.db.IndexedDb');
53 goog.require('goog.db.Transaction');
54
55
56 /**
57 * The IndexedDB factory object.
58 *
59 * @type {!IDBFactory|undefined}
60 * @private
61 */
62 goog.db.indexedDb_ = goog.global.indexedDB || goog.global.mozIndexedDB ||
63 goog.global.webkitIndexedDB || goog.global.moz_indexedDB;
64
65
66 /**
67 * A callback that's called if a blocked event is received. When a database is
68 * supposed to be deleted or upgraded (i.e. versionchange), and there are open
69 * connections to this database, a block event will be fired to prevent the
70 * operations from going through until all such open connections are closed.
71 * This callback can be used to notify users that they should close other tabs
72 * that have open connections, or to close the connections manually. Databases
73 * can also listen for the {@link goog.db.IndexedDb.EventType.VERSION_CHANGE}
74 * event to automatically close themselves when they're blocking such
75 * operations.
76 *
77 * This is passed a VersionChangeEvent that has the version of the database
78 * before it was deleted, and "null" as the new version.
79 *
80 * @typedef {function(!goog.db.IndexedDb.VersionChangeEvent)}
81 */
82 goog.db.BlockedCallback;
83
84
85 /**
86 * A callback that's called when opening a database whose internal version is
87 * lower than the version passed to {@link goog.db.openDatabase}.
88 *
89 * This callback is passed three arguments: a VersionChangeEvent with both the
90 * old version and the new version of the database; the database that's being
91 * opened, for which you can create and delete object stores; and the version
92 * change transaction, with which you can abort the version change.
93 *
94 * Note that the transaction is not active, which means that it can't be used to
95 * make changes to the database. However, since there is a transaction running,
96 * you can't create another one via {@link goog.db.IndexedDb.createTransaction}.
97 * This means that it's not possible to manipulate the database other than
98 * creating or removing object stores in this callback.
99 *
100 * @typedef {function(!goog.db.IndexedDb.VersionChangeEvent,
101 * !goog.db.IndexedDb,
102 * !goog.db.Transaction)}
103 */
104 goog.db.UpgradeNeededCallback;
105
106
107 /**
108 * Opens a database connection and wraps it.
109 *
110 * @param {string} name The name of the database to open.
111 * @param {number=} opt_version The expected version of the database. If this is
112 * larger than the actual version, opt_onUpgradeNeeded will be called
113 * (possibly after opt_onBlocked; see {@link goog.db.BlockedCallback}). If
114 * this is passed, opt_onUpgradeNeeded must be passed as well.
115 * @param {goog.db.UpgradeNeededCallback=} opt_onUpgradeNeeded Called if
116 * opt_version is greater than the old version of the database. If
117 * opt_version is passed, this must be passed as well.
118 * @param {goog.db.BlockedCallback=} opt_onBlocked Called if there are active
119 * connections to the database.
120 * @return {!goog.async.Deferred} The deferred database object.
121 */
122 goog.db.openDatabase = function(
123 name, opt_version, opt_onUpgradeNeeded, opt_onBlocked) {
124 goog.asserts.assert(
125 goog.isDef(opt_version) == goog.isDef(opt_onUpgradeNeeded),
126 'opt_version must be passed to goog.db.openDatabase if and only if ' +
127 'opt_onUpgradeNeeded is also passed');
128
129 var d = new goog.async.Deferred();
130 var openRequest = opt_version ? goog.db.indexedDb_.open(name, opt_version) :
131 goog.db.indexedDb_.open(name);
132 openRequest.onsuccess = function(ev) {
133 var db = new goog.db.IndexedDb(ev.target.result);
134 d.callback(db);
135 };
136 openRequest.onerror = function(ev) {
137 var msg = 'opening database ' + name;
138 d.errback(goog.db.Error.fromRequest(ev.target, msg));
139 };
140 openRequest.onupgradeneeded = function(ev) {
141 if (!opt_onUpgradeNeeded) return;
142 var db = new goog.db.IndexedDb(ev.target.result);
143 opt_onUpgradeNeeded(
144 new goog.db.IndexedDb.VersionChangeEvent(ev.oldVersion, ev.newVersion),
145 db, new goog.db.Transaction(ev.target.transaction, db));
146 };
147 openRequest.onblocked = function(ev) {
148 if (opt_onBlocked) {
149 opt_onBlocked(
150 new goog.db.IndexedDb.VersionChangeEvent(
151 ev.oldVersion, ev.newVersion));
152 }
153 };
154 return d;
155 };
156
157
158 /**
159 * Deletes a database once all open connections have been closed.
160 *
161 * @param {string} name The name of the database to delete.
162 * @param {goog.db.BlockedCallback=} opt_onBlocked Called if there are active
163 * connections to the database.
164 * @return {!goog.async.Deferred} A deferred object that will fire once the
165 * database is deleted.
166 */
167 goog.db.deleteDatabase = function(name, opt_onBlocked) {
168 var d = new goog.async.Deferred();
169 var deleteRequest = goog.db.indexedDb_.deleteDatabase(name);
170 deleteRequest.onsuccess = function(ev) { d.callback(); };
171 deleteRequest.onerror = function(ev) {
172 var msg = 'deleting database ' + name;
173 d.errback(goog.db.Error.fromRequest(ev.target, msg));
174 };
175 deleteRequest.onblocked = function(ev) {
176 if (opt_onBlocked) {
177 opt_onBlocked(
178 new goog.db.IndexedDb.VersionChangeEvent(
179 ev.oldVersion, ev.newVersion));
180 }
181 };
182 return d;
183 };