Debian Codegraph @

closure-library/closure/goog/db/transaction.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 transaction.
17 *
18 */
19
20
21 goog.provide('goog.db.Transaction');
22 goog.provide('goog.db.Transaction.TransactionMode');
23
24 goog.require('goog.async.Deferred');
25 goog.require('goog.db.Error');
26 goog.require('goog.db.ObjectStore');
27 goog.require('goog.events');
28 goog.require('goog.events.EventHandler');
29 goog.require('goog.events.EventTarget');
30
31
32
33 /**
34 * Creates a new transaction. Transactions contain methods for accessing object
35 * stores and are created from the database object. Should not be created
36 * directly, open a database and call createTransaction on it.
37 * @see goog.db.IndexedDb#createTransaction
38 *
39 * @param {!IDBTransaction} tx IndexedDB transaction to back this wrapper.
40 * @param {!goog.db.IndexedDb} db The database that this transaction modifies.
41 * @constructor
42 * @extends {goog.events.EventTarget}
43 * @final
44 */
45 goog.db.Transaction = function(tx, db) {
46 goog.db.Transaction.base(this, 'constructor');
47
48 /**
49 * Underlying IndexedDB transaction object.
50 *
51 * @type {!IDBTransaction}
52 * @private
53 */
54 this.tx_ = tx;
55
56 /**
57 * The database that this transaction modifies.
58 *
59 * @type {!goog.db.IndexedDb}
60 * @private
61 */
62 this.db_ = db;
63
64 /**
65 * Event handler for this transaction.
66 *
67 * @type {!goog.events.EventHandler<!goog.db.Transaction>}
68 * @private
69 */
70 this.eventHandler_ = new goog.events.EventHandler(this);
71
72 // TODO(user): remove these casts once the externs file is updated to
73 // correctly reflect that IDBTransaction extends EventTarget
74 this.eventHandler_.listen(
75 /** @type {!EventTarget} */ (this.tx_), 'complete',
76 goog.bind(
77 this.dispatchEvent, this, goog.db.Transaction.EventTypes.COMPLETE));
78 this.eventHandler_.listen(
79 /** @type {!EventTarget} */ (this.tx_), 'abort',
80 goog.bind(
81 this.dispatchEvent, this, goog.db.Transaction.EventTypes.ABORT));
82 this.eventHandler_.listen(
83 /** @type {!EventTarget} */ (this.tx_), 'error', this.dispatchError_);
84 };
85 goog.inherits(goog.db.Transaction, goog.events.EventTarget);
86
87
88 /**
89 * Dispatches an error event based on the given event, wrapping the error
90 * if necessary.
91 *
92 * @param {Event} ev The error event given to the underlying IDBTransaction.
93 * @private
94 */
95 goog.db.Transaction.prototype.dispatchError_ = function(ev) {
96 if (ev.target instanceof goog.db.Error) {
97 this.dispatchEvent(
98 {type: goog.db.Transaction.EventTypes.ERROR, target: ev.target});
99 } else {
100 this.dispatchEvent({
101 type: goog.db.Transaction.EventTypes.ERROR,
102 target: goog.db.Error.fromRequest(
103 /** @type {!IDBRequest} */ (ev.target), 'in transaction')
104 });
105 }
106 };
107
108
109 /**
110 * Event types the Transaction can dispatch. COMPLETE events are dispatched
111 * when the transaction is committed. If a transaction is aborted it dispatches
112 * both an ABORT event and an ERROR event with the ABORT_ERR code. Error events
113 * are dispatched on any error.
114 *
115 * @enum {string}
116 */
117 goog.db.Transaction.EventTypes = {
118 COMPLETE: 'complete',
119 ABORT: 'abort',
120 ERROR: 'error'
121 };
122
123
124 /**
125 * @return {goog.db.Transaction.TransactionMode} The transaction's mode.
126 */
127 goog.db.Transaction.prototype.getMode = function() {
128 return /** @type {goog.db.Transaction.TransactionMode} */ (this.tx_.mode);
129 };
130
131
132 /**
133 * @return {!goog.db.IndexedDb} The database that this transaction modifies.
134 */
135 goog.db.Transaction.prototype.getDatabase = function() {
136 return this.db_;
137 };
138
139
140 /**
141 * Opens an object store to do operations on in this transaction. The requested
142 * object store must be one that is in this transaction's scope.
143 * @see goog.db.IndexedDb#createTransaction
144 *
145 * @param {string} name The name of the requested object store.
146 * @return {!goog.db.ObjectStore} The wrapped object store.
147 * @throws {goog.db.Error} In case of error getting the object store.
148 */
149 goog.db.Transaction.prototype.objectStore = function(name) {
150 try {
151 return new goog.db.ObjectStore(this.tx_.objectStore(name));
152 } catch (ex) {
153 throw goog.db.Error.fromException(ex, 'getting object store ' + name);
154 }
155 };
156
157
158 /**
159 * @return {!goog.async.Deferred} A deferred that will fire once the
160 * transaction is complete. It fires the errback chain if an error occurs
161 * in the transaction, or if it is aborted.
162 */
163 goog.db.Transaction.prototype.wait = function() {
164 var d = new goog.async.Deferred();
165 goog.events.listenOnce(
166 this, goog.db.Transaction.EventTypes.COMPLETE, goog.bind(d.callback, d));
167 var errorKey;
168 var abortKey = goog.events.listenOnce(
169 this, goog.db.Transaction.EventTypes.ABORT, function() {
170 goog.events.unlistenByKey(errorKey);
171 d.errback(
172 new goog.db.Error(
173 goog.db.Error.ErrorCode.ABORT_ERR,
174 'waiting for transaction to complete'));
175 });
176 errorKey = goog.events.listenOnce(
177 this, goog.db.Transaction.EventTypes.ERROR, function(e) {
178 goog.events.unlistenByKey(abortKey);
179 d.errback(e.target);
180 });
181
182 var db = this.getDatabase();
183 return d.addCallback(function() { return db; });
184 };
185
186
187 /**
188 * Aborts this transaction. No pending operations will be applied to the
189 * database. Dispatches an ABORT event.
190 */
191 goog.db.Transaction.prototype.abort = function() {
192 this.tx_.abort();
193 };
194
195
196 /** @override */
197 goog.db.Transaction.prototype.disposeInternal = function() {
198 goog.db.Transaction.base(this, 'disposeInternal');
199 this.eventHandler_.dispose();
200 };
201
202
203 /**
204 * The three possible transaction modes.
205 * @see http://www.w3.org/TR/IndexedDB/#idl-def-IDBTransaction
206 *
207 * @enum {string}
208 */
209 goog.db.Transaction.TransactionMode = {
210 READ_ONLY: 'readonly',
211 READ_WRITE: 'readwrite',
212 VERSION_CHANGE: 'versionchange'
213 };