result

Classes

goog.result.DeferredAdaptor
An adaptor from Result to a Deferred, for use with existing Deferred chains.
goog.result.DependentResult
A DependentResult represents a Result whose eventual value depends on the value of one or more other Results. For example, the Result returned by
goog.result.DependentResultImpl_
A DependentResult represents a Result whose eventual value depends on the value of one or more other Results. For example, the Result returned by
goog.result.Result
A Result object represents a value returned by an asynchronous operation at some point in the future (e.g. a network fetch). This is akin to a 'Promise' or a 'Future' in other languages and frameworks.
goog.result.SimpleResult
A SimpleResult object is a basic implementation of the goog.result.Result interface. This could be subclassed(e.g. XHRResult) or instantiated and returned by another class as a form of result. The caller receiving the result could then attach handlers to be called when the result is resolved(success or error).

Public Protected Private

Global Functions

goog.result.cancelParentResults(dependentResult) boolean
Given a DependentResult, cancels the Results it depends on (that is, the results returned by getParentResults). This function does not recurse, so e.g. parents of parents are not canceled; only the immediate parents of the given Result are canceled. Example using @see goog.result.combine:
var result1 = xhr.get('testdata/xhr_test_text.data');

// Get a second independent Result.
var result2 = xhr.getJson('testdata/xhr_test_json.data');

// Create a Result that resolves when both prior results resolve.
var combinedResult = goog.result.combineOnSuccess(result1, result2);

combinedResult.wait(function() {
  if (combinedResult.isCanceled()) {
    goog.result.cancelParentResults(combinedResult);
  }
});

// Now, canceling combinedResult will cancel both result1 and result2.
combinedResult.cancel();
Arguments:
dependentResult : !goog.result.DependentResult
A Result that is dependent on the values of other Results (for example the Result of a goog.result.combine, goog.result.chain, or goog.result.transform call).
Returns: boolean  True if any results were successfully canceled; otherwise false. TODO(user): Implement a recursive version of this that cancels all ancestor results.
code »
goog.result.canceledResult() !goog.result.Result
Returns a canceled result. The result will be resolved to an error of type CancelError. Example:

var result = goog.result.canceledResult();
assertEquals(goog.result.Result.State.ERROR, result.getState());
var error = result.getError();
assertTrue(error instanceof goog.result.Result.CancelError);

Returns: !goog.result.Result  A canceled Result.
code »
goog.result.chain(resultactionCallbackopt_scope) !goog.result.DependentResult
The chain function aids in chaining of asynchronous Results. This provides a convenience for use cases where asynchronous operations must happen serially i.e. subsequent asynchronous operations are dependent on data returned by prior asynchronous operations. It accepts a result and an action callback as arguments and returns a result. The action callback is called when the first result succeeds and is supposed to return a second result. The returned result is resolved when one of both of the results resolve (depending on their success or failure.) The state and value of the returned result in the various cases is documented below:

First Result State:    Second Result State:    Returned Result State:
SUCCESS                SUCCESS                 SUCCESS
SUCCESS                ERROR                   ERROR
ERROR                  Not created             ERROR
The value of the returned result, in the case both results succeed, is the value of the second result (the result returned by the action callback.) Example:

var testDataResult = xhr.get('testdata/xhr_test_text.data');

// Chain this result to perform another asynchronous operation when this
// Result is resolved.
var chainedResult = goog.result.chain(testDataResult,
    function(testDataResult) {

      // The result value of testDataResult is the URL for JSON data.
      var jsonDataUrl = testDataResult.getValue();

      // Create a new Result object when the original result is resolved.
      var jsonResult = xhr.getJson(jsonDataUrl);

      // Return the newly created Result.
      return jsonResult;
    });

// The chained result resolves to success when both results resolve to
// success.
goog.result.waitOnSuccess(chainedResult, function(resultValue, result) {

  // At this point, both results have succeeded and we can use the JSON
  // data returned by the second asynchronous call.
  var jsonData = resultValue;
  assertEquals('ok', jsonData['stat']);
});

// Attach the error handler to be called when either Result fails.
goog.result.waitOnError(chainedResult, function(result) {
  alert('chained result failed!');
});
Arguments:
result : !goog.result.Result
The result to chain.
actionCallback : function(this:T, !goog.result.Result):!goog.result.Result
The callback called when the result is resolved. This callback must return a Result.
opt_scope : T=
Optional scope for the action callback.
Returns: !goog.result.DependentResult  A result that is resolved when both the given Result and the Result returned by the actionCallback have resolved.
code »
goog.result.combine(var_args) !goog.result.DependentResult
Returns a result that waits on all given results to resolve. Once all have resolved, the returned result will succeed (and never error). Example:

var result1 = xhr.get('testdata/xhr_test_text.data');

// Get a second independent Result.
var result2 = xhr.getJson('testdata/xhr_test_json.data');

// Create a Result that resolves when both prior results resolve.
var combinedResult = goog.result.combine(result1, result2);

// Process data after resolution of both results.
goog.result.waitOnSuccess(combinedResult, function(results) {
  goog.array.forEach(results, function(result) {
      alert(result.getState());
  });
});
Arguments:
var_args : ...!goog.result.Result
The results to wait on.
Returns: !goog.result.DependentResult  A new Result whose eventual value will be the resolved given Result objects.
code »
goog.result.combineOnSuccess(var_args) !goog.result.DependentResult
Returns a result that waits on all given results to resolve. Once all have resolved, the returned result will succeed if and only if all given results succeeded. Otherwise it will error. Example:

var result1 = xhr.get('testdata/xhr_test_text.data');

// Get a second independent Result.
var result2 = xhr.getJson('testdata/xhr_test_json.data');

// Create a Result that resolves when both prior results resolve.
var combinedResult = goog.result.combineOnSuccess(result1, result2);

// Process data after successful resolution of both results.
goog.result.waitOnSuccess(combinedResult, function(results) {
  var textData = results[0].getValue();
  var jsonData = results[1].getValue();
  assertEquals('Just some data.', textData);
  assertEquals('ok', jsonData['stat']);
});

// Handle errors when either or both results failed.
goog.result.waitOnError(combinedResult, function(combined) {
  var results = combined.getError();

  if (results[0].getState() == goog.result.Result.State.ERROR) {
    alert('result1 failed');
  }

  if (results[1].getState() == goog.result.Result.State.ERROR) {
    alert('result2 failed');
  }
});
Arguments:
var_args : ...!goog.result.Result
The results to wait on.
Returns: !goog.result.DependentResult  A new Result whose eventual value will be an array of values of the given Result objects.
code »
goog.result.failedResult(opt_error) !goog.result.Result
Returns a failed result with the optional error slug set. Example:

var error = new Error('something-failed');
var result = goog.result.failedResult(error);
assertEquals(goog.result.Result.State.ERROR, result.getState());
assertEquals(error, result.getError());

Arguments:
opt_error : *=
The error to which the result should resolve.
Returns: !goog.result.Result  A Result object that has already been resolved to the supplied Error.
code »
goog.result.successfulResult(value) !goog.result.Result
Returns a successful result containing the provided value. Example:

var value = 'some-value';
var result = goog.result.immediateResult(value);
assertEquals(goog.result.Result.State.SUCCESS, result.getState());
assertEquals(value, result.getValue());

Arguments:
value : *
The value of the result.
Returns: !goog.result.Result  A Result object that has already been resolved to the supplied value.
code »
goog.result.transform(resulttransformer) !goog.result.DependentResult
Given a result and a transform function, returns a new result whose value, on success, will be the value of the given result after having been passed through the transform function. If the given result is an error, the returned result is also an error and the transform will not be called. Example:

var result = xhr.getJson('testdata/xhr_test_json.data');

// Transform contents of returned data using 'processJson' and create a
// transformed result to use returned JSON.
var transformedResult = goog.result.transform(result, processJson);

// Attach success and failure handlers to the tranformed result.
goog.result.waitOnSuccess(transformedResult, function(resultValue, result) {
  var jsonData = resultValue;
  assertEquals('ok', jsonData['stat']);
});

goog.result.waitOnError(transformedResult, function(error) {
  // Failed getJson call
});
Arguments:
result : !goog.result.Result
The result whose value will be transformed.
transformer : ?function():?
The transformer function. The return value of this function will become the value of the returned result.
Returns: !goog.result.DependentResult  A new Result whose eventual value will be the returned value of the transformer function.
code »
goog.result.wait(resulthandleropt_scope)
Calls the handler on resolution of the result (success or failure). The handler is passed the result object as the only parameter. The call will be immediate if the result is no longer pending. Example:

var result = xhr.get('testdata/xhr_test_text.data');

// Wait for the result to be resolved and alert it's state.
goog.result.wait(result, function(result) {
  alert('State: ' + result.getState());
});
Arguments:
result : !goog.result.Result
The result to install the handlers.
handler : function(this:T, !goog.result.Result)
The handler to be called. The handler is passed the result object as the only parameter.
opt_scope : !T=
Optional scope for the handler.
code »
goog.result.waitOnError(resulthandleropt_scope)
Calls the handler if the result action errors. The result object is passed as the only parameter to the handler. The call will be immediate if the result object has already resolved to an error. Example:

var result = xhr.get('testdata/xhr_test_text.data');

// Attach a failure handler.
goog.result.waitOnError(result, function(error) {
 // Failed asynchronous call!
});
Arguments:
result : !goog.result.Result
The result to install the handlers.
handler : function(this:T, ?, !goog.result.Result)
The handler to be called. The handler is passed the error and the result object as parameters.
opt_scope : !T=
Optional scope for the handler.
code »
goog.result.waitOnSuccess(resulthandleropt_scope)
Calls the handler if the result succeeds. The result object is the only parameter passed to the handler. The call will be immediate if the result has already succeeded. Example:

var result = xhr.get('testdata/xhr_test_text.data');

// attach a success handler.
goog.result.waitOnSuccess(result, function(resultValue, result) {
  var datavalue = result.getvalue();
  alert('value: ' + datavalue + ' == ' + resultValue);
});
Arguments:
result : !goog.result.Result
The result to install the handlers.
handler : function(this:T, ?, !goog.result.Result)
The handler to be called. The handler is passed the result value and the result as parameters.
opt_scope : !T=
Optional scope for the handler.
code »

Package result

Package Reference