src/data/Operation.js

   1 /*
   2
   3 This file is part of Ext JS 4
   4
   5 Copyright (c) 2011 Sencha Inc
   6
   7 Contact:  http://www.sencha.com/contact
   8
   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.
  11
  12 If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
  13
  14 */
  15 /**
  16  * @author Ed Spencer
  17  * @class Ext.data.Operation
  18  * @extends Object
  19  *
  20  * <p>Represents a single read or write operation performed by a {@link Ext.data.proxy.Proxy Proxy}.
  21  * Operation objects are used to enable communication between Stores and Proxies. Application
  22  * developers should rarely need to interact with Operation objects directly.</p>
  23  *
  24  * <p>Several Operations can be batched together in a {@link Ext.data.Batch batch}.</p>
  25  *
  26  */
  27 Ext.define('Ext.data.Operation', {
  28     /**
  29      * @cfg {Boolean} synchronous True if this Operation is to be executed synchronously (defaults to true). This
  30      * property is inspected by a {@link Ext.data.Batch Batch} to see if a series of Operations can be executed in
  31      * parallel or not.
  32      */
  33     synchronous: true,
  34
  35     /**
  36      * @cfg {String} action The action being performed by this Operation. Should be one of 'create', 'read', 'update' or 'destroy'
  37      */
  38     action: undefined,
  39
  40     /**
  41      * @cfg {Array} filters Optional array of filter objects. Only applies to 'read' actions.
  42      */
  43     filters: undefined,
  44
  45     /**
  46      * @cfg {Array} sorters Optional array of sorter objects. Only applies to 'read' actions.
  47      */
  48     sorters: undefined,
  49
  50     /**
  51      * @cfg {Object} group Optional grouping configuration. Only applies to 'read' actions where grouping is desired.
  52      */
  53     group: undefined,
  54
  55     /**
  56      * @cfg {Number} start The start index (offset), used in paging when running a 'read' action.
  57      */
  58     start: undefined,
  59
  60     /**
  61      * @cfg {Number} limit The number of records to load. Used on 'read' actions when paging is being used.
  62      */
  63     limit: undefined,
  64
  65     /**
  66      * @cfg {Ext.data.Batch} batch The batch that this Operation is a part of (optional)
  67      */
  68     batch: undefined,
  69
  70     /**
  71      * Read-only property tracking the start status of this Operation. Use {@link #isStarted}.
  72      * @property started
  73      * @type Boolean
  74      * @private
  75      */
  76     started: false,
  77
  78     /**
  79      * Read-only property tracking the run status of this Operation. Use {@link #isRunning}.
  80      * @property running
  81      * @type Boolean
  82      * @private
  83      */
  84     running: false,
  85
  86     /**
  87      * Read-only property tracking the completion status of this Operation. Use {@link #isComplete}.
  88      * @property complete
  89      * @type Boolean
  90      * @private
  91      */
  92     complete: false,
  93
  94     /**
  95      * Read-only property tracking whether the Operation was successful or not. This starts as undefined and is set to true
  96      * or false by the Proxy that is executing the Operation. It is also set to false by {@link #setException}. Use
  97      * {@link #wasSuccessful} to query success status.
  98      * @property success
  99      * @type Boolean
 100      * @private
 101      */
 102     success: undefined,
 103
 104     /**
 105      * Read-only property tracking the exception status of this Operation. Use {@link #hasException} and see {@link #getError}.
 106      * @property exception
 107      * @type Boolean
 108      * @private
 109      */
 110     exception: false,
 111
 112     /**
 113      * The error object passed when {@link #setException} was called. This could be any object or primitive.
 114      * @property error
 115      * @type Mixed
 116      * @private
 117      */
 118     error: undefined,
 119
 120     /**
 121      * Creates new Operation object.
 122      * @param {Object} config (optional) Config object.
 123      */
 124     constructor: function(config) {
 125         Ext.apply(this, config || {});
 126     },
 127
 128     /**
 129      * Marks the Operation as started
 130      */
 131     setStarted: function() {
 132         this.started = true;
 133         this.running = true;
 134     },
 135
 136     /**
 137      * Marks the Operation as completed
 138      */
 139     setCompleted: function() {
 140         this.complete = true;
 141         this.running  = false;
 142     },
 143
 144     /**
 145      * Marks the Operation as successful
 146      */
 147     setSuccessful: function() {
 148         this.success = true;
 149     },
 150
 151     /**
 152      * Marks the Operation as having experienced an exception. Can be supplied with an option error message/object.
 153      * @param {Mixed} error Optional error string/object
 154      */
 155     setException: function(error) {
 156         this.exception = true;
 157         this.success = false;
 158         this.running = false;
 159         this.error = error;
 160     },
 161
 162     /**
 163      * Returns true if this Operation encountered an exception (see also {@link #getError})
 164      * @return {Boolean} True if there was an exception
 165      */
 166     hasException: function() {
 167         return this.exception === true;
 168     },
 169
 170     /**
 171      * Returns the error string or object that was set using {@link #setException}
 172      * @return {Mixed} The error object
 173      */
 174     getError: function() {
 175         return this.error;
 176     },
 177
 178     /**
 179      * Returns an array of Ext.data.Model instances as set by the Proxy.
 180      * @return {Array} Any loaded Records
 181      */
 182     getRecords: function() {
 183         var resultSet = this.getResultSet();
 184
 185         return (resultSet === undefined ? this.records : resultSet.records);
 186     },
 187
 188     /**
 189      * Returns the ResultSet object (if set by the Proxy). This object will contain the {@link Ext.data.Model model} instances
 190      * as well as meta data such as number of instances fetched, number available etc
 191      * @return {Ext.data.ResultSet} The ResultSet object
 192      */
 193     getResultSet: function() {
 194         return this.resultSet;
 195     },
 196
 197     /**
 198      * Returns true if the Operation has been started. Note that the Operation may have started AND completed,
 199      * see {@link #isRunning} to test if the Operation is currently running.
 200      * @return {Boolean} True if the Operation has started
 201      */
 202     isStarted: function() {
 203         return this.started === true;
 204     },
 205
 206     /**
 207      * Returns true if the Operation has been started but has not yet completed.
 208      * @return {Boolean} True if the Operation is currently running
 209      */
 210     isRunning: function() {
 211         return this.running === true;
 212     },
 213
 214     /**
 215      * Returns true if the Operation has been completed
 216      * @return {Boolean} True if the Operation is complete
 217      */
 218     isComplete: function() {
 219         return this.complete === true;
 220     },
 221
 222     /**
 223      * Returns true if the Operation has completed and was successful
 224      * @return {Boolean} True if successful
 225      */
 226     wasSuccessful: function() {
 227         return this.isComplete() && this.success === true;
 228     },
 229
 230     /**
 231      * @private
 232      * Associates this Operation with a Batch
 233      * @param {Ext.data.Batch} batch The batch
 234      */
 235     setBatch: function(batch) {
 236         this.batch = batch;
 237     },
 238
 239     /**
 240      * Checks whether this operation should cause writing to occur.
 241      * @return {Boolean} Whether the operation should cause a write to occur.
 242      */
 243     allowWrite: function() {
 244         return this.action != 'read';
 245     }
 246 });