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 * Represents a single read or write operation performed by a {@link Ext.data.proxy.Proxy Proxy}. Operation objects are
19 * used to enable communication between Stores and Proxies. Application developers should rarely need to interact with
20 * Operation objects directly.
22 * Several Operations can be batched together in a {@link Ext.data.Batch batch}.
24 Ext.define('Ext.data.Operation', {
26 * @cfg {Boolean} synchronous
27 * True if this Operation is to be executed synchronously. This property is inspected by a
28 * {@link Ext.data.Batch Batch} to see if a series of Operations can be executed in parallel or not.
33 * @cfg {String} action
34 * The action being performed by this Operation. Should be one of 'create', 'read', 'update' or 'destroy'.
39 * @cfg {Ext.util.Filter[]} filters
40 * Optional array of filter objects. Only applies to 'read' actions.
45 * @cfg {Ext.util.Sorter[]} sorters
46 * Optional array of sorter objects. Only applies to 'read' actions.
51 * @cfg {Ext.util.Grouper} group
52 * Optional grouping configuration. Only applies to 'read' actions where grouping is desired.
58 * The start index (offset), used in paging when running a 'read' action.
64 * The number of records to load. Used on 'read' actions when paging is being used.
69 * @cfg {Ext.data.Batch} batch
70 * The batch that this Operation is a part of.
75 * @cfg {Function} callback
76 * Function to execute when operation completed. Will be called with the following parameters:
78 * - records : Array of Ext.data.Model objects.
79 * - operation : The Ext.data.Operation itself.
80 * - success : True when operation completed successfully.
86 * Scope for the {@link #callback} function.
91 * @property {Boolean} started
92 * Read-only property tracking the start status of this Operation. Use {@link #isStarted}.
98 * @property {Boolean} running
99 * Read-only property tracking the run status of this Operation. Use {@link #isRunning}.
105 * @property {Boolean} complete
106 * Read-only property tracking the completion status of this Operation. Use {@link #isComplete}.
112 * @property {Boolean} success
113 * Read-only property tracking whether the Operation was successful or not. This starts as undefined and is set to true
114 * or false by the Proxy that is executing the Operation. It is also set to false by {@link #setException}. Use
115 * {@link #wasSuccessful} to query success status.
121 * @property {Boolean} exception
122 * Read-only property tracking the exception status of this Operation. Use {@link #hasException} and see {@link #getError}.
128 * @property {String/Object} error
129 * The error object passed when {@link #setException} was called. This could be any object or primitive.
135 * @property {RegExp} actionCommitRecordsRe
136 * The RegExp used to categorize actions that require record commits.
138 actionCommitRecordsRe: /^(?:create|update)$/i,
141 * @property {RegExp} actionSkipSyncRe
142 * The RegExp used to categorize actions that skip local record synchronization. This defaults
143 * to match 'destroy'.
145 actionSkipSyncRe: /^destroy$/i,
148 * Creates new Operation object.
149 * @param {Object} config (optional) Config object.
151 constructor: function(config) {
152 Ext.apply(this, config || {});
156 * This method is called to commit data to this instance's records given the records in
157 * the server response. This is followed by calling {@link Ext.data.Model#commit} on all
158 * those records (for 'create' and 'update' actions).
160 * If this {@link #action} is 'destroy', any server records are ignored and the
161 * {@link Ext.data.Model#commit} method is not called.
163 * @param {Ext.data.Model[]} serverRecords An array of {@link Ext.data.Model} objects returned by
167 commitRecords: function (serverRecords) {
169 mc, index, clientRecords, serverRec, clientRec;
171 if (!me.actionSkipSyncRe.test(me.action)) {
172 clientRecords = me.records;
174 if (clientRecords && clientRecords.length) {
175 mc = Ext.create('Ext.util.MixedCollection', true, function(r) {return r.getId();});
176 mc.addAll(clientRecords);
178 for (index = serverRecords ? serverRecords.length : 0; index--; ) {
179 serverRec = serverRecords[index];
180 clientRec = mc.get(serverRec.getId());
183 clientRec.beginEdit();
184 clientRec.set(serverRec.data);
185 clientRec.endEdit(true);
189 if (me.actionCommitRecordsRe.test(me.action)) {
190 for (index = clientRecords.length; index--; ) {
191 clientRecords[index].commit();
199 * Marks the Operation as started.
201 setStarted: function() {
207 * Marks the Operation as completed.
209 setCompleted: function() {
210 this.complete = true;
211 this.running = false;
215 * Marks the Operation as successful.
217 setSuccessful: function() {
222 * Marks the Operation as having experienced an exception. Can be supplied with an option error message/object.
223 * @param {String/Object} error (optional) error string/object
225 setException: function(error) {
226 this.exception = true;
227 this.success = false;
228 this.running = false;
233 * Returns true if this Operation encountered an exception (see also {@link #getError})
234 * @return {Boolean} True if there was an exception
236 hasException: function() {
237 return this.exception === true;
241 * Returns the error string or object that was set using {@link #setException}
242 * @return {String/Object} The error object
244 getError: function() {
249 * Returns an array of Ext.data.Model instances as set by the Proxy.
250 * @return {Ext.data.Model[]} Any loaded Records
252 getRecords: function() {
253 var resultSet = this.getResultSet();
255 return (resultSet === undefined ? this.records : resultSet.records);
259 * Returns the ResultSet object (if set by the Proxy). This object will contain the {@link Ext.data.Model model}
260 * instances as well as meta data such as number of instances fetched, number available etc
261 * @return {Ext.data.ResultSet} The ResultSet object
263 getResultSet: function() {
264 return this.resultSet;
268 * Returns true if the Operation has been started. Note that the Operation may have started AND completed, see
269 * {@link #isRunning} to test if the Operation is currently running.
270 * @return {Boolean} True if the Operation has started
272 isStarted: function() {
273 return this.started === true;
277 * Returns true if the Operation has been started but has not yet completed.
278 * @return {Boolean} True if the Operation is currently running
280 isRunning: function() {
281 return this.running === true;
285 * Returns true if the Operation has been completed
286 * @return {Boolean} True if the Operation is complete
288 isComplete: function() {
289 return this.complete === true;
293 * Returns true if the Operation has completed and was successful
294 * @return {Boolean} True if successful
296 wasSuccessful: function() {
297 return this.isComplete() && this.success === true;
302 * Associates this Operation with a Batch
303 * @param {Ext.data.Batch} batch The batch
305 setBatch: function(batch) {
310 * Checks whether this operation should cause writing to occur.
311 * @return {Boolean} Whether the operation should cause a write to occur.
313 allowWrite: function() {
314 return this.action != 'read';