sproutcore 1.0.1003 → 1.0.1008

data/frameworks/sproutcore/frameworks/foundation/system/request.js

@@ -4,383 +4,540 @@
 //            Portions ©2008-2009 Apple Inc. All rights reserved.
 // License:   Licened under MIT license (see license.js)
 // ==========================================================================
-/*global ActiveXObject */
+
+sc_require('system/response');
 
 /**
-  Description to come.
+  @class
+  
+  Implements support for Ajax requests using XHR, JSON-P and other prototcols.
+  
+  SC.Request is much like an inverted version of the request/response objects
+  you receive when implement HTTP servers.  
+  
+  To send a request, you just need to create your request object, configure
+  your options, and call send() to initiate the request.
   
+  @extends SC.Object
+  @extends SC.Copyable
+  @extends SC.Freezable
   @since SproutCore 1.0
 */
 
-SC.Request = SC.Object.extend({
+SC.Request = SC.Object.extend(SC.Copyable, SC.Freezable,
+  /** @scope SC.Request.prototype */ {
   
-  isAsynchronous: true,
-  rawResponse: null,
-  error: null,
-  transportClass: null,
-  isJSON: false,
+  // ..........................................................
+  // PROPERTIES
+  // 
   
   /**
-    Sets up the request object
+    Sends the request asynchronously instead of blocking the browser.  You
+    should almost always make requests asynchronous.  You can change this 
+    options with the async() helper option (or simply set it directly).
+    
+    Defaults to YES. 
+    
+    @property {Boolean}
   */
-  init: function(){
-    sc_super() ;  
-    this._headers = {};
-  },
-  
+  isAsynchronous: YES,
+
   /**
-    To set headers on the request object
+    Processes the request and response as JSON if possible.  You can change
+    this option with the json() helper method.
+
+    Defaults to NO 
     
-    @param {String} key
-    @param {String} value
-    @returns {SC.Request} receiver
+    @property {Boolean}
   */
-  header: function(key, value) {
-    if (typeof key == 'object' && !value) {
-      for (var headerKey in key) {
-        this.header(headerKey,key[headerKey]) ;
-      }
-      return this;
-    }
-    
-    if (typeof key == 'string' && !value) {
-      return this._headers[key] ;
-    }
-    
-    this.propertyWillChange('headers') ;
-    
-    //set value for key
-    this._headers[key] = value ;
+  isJSON: NO,
+
+  /**
+    Process the request and response as XML if possible.  You can change this
+    option with the xml() helper method.
     
-    this.propertyDidChange('headers') ;
-    return this ;
-  },
+    Defaults to NO
+  
+    @property {Boolean}
+  */
+  isXML: NO,
   
   /**
-    Will fire the actual request.
-    
-    @param {String} body (optional)
-    @returns {SC.Request} receiver
-  */  
-  send: function(body) {
-    var request = this ; 
-    
-    var isJSON = request.get('isJSON');
-    
-    // Set the content-type to JSON (many browsers will otherwise default it
-    // to XML).
-    if (isJSON) request.header('Content-Type', 'application/json');
+    Current set of headers for the request
+  */
+  headers: function() {
+    var ret = this._headers ;
+    if (!ret) ret = this._headers = {} ;
+    return ret ;  
+  }.property().cacheable(),
+
+  /**
+    Underlying response class to actually handle this request.  Currently the
+    only supported option is SC.XHRResponse which uses a traditional
+    XHR transport.
     
-    if (body) {
-      if (isJSON) {
-        body=SC.json.encode(body);
-        if(body===undefined) console.error('There was an error encoding to JSON');
-      }
-      request.set('body', body) ;
-    }
-    SC.Request.manager.sendRequest(request) ;
-    return request ;
-  },
+    @property {SC.Response}
+  */
+  responseClass: SC.XHRResponse,
 
   /**
-    Set up notifications.
+    The original request for copied requests.
     
-    @param {Object} target
-    @param {String|function} action
-    @param {Hash} params
-    @returns {SC.Request} receiver
+    @property {SC.Request}
   */
-  notify: function(target, action, params) {
-    if (SC.typeOf(action) === SC.T_STRING) action = target[action];
-    this.set('notifyTarget', target)
-    .set('notifyAction', action)
-    .set('notifyParams', params);
-    return this;
-  },
+  source: null,
   
   /**
-    Response method
+    The URL this request to go to.
     
-    @returns {Object} response
+    @param {String}
   */
-  response: function() {
-    var response = this.get("rawResponse") ;
-    if (!response || !SC.$ok(response) || response.responseText.trim()==='') {
-        return response ;
-    }
-    
-    if (this.get("isJSON")) {
-      var source = response.responseText ;
-      try{
-        var json = SC.json.decode(source) ;
-      }catch(e){
-        json = response.responseText ;
-      }
-      //TODO cache this value?
-      return json ;
-    }
-    
-    if(response.responseXML) return response.responseXML ;
-    return response.responseText ;
-  }.property('rawResponse').cacheable()
+  address: null,
   
-});
-
-/**
-  Helper method for quickly setting up a GET request.
+  /**
+    The HTTP method to use.
+    
+    @param {String}
+  */
+  type: 'GET',
   
-  @param {String} address url of request
-  @returns {SC.Request} receiver
-*/
-SC.Request.getUrl = function(address) {
-  var req = SC.Request.create() ;
-  req.set('address', address) ;
-  req.set('type', 'GET') ;
+  /**
+    The body of the request.  May be an object is isJSON or isXML is set,
+    otherwise should be a string.
+  */
+  body: null,
   
-  return req ;
-};
+  /**
+    The body, encoded as JSON or XML if needed.
+  */
+  encodedBody: function() {
+    // TODO: support XML
+    var ret = this.get('body');
+    if (ret && this.get('isJSON')) ret = SC.json.encode(ret);
+    return ret ;
+  }.property('isJSON', 'isXML', 'body').cacheable(),
 
-/**
-  Helper method for quickly setting up a POST request.
-  
-  @param {String} address url of request
-  @param {String} body
-  @returns {SC.Request} receiver
-*/
-SC.Request.postUrl = function(address, body) {
-  var req = SC.Request.create() ;
-  req.set('address',address) ;
-  if(body) req.set('body', body) ;
-  req.set('type', 'POST') ;
+  // ..........................................................
+  // CALLBACKS
+  // 
   
-  return req ;
-};
-
-/**
-  Helper method for quickly setting up a DELETE request.
+  /**
+    Invoked on the original request object just before a copied request is 
+    frozen and then sent to the server.  This gives you one last change to 
+    fixup the request; possibly adding headers and other options.
+    
+    If you do not want the request to actually send, call cancel().
+    
+    @param {SC.Request} request a copy of the request, not frozen
+    @returns {void}
+  */
+  willSend: function(request, response) {},
   
-  @param {String} address url of request
-  @returns {SC.Request} receiver
-*/
-SC.Request.deleteUrl = function(address) {
-  var req = SC.Request.create() ;
-  req.set('address',address) ;
-  req.set('type', 'DELETE') ;
+  /**
+    Invoked on the original request object just after the request is sent to
+    the server.  You might use this callback to update some state in your 
+    application.
+    
+    The passed request is a frozen copy of the request, indicating the 
+    options set at the time of the request.
+    
+    @param {SC.Request} request a copy of the request, frozen
+    @param {SC.Response} response the object that will carry the response
+    @returns {void}
+  */
+  didSend: function(request, response) {},
   
-  return req ;
-};
-
-/**
-  Helper method for quickly setting up a PUT request.
+  /**
+    Invoked when a response has been received but not yet processed.  This is
+    your chance to fixup the response based on the results.  If you don't want
+    to continue processing the response call response.cancel().
+    
+    @param {SC.Response} response the response
+    @returns {void}
+  */
+  willReceive: function(request, response) {},
   
-  @param {String} address url of request
-  @param {String} body
-  @returns {SC.Request} receiver
-*/
-SC.Request.putUrl = function(address, body) {
-  var req = SC.Request.create() ;
-  req.set('address',address) ;
-  if(body) req.set('body', body) ;
-  req.set('type', 'PUT') ;
+  /**
+    Invoked after a response has been processed but before any listeners are
+    notified.  You can do any standard processing on the request at this 
+    point.  If you don't want to allow notifications to continue, call
+    response.cancel()
+    
+    @param {SC.Response} response reponse
+    @returns {void}
+  */
+  didReceive: function(request, response) {},
   
-  return req ;
-};
+  // ..........................................................
+  // HELPER METHODS
+  // 
 
-/**
-  The request manager.
-  More description to come.
-*/
-SC.Request.manager = SC.Object.create( SC.DelegateSupport, {
-  maxRequests: 2,
-  
-  currentRequests: [],
-  queue: [],
-  
-  canLoadAnotherRequest: function() {
-    return (this.get('numberOfCurrentRequests') < this.get('maxRequests')) ;
-  }.property('numberOfCurrentRequests', 'maxRequests'),
+  COPY_KEYS: 'isAsynchronous isJSON isXML address type body responseClass willSend didSend willReceive didReceive'.w(),
   
-  numberOfCurrentRequests: function() {
-    return this.get('currentRequests').length ;
-  }.property('currentRequests'),
-  
-  numberOfRequests: function() {
-    return this.get('queue').length ;
-  }.property('queue'),
-  
-  sendRequest: function(request) {
-    if(!request) return;
+  /**
+    Returns a copy of the current request.  This will only copy certain
+    properties so if you want to add additional properties to the copy you
+    will need to override copy() in a subclass.
     
-    request = { 
-      request: request, 
-      action:  request.get('notifyAction'),
-      target:  request.get('notifyTarget'),
-      params:  request.get('notifyParams') };
+    @returns {SC.Request} new request
+  */
+  copy: function() {
+    var ret = {},
+        keys = this.COPY_KEYS,
+        loc  = keys.length, 
+        key, listeners, headers;
+        
+    while(--loc>=0) {
+      key = keys[loc];
+      if (this.hasOwnProperty(key)) ret[key] = this.get(key);
+    }
     
-    this.propertyWillChange("queue");
-    this.get('queue').pushObject(request);
-    this.propertyDidChange("queue");
+    if (this.hasOwnProperty('listeners')) {
+      ret.listeners = SC.copy(this.get('listeners'));
+    }
     
-    this.fireRequestIfNeeded();
-  },
-  
-  removeRequest: function(request) {
-    this.get('queue').removeObject(request);
-    return YES;
-  },  
-  
-  cancelAllRequests: function() {
-    var r, xhrRequest;
-    this.set('queue', []);
-    var activeRequests=this.get('currentRequests');
-    while(r=activeRequests.shiftObject()){
-      xhrRequest = r.get('request');
-      xhrRequest.abort();
+    if (this.hasOwnProperty('_headers')) {
+      ret._headers = SC.copy(this._headers);
     }
-    return YES;
+    
+    ret.source = this.get('source') || this ;
+    
+    return this.constructor.create(ret);
   },
   
-  fireRequestIfNeeded: function() {
-    if (this.canLoadAnotherRequest()) {
-      this.propertyWillChange('queue') ;
-      var item = this.get('queue').shiftObject() ;
-      this.propertyDidChange('queue') ;
-      
-      if (item) {
-        var transportClass = item.request.get('transportClass') ;
-        if (!transportClass) transportClass = this.get('transportClass') ;
-        
-        if (transportClass) {
-          var transport = this.transportClass.create(item) ;
-          if (transport) {
-            item.request.set('transport', transport) ;
-            this._transportDidOpen(transport) ;
-          }
-        }
+  /**
+    To set headers on the request object.  Pass either a single key/value 
+    pair or a hash of key/value pairs.  If you pass only a header name, this
+    will return the current value of the header.
+    
+    @param {String|Hash} key
+    @param {String} value
+    @returns {SC.Request|Object} receiver
+  */
+  header: function(key, value) {
+    var headers;
+    
+    if (SC.typeOf(key) === SC.T_STRING) {
+      headers = this._headers ;
+      if (arguments.length===1) {
+        return headers ? headers[key] : null;
+      } else {
+        this.propertyWillChange('headers');
+        if (!headers) headers = this._headers = {};
+        headers[key] = value;
+        this.propertyDidChange('headers');
+        return this;
       }
+    
+    // handle parsing hash of parameters
+    } else if (value === undefined) {
+      headers = key;
+      this.beginPropertyChanges();
+      for(key in headers) {
+        if (!headers.hasOwnProperty(key)) continue ;
+        this.header(key, headers[key]);
+      }
+      this.endPropertyChanges();
+      return this;
     }
-  }.observes('currentRequests'),
-  
-  _transportDidOpen: function(transport) {
-    this.propertyWillChange('currentRequests') ;
-    this.get('currentRequests').pushObject(transport) ;
-    this.propertyDidChange('currentRequests') ;
-    transport.fire() ;
+
+    return this ;
   },
   
-  transportDidClose: function(request) {
-    this.propertyWillChange('currentRequests') ;
-    this.get('currentRequests').removeObject(request) ;
-    this.propertyDidChange('currentRequests') ;
-  }
+  /**
+    Converts the current request to use JSON.
+    
+    @property {Boolean} flag YES to make JSON, NO or undefined
+    @returns {SC.Request} receiver
+  */
+  json: function(flag) {
+    if (flag === undefined) flag = YES;
+    if (flag) this.set('isXML', NO);
+    return this.set('isJSON', flag);
+  },
   
-});
-
-// abstract superclass, creates no-op objects
-SC.RequestTransport = SC.Object.extend({
+  /**
+    Converts the current request to use XML.
+    
+    @property {Boolean} flag YES to make XML, NO or undefined
+    @returns {SC.Request} recevier
+  */
+  xml: function(flag) {
+    if (flag === undefined) flag = YES ;
+    if (flag) this.set('isJSON', NO);
+    return this.set('isXML', flag);
+  },
   
-  fire: function() {
-    SC.Request.manager.transportDidClose(this) ;
-  }
+  /** 
+    Called just before a request is enqueued.  This will encode the body 
+    into JSON if it is not already encoded.
+  */
+  _prep: function() {
+    var hasContentType = !!this.header('Content-Type');
+    if (this.get('isJSON') && !hasContentType) {
+      this.header('Content-Type', 'application/json');
+    } else if (this.get('isXML') && !hasContentType) {
+      this.header('Content-Type', 'text/xml');
+    }
+    return this ;
+  },
   
-});
+  /**
+    Will fire the actual request.  If you have set the request to use JSON 
+    mode then you can pass any object that can be converted to JSON as the 
+    body.  Otherwise you should pass a string body.
+    
+    @param {String|Object} body (optional)
+    @returns {SC.Response} new response object
+  */  
+  send: function(body) {
+    if (body) this.set('body', body);
+    return SC.Request.manager.sendRequest(this.copy()._prep());
+  },
 
-SC.XHRRequestTransport = SC.RequestTransport.extend({
+  /**
+    Resends the current request.  This is more efficient than calling send()
+    for requests that have already been used in a send.  Otherwise acts just
+    like send().  Does not take a body argument.
+    
+    @returns {SC.Response} new response object
+  */
+  resend: function() {
+    var req = this.get('source') ? this : this.copy()._prep();
+    return SC.Request.manager.sendRequest(req);
+  },
   
-  fire: function() {
-    
-    var tryThese = function() {
-      for (var i=0; i < arguments.length; i++) {
-        try {
-          var item = arguments[i]() ;
-          return item ;
-        } catch (e) {}
-      }
-      return NO;
-    };
+  /**
+    Configures a callback to execute when a request completes.  You must pass
+    at least a target and action/method to this and optionally a status code.
+    You may also pass additional parameters which will be passed along to your
+    callback.
     
-    var rawRequest = tryThese(
-      function() { return new XMLHttpRequest(); },
-      function() { return new ActiveXObject('Msxml2.XMLHTTP'); },
-      function() { return new ActiveXObject('Microsoft.XMLHTTP'); }
-    );
+    h2. Scoping With Status Codes
     
-    var request = this.get('request') ;
+    If you pass a status code as the first option to this method, then your 
+    notification callback will only be called if the response status matches
+    the code.  For example, if you pass 201 (or SC.Request.CREATED) then 
+    your method will only be called if the response status from the server
+    is 201.
     
-    rawRequest.source = request;
+    You can also pass "generic" status codes such as 200, 300, or 400, which
+    will be invoked anytime the status code is the range if a more specific 
+    notifier was not registered first and returned YES.  
     
+    Finally, passing a status code of 0 or no status at all will cause your
+    method to be executed no matter what the resulting status is unless a 
+    more specific notifier was registered and returned YES.
     
-    //Part of the fix for IE
-    var transport=this;
-    var handleReadyStateChange = function() {
-      return transport.finishRequest(rawRequest) ;
-    };
-    //End of the fix for IE
+    h2. Callback Format
     
-    var async = (request.get('isAsynchronous') ? YES : NO) ;
-    if (async) {
-      if (!SC.browser.msie) {
-        SC.Event.add(rawRequest, 'readystatechange', this, handleReadyStateChange, rawRequest) ;
-      } else rawRequest.onreadystatechange = handleReadyStateChange;
-    }
+    Your notification callback should expect to receive the Response object
+    as the first parameter plus any additional parameters that you pass.  
     
+    @param {Object} target
+    @param {String|function} action
+    @param {Hash} params
+    @returns {SC.Request} receiver
+  */
+  notify: function(status, target, action) {
+    
+    // normalize status
+    var hasStatus = YES, params ;
+    if (SC.typeOf(status) !== SC.T_NUMBER) {
+      params = SC.A(arguments).slice(2);
+      action = target;
+      target = status;
+      status = 0 ;
+      hasStatus = NO ;
+    } else params = SC.A(arguments).slice(3);
+    
+    var listeners = this.get('listeners');
+    if (!listeners) this.set('listeners', listeners = {});
+    listeners[status] = { target: target, action: action, params: params };
+
+    return this;
+  }
     
+});
+
+SC.Request.mixin(/** @scope SC.Request */ {
+  
+  /**
+    Helper method for quickly setting up a GET request.
+
+    @param {String} address url of request
+    @returns {SC.Request} receiver
+  */
+  getUrl: function(address) {
+    return SC.Request.create().set('address', address).set('type', 'GET');
+  },
+
+  /**
+    Helper method for quickly setting up a POST request.
+
+    @param {String} address url of request
+    @param {String} body
+    @returns {SC.Request} receiver
+  */
+  postUrl: function(address, body) {
+    var req = SC.Request.create().set('address', address).set('type', 'POST');
+    if(body) req.set('body', body) ;
+    return req ;
+  },
+
+  /**
+    Helper method for quickly setting up a DELETE request.
+
+    @param {String} address url of request
+    @returns {SC.Request} receiver
+  */
+  deleteUrl: function(address) {
+    return SC.Request.create().set('address', address).set('type', 'DELETE');
+  },
+
+  /**
+    Helper method for quickly setting up a PUT request.
+
+    @param {String} address url of request
+    @param {String} body
+    @returns {SC.Request} receiver
+  */
+  putUrl: function(address, body) {
+    var req = SC.Request.create().set('address', address).set('type', 'PUT');
+    if(body) req.set('body', body) ;
+    return req ;
+  }
+  
+});
+
+
+
+/**
+  The request manager coordinates all of the active XHR requests.  It will
+  only allow a certain number of requests to be active at a time; queuing 
+  any others.  This allows you more precise control over which requests load
+  in which order.
+*/
+SC.Request.manager = SC.Object.create( SC.DelegateSupport, {
+
+  /**
+    Maximum number of concurrent requests allowed.  6 for all browsers.
     
-    rawRequest.open( request.get('type'), request.get('address'), async ) ;
+    @property {Number}
+  */
+  maxRequests: 6,
+
+  /**
+    Current requests that are inflight.
     
-    // headers need to be set *After* the open call.
-    var headers = request._headers ;
-    for (var headerKey in headers) {
-      rawRequest.setRequestHeader(headerKey, headers[headerKey]) ;
-    }
+    @property {Array}
+  */
+  inflight: [],
+  
+  /**
+    Requests that are pending and have not been started yet.
+  
+    @property {Array}
+  */
+  pending: [],
+
+  // ..........................................................
+  // METHODS
+  // 
+  
+  /**
+    Invoked by the send() method on a request.  This will create a new low-
+    level transport object and queue it if needed.
     
-    rawRequest.send(request.get('body')) ;
+    @param {SC.Request} request the request to send
+    @returns {SC.Object} response object
+  */
+  sendRequest: function(request) {
+    if (!request) return null ;
     
-    if (!async) this.finishRequest(rawRequest) ;
+    // create low-level transport.  copy all critical data for request over
+    // so that if the request has been reconfigured the transport will still
+    // work.
+    var response = request.get('responseClass').create({ request: request });
+
+    // add to pending queue
+    this.get('pending').pushObject(response);
+    this.fireRequestIfNeeded();
     
-    return rawRequest ;
+    return response ;
   },
-  
-  didSucceed: function(request) {
-    var status = null ;
-    try {
-        status = request.status || 0;
-    } catch (e) {}
-    return !status || (status >= 200 && status < 300) ;      
-  },
-  
-  finishRequest: function(request) {
-    
-    var readyState = request.readyState ;
-    var didSucceed = !request ? NO : this.didSucceed(request) ;
+
+  /** 
+    Cancels a specific request.  If the request is pending it will simply
+    be removed.  Otherwise it will actually be cancelled.
     
-    if (readyState == 4) {
-      request._complete = YES ;
+    @param {Object} response a response object
+    @returns {Boolean} YES if cancelled
+  */
+  cancel: function(response) {
+
+    var pending = this.get('pending'),
+        inflight = this.get('inflight'),
+        idx ;
+
+    if (pending.indexOf(response) >= 0) {
+      this.propertyWillChange('pending');
+      pending.removeObject(response);
+      this.propertyDidChange('pending');
+      return YES;
       
-      if (didSucceed) {
-        var response = request ;
-        request.source.set('rawResponse', response) ; 
-      } else {
-        var error = SC.$error("HTTP Request failed", "Fail", -1) ;
-        error.set("request",request) ;
-        request.source.set('rawResponse', error) ;
-      }
-      if (this.target && this.action) {
-        SC.RunLoop.begin();
-        this.action.call(this.target, request.source, this.params);
-        SC.RunLoop.end();
-      }
+    } else if (inflight.indexOf(response) >= 0) {
       
-      SC.Request.manager.transportDidClose(this) ;
-     }
-     
-     if (readyState == 4) {
-       // avoid memory leak in MSIE: clean up
-       request.onreadystatechange = function() {} ;
-     }
-  }
+      response.cancel();
+      
+      inflight.removeObject(response);
+      this.fireRequestIfNeeded();
+      return YES;
+
+    } else return NO ;
+  },  
+
+  /**
+    Cancels all inflight and pending requests.  
+    
+    @returns {Boolean} YES if any items were cancelled.
+  */
+  cancelAll: function() {
+    if (this.get('pending').length || this.get('inflight').length) {
+      this.set('pending', []);
+      this.get('inflight').forEach(function(r) { r.cancel(); });
+      this.set('inflight', []);
+      return YES;
+      
+    } else return NO ;
+  },
+  
+  /**
+    Checks the inflight queue.  If there is an open slot, this will move a 
+    request from pending to inflight.
+    
+    @returns {Object} receiver
+  */
+  fireRequestIfNeeded: function() {
+    var pending = this.get('pending'), 
+        inflight = this.get('inflight'),
+        max = this.get('maxRequests'),
+        next ;
+        
+    if ((pending.length>0) && (inflight.length<max)) {
+      next = pending.shiftObject();
+      inflight.pushObject(next);
+      next.fire();
+    }
+  },
 
+  /**
+    Called by a response/transport object when finishes running.  Removes 
+    the transport from the queue and kicks off the next one.
+  */
+  transportDidClose: function(response) {
+    this.get('inflight').removeObject(response);
+    this.fireRequestIfNeeded();
+  }
   
 });
-
-SC.Request.manager.set('transportClass', SC.XHRRequestTransport) ;