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

215