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

185