PageRenderTime 40ms CodeModel.GetById 11ms app.highlight 20ms RepoModel.GetById 2ms app.codeStats 0ms

/hippo/src/main/webapp/ext/src/data/Api.js

http://hdbc.googlecode.com/
JavaScript | 210 lines | 87 code | 10 blank | 113 comment | 17 complexity | 3158f7b88929528b125eb30fea2ba445 MD5 | raw file
  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 */
 16Ext.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>
 28actions: {
 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>
 50restActions : {
 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>
139new 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
150new 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 */
196Ext.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});
203Ext.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});