src/data/Api.js

   1 /*!
   2  * Ext JS Library 3.0.0
   3  * Copyright(c) 2006-2009 Ext JS, LLC
   4  * licensing@extjs.com
   5  * http://www.extjs.com/license
   6  */
   7 /**
   8  * @class Ext.data.Api
   9  * @extends Object
  10  * Ext.data.Api is a singleton designed to manage the data API including methods
  11  * for validating a developer's DataProxy API.  Defines variables for CRUD actions
  12  * create, read, update and destroy in addition to a mapping of RESTful HTTP methods
  13  * GET, POST, PUT and DELETE to CRUD actions.
  14  * @singleton
  15  */
  16 Ext.data.Api = (function() {
  17
  18     // private validActions.  validActions is essentially an inverted hash of Ext.data.Api.actions, where value becomes the key.
  19     // Some methods in this singleton (e.g.: getActions, getVerb) will loop through actions with the code <code>for (var verb in this.actions)</code>
  20     // For efficiency, some methods will first check this hash for a match.  Those methods which do acces validActions will cache their result here.
  21     // We cannot pre-define this hash since the developer may over-ride the actions at runtime.
  22     var validActions = {};
  23
  24     return {
  25         /**
  26          * Defined actions corresponding to remote actions:
  27          * <pre><code>
  28 actions: {
  29     create  : 'create',  // Text representing the remote-action to create records on server.
  30     read    : 'read',    // Text representing the remote-action to read/load data from server.
  31     update  : 'update',  // Text representing the remote-action to update records on server.
  32     destroy : 'destroy'  // Text representing the remote-action to destroy records on server.
  33 }
  34          * </code></pre>
  35          * @property actions
  36          * @type Object
  37          */
  38         actions : {
  39             create  : 'create',
  40             read    : 'read',
  41             update  : 'update',
  42             destroy : 'destroy'
  43         },
  44
  45         /**
  46          * Defined {CRUD action}:{HTTP method} pairs to associate HTTP methods with the
  47          * corresponding actions for {@link Ext.data.DataProxy#restful RESTful proxies}.
  48          * Defaults to:
  49          * <pre><code>
  50 restActions : {
  51     create  : 'POST',
  52     read    : 'GET',
  53     update  : 'PUT',
  54     destroy : 'DELETE'
  55 },
  56          * </code></pre>
  57          */
  58         restActions : {
  59             create  : 'POST',
  60             read    : 'GET',
  61             update  : 'PUT',
  62             destroy : 'DELETE'
  63         },
  64
  65         /**
  66          * Returns true if supplied action-name is a valid API action defined in <code>{@link #actions}</code> constants
  67          * @param {String} action
  68          * @param {String[]}(Optional) List of available CRUD actions.  Pass in list when executing multiple times for efficiency.
  69          * @return {Boolean}
  70          */
  71         isAction : function(action) {
  72             return (Ext.data.Api.actions[action]) ? true : false;
  73         },
  74
  75         /**
  76          * Returns the actual CRUD action KEY "create", "read", "update" or "destroy" from the supplied action-name.  This method is used internally and shouldn't generally
  77          * need to be used directly.  The key/value pair of Ext.data.Api.actions will often be identical but this is not necessarily true.  A developer can override this naming
  78          * convention if desired.  However, the framework internally calls methods based upon the KEY so a way of retreiving the the words "create", "read", "update" and "destroy" is
  79          * required.  This method will cache discovered KEYS into the private validActions hash.
  80          * @param {String} name The runtime name of the action.
  81          * @return {String||null} returns the action-key, or verb of the user-action or null if invalid.
  82          * @nodoc
  83          */
  84         getVerb : function(name) {
  85             if (validActions[name]) {
  86                 return validActions[name];  // <-- found in cache.  return immediately.
  87             }
  88             for (var verb in this.actions) {
  89                 if (this.actions[verb] === name) {
  90                     validActions[name] = verb;
  91                     break;
  92                 }
  93             }
  94             return (validActions[name] !== undefined) ? validActions[name] : null;
  95         },
  96
  97         /**
  98          * Returns true if the supplied API is valid; that is, check that all keys match defined actions
  99          * otherwise returns an array of mistakes.
 100          * @return {String[]||true}
 101          */
 102         isValid : function(api){
 103             var invalid = [];
 104             var crud = this.actions; // <-- cache a copy of the actions.
 105             for (var action in api) {
 106                 if (!(action in crud)) {
 107                     invalid.push(action);
 108                 }
 109             }
 110             return (!invalid.length) ? true : invalid;
 111         },
 112
 113         /**
 114          * Returns true if the supplied verb upon the supplied proxy points to a unique url in that none of the other api-actions
 115          * point to the same url.  The question is important for deciding whether to insert the "xaction" HTTP parameter within an
 116          * Ajax request.  This method is used internally and shouldn't generally need to be called directly.
 117          * @param {Ext.data.DataProxy} proxy
 118          * @param {String} verb
 119          * @return {Boolean}
 120          */
 121         hasUniqueUrl : function(proxy, verb) {
 122             var url = (proxy.api[verb]) ? proxy.api[verb].url : null;
 123             var unique = true;
 124             for (var action in proxy.api) {
 125                 if ((unique = (action === verb) ? true : (proxy.api[action].url != url) ? true : false) === false) {
 126                     break;
 127                 }
 128             }
 129             return unique;
 130         },
 131
 132         /**
 133          * This method is used internally by <tt>{@link Ext.data.DataProxy DataProxy}</tt> and should not generally need to be used directly.
 134          * Each action of a DataProxy api can be initially defined as either a String or an Object.  When specified as an object,
 135          * one can explicitly define the HTTP method (GET|POST) to use for each CRUD action.  This method will prepare the supplied API, setting
 136          * each action to the Object form.  If your API-actions do not explicitly define the HTTP method, the "method" configuration-parameter will
 137          * be used.  If the method configuration parameter is not specified, POST will be used.
 138          <pre><code>
 139 new Ext.data.HttpProxy({
 140     method: "POST",     // <-- default HTTP method when not specified.
 141     api: {
 142         create: 'create.php',
 143         load: 'read.php',
 144         save: 'save.php',
 145         destroy: 'destroy.php'
 146     }
 147 });
 148
 149 // Alternatively, one can use the object-form to specify the API
 150 new Ext.data.HttpProxy({
 151     api: {
 152         load: {url: 'read.php', method: 'GET'},
 153         create: 'create.php',
 154         destroy: 'destroy.php',
 155         save: 'update.php'
 156     }
 157 });
 158         </code></pre>
 159          *
 160          * @param {Ext.data.DataProxy} proxy
 161          */
 162         prepare : function(proxy) {
 163             if (!proxy.api) {
 164                 proxy.api = {}; // <-- No api?  create a blank one.
 165             }
 166             for (var verb in this.actions) {
 167                 var action = this.actions[verb];
 168                 proxy.api[action] = proxy.api[action] || proxy.url || proxy.directFn;
 169                 if (typeof(proxy.api[action]) == 'string') {
 170                     proxy.api[action] = {
 171                         url: proxy.api[action]
 172                     };
 173                 }
 174             }
 175         },
 176
 177         /**
 178          * Prepares a supplied Proxy to be RESTful.  Sets the HTTP method for each api-action to be one of
 179          * GET, POST, PUT, DELETE according to the defined {@link #restActions}.
 180          * @param {Ext.data.DataProxy} proxy
 181          */
 182         restify : function(proxy) {
 183             proxy.restful = true;
 184             for (var verb in this.restActions) {
 185                 proxy.api[this.actions[verb]].method = this.restActions[verb];
 186             }
 187         }
 188     };
 189 })();
 190
 191 /**
 192  * @class Ext.data.Api.Error
 193  * @extends Ext.Error
 194  * Error class for Ext.data.Api errors
 195  */
 196 Ext.data.Api.Error = Ext.extend(Ext.Error, {
 197     constructor : function(message, arg) {
 198         this.arg = arg;
 199         Ext.Error.call(this, message);
 200     },
 201     name: 'Ext.data.Api'
 202 });
 203 Ext.apply(Ext.data.Api.Error.prototype, {
 204     lang: {
 205         'action-url-undefined': 'No fallback url defined for this action.  When defining a DataProxy api, please be sure to define an url for each CRUD action in Ext.data.Api.actions or define a default url in addition to your api-configuration.',
 206         'invalid': 'received an invalid API-configuration.  Please ensure your proxy API-configuration contains only the actions defined in Ext.data.Api.actions',
 207         'invalid-url': 'Invalid url.  Please review your proxy configuration.',
 208         'execute': 'Attempted to execute an unknown action.  Valid API actions are defined in Ext.data.Api.actions"'
 209     }
 210 });