3 This file is part of Ext JS 4
5 Copyright (c) 2011 Sencha Inc
7 Contact: http://www.sencha.com/contact
9 GNU General Public License Usage
10 This file may be used under the terms of the GNU General Public License version 3.0 as published by the Free Software Foundation and appearing in the file LICENSE included in the packaging of this file. Please review the following information to ensure the GNU General Public License version 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
12 If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
18 * Proxies are used by {@link Ext.data.Store Stores} to handle the loading and saving of {@link Ext.data.Model Model}
19 * data. Usually developers will not need to create or interact with proxies directly.
23 * There are two main types of Proxy - {@link Ext.data.proxy.Client Client} and {@link Ext.data.proxy.Server Server}.
24 * The Client proxies save their data locally and include the following subclasses:
26 * - {@link Ext.data.proxy.LocalStorage LocalStorageProxy} - saves its data to localStorage if the browser supports it
27 * - {@link Ext.data.proxy.SessionStorage SessionStorageProxy} - saves its data to sessionStorage if the browsers supports it
28 * - {@link Ext.data.proxy.Memory MemoryProxy} - holds data in memory only, any data is lost when the page is refreshed
30 * The Server proxies save their data by sending requests to some remote server. These proxies include:
32 * - {@link Ext.data.proxy.Ajax Ajax} - sends requests to a server on the same domain
33 * - {@link Ext.data.proxy.JsonP JsonP} - uses JSON-P to send requests to a server on a different domain
34 * - {@link Ext.data.proxy.Direct Direct} - uses {@link Ext.direct.Manager} to send requests
36 * Proxies operate on the principle that all operations performed are either Create, Read, Update or Delete. These four
37 * operations are mapped to the methods {@link #create}, {@link #read}, {@link #update} and {@link #destroy}
38 * respectively. Each Proxy subclass implements these functions.
40 * The CRUD methods each expect an {@link Ext.data.Operation Operation} object as the sole argument. The Operation
41 * encapsulates information about the action the Store wishes to perform, the {@link Ext.data.Model model} instances
42 * that are to be modified, etc. See the {@link Ext.data.Operation Operation} documentation for more details. Each CRUD
43 * method also accepts a callback function to be called asynchronously on completion.
45 * Proxies also support batching of Operations via a {@link Ext.data.Batch batch} object, invoked by the {@link #batch}
48 Ext.define('Ext.data.proxy.Proxy', {
50 alternateClassName: ['Ext.data.DataProxy', 'Ext.data.Proxy'],
52 'Ext.data.reader.Json',
53 'Ext.data.writer.Json'
61 observable: 'Ext.util.Observable'
65 * @cfg {String} batchOrder
66 * Comma-separated ordering 'create', 'update' and 'destroy' actions when batching. Override this to set a different
67 * order for the batched CRUD actions to be executed in. Defaults to 'create,update,destroy'.
69 batchOrder: 'create,update,destroy',
72 * @cfg {Boolean} batchActions
73 * True to batch actions of a particular type when synchronizing the store. Defaults to true.
78 * @cfg {String} defaultReaderType
79 * The default registered reader type. Defaults to 'json'.
82 defaultReaderType: 'json',
85 * @cfg {String} defaultWriterType
86 * The default registered writer type. Defaults to 'json'.
89 defaultWriterType: 'json',
92 * @cfg {String/Ext.data.Model} model
93 * The name of the Model to tie to this Proxy. Can be either the string name of the Model, or a reference to the
94 * Model constructor. Required.
98 * @cfg {Object/String/Ext.data.reader.Reader} reader
99 * The Ext.data.reader.Reader to use to decode the server's response or data read from client. This can either be a
100 * Reader instance, a config object or just a valid Reader type name (e.g. 'json', 'xml').
104 * @cfg {Object/String/Ext.data.writer.Writer} writer
105 * The Ext.data.writer.Writer to use to encode any request sent to the server or saved to client. This can either be
106 * a Writer instance, a config object or just a valid Writer type name (e.g. 'json', 'xml').
113 * @param {Object} config (optional) Config object.
115 constructor: function(config) {
116 config = config || {};
118 if (config.model === undefined) {
122 this.mixins.observable.constructor.call(this, config);
124 if (this.model !== undefined && !(this.model instanceof Ext.data.Model)) {
125 this.setModel(this.model);
130 * Sets the model associated with this proxy. This will only usually be called by a Store
132 * @param {String/Ext.data.Model} model The new model. Can be either the model name string,
133 * or a reference to the model's constructor
134 * @param {Boolean} setOnStore Sets the new model on the associated Store, if one is present
136 setModel: function(model, setOnStore) {
137 this.model = Ext.ModelManager.getModel(model);
139 var reader = this.reader,
140 writer = this.writer;
142 this.setReader(reader);
143 this.setWriter(writer);
145 if (setOnStore && this.store) {
146 this.store.setModel(this.model);
151 * Returns the model attached to this Proxy
152 * @return {Ext.data.Model} The model
154 getModel: function() {
159 * Sets the Proxy's Reader by string, config object or Reader instance
161 * @param {String/Object/Ext.data.reader.Reader} reader The new Reader, which can be either a type string,
162 * a configuration object or an Ext.data.reader.Reader instance
163 * @return {Ext.data.reader.Reader} The attached Reader object
165 setReader: function(reader) {
168 if (reader === undefined || typeof reader == 'string') {
174 if (reader.isReader) {
175 reader.setModel(me.model);
177 Ext.applyIf(reader, {
180 type : me.defaultReaderType
183 reader = Ext.createByAlias('reader.' + reader.type, reader);
191 * Returns the reader currently attached to this proxy instance
192 * @return {Ext.data.reader.Reader} The Reader instance
194 getReader: function() {
199 * Sets the Proxy's Writer by string, config object or Writer instance
201 * @param {String/Object/Ext.data.writer.Writer} writer The new Writer, which can be either a type string,
202 * a configuration object or an Ext.data.writer.Writer instance
203 * @return {Ext.data.writer.Writer} The attached Writer object
205 setWriter: function(writer) {
206 if (writer === undefined || typeof writer == 'string') {
212 if (!(writer instanceof Ext.data.writer.Writer)) {
213 Ext.applyIf(writer, {
215 type : this.defaultWriterType
218 writer = Ext.createByAlias('writer.' + writer.type, writer);
221 this.writer = writer;
227 * Returns the writer currently attached to this proxy instance
228 * @return {Ext.data.writer.Writer} The Writer instance
230 getWriter: function() {
235 * Performs the given create operation.
236 * @param {Ext.data.Operation} operation The Operation to perform
237 * @param {Function} callback Callback function to be called when the Operation has completed (whether successful or not)
238 * @param {Object} scope Scope to execute the callback function in
244 * Performs the given read operation.
245 * @param {Ext.data.Operation} operation The Operation to perform
246 * @param {Function} callback Callback function to be called when the Operation has completed (whether successful or not)
247 * @param {Object} scope Scope to execute the callback function in
253 * Performs the given update operation.
254 * @param {Ext.data.Operation} operation The Operation to perform
255 * @param {Function} callback Callback function to be called when the Operation has completed (whether successful or not)
256 * @param {Object} scope Scope to execute the callback function in
262 * Performs the given destroy operation.
263 * @param {Ext.data.Operation} operation The Operation to perform
264 * @param {Function} callback Callback function to be called when the Operation has completed (whether successful or not)
265 * @param {Object} scope Scope to execute the callback function in
268 destroy: Ext.emptyFn,
271 * Performs a batch of {@link Ext.data.Operation Operations}, in the order specified by {@link #batchOrder}. Used
272 * internally by {@link Ext.data.Store}'s {@link Ext.data.Store#sync sync} method. Example usage:
275 * create : [myModel1, myModel2],
276 * update : [myModel3],
277 * destroy: [myModel4, myModel5]
280 * Where the myModel* above are {@link Ext.data.Model Model} instances - in this case 1 and 2 are new instances and
281 * have not been saved before, 3 has been saved previously but needs to be updated, and 4 and 5 have already been
282 * saved but should now be destroyed.
284 * @param {Object} operations Object containing the Model instances to act upon, keyed by action name
285 * @param {Object} listeners (optional) listeners object passed straight through to the Batch -
286 * see {@link Ext.data.Batch}
287 * @return {Ext.data.Batch} The newly created Ext.data.Batch object
289 batch: function(operations, listeners) {
291 batch = Ext.create('Ext.data.Batch', {
293 listeners: listeners || {}
295 useBatch = me.batchActions,
298 Ext.each(me.batchOrder.split(','), function(action) {
299 records = operations[action];
302 batch.add(Ext.create('Ext.data.Operation', {
307 Ext.each(records, function(record){
308 batch.add(Ext.create('Ext.data.Operation', {
321 // Ext.data.proxy.ProxyMgr.registerType('proxy', this);
323 //backwards compatibility
324 Ext.data.DataProxy = this;
325 // Ext.deprecate('platform', '2.0', function() {
326 // Ext.data.DataProxy = this;