DataProxy.js
上传用户:shuoshiled
上传日期:2018-01-28
资源大小:10124k
文件大小:19k
源码类别:

中间件编程

开发平台:

JavaScript

  1. /*!  * Ext JS Library 3.0.0  * Copyright(c) 2006-2009 Ext JS, LLC  * licensing@extjs.com  * http://www.extjs.com/license  */ /**
  2.  * @class Ext.data.DataProxy
  3.  * @extends Ext.util.Observable
  4.  * <p>Abstract base class for implementations which provide retrieval of unformatted data objects.
  5.  * This class is intended to be extended and should not be created directly. For existing implementations,
  6.  * see {@link Ext.data.DirectProxy}, {@link Ext.data.HttpProxy}, {@link Ext.data.ScriptTagProxy} and
  7.  * {@link Ext.data.MemoryProxy}.</p>
  8.  * <p>DataProxy implementations are usually used in conjunction with an implementation of {@link Ext.data.DataReader}
  9.  * (of the appropriate type which knows how to parse the data object) to provide a block of
  10.  * {@link Ext.data.Records} to an {@link Ext.data.Store}.</p>
  11.  * <p>The parameter to a DataProxy constructor may be an {@link Ext.data.Connection} or can also be the
  12.  * config object to an {@link Ext.data.Connection}.</p>
  13.  * <p>Custom implementations must implement either the <code><b>doRequest</b></code> method (preferred) or the
  14.  * <code>load</code> method (deprecated). See
  15.  * {@link Ext.data.HttpProxy}.{@link Ext.data.HttpProxy#doRequest doRequest} or
  16.  * {@link Ext.data.HttpProxy}.{@link Ext.data.HttpProxy#load load} for additional details.</p>
  17.  * <p><b><u>Example 1</u></b></p>
  18.  * <pre><code>
  19. proxy: new Ext.data.ScriptTagProxy({
  20.     {@link Ext.data.Connection#url url}: 'http://extjs.com/forum/topics-remote.php'
  21. }),
  22.  * </code></pre>
  23.  * <p><b><u>Example 2</u></b></p>
  24.  * <pre><code>
  25. proxy : new Ext.data.HttpProxy({
  26.     {@link Ext.data.Connection#method method}: 'GET',
  27.     {@link Ext.data.HttpProxy#prettyUrls prettyUrls}: false,
  28.     {@link Ext.data.Connection#url url}: 'local/default.php', // see options parameter for {@link Ext.Ajax#request}
  29.     {@link #api}: {
  30.         // all actions except the following will use above url
  31.         create  : 'local/new.php',
  32.         update  : 'local/update.php'
  33.     }
  34. }),
  35.  * </code></pre>
  36.  */
  37. Ext.data.DataProxy = function(conn){
  38.     // make sure we have a config object here to support ux proxies.
  39.     // All proxies should now send config into superclass constructor.
  40.     conn = conn || {};
  41.     // This line caused a bug when people use custom Connection object having its own request method.
  42.     // http://extjs.com/forum/showthread.php?t=67194.  Have to set DataProxy config
  43.     //Ext.applyIf(this, conn);
  44.     this.api     = conn.api;
  45.     this.url     = conn.url;
  46.     this.restful = conn.restful;
  47.     this.listeners = conn.listeners;
  48.     // deprecated
  49.     this.prettyUrls = conn.prettyUrls;
  50.     /**
  51.      * @cfg {Object} api
  52.      * Specific urls to call on CRUD action methods "read", "create", "update" and "destroy".
  53.      * Defaults to:<pre><code>
  54. api: {
  55.     read    : undefined,
  56.     create  : undefined,
  57.     update  : undefined,
  58.     destroy : undefined
  59. }
  60. </code></pre>
  61.      * <p>If the specific URL for a given CRUD action is undefined, the CRUD action request
  62.      * will be directed to the configured <tt>{@link Ext.data.Connection#url url}</tt>.</p>
  63.      * <br><p><b>Note</b>: To modify the URL for an action dynamically the appropriate API
  64.      * property should be modified before the action is requested using the corresponding before
  65.      * action event.  For example to modify the URL associated with the load action:
  66.      * <pre><code>
  67. // modify the url for the action
  68. myStore.on({
  69.     beforeload: {
  70.         fn: function (store, options) {
  71.             // use <tt>{@link Ext.data.HttpProxy#setUrl setUrl}</tt> to change the URL for *just* this request.
  72.             store.proxy.setUrl('changed1.php');
  73.             // set optional second parameter to true to make this URL change
  74.             // permanent, applying this URL for all subsequent requests.
  75.             store.proxy.setUrl('changed1.php', true);
  76.             // manually set the <b>private</b> connection URL.
  77.             // <b>Warning:</b>  Accessing the private URL property should be avoided.
  78.             // Use the public method <tt>{@link Ext.data.HttpProxy#setUrl setUrl}</tt> instead, shown above.
  79.             // It should be noted that changing the URL like this will affect
  80.             // the URL for just this request.  Subsequent requests will use the
  81.             // API or URL defined in your initial proxy configuration.
  82.             store.proxy.conn.url = 'changed1.php';
  83.             // proxy URL will be superseded by API (only if proxy created to use ajax):
  84.             // It should be noted that proxy API changes are permanent and will
  85.             // be used for all subsequent requests.
  86.             store.proxy.api.load = 'changed2.php';
  87.             // However, altering the proxy API should be done using the public
  88.             // method <tt>{@link Ext.data.DataProxy#setApi setApi}</tt> instead.
  89.             store.proxy.setApi('load', 'changed2.php');
  90.             // Or set the entire API with a config-object.
  91.             // When using the config-object option, you must redefine the <b>entire</b>
  92.             // API -- not just a specific action of it.
  93.             store.proxy.setApi({
  94.                 read    : 'changed_read.php',
  95.                 create  : 'changed_create.php',
  96.                 update  : 'changed_update.php',
  97.                 destroy : 'changed_destroy.php'
  98.             });
  99.         }
  100.     }
  101. });
  102.      * </code></pre>
  103.      * </p>
  104.      */
  105.     // Prepare the proxy api.  Ensures all API-actions are defined with the Object-form.
  106.     try {
  107.         Ext.data.Api.prepare(this);
  108.     } catch (e) {
  109.         if (e instanceof Ext.data.Api.Error) {
  110.             e.toConsole();
  111.         }
  112.     }
  113.     this.addEvents(
  114.         /**
  115.          * @event exception
  116.          * <p>Fires if an exception occurs in the Proxy during a remote request.
  117.          * This event is relayed through a corresponding
  118.          * {@link Ext.data.Store}.{@link Ext.data.Store#exception exception},
  119.          * so any Store instance may observe this event.
  120.          * This event can be fired for one of two reasons:</p>
  121.          * <div class="mdetail-params"><ul>
  122.          * <li>remote-request <b>failed</b> : <div class="sub-desc">
  123.          * The server did not return status === 200.
  124.          * </div></li>
  125.          * <li>remote-request <b>succeeded</b> : <div class="sub-desc">
  126.          * The remote-request succeeded but the reader could not read the response.
  127.          * This means the server returned data, but the configured Reader threw an
  128.          * error while reading the response.  In this case, this event will be
  129.          * raised and the caught error will be passed along into this event.
  130.          * </div></li>
  131.          * </ul></div>
  132.          * <br><p>This event fires with two different contexts based upon the 2nd
  133.          * parameter <tt>type [remote|response]</tt>.  The first four parameters
  134.          * are identical between the two contexts -- only the final two parameters
  135.          * differ.</p>
  136.          * @param {DataProxy} this The proxy that sent the request
  137.          * @param {String} type
  138.          * <p>The value of this parameter will be either <tt>'response'</tt> or <tt>'remote'</tt>.</p>
  139.          * <div class="mdetail-params"><ul>
  140.          * <li><b><tt>'response'</tt></b> : <div class="sub-desc">
  141.          * <p>An <b>invalid</b> response from the server was returned: either 404,
  142.          * 500 or the response meta-data does not match that defined in the DataReader
  143.          * (e.g.: root, idProperty, successProperty).</p>
  144.          * </div></li>
  145.          * <li><b><tt>'remote'</tt></b> : <div class="sub-desc">
  146.          * <p>A <b>valid</b> response was returned from the server having
  147.          * successProperty === false.  This response might contain an error-message
  148.          * sent from the server.  For example, the user may have failed
  149.          * authentication/authorization or a database validation error occurred.</p>
  150.          * </div></li>
  151.          * </ul></div>
  152.          * @param {String} action Name of the action (see {@link Ext.data.Api#actions}.
  153.          * @param {Object} options The options for the action that were specified in the {@link #request}.
  154.          * @param {Object} response
  155.          * <p>The value of this parameter depends on the value of the <code>type</code> parameter:</p>
  156.          * <div class="mdetail-params"><ul>
  157.          * <li><b><tt>'response'</tt></b> : <div class="sub-desc">
  158.          * <p>The raw browser response object (e.g.: XMLHttpRequest)</p>
  159.          * </div></li>
  160.          * <li><b><tt>'remote'</tt></b> : <div class="sub-desc">
  161.          * <p>The decoded response object sent from the server.</p>
  162.          * </div></li>
  163.          * </ul></div>
  164.          * @param {Mixed} arg
  165.          * <p>The type and value of this parameter depends on the value of the <code>type</code> parameter:</p>
  166.          * <div class="mdetail-params"><ul>
  167.          * <li><b><tt>'response'</tt></b> : Error<div class="sub-desc">
  168.          * <p>The JavaScript Error object caught if the configured Reader could not read the data.
  169.          * If the remote request returns success===false, this parameter will be null.</p>
  170.          * </div></li>
  171.          * <li><b><tt>'remote'</tt></b> : Record/Record[]<div class="sub-desc">
  172.          * <p>This parameter will only exist if the <tt>action</tt> was a <b>write</b> action
  173.          * (Ext.data.Api.actions.create|update|destroy).</p>
  174.          * </div></li>
  175.          * </ul></div>
  176.          */
  177.         'exception',
  178.         /**
  179.          * @event beforeload
  180.          * Fires before a request to retrieve a data object.
  181.          * @param {DataProxy} this The proxy for the request
  182.          * @param {Object} params The params object passed to the {@link #request} function
  183.          */
  184.         'beforeload',
  185.         /**
  186.          * @event load
  187.          * Fires before the load method's callback is called.
  188.          * @param {DataProxy} this The proxy for the request
  189.          * @param {Object} o The request transaction object
  190.          * @param {Object} options The callback's <tt>options</tt> property as passed to the {@link #request} function
  191.          */
  192.         'load',
  193.         /**
  194.          * @event loadexception
  195.          * <p>This event is <b>deprecated</b>.  The signature of the loadexception event
  196.          * varies depending on the proxy, use the catch-all {@link #exception} event instead.
  197.          * This event will fire in addition to the {@link #exception} event.</p>
  198.          * @param {misc} misc See {@link #exception}.
  199.          * @deprecated
  200.          */
  201.         'loadexception',
  202.         /**
  203.          * @event beforewrite
  204.          * Fires before a request is generated for one of the actions Ext.data.Api.actions.create|update|destroy
  205.          * @param {DataProxy} this The proxy for the request
  206.          * @param {String} action [Ext.data.Api.actions.create|update|destroy]
  207.          * @param {Record/Array[Record]} rs The Record(s) to create|update|destroy.
  208.          * @param {Object} params The request <code>params</code> object.  Edit <code>params</code> to add parameters to the request.
  209.          */
  210.         'beforewrite',
  211.         /**
  212.          * @event write
  213.          * Fires before the request-callback is called
  214.          * @param {DataProxy} this The proxy that sent the request
  215.          * @param {String} action [Ext.data.Api.actions.create|upate|destroy]
  216.          * @param {Object} data The data object extracted from the server-response
  217.          * @param {Object} response The decoded response from server
  218.          * @param {Record/Record{}} rs The records from Store
  219.          * @param {Object} options The callback's <tt>options</tt> property as passed to the {@link #request} function
  220.          */
  221.         'write'
  222.     );
  223.     Ext.data.DataProxy.superclass.constructor.call(this);
  224. };
  225. Ext.extend(Ext.data.DataProxy, Ext.util.Observable, {
  226.     /**
  227.      * @cfg {Boolean} restful
  228.      * <p>Defaults to <tt>false</tt>.  Set to <tt>true</tt> to operate in a RESTful manner.</p>
  229.      * <br><p> Note: this parameter will automatically be set to <tt>true</tt> if the
  230.      * {@link Ext.data.Store} it is plugged into is set to <code>restful: true</code>. If the
  231.      * Store is RESTful, there is no need to set this option on the proxy.</p>
  232.      * <br><p>RESTful implementations enable the serverside framework to automatically route
  233.      * actions sent to one url based upon the HTTP method, for example:
  234.      * <pre><code>
  235. store: new Ext.data.Store({
  236.     restful: true,
  237.     proxy: new Ext.data.HttpProxy({url:'/users'}); // all requests sent to /users
  238.     ...
  239. )}
  240.      * </code></pre>
  241.      * There is no <code>{@link #api}</code> specified in the configuration of the proxy,
  242.      * all requests will be marshalled to a single RESTful url (/users) so the serverside
  243.      * framework can inspect the HTTP Method and act accordingly:
  244.      * <pre>
  245. <u>Method</u>   <u>url</u>        <u>action</u>
  246. POST     /users     create
  247. GET      /users     read
  248. PUT      /users/23  update
  249. DESTROY  /users/23  delete
  250.      * </pre></p>
  251.      */
  252.     restful: false,
  253.     /**
  254.      * <p>Redefines the Proxy's API or a single action of an API. Can be called with two method signatures.</p>
  255.      * <p>If called with an object as the only parameter, the object should redefine the <b>entire</b> API, e.g.:</p><pre><code>
  256. proxy.setApi({
  257.     read    : '/users/read',
  258.     create  : '/users/create',
  259.     update  : '/users/update',
  260.     destroy : '/users/destroy'
  261. });
  262. </code></pre>
  263.      * <p>If called with two parameters, the first parameter should be a string specifying the API action to
  264.      * redefine and the second parameter should be the URL (or function if using DirectProxy) to call for that action, e.g.:</p><pre><code>
  265. proxy.setApi(Ext.data.Api.actions.read, '/users/new_load_url');
  266. </code></pre>
  267.      * @param {String/Object} api An API specification object, or the name of an action.
  268.      * @param {String/Function} url The URL (or function if using DirectProxy) to call for the action.
  269.      */
  270.     setApi : function() {
  271.         if (arguments.length == 1) {
  272.             var valid = Ext.data.Api.isValid(arguments[0]);
  273.             if (valid === true) {
  274.                 this.api = arguments[0];
  275.             }
  276.             else {
  277.                 throw new Ext.data.Api.Error('invalid', valid);
  278.             }
  279.         }
  280.         else if (arguments.length == 2) {
  281.             if (!Ext.data.Api.isAction(arguments[0])) {
  282.                 throw new Ext.data.Api.Error('invalid', arguments[0]);
  283.             }
  284.             this.api[arguments[0]] = arguments[1];
  285.         }
  286.         Ext.data.Api.prepare(this);
  287.     },
  288.     /**
  289.      * Returns true if the specified action is defined as a unique action in the api-config.
  290.      * request.  If all API-actions are routed to unique urls, the xaction parameter is unecessary.  However, if no api is defined
  291.      * and all Proxy actions are routed to DataProxy#url, the server-side will require the xaction parameter to perform a switch to
  292.      * the corresponding code for CRUD action.
  293.      * @param {String [Ext.data.Api.CREATE|READ|UPDATE|DESTROY]} action
  294.      * @return {Boolean}
  295.      */
  296.     isApiAction : function(action) {
  297.         return (this.api[action]) ? true : false;
  298.     },
  299.     /**
  300.      * All proxy actions are executed through this method.  Automatically fires the "before" + action event
  301.      * @param {String} action Name of the action
  302.      * @param {Ext.data.Record/Ext.data.Record[]/null} rs Will be null when action is 'load'
  303.      * @param {Object} params
  304.      * @param {Ext.data.DataReader} reader
  305.      * @param {Function} callback
  306.      * @param {Object} scope Scope with which to call the callback (defaults to the Proxy object)
  307.      * @param {Object} options Any options specified for the action (e.g. see {@link Ext.data.Store#load}.
  308.      */
  309.     request : function(action, rs, params, reader, callback, scope, options) {
  310.         if (!this.api[action] && !this.load) {
  311.             throw new Ext.data.DataProxy.Error('action-undefined', action);
  312.         }
  313.         params = params || {};
  314.         if ((action === Ext.data.Api.actions.read) ? this.fireEvent("beforeload", this, params) : this.fireEvent("beforewrite", this, action, rs, params) !== false) {
  315.             this.doRequest.apply(this, arguments);
  316.         }
  317.         else {
  318.             callback.call(scope || this, null, options, false);
  319.         }
  320.     },
  321.     /**
  322.      * <b>Deprecated</b> load method using old method signature. See {@doRequest} for preferred method.
  323.      * @deprecated
  324.      * @param {Object} params
  325.      * @param {Object} reader
  326.      * @param {Object} callback
  327.      * @param {Object} scope
  328.      * @param {Object} arg
  329.      */
  330.     load : null,
  331.     /**
  332.      * @cfg {Function} doRequest Abstract method that should be implemented in all subclasses
  333.      * (e.g.: {@link Ext.data.HttpProxy#doRequest HttpProxy.doRequest},
  334.      * {@link Ext.data.DirectProxy#doRequest DirectProxy.doRequest}).
  335.      */
  336.     doRequest : function(action, rs, params, reader, callback, scope, options) {
  337.         // default implementation of doRequest for backwards compatibility with 2.0 proxies.
  338.         // If we're executing here, the action is probably "load".
  339.         // Call with the pre-3.0 method signature.
  340.         this.load(params, reader, callback, scope, options);
  341.     },
  342.     /**
  343.      * buildUrl
  344.      * Sets the appropriate url based upon the action being executed.  If restful is true, and only a single record is being acted upon,
  345.      * url will be built Rails-style, as in "/controller/action/32".  restful will aply iff the supplied record is an
  346.      * instance of Ext.data.Record rather than an Array of them.
  347.      * @param {String} action The api action being executed [read|create|update|destroy]
  348.      * @param {Ext.data.Record/Array[Ext.data.Record]} The record or Array of Records being acted upon.
  349.      * @return {String} url
  350.      * @private
  351.      */
  352.     buildUrl : function(action, record) {
  353.         record = record || null;
  354.         var url = (this.api[action]) ? this.api[action].url : this.url;
  355.         if (!url) {
  356.             throw new Ext.data.Api.Error('invalid-url', action);
  357.         }
  358.         var format = null;
  359.         var m = url.match(/(.*)(.w+)$/);  // <-- look for urls with "provides" suffix, e.g.: /users.json, /users.xml, etc
  360.         if (m) {
  361.             format = m[2];
  362.             url = m[1];
  363.         }
  364.         // prettyUrls is deprectated in favor of restful-config
  365.         if ((this.prettyUrls === true || this.restful === true) && record instanceof Ext.data.Record && !record.phantom) {
  366.             url += '/' + record.id;
  367.         }
  368.         if (format) {   // <-- append the request format if exists (ie: /users/update/69[.json])
  369.             url += format;
  370.         }
  371.         return url;
  372.     },
  373.     /**
  374.      * Destroys the proxy by purging any event listeners and cancelling any active requests.
  375.      */
  376.     destroy: function(){
  377.         this.purgeListeners();
  378.     }
  379. });
  380. /**
  381.  * @class Ext.data.DataProxy.Error
  382.  * @extends Ext.Error
  383.  * DataProxy Error extension.
  384.  * constructor
  385.  * @param {String} name
  386.  * @param {Record/Array[Record]/Array}
  387.  */
  388. Ext.data.DataProxy.Error = Ext.extend(Ext.Error, {
  389.     constructor : function(message, arg) {
  390.         this.arg = arg;
  391.         Ext.Error.call(this, message);
  392.     },
  393.     name: 'Ext.data.DataProxy'
  394. });
  395. Ext.apply(Ext.data.DataProxy.Error.prototype, {
  396.     lang: {
  397.         'action-undefined': "DataProxy attempted to execute an API-action but found an undefined url / function.  Please review your Proxy url/api-configuration.",
  398.         'api-invalid': 'Recieved an invalid API-configuration.  Please ensure your proxy API-configuration contains only the actions from Ext.data.Api.actions.'
  399.     }
  400. });