Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / Server.html
index 750513e..8e8799a 100644 (file)
@@ -3,8 +3,8 @@
 <head>
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <title>The source code</title>
-  <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
-  <script type="text/javascript" src="../prettify/prettify.js"></script>
+  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   <style type="text/css">
     .highlight { display: block; background-color: #ddd; }
   </style>
 <body onload="prettyPrint(); highlight();">
   <pre class="prettyprint lang-js"><span id='Ext-data-proxy-Server'>/**
 </span> * @author Ed Spencer
- * @class Ext.data.proxy.Server
- * @extends Ext.data.proxy.Proxy
- * 
- * &lt;p&gt;ServerProxy is a superclass of {@link Ext.data.proxy.JsonP JsonPProxy} and {@link Ext.data.proxy.Ajax AjaxProxy},
- * and would not usually be used directly.&lt;/p&gt;
- * 
- * &lt;p&gt;ServerProxy should ideally be named HttpProxy as it is a superclass for all HTTP proxies - for Ext JS 4.x it has been 
- * called ServerProxy to enable any 3.x applications that reference the HttpProxy to continue to work (HttpProxy is now an 
- * alias of AjaxProxy).&lt;/p&gt;
+ *
+ * ServerProxy is a superclass of {@link Ext.data.proxy.JsonP JsonPProxy} and {@link Ext.data.proxy.Ajax AjaxProxy}, and
+ * would not usually be used directly.
+ *
+ * ServerProxy should ideally be named HttpProxy as it is a superclass for all HTTP proxies - for Ext JS 4.x it has been
+ * called ServerProxy to enable any 3.x applications that reference the HttpProxy to continue to work (HttpProxy is now
+ * an alias of AjaxProxy).
+ * @private
  */
 Ext.define('Ext.data.proxy.Server', {
     extend: 'Ext.data.proxy.Proxy',
     alias : 'proxy.server',
     alternateClassName: 'Ext.data.ServerProxy',
     uses  : ['Ext.data.Request'],
-    
+
 <span id='Ext-data-proxy-Server-cfg-url'>    /**
-</span>     * @cfg {String} url The URL from which to request the data object.
-     */
-    
-<span id='Ext-data-proxy-Server-cfg-reader'>    /**
-</span>     * @cfg {Object/String/Ext.data.reader.Reader} reader The Ext.data.reader.Reader to use to decode the server's response. This can
-     * either be a Reader instance, a config object or just a valid Reader type name (e.g. 'json', 'xml').
-     */
-    
-<span id='Ext-data-proxy-Server-cfg-writer'>    /**
-</span>     * @cfg {Object/String/Ext.data.writer.Writer} writer The Ext.data.writer.Writer to use to encode any request sent to the server.
-     * This can either be a Writer instance, a config object or just a valid Writer type name (e.g. 'json', 'xml').
+</span>     * @cfg {String} url
+     * The URL from which to request the data object.
      */
-    
+
 <span id='Ext-data-proxy-Server-cfg-pageParam'>    /**
-</span>     * @cfg {String} pageParam The name of the 'page' parameter to send in a request. Defaults to 'page'. Set this to
-     * undefined if you don't want to send a page parameter
+</span>     * @cfg {String} pageParam
+     * The name of the 'page' parameter to send in a request. Defaults to 'page'. Set this to undefined if you don't
+     * want to send a page parameter.
      */
     pageParam: 'page',
-    
+
 <span id='Ext-data-proxy-Server-cfg-startParam'>    /**
-</span>     * @cfg {String} startParam The name of the 'start' parameter to send in a request. Defaults to 'start'. Set this
-     * to undefined if you don't want to send a start parameter
+</span>     * @cfg {String} startParam
+     * The name of the 'start' parameter to send in a request. Defaults to 'start'. Set this to undefined if you don't
+     * want to send a start parameter.
      */
     startParam: 'start',
 
 <span id='Ext-data-proxy-Server-cfg-limitParam'>    /**
-</span>     * @cfg {String} limitParam The name of the 'limit' parameter to send in a request. Defaults to 'limit'. Set this
-     * to undefined if you don't want to send a limit parameter
+</span>     * @cfg {String} limitParam
+     * The name of the 'limit' parameter to send in a request. Defaults to 'limit'. Set this to undefined if you don't
+     * want to send a limit parameter.
      */
     limitParam: 'limit',
-    
+
 <span id='Ext-data-proxy-Server-cfg-groupParam'>    /**
-</span>     * @cfg {String} groupParam The name of the 'group' parameter to send in a request. Defaults to 'group'. Set this
-     * to undefined if you don't want to send a group parameter
+</span>     * @cfg {String} groupParam
+     * The name of the 'group' parameter to send in a request. Defaults to 'group'. Set this to undefined if you don't
+     * want to send a group parameter.
      */
     groupParam: 'group',
-    
+
 <span id='Ext-data-proxy-Server-cfg-sortParam'>    /**
-</span>     * @cfg {String} sortParam The name of the 'sort' parameter to send in a request. Defaults to 'sort'. Set this
-     * to undefined if you don't want to send a sort parameter
+</span>     * @cfg {String} sortParam
+     * The name of the 'sort' parameter to send in a request. Defaults to 'sort'. Set this to undefined if you don't
+     * want to send a sort parameter.
      */
     sortParam: 'sort',
-    
+
 <span id='Ext-data-proxy-Server-cfg-filterParam'>    /**
-</span>     * @cfg {String} filterParam The name of the 'filter' parameter to send in a request. Defaults to 'filter'. Set 
-     * this to undefined if you don't want to send a filter parameter
+</span>     * @cfg {String} filterParam
+     * The name of the 'filter' parameter to send in a request. Defaults to 'filter'. Set this to undefined if you don't
+     * want to send a filter parameter.
      */
     filterParam: 'filter',
-    
+
 <span id='Ext-data-proxy-Server-cfg-directionParam'>    /**
-</span>     * @cfg {String} directionParam The name of the direction parameter to send in a request. &lt;strong&gt;This is only used when simpleSortMode is set to true.&lt;/strong&gt;
-     * Defaults to 'dir'.
+</span>     * @cfg {String} directionParam
+     * The name of the direction parameter to send in a request. **This is only used when simpleSortMode is set to
+     * true.** Defaults to 'dir'.
      */
     directionParam: 'dir',
-    
+
 <span id='Ext-data-proxy-Server-cfg-simpleSortMode'>    /**
-</span>     * @cfg {Boolean} simpleSortMode Enabling simpleSortMode in conjunction with remoteSort will only send one sort property and a direction when a remote sort is requested.
-     * The directionParam and sortParam will be sent with the property name and either 'ASC' or 'DESC'
+</span>     * @cfg {Boolean} simpleSortMode
+     * Enabling simpleSortMode in conjunction with remoteSort will only send one sort property and a direction when a
+     * remote sort is requested. The directionParam and sortParam will be sent with the property name and either 'ASC'
+     * or 'DESC'.
      */
     simpleSortMode: false,
-    
+
 <span id='Ext-data-proxy-Server-cfg-noCache'>    /**
-</span>     * @cfg {Boolean} noCache (optional) Defaults to true. Disable caching by adding a unique parameter
-     * name to the request.
+</span>     * @cfg {Boolean} noCache
+     * Disable caching by adding a unique parameter name to the request. Set to false to allow caching. Defaults to true.
      */
     noCache : true,
-    
+
 <span id='Ext-data-proxy-Server-cfg-cacheString'>    /**
-</span>     * @cfg {String} cacheString The name of the cache param added to the url when using noCache (defaults to &quot;_dc&quot;)
+</span>     * @cfg {String} cacheString
+     * The name of the cache param added to the url when using noCache. Defaults to &quot;_dc&quot;.
      */
     cacheString: &quot;_dc&quot;,
-    
+
 <span id='Ext-data-proxy-Server-cfg-timeout'>    /**
-</span>     * @cfg {Number} timeout (optional) The number of milliseconds to wait for a response.
-     * Defaults to 30000 milliseconds (30 seconds).
+</span>     * @cfg {Number} timeout
+     * The number of milliseconds to wait for a response. Defaults to 30000 milliseconds (30 seconds).
      */
     timeout : 30000,
-    
+
 <span id='Ext-data-proxy-Server-cfg-api'>    /**
 </span>     * @cfg {Object} api
-     * Specific urls to call on CRUD action methods &quot;create&quot;, &quot;read&quot;, &quot;update&quot; and &quot;destroy&quot;.
-     * Defaults to:&lt;pre&gt;&lt;code&gt;
-api: {
-    create  : undefined,
-    read    : undefined,
-    update  : undefined,
-    destroy : undefined
-}
-     * &lt;/code&gt;&lt;/pre&gt;
-     * &lt;p&gt;The url is built based upon the action being executed &lt;tt&gt;[create|read|update|destroy]&lt;/tt&gt;
-     * using the commensurate &lt;tt&gt;{@link #api}&lt;/tt&gt; property, or if undefined default to the
-     * configured {@link Ext.data.Store}.{@link Ext.data.proxy.Server#url url}.&lt;/p&gt;&lt;br&gt;
-     * &lt;p&gt;For example:&lt;/p&gt;
-     * &lt;pre&gt;&lt;code&gt;
-api: {
-    create  : '/controller/new',
-    read    : '/controller/load',
-    update  : '/controller/update',
-    destroy : '/controller/destroy_action'
-}
-     * &lt;/code&gt;&lt;/pre&gt;
-     * &lt;p&gt;If the specific URL for a given CRUD action is undefined, the CRUD action request
-     * will be directed to the configured &lt;tt&gt;{@link Ext.data.proxy.Server#url url}&lt;/tt&gt;.&lt;/p&gt;
-     */
-    
-<span id='Ext-data-proxy-Server-method-constructor'>    /**
-</span>     * @ignore
+     * Specific urls to call on CRUD action methods &quot;create&quot;, &quot;read&quot;, &quot;update&quot; and &quot;destroy&quot;. Defaults to:
+     *
+     *     api: {
+     *         create  : undefined,
+     *         read    : undefined,
+     *         update  : undefined,
+     *         destroy : undefined
+     *     }
+     *
+     * The url is built based upon the action being executed [create|read|update|destroy] using the commensurate
+     * {@link #api} property, or if undefined default to the configured
+     * {@link Ext.data.Store}.{@link Ext.data.proxy.Server#url url}.
+     *
+     * For example:
+     *
+     *     api: {
+     *         create  : '/controller/new',
+     *         read    : '/controller/load',
+     *         update  : '/controller/update',
+     *         destroy : '/controller/destroy_action'
+     *     }
+     *
+     * If the specific URL for a given CRUD action is undefined, the CRUD action request will be directed to the
+     * configured {@link Ext.data.proxy.Server#url url}.
      */
+
     constructor: function(config) {
         var me = this;
-        
+
         config = config || {};
         this.addEvents(
 <span id='Ext-data-proxy-Server-event-exception'>            /**
@@ -157,36 +155,37 @@ api: {
             'exception'
         );
         me.callParent([config]);
-        
+
 <span id='Ext-data-proxy-Server-cfg-extraParams'>        /**
-</span>         * @cfg {Object} extraParams Extra parameters that will be included on every request. Individual requests with params
-         * of the same name will override these params when they are in conflict.
+</span>         * @cfg {Object} extraParams
+         * Extra parameters that will be included on every request. Individual requests with params of the same name
+         * will override these params when they are in conflict.
          */
         me.extraParams = config.extraParams || {};
-        
+
         me.api = config.api || {};
-        
+
         //backwards compatibility, will be deprecated in 5.0
         me.nocache = me.noCache;
     },
-    
+
     //in a ServerProxy all four CRUD operations are executed in the same manner, so we delegate to doRequest in each case
     create: function() {
         return this.doRequest.apply(this, arguments);
     },
-    
+
     read: function() {
         return this.doRequest.apply(this, arguments);
     },
-    
+
     update: function() {
         return this.doRequest.apply(this, arguments);
     },
-    
+
     destroy: function() {
         return this.doRequest.apply(this, arguments);
     },
-    
+
 <span id='Ext-data-proxy-Server-method-buildRequest'>    /**
 </span>     * Creates and returns an Ext.data.Request object based on the options passed by the {@link Ext.data.Store Store}
      * that this Proxy is attached to.
@@ -196,14 +195,14 @@ api: {
     buildRequest: function(operation) {
         var params = Ext.applyIf(operation.params || {}, this.extraParams || {}),
             request;
-        
+
         //copy any sorters, filters etc into the params so they can be sent over the wire
-        params = Ext.applyIf(params, this.getParams(params, operation));
-        
+        params = Ext.applyIf(params, this.getParams(operation));
+
         if (operation.id &amp;&amp; !params.id) {
             params.id = operation.id;
         }
-        
+
         request = Ext.create('Ext.data.Request', {
             params   : params,
             action   : operation.action,
@@ -211,56 +210,36 @@ api: {
             operation: operation,
             url      : operation.url
         });
-        
+
         request.url = this.buildUrl(request);
-        
+
         /*
          * Save the request on the Operation. Operations don't usually care about Request and Response data, but in the
          * ServerProxy and any of its subclasses we add both request and response as they may be useful for further processing
          */
         operation.request = request;
-        
+
         return request;
     },
-    
-<span id='Ext-data-proxy-Server-method-processResponse'>    /**
-</span>     * 
-     */
+
+    // Should this be documented as protected method?
     processResponse: function(success, operation, request, response, callback, scope){
         var me = this,
             reader,
-            result,
-            records,
-            length,
-            mc,
-            record,
-            i;
-            
+            result;
+
         if (success === true) {
             reader = me.getReader();
             result = reader.read(me.extractResponseData(response));
-            records = result.records;
-            length = records.length;
-            
+
             if (result.success !== false) {
-                mc = Ext.create('Ext.util.MixedCollection', true, function(r) {return r.getId();});
-                mc.addAll(operation.records);
-                for (i = 0; i &lt; length; i++) {
-                    record = mc.get(records[i].getId());
-                    
-                    if (record) {
-                        record.beginEdit();
-                        record.set(record.data);
-                        record.endEdit(true);
-                    }
-                }
-                
                 //see comment in buildRequest for why we include the response object here
                 Ext.apply(operation, {
                     response: response,
                     resultSet: result
                 });
-                
+
+                operation.commitRecords(result.records);
                 operation.setCompleted();
                 operation.setSuccessful();
             } else {
@@ -269,17 +248,17 @@ api: {
             }
         } else {
             me.setException(operation, response);
-            me.fireEvent('exception', this, response, operation);              
+            me.fireEvent('exception', this, response, operation);
         }
-            
+
         //this callback is the one that was passed to the 'read' or 'write' function above
         if (typeof callback == 'function') {
             callback.call(scope || me, operation);
         }
-            
+
         me.afterRequest(request, success);
     },
-    
+
 <span id='Ext-data-proxy-Server-method-setException'>    /**
 </span>     * Sets up an exception on the operation
      * @private
@@ -290,40 +269,41 @@ api: {
         operation.setException({
             status: response.status,
             statusText: response.statusText
-        });     
+        });
     },
-    
+
 <span id='Ext-data-proxy-Server-method-extractResponseData'>    /**
 </span>     * Template method to allow subclasses to specify how to get the response for the reader.
+     * @template
      * @private
      * @param {Object} response The server response
-     * @return {Mixed} The response data to be used by the reader
+     * @return {Object} The response data to be used by the reader
      */
     extractResponseData: function(response){
-        return response; 
+        return response;
     },
-    
+
 <span id='Ext-data-proxy-Server-method-applyEncoding'>    /**
 </span>     * Encode any values being sent to the server. Can be overridden in subclasses.
      * @private
      * @param {Array} An array of sorters/filters.
-     * @return {Mixed} The encoded value
+     * @return {Object} The encoded value
      */
     applyEncoding: function(value){
         return Ext.encode(value);
     },
-    
+
 <span id='Ext-data-proxy-Server-method-encodeSorters'>    /**
-</span>     * Encodes the array of {@link Ext.util.Sorter} objects into a string to be sent in the request url. By default, 
+</span>     * Encodes the array of {@link Ext.util.Sorter} objects into a string to be sent in the request url. By default,
      * this simply JSON-encodes the sorter data
-     * @param {Array} sorters The array of {@link Ext.util.Sorter Sorter} objects
+     * @param {Ext.util.Sorter[]} sorters The array of {@link Ext.util.Sorter Sorter} objects
      * @return {String} The encoded sorters
      */
     encodeSorters: function(sorters) {
         var min = [],
             length = sorters.length,
             i = 0;
-        
+
         for (; i &lt; length; i++) {
             min[i] = {
                 property : sorters[i].property,
@@ -331,20 +311,20 @@ api: {
             };
         }
         return this.applyEncoding(min);
-        
+
     },
-    
+
 <span id='Ext-data-proxy-Server-method-encodeFilters'>    /**
-</span>     * Encodes the array of {@link Ext.util.Filter} objects into a string to be sent in the request url. By default, 
+</span>     * Encodes the array of {@link Ext.util.Filter} objects into a string to be sent in the request url. By default,
      * this simply JSON-encodes the filter data
-     * @param {Array} sorters The array of {@link Ext.util.Filter Filter} objects
+     * @param {Ext.util.Filter[]} filters The array of {@link Ext.util.Filter Filter} objects
      * @return {String} The encoded filters
      */
     encodeFilters: function(filters) {
         var min = [],
             length = filters.length,
             i = 0;
-        
+
         for (; i &lt; length; i++) {
             min[i] = {
                 property: filters[i].property,
@@ -353,15 +333,14 @@ api: {
         }
         return this.applyEncoding(min);
     },
-    
+
 <span id='Ext-data-proxy-Server-method-getParams'>    /**
 </span>     * @private
      * Copy any sorters, filters etc into the params so they can be sent over the wire
      */
-    getParams: function(params, operation) {
-        params = params || {};
-        
+    getParams: function(operation) {
         var me             = this,
+            params         = {},
             isDef          = Ext.isDefined,
             groupers       = operation.groupers,
             sorters        = operation.sorters,
@@ -369,34 +348,34 @@ api: {
             page           = operation.page,
             start          = operation.start,
             limit          = operation.limit,
-            
+
             simpleSortMode = me.simpleSortMode,
-            
+
             pageParam      = me.pageParam,
             startParam     = me.startParam,
             limitParam     = me.limitParam,
             groupParam     = me.groupParam,
             sortParam      = me.sortParam,
             filterParam    = me.filterParam,
-            directionParam       = me.directionParam;
-        
+            directionParam = me.directionParam;
+
         if (pageParam &amp;&amp; isDef(page)) {
             params[pageParam] = page;
         }
-        
+
         if (startParam &amp;&amp; isDef(start)) {
             params[startParam] = start;
         }
-        
+
         if (limitParam &amp;&amp; isDef(limit)) {
             params[limitParam] = limit;
         }
-        
+
         if (groupParam &amp;&amp; groupers &amp;&amp; groupers.length &gt; 0) {
             // Grouper is a subclass of sorter, so we can just use the sorter method
             params[groupParam] = me.encodeSorters(groupers);
         }
-        
+
         if (sortParam &amp;&amp; sorters &amp;&amp; sorters.length &gt; 0) {
             if (simpleSortMode) {
                 params[sortParam] = sorters[0].property;
@@ -404,40 +383,39 @@ api: {
             } else {
                 params[sortParam] = me.encodeSorters(sorters);
             }
-            
+
         }
-        
+
         if (filterParam &amp;&amp; filters &amp;&amp; filters.length &gt; 0) {
             params[filterParam] = me.encodeFilters(filters);
         }
-        
+
         return params;
     },
-    
+
 <span id='Ext-data-proxy-Server-method-buildUrl'>    /**
-</span>     * Generates a url based on a given Ext.data.Request object. By default, ServerProxy's buildUrl will
-     * add the cache-buster param to the end of the url. Subclasses may need to perform additional modifications
-     * to the url.
+</span>     * Generates a url based on a given Ext.data.Request object. By default, ServerProxy's buildUrl will add the
+     * cache-buster param to the end of the url. Subclasses may need to perform additional modifications to the url.
      * @param {Ext.data.Request} request The request object
      * @return {String} The url
      */
     buildUrl: function(request) {
         var me = this,
             url = me.getUrl(request);
-        
+
         //&lt;debug&gt;
         if (!url) {
             Ext.Error.raise(&quot;You are using a ServerProxy but have not supplied it with a url.&quot;);
         }
         //&lt;/debug&gt;
-        
+
         if (me.noCache) {
             url = Ext.urlAppend(url, Ext.String.format(&quot;{0}={1}&quot;, me.cacheString, Ext.Date.now()));
         }
-        
+
         return url;
     },
-    
+
 <span id='Ext-data-proxy-Server-method-getUrl'>    /**
 </span>     * Get the url for the request taking into account the order of priority,
      * - The request
@@ -450,11 +428,13 @@ api: {
     getUrl: function(request){
         return request.url || this.api[request.action] || this.url;
     },
-    
+
 <span id='Ext-data-proxy-Server-method-doRequest'>    /**
-</span>     * In ServerProxy subclasses, the {@link #create}, {@link #read}, {@link #update} and {@link #destroy} methods all pass
-     * through to doRequest. Each ServerProxy subclass must implement the doRequest method - see {@link Ext.data.proxy.JsonP}
-     * and {@link Ext.data.proxy.Ajax} for examples. This method carries the same signature as each of the methods that delegate to it.
+</span>     * In ServerProxy subclasses, the {@link #create}, {@link #read}, {@link #update} and {@link #destroy} methods all
+     * pass through to doRequest. Each ServerProxy subclass must implement the doRequest method - see {@link
+     * Ext.data.proxy.JsonP} and {@link Ext.data.proxy.Ajax} for examples. This method carries the same signature as
+     * each of the methods that delegate to it.
+     *
      * @param {Ext.data.Operation} operation The Ext.data.Operation object
      * @param {Function} callback The callback function to call when the Operation has completed
      * @param {Object} scope The scope in which to execute the callback
@@ -464,7 +444,7 @@ api: {
         Ext.Error.raise(&quot;The doRequest function has not been implemented on your Ext.data.proxy.Server subclass. See src/data/ServerProxy.js for details&quot;);
         //&lt;/debug&gt;
     },
-    
+
 <span id='Ext-data-proxy-Server-method-afterRequest'>    /**
 </span>     * Optional callback function which can be used to clean up after a request has been completed.
      * @param {Ext.data.Request} request The Request object
@@ -472,7 +452,7 @@ api: {
      * @method
      */
     afterRequest: Ext.emptyFn,
-    
+
     onDestroy: function() {
         Ext.destroy(this.reader, this.writer);
     }