1
// Copyright 2012 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 A SimpleResult object that implements goog.result.Result.
17
 * See below for a more detailed description.
18
 */
19

20
goog.provide('goog.result.SimpleResult');
21
goog.provide('goog.result.SimpleResult.StateError');
22

23
goog.require('goog.Promise');
24
goog.require('goog.Thenable');
25
goog.require('goog.debug.Error');
26
goog.require('goog.result.Result');
27

28

29

30
/**
31
 * A SimpleResult object is a basic implementation of the
32
 * goog.result.Result interface. This could be subclassed(e.g. XHRResult)
33
 * or instantiated and returned by another class as a form of result. The caller
34
 * receiving the result could then attach handlers to be called when the result
35
 * is resolved(success or error).
36
 *
37
 * @constructor
38
 * @implements {goog.result.Result}
39
 * @deprecated Use {@link goog.Promise} instead - http://go/promisemigration
40
 */
41
goog.result.SimpleResult = function() {
42
  /**
43
   * The current state of this Result.
44
   * @type {goog.result.Result.State}
45
   * @private
46
   */
47
  this.state_ = goog.result.Result.State.PENDING;
48

49
  /**
50
   * The list of handlers to call when this Result is resolved.
51
   * @type {!Array<!goog.result.SimpleResult.HandlerEntry_>}
52
   * @private
53
   */
54
  this.handlers_ = [];
55

56
  // The value_ and error_ properties are initialized in the constructor to
57
  // ensure that all SimpleResult instances share the same hidden class in
58
  // modern JavaScript engines.
59

60
  /**
61
   * The 'value' of this Result.
62
   * @type {*}
63
   * @private
64
   */
65
  this.value_ = undefined;
66

67
  /**
68
   * The error slug for this Result.
69
   * @type {*}
70
   * @private
71
   */
72
  this.error_ = undefined;
73
};
74
goog.Thenable.addImplementation(goog.result.SimpleResult);
75

76

77
/**
78
 * A waiting handler entry.
79
 * @typedef {{
80
 *   callback: !function(goog.result.SimpleResult),
81
 *   scope: Object
82
 * }}
83
 * @private
84
 */
85
goog.result.SimpleResult.HandlerEntry_;
86

87

88

89
/**
90
 * Error thrown if there is an attempt to set the value or error for this result
91
 * more than once.
92
 *
93
 * @constructor
94
 * @extends {goog.debug.Error}
95
 * @final
96
 * @deprecated Use {@link goog.Promise} instead - http://go/promisemigration
97
 */
98
goog.result.SimpleResult.StateError = function() {
99
  goog.result.SimpleResult.StateError.base(
100
      this, 'constructor', 'Multiple attempts to set the state of this Result');
101
};
102
goog.inherits(goog.result.SimpleResult.StateError, goog.debug.Error);
103

104

105
/** @override */
106
goog.result.SimpleResult.prototype.getState = function() {
107
  return this.state_;
108
};
109

110

111
/** @override */
112
goog.result.SimpleResult.prototype.getValue = function() {
113
  return this.value_;
114
};
115

116

117
/** @override */
118
goog.result.SimpleResult.prototype.getError = function() {
119
  return this.error_;
120
};
121

122

123
/**
124
 * Attaches handlers to be called when the value of this Result is available.
125
 *
126
 * @param {function(this:T, !goog.result.SimpleResult)} handler The function
127
 *     called when the value is available. The function is passed the Result
128
 *     object as the only argument.
129
 * @param {T=} opt_scope Optional scope for the handler.
130
 * @template T
131
 * @override
132
 */
133
goog.result.SimpleResult.prototype.wait = function(handler, opt_scope) {
134
  if (this.isPending_()) {
135
    this.handlers_.push({callback: handler, scope: opt_scope || null});
136
  } else {
137
    handler.call(opt_scope, this);
138
  }
139
};
140

141

142
/**
143
 * Sets the value of this Result, changing the state.
144
 *
145
 * @param {*} value The value to set for this Result.
146
 */
147
goog.result.SimpleResult.prototype.setValue = function(value) {
148
  if (this.isPending_()) {
149
    this.value_ = value;
150
    this.state_ = goog.result.Result.State.SUCCESS;
151
    this.callHandlers_();
152
  } else if (!this.isCanceled()) {
153
    // setValue is a no-op if this Result has been canceled.
154
    throw new goog.result.SimpleResult.StateError();
155
  }
156
};
157

158

159
/**
160
 * Sets the Result to be an error Result.
161
 *
162
 * @param {*=} opt_error Optional error slug to set for this Result.
163
 */
164
goog.result.SimpleResult.prototype.setError = function(opt_error) {
165
  if (this.isPending_()) {
166
    this.error_ = opt_error;
167
    this.state_ = goog.result.Result.State.ERROR;
168
    this.callHandlers_();
169
  } else if (!this.isCanceled()) {
170
    // setError is a no-op if this Result has been canceled.
171
    throw new goog.result.SimpleResult.StateError();
172
  }
173
};
174

175

176
/**
177
 * Calls the handlers registered for this Result.
178
 *
179
 * @private
180
 */
181
goog.result.SimpleResult.prototype.callHandlers_ = function() {
182
  var handlers = this.handlers_;
183
  this.handlers_ = [];
184
  for (var n = 0; n < handlers.length; n++) {
185
    var handlerEntry = handlers[n];
186
    handlerEntry.callback.call(handlerEntry.scope, this);
187
  }
188
};
189

190

191
/**
192
 * @return {boolean} Whether the Result is pending.
193
 * @private
194
 */
195
goog.result.SimpleResult.prototype.isPending_ = function() {
196
  return this.state_ == goog.result.Result.State.PENDING;
197
};
198

199

200
/**
201
 * Cancels the Result.
202
 *
203
 * @return {boolean} Whether the result was canceled. It will not be canceled if
204
 *    the result was already canceled or has already resolved.
205
 * @override
206
 */
207
goog.result.SimpleResult.prototype.cancel = function() {
208
  // cancel is a no-op if the result has been resolved.
209
  if (this.isPending_()) {
210
    this.setError(new goog.result.Result.CancelError());
211
    return true;
212
  }
213
  return false;
214
};
215

216

217
/** @override */
218
goog.result.SimpleResult.prototype.isCanceled = function() {
219
  return this.state_ == goog.result.Result.State.ERROR &&
220
      this.error_ instanceof goog.result.Result.CancelError;
221
};
222

223

224
/** @override */
225
goog.result.SimpleResult.prototype.then = function(
226
    opt_onFulfilled, opt_onRejected, opt_context) {
227
  var resolve, reject;
228
  // Copy the resolvers to outer scope, so that they are available
229
  // when the callback to wait() fires (which may be synchronous).
230
  var promise = new goog.Promise(function(res, rej) {
231
    resolve = res;
232
    reject = rej;
233
  });
234
  this.wait(function(result) {
235
    if (result.isCanceled()) {
236
      promise.cancel();
237
    } else if (result.getState() == goog.result.Result.State.SUCCESS) {
238
      resolve(result.getValue());
239
    } else if (result.getState() == goog.result.Result.State.ERROR) {
240
      reject(result.getError());
241
    }
242
  });
243
  return promise.then(opt_onFulfilled, opt_onRejected, opt_context);
244
};
245

246

247
/**
248
 * Creates a SimpleResult that fires when the given promise resolves.
249
 * Use only during migration to Promises.
250
 * @param {!goog.Promise<?>} promise
251
 * @return {!goog.result.Result}
252
 */
253
goog.result.SimpleResult.fromPromise = function(promise) {
254
  var result = new goog.result.SimpleResult();
255
  promise.then(result.setValue, result.setError, result);
256
  return result;
257
};
258

259