src/data/Api.js

   1 /*!
   2  * Ext JS Library 3.1.1
   3  * Copyright(c) 2006-2010 Ext JS, LLC
   4  * licensing@extjs.com
   5  * http://www.extjs.com/license
   6  */
   7
   8 /**
   9  * @class Ext.data.Api
  10  * @extends Object
  11  * Ext.data.Api is a singleton designed to manage the data API including methods
  12  * for validating a developer's DataProxy API.  Defines variables for CRUD actions
  13  * create, read, update and destroy in addition to a mapping of RESTful HTTP methods
  14  * GET, POST, PUT and DELETE to CRUD actions.
  15  * @singleton
  16  */
  17 Ext.data.Api = (function() {
  18
  19     // private validActions.  validActions is essentially an inverted hash of Ext.data.Api.actions, where value becomes the key.
  20     // Some methods in this singleton (e.g.: getActions, getVerb) will loop through actions with the code <code>for (var verb in this.actions)</code>
  21     // For efficiency, some methods will first check this hash for a match.  Those methods which do acces validActions will cache their result here.
  22     // We cannot pre-define this hash since the developer may over-ride the actions at runtime.
  23     var validActions = {};
  24
  25     return {
  26         /**
  27          * Defined actions corresponding to remote actions:
  28          * <pre><code>
  29 actions: {
  30     create  : 'create',  // Text representing the remote-action to create records on server.
  31     read    : 'read',    // Text representing the remote-action to read/load data from server.
  32     update  : 'update',  // Text representing the remote-action to update records on server.
  33     destroy : 'destroy'  // Text representing the remote-action to destroy records on server.
  34 }
  35          * </code></pre>
  36          * @property actions
  37          * @type Object
  38          */
  39         actions : {
  40             create  : 'create',
  41             read    : 'read',
  42             update  : 'update',
  43             destroy : 'destroy'
  44         },
  45
  46         /**
  47          * Defined {CRUD action}:{HTTP method} pairs to associate HTTP methods with the
  48          * corresponding actions for {@link Ext.data.DataProxy#restful RESTful proxies}.
  49          * Defaults to:
  50          * <pre><code>
  51 restActions : {
  52     create  : 'POST',
  53     read    : 'GET',
  54     update  : 'PUT',
  55     destroy : 'DELETE'
  56 },
  57          * </code></pre>
  58          */
  59         restActions : {
  60             create  : 'POST',
  61             read    : 'GET',
  62             update  : 'PUT',
  63             destroy : 'DELETE'
  64         },
  65
  66         /**
  67          * Returns true if supplied action-name is a valid API action defined in <code>{@link #actions}</code> constants
  68          * @param {String} action
  69          * @param {String[]}(Optional) List of available CRUD actions.  Pass in list when executing multiple times for efficiency.
  70          * @return {Boolean}
  71          */
  72         isAction : function(action) {
  73             return (Ext.data.Api.actions[action]) ? true : false;
  74         },
  75
  76         /**
  77          * 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
  78          * 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
  79          * 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
  80          * required.  This method will cache discovered KEYS into the private validActions hash.
  81          * @param {String} name The runtime name of the action.
  82          * @return {String||null} returns the action-key, or verb of the user-action or null if invalid.
  83          * @nodoc
  84          */
  85         getVerb : function(name) {
  86             if (validActions[name]) {
  87                 return validActions[name];  // <-- found in cache.  return immediately.
  88             }
  89             for (var verb in this.actions) {
  90                 if (this.actions[verb] === name) {
  91                     validActions[name] = verb;
  92                     break;
  93                 }
  94             }
  95             return (validActions[name] !== undefined) ? validActions[name] : null;
  96         },
  97
  98         /**
  99          * Returns true if the supplied API is valid; that is, check that all keys match defined actions
 100          * otherwise returns an array of mistakes.
 101          * @return {String[]||true}
 102          */
 103         isValid : function(api){
 104             var invalid = [];
 105             var crud = this.actions; // <-- cache a copy of the actions.
 106             for (var action in api) {
 107                 if (!(action in crud)) {
 108                     invalid.push(action);
 109                 }
 110             }
 111             return (!invalid.length) ? true : invalid;
 112         },
 113
 114         /**
 115          * Returns true if the supplied verb upon the supplied proxy points to a unique url in that none of the other api-actions
 116          * point to the same url.  The question is important for deciding whether to insert the "xaction" HTTP parameter within an
 117          * Ajax request.  This method is used internally and shouldn't generally need to be called directly.
 118          * @param {Ext.data.DataProxy} proxy
 119          * @param {String} verb
 120          * @return {Boolean}
 121          */
 122         hasUniqueUrl : function(proxy, verb) {
 123             var url = (proxy.api[verb]) ? proxy.api[verb].url : null;
 124             var unique = true;
 125             for (var action in proxy.api) {
 126                 if ((unique = (action === verb) ? true : (proxy.api[action].url != url) ? true : false) === false) {
 127                     break;
 128                 }
 129             }
 130             return unique;
 131         },
 132
 133         /**
 134          * This method is used internally by <tt>{@link Ext.data.DataProxy DataProxy}</tt> and should not generally need to be used directly.
 135          * Each action of a DataProxy api can be initially defined as either a String or an Object.  When specified as an object,
 136          * one can explicitly define the HTTP method (GET|POST) to use for each CRUD action.  This method will prepare the supplied API, setting
 137          * each action to the Object form.  If your API-actions do not explicitly define the HTTP method, the "method" configuration-parameter will
 138          * be used.  If the method configuration parameter is not specified, POST will be used.
 139          <pre><code>
 140 new Ext.data.HttpProxy({
 141     method: "POST",     // <-- default HTTP method when not specified.
 142     api: {
 143         create: 'create.php',
 144         load: 'read.php',
 145         save: 'save.php',
 146         destroy: 'destroy.php'
 147     }
 148 });
 149
 150 // Alternatively, one can use the object-form to specify the API
 151 new Ext.data.HttpProxy({
 152     api: {
 153         load: {url: 'read.php', method: 'GET'},
 154         create: 'create.php',
 155         destroy: 'destroy.php',
 156         save: 'update.php'
 157     }
 158 });
 159         </code></pre>
 160          *
 161          * @param {Ext.data.DataProxy} proxy
 162          */
 163         prepare : function(proxy) {
 164             if (!proxy.api) {
 165                 proxy.api = {}; // <-- No api?  create a blank one.
 166             }
 167             for (var verb in this.actions) {
 168                 var action = this.actions[verb];
 169                 proxy.api[action] = proxy.api[action] || proxy.url || proxy.directFn;
 170                 if (typeof(proxy.api[action]) == 'string') {
 171                     proxy.api[action] = {
 172                         url: proxy.api[action],
 173                         method: (proxy.restful === true) ? Ext.data.Api.restActions[action] : undefined
 174                     };
 175                 }
 176             }
 177         },
 178
 179         /**
 180          * Prepares a supplied Proxy to be RESTful.  Sets the HTTP method for each api-action to be one of
 181          * GET, POST, PUT, DELETE according to the defined {@link #restActions}.
 182          * @param {Ext.data.DataProxy} proxy
 183          */
 184         restify : function(proxy) {
 185             proxy.restful = true;
 186             for (var verb in this.restActions) {
 187                 proxy.api[this.actions[verb]].method ||
 188                     (proxy.api[this.actions[verb]].method = this.restActions[verb]);
 189             }
 190             // TODO: perhaps move this interceptor elsewhere?  like into DataProxy, perhaps?  Placed here
 191             // to satisfy initial 3.0 final release of REST features.
 192             proxy.onWrite = proxy.onWrite.createInterceptor(function(action, o, response, rs) {
 193                 var reader = o.reader;
 194                 var res = new Ext.data.Response({
 195                     action: action,
 196                     raw: response
 197                 });
 198
 199                 switch (response.status) {
 200                     case 200:   // standard 200 response, send control back to HttpProxy#onWrite by returning true from this intercepted #onWrite
 201                         return true;
 202                         break;
 203                     case 201:   // entity created but no response returned
 204                         if (Ext.isEmpty(res.raw.responseText)) {
 205                           res.success = true;
 206                         } else {
 207                           //if the response contains data, treat it like a 200
 208                           return true;
 209                         }
 210                         break;
 211                     case 204:  // no-content.  Create a fake response.
 212                         res.success = true;
 213                         res.data = null;
 214                         break;
 215                     default:
 216                         return true;
 217                         break;
 218                 }
 219                 if (res.success === true) {
 220                     this.fireEvent("write", this, action, res.data, res, rs, o.request.arg);
 221                 } else {
 222                     this.fireEvent('exception', this, 'remote', action, o, res, rs);
 223                 }
 224                 o.request.callback.call(o.request.scope, res.data, res, res.success);
 225
 226                 return false;   // <-- false to prevent intercepted function from running.
 227             }, proxy);
 228         }
 229     };
 230 })();
 231
 232 /**
 233  * Ext.data.Response
 234  * Experimental.  Do not use directly.
 235  */
 236 Ext.data.Response = function(params, response) {
 237     Ext.apply(this, params, {
 238         raw: response
 239     });
 240 };
 241 Ext.data.Response.prototype = {
 242     message : null,
 243     success : false,
 244     status : null,
 245     root : null,
 246     raw : null,
 247
 248     getMessage : function() {
 249         return this.message;
 250     },
 251     getSuccess : function() {
 252         return this.success;
 253     },
 254     getStatus : function() {
 255         return this.status;
 256     },
 257     getRoot : function() {
 258         return this.root;
 259     },
 260     getRawResponse : function() {
 261         return this.raw;
 262     }
 263 };
 264
 265 /**
 266  * @class Ext.data.Api.Error
 267  * @extends Ext.Error
 268  * Error class for Ext.data.Api errors
 269  */
 270 Ext.data.Api.Error = Ext.extend(Ext.Error, {
 271     constructor : function(message, arg) {
 272         this.arg = arg;
 273         Ext.Error.call(this, message);
 274     },
 275     name: 'Ext.data.Api'
 276 });
 277 Ext.apply(Ext.data.Api.Error.prototype, {
 278     lang: {
 279         '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.',
 280         'invalid': 'received an invalid API-configuration.  Please ensure your proxy API-configuration contains only the actions defined in Ext.data.Api.actions',
 281         'invalid-url': 'Invalid url.  Please review your proxy configuration.',
 282         'execute': 'Attempted to execute an unknown action.  Valid API actions are defined in Ext.data.Api.actions"'
 283     }
 284 });
 285
 286