sproutcore 1.6.0.beta.3 → 1.6.0.rc.1

data/lib/frameworks/sproutcore/frameworks/ajax/system/response.js

@@ -6,49 +6,58 @@
 // ==========================================================================
 /*global ActiveXObject */
 
+/*
+  TODO Document SC.Response and SC.XHRResponse
+*/
+
 /**
+  @class
+
   A response represents a single response from a server request.  An instance
   of this class is returned whenever you call SC.Request.send().
-  
-  TODO: Add more info
-  
+
   @extend SC.Object
   @since SproutCore 1.0
 */
 SC.Response = SC.Object.extend(
 /** @scope SC.Response.prototype */ {
-  
+
   /**
     Becomes true if there was a failure.  Makes this into an error object.
     
-    @property {Boolean}
+    @type Boolean
+    @default NO
   */
   isError: NO,
-  
+
   /**
     Always the current response
-    
-    @property {SC.Response}
+
+    @field
+    @type SC.Response
+    @default `this`
   */
   errorValue: function() {
     return this;
   }.property().cacheable(),
-  
+
   /**
     The error object generated when this becomes an error
-    
-    @property {SC.Error}
+
+    @type SC.Error
+    @default null
   */
   errorObject: null,
-  
-  /** 
+
+  /**
     Request used to generate this response.  This is a copy of the original
     request object as you may have modified the original request object since
     then.
-   
+
     To retrieve the original request object use originalRequest.
-    
-    @property {SC.Request}
+
+    @type SC.Request
+    @default null
   */
   request: null,
   
@@ -56,38 +65,47 @@ SC.Response = SC.Object.extend(
     The request object that originated this request series.  Mostly this is
     useful if you are looking for a reference to the original request.  To
     inspect actual properties you should use request instead.
-    
-    @property {SC.Request}
+
+    @field
+    @type SC.Request
+    @observes request
   */
   originalRequest: function() {
     var ret = this.get('request');
-    while (ret.get('source')) ret = ret.get('source');
+    while (ret.get('source')) { ret = ret.get('source'); }
     return ret ;
   }.property('request').cacheable(),
 
   /** 
-    Type of request.  Must be an HTTP method.  Based on the request
-  
-    @property {String}
+    Type of request. Must be an HTTP method. Based on the request.
+
+    @field
+    @type String
+    @observes request
   */
   type: function() {
     return this.getPath('request.type');
   }.property('request').cacheable(),
-  
+
   /**
-    URL of request. 
-    
-    @property {String}
+    URL of request.
+
+    @field
+    @type String
+    @observes request
   */
   address: function() {
     return this.getPath('request.address');
   }.property('request').cacheable(),
-  
+
   /**
     If set then will attempt to automatically parse response as JSON 
     regardless of headers.
-    
-    @property {Boolean}
+
+    @field
+    @type Boolean
+    @default NO
+    @observes request
   */
   isJSON: function() {
     return this.getPath('request.isJSON') || NO;
@@ -96,41 +114,50 @@ SC.Response = SC.Object.extend(
   /**
     If set, then will attempt to automatically parse response as XML
     regarldess of headers.
-    
-    @property {Boolean}
+
+    @field
+    @type Boolean
+    @default NO
+    @observes request
   */
   isXML: function() {
     return this.getPath('request.isXML') || NO ;
   }.property('request').cacheable(),
-  
-  /** 
+
+  /**
     Returns the hash of listeners set on the request.
-    
-    @property {Hash}
+
+    @field
+    @type Hash
+    @observes request
   */
   listeners: function() {
     return this.getPath('request.listeners');
   }.property('request').cacheable(),
-  
+
   /**
     The response status code.
-    
-    @property {Number}
+
+    @type Number
+    @default -100
   */
   status: -100, // READY
 
   /**
-    Headers from the response.  Computed on-demand
-    
-    @property {Hash}
+    Headers from the response. Computed on-demand
+
+    @type Hash
+    @default null
   */
   headers: null,
-  
+
   /**
-    Response body. If isJSON was set, will be parsed automatically.
-    
-    @response {Hash|String|SC.Error} the response body or the parsed JSON.
-      Returns a SC.Error instance if there is a JSON parsing error.
+    The response body or the parsed JSON. Returns a SC.Error instance
+    if there is a JSON parsing error. If isJSON was set, will be parsed
+    automatically.
+
+    @field
+    @type {Hash|String|SC.Error}
   */
   body: function() {
     // TODO: support XML
@@ -147,74 +174,82 @@ SC.Response = SC.Object.extend(
     }
     return ret;
   }.property('encodedBody').cacheable(),
-  
-  /** 
+
+  /**
     @private
     @deprecated
-  
-    Alias for body.  Provides compatibility with older code.
-    
-    @property {Hash|String}
+
+    Alias for body. Provides compatibility with older code.
+
+    @type Hash|String
+    @see #body
   */
   response: function() {
     return this.get('body');
   }.property('body').cacheable(),
-  
+
   /**
     Set to YES if response is cancelled
+
+    @type Boolean
+    @default NO
   */
   isCancelled: NO,
-  
+
   /**
-    Set to YES if the request timed out.  Set to NO if the request has
-    completed before the timeout value.  Set to null if the timeout timer is
+    Set to YES if the request timed out. Set to NO if the request has
+    completed before the timeout value. Set to null if the timeout timer is
     still ticking.
+
+    @type Boolean
+    @default null
   */
   timedOut: null,
   
   /**
     The timer tracking the timeout
+
+    @type Number
+    @default null
   */
   timeoutTimer: null,
-  
+
+
   // ..........................................................
   // METHODS
   // 
 
   /**
-    Called by the request manager when its time to actually run.  This will
-    invoke any callbacks on the source request then invoke transport() to 
+    Called by the request manager when its time to actually run. This will
+    invoke any callbacks on the source request then invoke transport() to
     begin the actual request.
   */
   fire: function() {
     var req = this.get('request'),
         source = req ? req.get('source') : null;
-    
-    
+
     // first give the source a chance to fixup the request and response
     // then freeze req so no more changes can happen.
-    if (source && source.willSend) source.willSend(req, this);
+    if (source && source.willSend) { source.willSend(req, this); }
     req.freeze();
 
     // if the source did not cancel the request, then invoke the transport
     // to actually trigger the request.  This might receive a response 
     // immediately if it is synchronous.
-    if (!this.get('isCancelled')) this.invokeTransport();
-
+    if (!this.get('isCancelled')) { this.invokeTransport(); }
 
     // If the request specified a timeout value, then set a timer for it now.
     var timeout = req.get('timeout');
     if (timeout) {
       var timer = SC.Timer.schedule({
-        target:   this, 
-        action:   'timeoutReached', 
+        target: this,
+        action: 'timeoutReached',
         interval: timeout,
-        repeats:  NO
+        repeats: NO
       });
       this.set('timeoutTimer', timer);
     }
 
-
     // if the transport did not cancel the request for some reason, let the
     // source know that the request was sent
     if (!this.get('isCancelled') && source && source.didSend) {
@@ -222,17 +257,21 @@ SC.Response = SC.Object.extend(
     }
   },
 
+  /**
+    Called by `SC.Response#fire()`. Starts the transport by invoking the
+    `SC.Response#receive()` function.
+  */
   invokeTransport: function() {
     this.receive(function(proceed) { this.set('status', 200); }, this);
   },
-  
+
   /**
-    Invoked by the transport when it receives a response.  The passed-in
-    callback will be invoked to actually process the response.  If cancelled
-    we will pass NO.  You should clean up instead.
-    
+    Invoked by the transport when it receives a response. The passed-in
+    callback will be invoked to actually process the response. If cancelled
+    we will pass NO. You should clean up instead.
+
     Invokes callbacks on the source request also.
-    
+
     @param {Function} callback the function to receive
     @param {Object} context context to execute the callback in
     @returns {SC.Response} receiver
@@ -241,7 +280,7 @@ SC.Response = SC.Object.extend(
     if (!this.get('timedOut')) {
       // If we had a timeout timer scheduled, invalidate it now.
       var timer = this.get('timeoutTimer');
-      if (timer) timer.invalidate();
+      if (timer) { timer.invalidate(); }
       this.set('timedOut', NO);
     }
 
@@ -251,7 +290,7 @@ SC.Response = SC.Object.extend(
     SC.run(function() {
       // invoke the source, giving a chance to fixup the response or (more
       // likely) cancel the request.
-      if (source && source.willReceive) source.willReceive(req, this);
+      if (source && source.willReceive) { source.willReceive(req, this); }
 
       // invoke the callback.  note if the response was cancelled or not
       callback.call(context, !this.get('isCancelled'));
@@ -264,16 +303,16 @@ SC.Response = SC.Object.extend(
       }
 
       // notify listeners if we weren't cancelled.
-      if (!this.get('isCancelled')) this.notify();
+      if (!this.get('isCancelled')) { this.notify(); }
     }, this);
 
     // no matter what, remove from inflight queue
-    SC.Request.manager.transportDidClose(this) ;
+    SC.Request.manager.transportDidClose(this);
     return this;
   },
-  
+
   /**
-    Default method just closes the connection.  It will also mark the request
+    Default method just closes the connection. It will also mark the request
     as cancelled, which will not call any listeners.
   */
   cancel: function() {
@@ -283,9 +322,11 @@ SC.Response = SC.Object.extend(
       SC.Request.manager.transportDidClose(this) ;
     }
   },
-  
+
   /**
     Default method just closes the connection.
+
+    @returns {Boolean} YES if this response has not timed out yet, NO otherwise
   */
   timeoutReached: function() {
     // If we already received a response yet the timer still fired for some
@@ -298,7 +339,7 @@ SC.Response = SC.Object.extend(
       // any. In the event of a timeout, we set the status to 0 since we
       // didn't actually get a response from the server.
       this.receive(function(proceed) {
-        if (!proceed) return;
+        if (!proceed) { return; }
 
         // Set our value to an error.
         var error = SC.$error("HTTP Request timed out", "Request", 0) ;
@@ -313,67 +354,82 @@ SC.Response = SC.Object.extend(
 
     return NO;
   },
-  
+
   /**
     Override with concrete implementation to actually cancel the transport.
   */
   cancelTransport: function() {},
-  
-  /** @private
-    Will notify each listener.
+
+  /**
+    @private
+
+    Will notify each listener. Returns true if any of the listeners handle.
   */
-  _notifyListener: function(listeners, status) {
-    var info = listeners[status], params, target, action;
-    if (!info) return NO ;
-    
-    params = (info.params || []).copy();
-    params.unshift(this);
-    
-    target = info.target;
-    action = info.action;
-    if (SC.typeOf(action) === SC.T_STRING) action = target[action];
-    
-    return action.apply(target, params);
+  _notifyListeners: function(listeners, status) {
+    var notifiers = listeners[status], params, target, action;
+    if (!notifiers) { return NO; }
+
+    var handled = NO;
+    var len = notifiers.length;
+
+    for (var i = 0; i < len; i++) {
+      var notifier = notifiers[i];
+      params = (notifier.params || []).copy();
+      params.unshift(this);
+
+      target = notifier.target;
+      action = notifier.action;
+      if (SC.typeOf(action) === SC.T_STRING) { action = target[action]; }
+
+      handled = action.apply(target, params);
+    }
+
+    return handled;
   },
-  
+
   /**
-    Notifies any saved target/action.  Call whenever you cancel, or end.
-    
+    Notifies any saved target/action. Call whenever you cancel, or end.
+
     @returns {SC.Response} receiver
   */
   notify: function() {
-    var listeners = this.get('listeners'), 
-        status    = this.get('status'),
-        baseStat  = Math.floor(status / 100) * 100,
-        handled   = NO ;
-        
-    if (!listeners) return this ; // nothing to do
-    
-    handled = this._notifyListener(listeners, status);
-    if (!handled) handled = this._notifyListener(listeners, baseStat);
-    if (!handled) handled = this._notifyListener(listeners, 0);
+    var listeners = this.get('listeners'),
+        status = this.get('status'),
+        baseStat = Math.floor(status / 100) * 100,
+        handled = NO;
+
+    if (!listeners) { return this; }
+
+    handled = this._notifyListeners(listeners, status);
+    if (!handled && baseStat !== status) { handled = this._notifyListeners(listeners, baseStat); }
+    if (!handled && status !== 0) { handled = this._notifyListeners(listeners, 0); }
     
     return this ;
   },
   
   /**
     String representation of the response object
+
+    @returns {String}
   */
   toString: function() {
     var ret = sc_super();
     return "%@<%@ %@, status=%@".fmt(ret, this.get('type'), this.get('address'), this.get('status'));
   }
-  
+
 });
 
 /**
-  Concrete implementation of SC.Response that implements support for using 
+  @class
+
+  Concrete implementation of SC.Response that implements support for using
   XHR requests.
-  
+
   @extends SC.Response
   @since SproutCore 1.0
 */
-SC.XHRResponse = SC.Response.extend({
+SC.XHRResponse = SC.Response.extend(
+/** @scope SC.XHRResponse.prototype */{
 
   /**
     Implement transport-specific support for fetching all headers
@@ -382,77 +438,94 @@ SC.XHRResponse = SC.Response.extend({
     var xhr = this.get('rawRequest'),
         str = xhr ? xhr.getAllResponseHeaders() : null,
         ret = {};
-        
-    if (!str) return ret;
-    
+
+    if (!str) { return ret; }
+
     str.split("\n").forEach(function(header) {
       var idx = header.indexOf(':'),
           key, value;
-      if (idx>=0) {
+
+      if (idx >= 0) {
         key = header.slice(0,idx);
-        value = header.slice(idx+1).trim();
-        ret[key] = value ;
+        value = header.slice(idx + 1).trim();
+        ret[key] = value;
       }
     }, this);
-    
-    return ret ;
+
+    return ret;
   }.property('status').cacheable(),
-  
-  // returns a header value if found...
+
+  /**
+    Returns a header value if found.
+
+    @param {String} key The header key
+    @returns {String}
+  */
   header: function(key) {
     var xhr = this.get('rawRequest');
-    return xhr ? xhr.getResponseHeader(key) : null;    
+    return xhr ? xhr.getResponseHeader(key) : null;
   },
-  
+
   /**
     Implement transport-specific support for fetching tasks
+
+    @field
+    @type String
+    @default #rawRequest
   */
   encodedBody: function() {
-    var xhr = this.get('rawRequest'), ret ;
-    if (!xhr) ret = null;
-    else if (this.get('isXML')) ret = xhr.responseXML;
-    else ret = xhr.responseText;
-    return ret ;
+    var xhr = this.get('rawRequest');
+
+    if (!xhr) { return null; }
+    if (this.get('isXML')) { return xhr.responseXML; }
+
+    return xhr.responseText;
   }.property('status').cacheable(),
-  
 
+  /**
+    Cancels the request.
+  */
   cancelTransport: function() {
     var rawRequest = this.get('rawRequest');
-    if (rawRequest) rawRequest.abort();
+    if (rawRequest) { rawRequest.abort(); }
     this.set('rawRequest', null);
   },
 
+  /**
+    Starts the transport of the request
+
+    @returns {XMLHttpRequest|ActiveXObject}
+  */
   invokeTransport: function() {
     var rawRequest, transport, handleReadyStateChange, async, headers;
-    
-    rawRequest = this.createRequest();
 
-    // save it 
+    rawRequest = this.createRequest();
     this.set('rawRequest', rawRequest);
-    
+
     // configure async callback - differs per browser...
-    async = !!this.getPath('request.isAsynchronous') ;
+    async = !!this.getPath('request.isAsynchronous');
+
     if (async) {
-      if (!SC.browser.msie && !SC.browser.opera ) {
-        SC.Event.add(rawRequest, 'readystatechange', this, 
-                     this.finishRequest, rawRequest) ;
+      if (!SC.browser.msie && !SC.browser.opera) {
+        SC.Event.add(rawRequest, 'readystatechange', this,
+                     this.finishRequest, rawRequest);
       } else {
-        transport=this;
+        transport = this;
         handleReadyStateChange = function() {
-          if (!transport) return null ;
+          if (!transport) { return null; }
           var ret = transport.finishRequest();
-          if (ret) transport = null ; // cleanup memory
-          return ret ;
+          if (ret) { transport = null; }
+          return ret;
         };
         rawRequest.onreadystatechange = handleReadyStateChange;
       }
     }
-    
-    // initiate request.  
-    rawRequest.open(this.get('type'), this.get('address'), async ) ;
-    
+
+    // initiate request.
+    rawRequest.open(this.get('type'), this.get('address'), async);
+
     // headers need to be set *after* the open call.
-    headers = this.getPath('request.headers') ;
+    headers = this.getPath('request.headers');
     for (var headerKey in headers) {
       rawRequest.setRequestHeader(headerKey, headers[headerKey]) ;
     }
@@ -460,11 +533,11 @@ SC.XHRResponse = SC.Response.extend({
     // now send the actual request body - for sync requests browser will
     // block here
     rawRequest.send(this.getPath('request.encodedBody')) ;
-    if (!async) this.finishRequest() ; // not async
-    
-    return rawRequest ;
+    if (!async) { this.finishRequest(); }
+
+    return rawRequest;
   },
-  
+
   /**
     Creates the correct XMLHttpRequest object for this browser.
 
@@ -474,12 +547,11 @@ SC.XHRResponse = SC.Response.extend({
     @returns {XMLHttpRequest|ActiveXObject}
   */
   createRequest: function() {
-    // Get an XHR object
     function tryThese() {
       for (var i=0; i < arguments.length; i++) {
         try {
-          var item = arguments[i]() ;
-          return item ;
+          var item = arguments[i]();
+          return item;
         } catch (e) {}
       }
       return NO;
@@ -492,12 +564,13 @@ SC.XHRResponse = SC.Response.extend({
     );
   },
 
-  /**  @private
-  
+  /**
+    @private
+
     Called by the XHR when it responds with some final results.
-    
+
     @param {XMLHttpRequest} rawRequest the actual request
-    @returns {SC.XHRRequestTransport} receiver
+    @returns {Boolean} YES if completed, NO otherwise
   */
   finishRequest: function(evt) {
     var rawRequest = this.get('rawRequest'),
@@ -506,24 +579,24 @@ SC.XHRResponse = SC.Response.extend({
 
     if (readyState === 4 && !this.get('timedOut')) {
       this.receive(function(proceed) {
-        if (!proceed) return ; // skip receiving...
-      
+        if (!proceed) { return; }
+
         // collect the status and decide if we're in an error state or not
-        status = -1 ;
+        status = -1;
         try {
           status = rawRequest.status || 0;
         } catch (e) {}
 
         // if there was an error - setup error and save it
         if ((status < 200) || (status >= 300)) {
-          
+
           try {
             msg = rawRequest.statusText || '';
           } catch(e2) {
             msg = '';
           }
-          
-          error = SC.$error(msg || "HTTP Request failed", "Request", status) ;
+
+          error = SC.$error(msg || "HTTP Request failed", "Request", status);
           error.set("errorValue", this) ;
           this.set('isError', YES);
           this.set('errorObject', error);
@@ -531,20 +604,18 @@ SC.XHRResponse = SC.Response.extend({
 
         // set the status - this will trigger changes on relatedp properties
         this.set('status', status);
-      
       }, this);
 
       // Avoid memory leaks
       if (!SC.browser.msie && !SC.browser.opera) {
-        SC.Event.remove(rawRequest, 'readystatechange', this, this.finishRequest);	  
+        SC.Event.remove(rawRequest, 'readystatechange', this, this.finishRequest);
       } else {
         rawRequest.onreadystatechange = null;
       }
 
       return YES;
     }
-    return NO; 
+    return NO;
   }
 
-  
 });