# lib/atoms/response.js

    1// Copyright 2011 Software Freedom Conservancy. 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 at6//7//      http://www.apache.org/licenses/LICENSE-2.08//9// Unless required by applicable law or agreed to in writing, software10// 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 and13// limitations under the License.1415/**16 * @fileoverview Utilities for working with WebDriver response objects.17 * @see: http://code.google.com/p/selenium/wiki/JsonWireProtocol#Responses18 */1920goog.provide('bot.response');21goog.provide('bot.response.ResponseObject');2223goog.require('bot.Error');24goog.require('bot.ErrorCode');252627/**28 * Type definition for a response object, as defined by the JSON wire protocol.29 * @typedef {{status: bot.ErrorCode, value: (*|{message: string})}}30 * @see http://code.google.com/p/selenium/wiki/JsonWireProtocol#Responses31 */32bot.response.ResponseObject;333435/**36 * @param {*} value The value to test.37 * @return {boolean} Whether the given value is a response object.38 */39bot.response.isResponseObject = function(value) {40  return goog.isObject(value) && goog.isNumber(value['status']);41};424344/**45 * Creates a new success response object with the provided value.46 * @param {*} value The response value.47 * @return {!bot.response.ResponseObject} The new response object.48 */49bot.response.createResponse = function(value) {50  if (bot.response.isResponseObject(value)) {51    return /** @type {!bot.response.ResponseObject} */ (value);52  }53  return {54    'status': bot.ErrorCode.SUCCESS,55    'value': value56  };57};585960/**61 * Converts an error value into its JSON representation as defined by the62 * WebDriver wire protocol.63 * @param {(bot.Error|Error|*)} error The error value to convert.64 * @return {!bot.response.ResponseObject} The new response object.65 */66bot.response.createErrorResponse = function(error) {67  if (bot.response.isResponseObject(error)) {68    return /** @type {!bot.response.ResponseObject} */ (error);69  }7071  var statusCode = error && goog.isNumber(error.code) ? error.code :72      bot.ErrorCode.UNKNOWN_ERROR;73  return {74    'status': /** @type {bot.ErrorCode} */ (statusCode),75    'value': {76      'message': (error && error.message || error) + ''77    }78  };79};808182/**83 * Checks that a response object does not specify an error as defined by the84 * WebDriver wire protocol. If the response object defines an error, it will85 * be thrown. Otherwise, the response will be returned as is.86 * @param {!bot.response.ResponseObject} responseObj The response object to87 *     check.88 * @return {!bot.response.ResponseObject} The checked response object.89 * @throws {bot.Error} If the response describes an error.90 * @see http://code.google.com/p/selenium/wiki/JsonWireProtocol#Failed_Commands91 */92bot.response.checkResponse = function(responseObj) {93  var status = responseObj['status'];94  if (status == bot.ErrorCode.SUCCESS) {95    return responseObj;96  }9798  // If status is not defined, assume an unknown error.99  status = status || bot.ErrorCode.UNKNOWN_ERROR;100101  var value = responseObj['value'];102  if (!value || !goog.isObject(value)) {103    throw new bot.Error(status, value + '');104  }105106  throw new bot.Error(status, value['message'] + '');107};