src/data/HttpProxy.js

   1 /*!
   2  * Ext JS Library 3.3.1
   3  * Copyright(c) 2006-2010 Sencha Inc.
   4  * licensing@sencha.com
   5  * http://www.sencha.com/license
   6  */
   7 /**
   8  * @class Ext.data.HttpProxy
   9  * @extends Ext.data.DataProxy
  10  * <p>An implementation of {@link Ext.data.DataProxy} that processes data requests within the same
  11  * domain of the originating page.</p>
  12  * <p><b>Note</b>: this class cannot be used to retrieve data from a domain other
  13  * than the domain from which the running page was served. For cross-domain requests, use a
  14  * {@link Ext.data.ScriptTagProxy ScriptTagProxy}.</p>
  15  * <p>Be aware that to enable the browser to parse an XML document, the server must set
  16  * the Content-Type header in the HTTP response to "<tt>text/xml</tt>".</p>
  17  * @constructor
  18  * @param {Object} conn
  19  * An {@link Ext.data.Connection} object, or options parameter to {@link Ext.Ajax#request}.
  20  * <p>Note that if this HttpProxy is being used by a {@link Ext.data.Store Store}, then the
  21  * Store's call to {@link #load} will override any specified <tt>callback</tt> and <tt>params</tt>
  22  * options. In this case, use the Store's {@link Ext.data.Store#events events} to modify parameters,
  23  * or react to loading events. The Store's {@link Ext.data.Store#baseParams baseParams} may also be
  24  * used to pass parameters known at instantiation time.</p>
  25  * <p>If an options parameter is passed, the singleton {@link Ext.Ajax} object will be used to make
  26  * the request.</p>
  27  */
  28 Ext.data.HttpProxy = function(conn){
  29     Ext.data.HttpProxy.superclass.constructor.call(this, conn);
  30
  31     /**
  32      * The Connection object (Or options parameter to {@link Ext.Ajax#request}) which this HttpProxy
  33      * uses to make requests to the server. Properties of this object may be changed dynamically to
  34      * change the way data is requested.
  35      * @property
  36      */
  37     this.conn = conn;
  38
  39     // nullify the connection url.  The url param has been copied to 'this' above.  The connection
  40     // url will be set during each execution of doRequest when buildUrl is called.  This makes it easier for users to override the
  41     // connection url during beforeaction events (ie: beforeload, beforewrite, etc).
  42     // Url is always re-defined during doRequest.
  43     this.conn.url = null;
  44
  45     this.useAjax = !conn || !conn.events;
  46
  47     // A hash containing active requests, keyed on action [Ext.data.Api.actions.create|read|update|destroy]
  48     var actions = Ext.data.Api.actions;
  49     this.activeRequest = {};
  50     for (var verb in actions) {
  51         this.activeRequest[actions[verb]] = undefined;
  52     }
  53 };
  54
  55 Ext.extend(Ext.data.HttpProxy, Ext.data.DataProxy, {
  56     /**
  57      * Return the {@link Ext.data.Connection} object being used by this Proxy.
  58      * @return {Connection} The Connection object. This object may be used to subscribe to events on
  59      * a finer-grained basis than the DataProxy events.
  60      */
  61     getConnection : function() {
  62         return this.useAjax ? Ext.Ajax : this.conn;
  63     },
  64
  65     /**
  66      * Used for overriding the url used for a single request.  Designed to be called during a beforeaction event.  Calling setUrl
  67      * will override any urls set via the api configuration parameter.  Set the optional parameter makePermanent to set the url for
  68      * all subsequent requests.  If not set to makePermanent, the next request will use the same url or api configuration defined
  69      * in the initial proxy configuration.
  70      * @param {String} url
  71      * @param {Boolean} makePermanent (Optional) [false]
  72      *
  73      * (e.g.: beforeload, beforesave, etc).
  74      */
  75     setUrl : function(url, makePermanent) {
  76         this.conn.url = url;
  77         if (makePermanent === true) {
  78             this.url = url;
  79             this.api = null;
  80             Ext.data.Api.prepare(this);
  81         }
  82     },
  83
  84     /**
  85      * HttpProxy implementation of DataProxy#doRequest
  86      * @param {String} action The crud action type (create, read, update, destroy)
  87      * @param {Ext.data.Record/Ext.data.Record[]} rs If action is load, rs will be null
  88      * @param {Object} params An object containing properties which are to be used as HTTP parameters
  89      * for the request to the remote server.
  90      * @param {Ext.data.DataReader} reader The Reader object which converts the data
  91      * object into a block of Ext.data.Records.
  92      * @param {Function} callback
  93      * <div class="sub-desc"><p>A function to be called after the request.
  94      * The <tt>callback</tt> is passed the following arguments:<ul>
  95      * <li><tt>r</tt> : Ext.data.Record[] The block of Ext.data.Records.</li>
  96      * <li><tt>options</tt>: Options object from the action request</li>
  97      * <li><tt>success</tt>: Boolean success indicator</li></ul></p></div>
  98      * @param {Object} scope The scope (<code>this</code> reference) in which the callback function is executed. Defaults to the browser window.
  99      * @param {Object} arg An optional argument which is passed to the callback as its second parameter.
 100      * @protected
 101      */
 102     doRequest : function(action, rs, params, reader, cb, scope, arg) {
 103         var  o = {
 104             method: (this.api[action]) ? this.api[action]['method'] : undefined,
 105             request: {
 106                 callback : cb,
 107                 scope : scope,
 108                 arg : arg
 109             },
 110             reader: reader,
 111             callback : this.createCallback(action, rs),
 112             scope: this
 113         };
 114
 115         // If possible, transmit data using jsonData || xmlData on Ext.Ajax.request (An installed DataWriter would have written it there.).
 116         // Use std HTTP params otherwise.
 117         if (params.jsonData) {
 118             o.jsonData = params.jsonData;
 119         } else if (params.xmlData) {
 120             o.xmlData = params.xmlData;
 121         } else {
 122             o.params = params || {};
 123         }
 124         // Set the connection url.  If this.conn.url is not null here,
 125         // the user must have overridden the url during a beforewrite/beforeload event-handler.
 126         // this.conn.url is nullified after each request.
 127         this.conn.url = this.buildUrl(action, rs);
 128
 129         if(this.useAjax){
 130
 131             Ext.applyIf(o, this.conn);
 132
 133             // If a currently running request is found for this action, abort it.
 134             if (this.activeRequest[action]) {
 135                 ////
 136                 // Disabled aborting activeRequest while implementing REST.  activeRequest[action] will have to become an array
 137                 // TODO ideas anyone?
 138                 //
 139                 //Ext.Ajax.abort(this.activeRequest[action]);
 140             }
 141             this.activeRequest[action] = Ext.Ajax.request(o);
 142         }else{
 143             this.conn.request(o);
 144         }
 145         // request is sent, nullify the connection url in preparation for the next request
 146         this.conn.url = null;
 147     },
 148
 149     /**
 150      * Returns a callback function for a request.  Note a special case is made for the
 151      * read action vs all the others.
 152      * @param {String} action [create|update|delete|load]
 153      * @param {Ext.data.Record[]} rs The Store-recordset being acted upon
 154      * @private
 155      */
 156     createCallback : function(action, rs) {
 157         return function(o, success, response) {
 158             this.activeRequest[action] = undefined;
 159             if (!success) {
 160                 if (action === Ext.data.Api.actions.read) {
 161                     // @deprecated: fire loadexception for backwards compat.
 162                     // TODO remove
 163                     this.fireEvent('loadexception', this, o, response);
 164                 }
 165                 this.fireEvent('exception', this, 'response', action, o, response);
 166                 o.request.callback.call(o.request.scope, null, o.request.arg, false);
 167                 return;
 168             }
 169             if (action === Ext.data.Api.actions.read) {
 170                 this.onRead(action, o, response);
 171             } else {
 172                 this.onWrite(action, o, response, rs);
 173             }
 174         };
 175     },
 176
 177     /**
 178      * Callback for read action
 179      * @param {String} action Action name as per {@link Ext.data.Api.actions#read}.
 180      * @param {Object} o The request transaction object
 181      * @param {Object} res The server response
 182      * @fires loadexception (deprecated)
 183      * @fires exception
 184      * @fires load
 185      * @protected
 186      */
 187     onRead : function(action, o, response) {
 188         var result;
 189         try {
 190             result = o.reader.read(response);
 191         }catch(e){
 192             // @deprecated: fire old loadexception for backwards-compat.
 193             // TODO remove
 194             this.fireEvent('loadexception', this, o, response, e);
 195
 196             this.fireEvent('exception', this, 'response', action, o, response, e);
 197             o.request.callback.call(o.request.scope, null, o.request.arg, false);
 198             return;
 199         }
 200         if (result.success === false) {
 201             // @deprecated: fire old loadexception for backwards-compat.
 202             // TODO remove
 203             this.fireEvent('loadexception', this, o, response);
 204
 205             // Get DataReader read-back a response-object to pass along to exception event
 206             var res = o.reader.readResponse(action, response);
 207             this.fireEvent('exception', this, 'remote', action, o, res, null);
 208         }
 209         else {
 210             this.fireEvent('load', this, o, o.request.arg);
 211         }
 212         // TODO refactor onRead, onWrite to be more generalized now that we're dealing with Ext.data.Response instance
 213         // the calls to request.callback(...) in each will have to be made identical.
 214         // NOTE reader.readResponse does not currently return Ext.data.Response
 215         o.request.callback.call(o.request.scope, result, o.request.arg, result.success);
 216     },
 217     /**
 218      * Callback for write actions
 219      * @param {String} action [Ext.data.Api.actions.create|read|update|destroy]
 220      * @param {Object} trans The request transaction object
 221      * @param {Object} res The server response
 222      * @fires exception
 223      * @fires write
 224      * @protected
 225      */
 226     onWrite : function(action, o, response, rs) {
 227         var reader = o.reader;
 228         var res;
 229         try {
 230             res = reader.readResponse(action, response);
 231         } catch (e) {
 232             this.fireEvent('exception', this, 'response', action, o, response, e);
 233             o.request.callback.call(o.request.scope, null, o.request.arg, false);
 234             return;
 235         }
 236         if (res.success === true) {
 237             this.fireEvent('write', this, action, res.data, res, rs, o.request.arg);
 238         } else {
 239             this.fireEvent('exception', this, 'remote', action, o, res, rs);
 240         }
 241         // TODO refactor onRead, onWrite to be more generalized now that we're dealing with Ext.data.Response instance
 242         // the calls to request.callback(...) in each will have to be made similar.
 243         // NOTE reader.readResponse does not currently return Ext.data.Response
 244         o.request.callback.call(o.request.scope, res.data, res, res.success);
 245     },
 246
 247     // inherit docs
 248     destroy: function(){
 249         if(!this.useAjax){
 250             this.conn.abort();
 251         }else if(this.activeRequest){
 252             var actions = Ext.data.Api.actions;
 253             for (var verb in actions) {
 254                 if(this.activeRequest[actions[verb]]){
 255                     Ext.Ajax.abort(this.activeRequest[actions[verb]]);
 256                 }
 257             }
 258         }
 259         Ext.data.HttpProxy.superclass.destroy.call(this);
 260     }
 261 });