closure 1.1.692

data/closure-library/closure/goog/net/jsonp.js

@@ -0,0 +1,379 @@
+// Copyright 2006 The Closure Library Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS-IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// The original file lives here: http://go/cross_domain_channel.js
+
+/**
+ * @fileoverview Implements a cross-domain communication channel. A
+ * typical web page is prevented by browser security from sending
+ * request, such as a XMLHttpRequest, to other servers than the ones
+ * from which it came. The Jsonp class provides a workound, by
+ * using dynamically generated script tags. Typical usage:.
+ *
+ * var jsonp = new goog.net.Jsonp(new goog.Uri('http://my.host.com/servlet'));
+ * var payload = { 'foo': 1, 'bar': true };
+ * jsonp.send(payload, function(reply) { alert(reply) });
+ *
+ * This script works in all browsers that are currently supported by
+ * the Google Maps API, which is IE 6.0+, Firefox 0.8+, Safari 1.2.4+,
+ * Netscape 7.1+, Mozilla 1.4+, Opera 8.02+.
+ *
+ */
+
+goog.provide('goog.net.Jsonp');
+
+goog.require('goog.Uri');
+goog.require('goog.dom');
+
+// WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
+//
+// This class allows us (Google) to send data from non-Google and thus
+// UNTRUSTED pages to our servers. Under NO CIRCUMSTANCES return
+// anything sensitive, such as session or cookie specific data. Return
+// only data that you want parties external to Google to have. Also
+// NEVER use this method to send data from web pages to untrusted
+// servers, or redirects to unknown servers (www.google.com/cache,
+// /q=xx&btnl, /url, www.googlepages.com, etc.)
+//
+// WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
+
+
+
+/**
+ * Creates a new cross domain channel that sends data to the specified
+ * host URL. By default, if no reply arrives within 5s, the channel
+ * assumes the call failed to complete successfully.
+ *
+ * @param {goog.Uri|string} uri The Uri of the server side code that receives
+ *     data posted through this channel (e.g.,
+ *     "http://maps.google.com/maps/geo").
+ *
+ * @param {string=} opt_callbackParamName The parameter name that is used to
+ *     specify the callback. Defaults to "callback".
+ *
+ * @constructor
+ */
+goog.net.Jsonp = function(uri, opt_callbackParamName) {
+  /**
+   * The uri_ object will be used to encode the payload that is sent to the
+   * server.
+   * @type {goog.Uri}
+   * @private
+   */
+  this.uri_ = new goog.Uri(uri);
+
+  /**
+   * This is the callback parameter name that is added to the uri.
+   * @type {string}
+   * @private
+   */
+  this.callbackParamName_ = opt_callbackParamName ?
+      opt_callbackParamName : 'callback';
+
+  /**
+   * The length of time, in milliseconds, this channel is prepared
+   * to wait for for a request to complete. The default value is 5 seconds.
+   * @type {number}
+   * @private
+   */
+  this.timeout_ = 5000;
+};
+
+
+/**
+ * The name of the property of goog.global under which the callback is
+ * stored.
+ */
+goog.net.Jsonp.CALLBACKS = '_callbacks_';
+
+
+/**
+ * Used to generate unique callback IDs. The counter must be global because
+ * all channels share a common callback object.
+ * @private
+ */
+goog.net.Jsonp.scriptCounter_ = 0;
+
+
+/**
+ * Sets the length of time, in milliseconds, this channel is prepared
+ * to wait for for a request to complete. If the call is not competed
+ * within the set time span, it is assumed to have failed. To wait
+ * indefinitely for a request to complete set the timout to a negative
+ * number.
+ *
+ * @param {number} timeout The length of time before calls are
+ * interrupted.
+ */
+goog.net.Jsonp.prototype.setRequestTimeout = function(timeout) {
+  this.timeout_ = timeout;
+};
+
+
+/**
+ * Returns the current timeout value, in milliseconds.
+ *
+ * @return {number} The timeout value.
+ */
+goog.net.Jsonp.prototype.getRequestTimeout = function() {
+  return this.timeout_;
+};
+
+
+/**
+ * Sends the given payload to the URL specified at the construction
+ * time. The reply is delivered to the given replyCallback. If the
+ * errorCallback is specified and the reply does not arrive within the
+ * timeout period set on this channel, the errorCallback is invoked
+ * with the original payload.
+ *
+ * If no reply callback is specified, then the response is expected to
+ * consist of calls to globally registered functions. No &callback=
+ * URL parameter will be sent in the request, and the script element
+ * will be cleaned up after the timeout.
+ *
+ * @param {Object=} opt_payload Name-value pairs.  If given, these will be
+ *     added as parameters to the supplied URI as GET parameters to the
+ *     given server URI.
+ *
+ * @param {Function=} opt_replyCallback A function expecting one
+ *     argument, called when the reply arrives, with the response data.
+ *
+ * @param {Function=} opt_errorCallback A function expecting one
+ *     argument, called on timeout, with the payload (if given), otherwise
+ *     null.
+ *
+ * @param {string=} opt_callbackParamValue Value to be used as the
+ *     parameter value for the callback parameter (callbackParamName).
+ *     To be used when the value needs to be fixed by the client for a
+ *     particular request, to make use of the cached responses for the request.
+ *     NOTE: If multiple requests are made with the same
+ *     opt_callbackParamValue, only the last call will work whenever the
+ *     response comes back.
+ *
+ * @return {Object} A request descriptor that may be used to cancel this
+ *     transmission, or null, if the message may not be cancelled.
+ */
+goog.net.Jsonp.prototype.send = function(opt_payload,
+                                         opt_replyCallback,
+                                         opt_errorCallback,
+                                         opt_callbackParamValue) {
+
+  var payload = opt_payload || null;
+
+  // This is a safeguard that we don't accidentally call appendChild
+  // on a null.
+  if (!document.documentElement.firstChild) {
+    if (opt_errorCallback) {
+      opt_errorCallback(payload);
+    }
+    return null;
+  }
+
+  var id = opt_callbackParamValue ||
+      '_' + (goog.net.Jsonp.scriptCounter_++).toString(36) +
+      goog.now().toString(36);
+
+  if (!goog.global[goog.net.Jsonp.CALLBACKS]) {
+    goog.global[goog.net.Jsonp.CALLBACKS] = {};
+  }
+
+  var script = goog.dom.createElement('script');
+
+  var timeout = null;
+  if (this.timeout_ > 0) {
+    var error = goog.net.Jsonp.newErrorHandler_(id, script, payload,
+                                                opt_errorCallback);
+    timeout = goog.global.setTimeout(error, this.timeout_);
+  }
+
+  // Create a new Uri object onto which this payload will be added
+  var uri = this.uri_.clone();
+  if (payload) {
+    goog.net.Jsonp.addPayloadToUri_(payload, uri);
+  }
+
+  if (opt_replyCallback) {
+    var reply = goog.net.Jsonp.newReplyHandler_(id, script, opt_replyCallback,
+                                                timeout);
+    goog.global[goog.net.Jsonp.CALLBACKS][id] = reply;
+
+    uri.setParameterValues(this.callbackParamName_,
+                           goog.net.Jsonp.CALLBACKS + '.' + id);
+  }
+
+  goog.dom.setProperties(script, {
+    'type': 'text/javascript',
+    'id': id,
+    'charset': 'UTF-8',
+    // NOTE(user): Safari never loads the script if we don't set
+    // the src attribute before appending.
+    'src': uri.toString()
+  });
+
+  goog.dom.appendChild(document.getElementsByTagName('head')[0], script);
+  return { id_: id, timeout_: timeout };
+};
+
+
+/**
+ * Cancels a given request. The request must be exactly the object returned by
+ * the send method.
+ *
+ * @param {Object} request The request object returned by the send method.
+ */
+goog.net.Jsonp.prototype.cancel = function(request) {
+  if (request && request.id_) {
+    var scriptNode = goog.dom.getElement(request.id_);
+
+    if (scriptNode && scriptNode.tagName == 'SCRIPT' &&
+        typeof goog.global[goog.net.Jsonp.CALLBACKS][request.id_] ==
+        'function') {
+      request.timeout_ && goog.global.clearTimeout(request.timeout_);
+      goog.net.Jsonp.cleanup_(request.id_, scriptNode, false);
+    }
+  }
+};
+
+
+/**
+ * Creates a timeout callback that removes the script node and calls
+ * the given timeoutCallback with the original payload.
+ *
+ * @param {string} id The id of the script node.
+ * @param {Element} scriptNode Script element.
+ * @param {Object} payload The payload that was sent to the server.
+ * @param {Function=} opt_errorCallback The function called on timeout.
+ * @return {Function} A zero argument function that handles callback duties.
+ * @private
+ */
+goog.net.Jsonp.newErrorHandler_ = function(id,
+                                           scriptNode,
+                                           payload,
+                                           opt_errorCallback) {
+  /**
+   * When we call across domains with a request, this function is the
+   * timeout handler. Once it's done executing the user-specified
+   * error-handler, it removes the script node and original function.
+   */
+  return function() {
+    goog.net.Jsonp.cleanup_(id, scriptNode, false);
+    if (opt_errorCallback) {
+      opt_errorCallback(payload);
+    }
+  }
+};
+
+
+/**
+ * Creates a reply callback that removes the script node and calls the
+ * given replyCallback with data returned by the server.
+ *
+ * @param {string} id The id of the script node.
+ * @param {Element} scriptNode Script element.
+ * @param {Function} replyCallback The function called on reply.
+ * @param {?number} timeout A timeout call that needs to be cleared.
+ * @return {Function} A reply callback function.
+ * @private
+ */
+goog.net.Jsonp.newReplyHandler_ = function(id,
+                                           scriptNode,
+                                           replyCallback,
+                                           timeout) {
+  /**
+   * This function is the handler for the all-is-well response. It
+   * clears the error timeout handler, calls the user's handler, then
+   * removes the script node and itself.
+   *
+   * @param {...Object} var_args The response data sent from the server.
+   */
+  return function(var_args) {
+    goog.global.clearTimeout(timeout);
+    goog.net.Jsonp.cleanup_(id, scriptNode, true);
+    replyCallback.apply(undefined, arguments);
+  };
+};
+
+
+/**
+ * Removes the script node and reply handler with the given id.
+ *
+ * @param {string} id The id of the script node to be removed.
+ * @param {Node} scriptNode The node to be removed.
+ * @param {boolean} deleteReplyHandler If true, delete the reply handler
+ *     instead of setting it to nullFunction (if we know the callback could
+ *     never be called again).
+ * @private
+ */
+goog.net.Jsonp.cleanup_ = function(id, scriptNode, deleteReplyHandler) {
+  // Do this after a delay (removing the script node of a running script can
+  // confuse older IEs).
+  goog.global.setTimeout(function() {
+    goog.dom.removeNode(scriptNode);
+  }, 0);
+
+  if (goog.global[goog.net.Jsonp.CALLBACKS][id]) {
+    if (deleteReplyHandler) {
+      delete goog.global[goog.net.Jsonp.CALLBACKS][id];
+    } else {
+      // Removing the script tag doesn't necessarily prevent the script
+      // from firing, so we make the callback a noop.
+      goog.global[goog.net.Jsonp.CALLBACKS][id] = goog.nullFunction;
+    }
+  }
+};
+
+
+/**
+ * Returns URL encoded payload. The payload should be a map of name-value
+ * pairs, in the form {"foo": 1, "bar": true, ...}.  If the map is empty,
+ * the URI will be unchanged.
+ *
+ * <p>The method uses hasOwnProperty() to assure the properties are on the
+ * object, not on its prototype.
+ *
+ * @param {!Object} payload A map of value name pairs to be encoded.
+ *     A value may be specified as an array, in which case a query parameter
+ *     will be created for each value, e.g.:
+ *     {"foo": [1,2]} will encode to "foo=1&foo=2".
+ *
+ * @param {!goog.Uri} uri A Uri object onto which the payload key value pairs
+ *     will be encoded.
+ *
+ * @return {!goog.Uri} A reference to the Uri sent as a parameter.
+ * @private
+ */
+goog.net.Jsonp.addPayloadToUri_ = function(payload, uri) {
+  for (var name in payload) {
+    // NOTE(user): Safari/1.3 doesn't have hasOwnProperty(). In that
+    // case, we iterate over all properties as a very lame workaround.
+    if (!payload.hasOwnProperty || payload.hasOwnProperty(name)) {
+      uri.setParameterValues(name, payload[name]);
+    }
+  }
+  return uri;
+};
+
+
+// WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
+//
+// This class allows us (Google) to send data from non-Google and thus
+// UNTRUSTED pages to our servers. Under NO CIRCUMSTANCES return
+// anything sensitive, such as session or cookie specific data. Return
+// only data that you want parties external to Google to have. Also
+// NEVER use this method to send data from web pages to untrusted
+// servers, or redirects to unknown servers (www.google.com/cache,
+// /q=xx&btnl, /url, www.googlepages.com, etc.)
+//
+// WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING

data/closure-library/closure/goog/net/jsonp_test.html

@@ -0,0 +1,328 @@
+<!DOCTYPE html>
+<html>
+<!--
+Copyright 2007 The Closure Library Authors. All Rights Reserved.
+
+Use of this source code is governed by the Apache License, Version 2.0.
+See the COPYING file for details.
+-->
+<!--
+-->
+<head>
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
+<title>Closure Unit Tests - goog.net.Jsonp</title>
+<script src="../base.js"></script>
+<script>
+  goog.require('goog.dom');
+  goog.require('goog.net.Jsonp');
+  goog.require('goog.testing.jsunit');
+  goog.require('goog.userAgent');
+  goog.require('goog.testing.recordFunction');
+  goog.require('goog.testing.PropertyReplacer');
+</script>
+</head>
+<body>
+<script>
+// Global vars to facilitate a shared set up function.
+
+var timeoutWasCalled;
+var timeoutHandler;
+
+var fakeUrl = 'http://fake-site.eek/';
+
+var originalTimeout;
+function setUp() {
+  timeoutWasCalled = false;
+  timeoutHandler = null;
+  originalTimeout = window.setTimeout;
+  window.setTimeout = function(handler, time) {
+    timeoutWasCalled = true;
+    timeoutHandler = handler;
+  };
+}
+
+// Firefox throws a JS error when a script is not found.  We catch that here and
+// ensure the test case doesn't fail because of it.
+var originalOnError = window.onerror;
+window.onerror = function(msg, url, line) {
+  // TODO(user): Safari 3 on the farm returns an object instead of the typcial
+  // params.  Pass through errors for safari for now.
+  if (goog.userAgent.WEBKIT ||
+      msg == 'Error loading script' && url.indexOf('fake-site') != -1) {
+    return true;
+  } else {
+    return originalOnError && originalOnError(msg, url, line);
+  }
+};
+
+function tearDown() {
+  window.setTimeout = originalTimeout;
+}
+
+// Quick function records the before-state of the DOM, and then return a
+// a function to check that XDC isn't leaving stuff behind.
+function newCleanupGuard() {
+  var bodyChildCount = document.body.childNodes.length;
+
+  return function() {
+    // let any timeout queues finish before we check these:
+    window.setTimeout(function() {
+      var propCounter = 0;
+
+      // All callbacks should have been deleted or be the null function.
+      for (var id in goog.global[goog.net.Jsonp.CALLBACKS]) {
+        if (goog.global[goog.net.Jsonp.CALLBACKS][id] != goog.nullFunction) {
+          propCounter++;
+        }
+      }
+
+      assertEquals(
+          'script cleanup', bodyChildCount, document.body.childNodes.length);
+      assertEquals('window jsonp array empty', 0, propCounter);
+    }, 0);
+  }
+}
+
+
+// Check that send function is sane when things go well.
+function testSend() {
+  var replyReceived;
+  var jsonp = new goog.net.Jsonp(fakeUrl);
+
+  var checkCleanup = newCleanupGuard();
+
+  var userCallback = function(data) {
+    replyReceived = data;
+  }
+
+  var payload = {atisket: 'atasket', basket: 'yellow'};
+  var result = jsonp.send(payload, userCallback);
+
+  var script = goog.dom.getElement(result.id_);
+
+  assertNotNull('script created', script);
+  assertEquals('encoding is utf-8', 'UTF-8', script.charset);
+
+  // Check that the URL matches our payload.
+  assertTrue('payload in url', script.src.indexOf('basket=yellow') > -1);
+  assertTrue('server url', script.src.indexOf(fakeUrl) == 0);
+
+  // Now, we have to track down the name of the callback function, so we can
+  // call that to simulate a returned request.
+  var callbackName = /callback=([^&]+)/.exec(script.src)[1];
+  var callbackFunc = eval(callbackName);
+  callbackFunc({some: 'data', another: ['data', 'right', 'here']});
+  assertEquals('input was received', 'right', replyReceived.another[1]);
+
+  // Verify that the same callback function does not break if it receives a
+  // second unexpected parameter.
+  callbackFunc({some: 'data', another: ['data', 'right', 'here']},
+      'unexpected');
+  assertEquals('input was received', 'right', replyReceived.another[1]);
+
+  // Because the callbackFunc calls cleanUp_ and that calls setTimeout which
+  // we have overwritten, we have to call the timeoutHandler to actually do
+  // the cleaning.
+  timeoutHandler();
+
+  checkCleanup();
+  timeoutHandler();
+}
+
+
+// Check that send function is sane when things go well.
+function testSendWhenCallbackHasTwoParameters() {
+  var replyReceived, replyReceived2;
+  var jsonp = new goog.net.Jsonp(fakeUrl);
+
+  var checkCleanup = newCleanupGuard();
+
+  var userCallback = function(data, opt_data2) {
+    replyReceived = data;
+    replyReceived2 = opt_data2;
+  }
+
+  var payload = {atisket: 'atasket', basket: 'yellow'};
+  var result = jsonp.send(payload, userCallback);
+  var script = goog.dom.getElement(result.id_);
+
+  // Test a callback function that receives two parameters.
+  var callbackName = /callback=([^&]+)/.exec(script.src)[1];
+  var callbackFunc = eval(callbackName);
+  callbackFunc('param1', {some: 'data', another: ['data', 'right', 'here']});
+  assertEquals('input was received', 'param1', replyReceived);
+  assertEquals('second input was received', 'right',
+      replyReceived2.another[1]);
+
+  // Because the callbackFunc calls cleanUp_ and that calls setTimeout which
+  // we have overwritten, we have to call the timeoutHandler to actually do
+  // the cleaning.
+  timeoutHandler();
+
+  checkCleanup();
+  timeoutHandler();
+}
+
+// Check that send function works correctly when callback param value is
+// specified.
+function testSendWithCallbackParamValue() {
+  var replyReceived;
+  var jsonp = new goog.net.Jsonp(fakeUrl);
+
+  var checkCleanup = newCleanupGuard();
+
+  var userCallback = function(data) {
+    replyReceived = data;
+  }
+
+  var payload = {atisket: 'atasket', basket: 'yellow'};
+  var result = jsonp.send(payload, userCallback, undefined, 'dummyId');
+
+  var script = goog.dom.getElement(result.id_);
+
+  assertNotNull('script created', script);
+  assertEquals('encoding is utf-8', 'UTF-8', script.charset);
+
+  // Check that the URL matches our payload.
+  assertTrue('payload in url', script.src.indexOf('basket=yellow') > -1);
+  assertTrue('dummyId in url',
+      script.src.indexOf('callback=_callbacks_.dummyId') > -1);
+  assertTrue('server url', script.src.indexOf(fakeUrl) == 0);
+
+  // Now, we simulate a returned request using the known callback function
+  // name.
+  var callbackFunc = _callbacks_.dummyId;
+  callbackFunc({some: 'data', another: ['data', 'right', 'here']});
+  assertEquals('input was received', 'right', replyReceived.another[1]);
+
+  // Verify that the same callback function does not break if it receives a
+  // second unexpected parameter.
+  callbackFunc({some: 'data', another: ['data', 'right', 'here']},
+      'unexpected');
+  assertEquals('input was received', 'right', replyReceived.another[1]);
+
+  // Because the callbackFunc calls cleanUp_ and that calls setTimeout which
+  // we have overwritten, we have to call the timeoutHandler to actually do
+  // the cleaning.
+  timeoutHandler();
+
+  checkCleanup();
+  timeoutHandler();
+}
+
+
+// Check that the send function is sane when the thing goes south.
+function testSendFailure() {
+  var replyReceived = false;
+  var errorReplyReceived = false;
+
+  var jsonp = new goog.net.Jsonp(fakeUrl);
+
+  var checkCleanup = newCleanupGuard();
+
+  var userCallback = function(data) {
+    replyReceived = data;
+  }
+  var userErrorCallback = function(data) {
+    errorReplyReceived = data;
+  }
+
+  var payload = { justa: 'test' };
+
+  jsonp.send(payload, userCallback, userErrorCallback);
+
+  assertTrue('timeout called', timeoutWasCalled);
+
+  // Now, simulate the time running out, so we go into error mode.
+  // After jsonp.send(), the timeoutHandler now is the Jsonp.cleanUp_ function.
+  timeoutHandler();
+  // But that function also calls a setTimeout(), so it changes the timeout
+  // handler once again, so to actually clean up we have to call the
+  // timeoutHandler() once again. Fun!
+  timeoutHandler();
+
+  assertFalse('standard callback not called', replyReceived);
+
+  // The user's error handler should be called back with the same payload
+  // passed back to it.
+  assertEquals('error handler called', 'test', errorReplyReceived.justa);
+
+  // Check that the relevant cleanup has occurred.
+  checkCleanup();
+  // Check cleanup just calls setTimeout so we have to call the handler to
+  // actually check that the cleanup worked.
+  timeoutHandler();
+}
+
+
+// Check that a cancel call works and cleans up after itself.
+function testCancel() {
+  var checkCleanup = newCleanupGuard();
+
+  var successCalled = false;
+  var successCallback = function() {
+    successCalled = true;
+  };
+
+  // Send and cancel a request, then make sure it was cleaned up.
+  var jsonp = new goog.net.Jsonp(fakeUrl);
+  var requestObject = jsonp.send({test: 'foo'}, successCallback);
+  jsonp.cancel(requestObject);
+
+  for (var key in goog.global[goog.net.Jsonp.CALLBACKS]) {
+    assertNotEquals('The success callback should have been removed',
+                    goog.global[goog.net.Jsonp.CALLBACKS][key],
+                    successCallback);
+  }
+
+  // Make sure cancelling removes the script tag
+  checkCleanup();
+  timeoutHandler();
+}
+
+function testPayloadParameters() {
+  var checkCleanup = newCleanupGuard();
+
+  var jsonp = new goog.net.Jsonp(fakeUrl);
+  var result = jsonp.send({
+    'foo': 3,
+    'bar': 'baz'
+  });
+
+  var script = goog.dom.getElement(result.id_);
+  assertEquals('Payload parameters should have been added to url.',
+               fakeUrl + '?foo=3&bar=baz',
+               script.src);
+
+  checkCleanup();
+  timeoutHandler();
+}
+
+function testOptionalPayload() {
+  var checkCleanup = newCleanupGuard();
+
+  var errorCallback = goog.testing.recordFunction();
+
+  var stubs = new goog.testing.PropertyReplacer();
+  stubs.set(goog.global, 'setTimeout', function(errorHandler) {
+    errorHandler();
+  });
+
+  var jsonp = new goog.net.Jsonp(fakeUrl);
+  var result = jsonp.send(null, null, errorCallback);
+
+  var script = goog.dom.getElement(result.id_);
+  assertEquals('Parameters should not have been added to url.',
+               fakeUrl, script.src);
+
+  var errorCallbackArguments = errorCallback.getLastCall().getArguments();
+  assertEquals(1, errorCallbackArguments.length);
+  assertNull(errorCallbackArguments[0]);
+
+  checkCleanup();
+  stubs.reset();
+}
+
+</script>
+</body>
+</html>