docs/source/Operation.html

   1 <!DOCTYPE html>
   2 <html>
   3 <head>
   4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   5   <title>The source code</title>
   6   <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
   7   <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   8   <style type="text/css">
   9     .highlight { display: block; background-color: #ddd; }
  10   </style>
  11   <script type="text/javascript">
  12     function highlight() {
  13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
  14     }
  15   </script>
  16 </head>
  17 <body onload="prettyPrint(); highlight();">
  18   <pre class="prettyprint lang-js"><span id='Ext-data-Operation'>/**
  19 </span> * @author Ed Spencer
  20  *
  21  * Represents a single read or write operation performed by a {@link Ext.data.proxy.Proxy Proxy}. Operation objects are
  22  * used to enable communication between Stores and Proxies. Application developers should rarely need to interact with
  23  * Operation objects directly.
  24  *
  25  * Several Operations can be batched together in a {@link Ext.data.Batch batch}.
  26  */
  27 Ext.define('Ext.data.Operation', {
  28 <span id='Ext-data-Operation-cfg-synchronous'>    /**
  29 </span>     * @cfg {Boolean} synchronous
  30      * True if this Operation is to be executed synchronously. This property is inspected by a
  31      * {@link Ext.data.Batch Batch} to see if a series of Operations can be executed in parallel or not.
  32      */
  33     synchronous: true,
  34
  35 <span id='Ext-data-Operation-cfg-action'>    /**
  36 </span>     * @cfg {String} action
  37      * The action being performed by this Operation. Should be one of 'create', 'read', 'update' or 'destroy'.
  38      */
  39     action: undefined,
  40
  41 <span id='Ext-data-Operation-cfg-filters'>    /**
  42 </span>     * @cfg {Ext.util.Filter[]} filters
  43      * Optional array of filter objects. Only applies to 'read' actions.
  44      */
  45     filters: undefined,
  46
  47 <span id='Ext-data-Operation-cfg-sorters'>    /**
  48 </span>     * @cfg {Ext.util.Sorter[]} sorters
  49      * Optional array of sorter objects. Only applies to 'read' actions.
  50      */
  51     sorters: undefined,
  52
  53 <span id='Ext-data-Operation-cfg-group'>    /**
  54 </span>     * @cfg {Ext.util.Grouper} group
  55      * Optional grouping configuration. Only applies to 'read' actions where grouping is desired.
  56      */
  57     group: undefined,
  58
  59 <span id='Ext-data-Operation-cfg-start'>    /**
  60 </span>     * @cfg {Number} start
  61      * The start index (offset), used in paging when running a 'read' action.
  62      */
  63     start: undefined,
  64
  65 <span id='Ext-data-Operation-cfg-limit'>    /**
  66 </span>     * @cfg {Number} limit
  67      * The number of records to load. Used on 'read' actions when paging is being used.
  68      */
  69     limit: undefined,
  70
  71 <span id='Ext-data-Operation-cfg-batch'>    /**
  72 </span>     * @cfg {Ext.data.Batch} batch
  73      * The batch that this Operation is a part of.
  74      */
  75     batch: undefined,
  76
  77 <span id='Ext-data-Operation-cfg-callback'>    /**
  78 </span>     * @cfg {Function} callback
  79      * Function to execute when operation completed.  Will be called with the following parameters:
  80      *
  81      * - records : Array of Ext.data.Model objects.
  82      * - operation : The Ext.data.Operation itself.
  83      * - success : True when operation completed successfully.
  84      */
  85     callback: undefined,
  86
  87 <span id='Ext-data-Operation-cfg-scope'>    /**
  88 </span>     * @cfg {Object} scope
  89      * Scope for the {@link #callback} function.
  90      */
  91     scope: undefined,
  92
  93 <span id='Ext-data-Operation-property-started'>    /**
  94 </span>     * @property {Boolean} started
  95      * Read-only property tracking the start status of this Operation. Use {@link #isStarted}.
  96      * @private
  97      */
  98     started: false,
  99
 100 <span id='Ext-data-Operation-property-running'>    /**
 101 </span>     * @property {Boolean} running
 102      * Read-only property tracking the run status of this Operation. Use {@link #isRunning}.
 103      * @private
 104      */
 105     running: false,
 106
 107 <span id='Ext-data-Operation-property-complete'>    /**
 108 </span>     * @property {Boolean} complete
 109      * Read-only property tracking the completion status of this Operation. Use {@link #isComplete}.
 110      * @private
 111      */
 112     complete: false,
 113
 114 <span id='Ext-data-Operation-property-success'>    /**
 115 </span>     * @property {Boolean} success
 116      * Read-only property tracking whether the Operation was successful or not. This starts as undefined and is set to true
 117      * or false by the Proxy that is executing the Operation. It is also set to false by {@link #setException}. Use
 118      * {@link #wasSuccessful} to query success status.
 119      * @private
 120      */
 121     success: undefined,
 122
 123 <span id='Ext-data-Operation-property-exception'>    /**
 124 </span>     * @property {Boolean} exception
 125      * Read-only property tracking the exception status of this Operation. Use {@link #hasException} and see {@link #getError}.
 126      * @private
 127      */
 128     exception: false,
 129
 130 <span id='Ext-data-Operation-property-error'>    /**
 131 </span>     * @property {String/Object} error
 132      * The error object passed when {@link #setException} was called. This could be any object or primitive.
 133      * @private
 134      */
 135     error: undefined,
 136
 137 <span id='Ext-data-Operation-property-actionCommitRecordsRe'>    /**
 138 </span>     * @property {RegExp} actionCommitRecordsRe
 139      * The RegExp used to categorize actions that require record commits.
 140      */
 141     actionCommitRecordsRe: /^(?:create|update)$/i,
 142
 143 <span id='Ext-data-Operation-property-actionSkipSyncRe'>    /**
 144 </span>     * @property {RegExp} actionSkipSyncRe
 145      * The RegExp used to categorize actions that skip local record synchronization. This defaults
 146      * to match 'destroy'.
 147      */
 148     actionSkipSyncRe: /^destroy$/i,
 149
 150 <span id='Ext-data-Operation-method-constructor'>    /**
 151 </span>     * Creates new Operation object.
 152      * @param {Object} config (optional) Config object.
 153      */
 154     constructor: function(config) {
 155         Ext.apply(this, config || {});
 156     },
 157
 158 <span id='Ext-data-Operation-method-commitRecords'>    /**
 159 </span>     * This method is called to commit data to this instance's records given the records in
 160      * the server response. This is followed by calling {@link Ext.data.Model#commit} on all
 161      * those records (for 'create' and 'update' actions).
 162      *
 163      * If this {@link #action} is 'destroy', any server records are ignored and the
 164      * {@link Ext.data.Model#commit} method is not called.
 165      *
 166      * @param {Ext.data.Model[]} serverRecords An array of {@link Ext.data.Model} objects returned by
 167      * the server.
 168      * @markdown
 169      */
 170     commitRecords: function (serverRecords) {
 171         var me = this,
 172             mc, index, clientRecords, serverRec, clientRec;
 173
 174         if (!me.actionSkipSyncRe.test(me.action)) {
 175             clientRecords = me.records;
 176
 177             if (clientRecords &amp;&amp; clientRecords.length) {
 178                 mc = Ext.create('Ext.util.MixedCollection', true, function(r) {return r.getId();});
 179                 mc.addAll(clientRecords);
 180
 181                 for (index = serverRecords ? serverRecords.length : 0; index--; ) {
 182                     serverRec = serverRecords[index];
 183                     clientRec = mc.get(serverRec.getId());
 184
 185                     if (clientRec) {
 186                         clientRec.beginEdit();
 187                         clientRec.set(serverRec.data);
 188                         clientRec.endEdit(true);
 189                     }
 190                 }
 191
 192                 if (me.actionCommitRecordsRe.test(me.action)) {
 193                     for (index = clientRecords.length; index--; ) {
 194                         clientRecords[index].commit();
 195                     }
 196                 }
 197             }
 198         }
 199     },
 200
 201 <span id='Ext-data-Operation-method-setStarted'>    /**
 202 </span>     * Marks the Operation as started.
 203      */
 204     setStarted: function() {
 205         this.started = true;
 206         this.running = true;
 207     },
 208
 209 <span id='Ext-data-Operation-method-setCompleted'>    /**
 210 </span>     * Marks the Operation as completed.
 211      */
 212     setCompleted: function() {
 213         this.complete = true;
 214         this.running  = false;
 215     },
 216
 217 <span id='Ext-data-Operation-method-setSuccessful'>    /**
 218 </span>     * Marks the Operation as successful.
 219      */
 220     setSuccessful: function() {
 221         this.success = true;
 222     },
 223
 224 <span id='Ext-data-Operation-method-setException'>    /**
 225 </span>     * Marks the Operation as having experienced an exception. Can be supplied with an option error message/object.
 226      * @param {String/Object} error (optional) error string/object
 227      */
 228     setException: function(error) {
 229         this.exception = true;
 230         this.success = false;
 231         this.running = false;
 232         this.error = error;
 233     },
 234
 235 <span id='Ext-data-Operation-method-hasException'>    /**
 236 </span>     * Returns true if this Operation encountered an exception (see also {@link #getError})
 237      * @return {Boolean} True if there was an exception
 238      */
 239     hasException: function() {
 240         return this.exception === true;
 241     },
 242
 243 <span id='Ext-data-Operation-method-getError'>    /**
 244 </span>     * Returns the error string or object that was set using {@link #setException}
 245      * @return {String/Object} The error object
 246      */
 247     getError: function() {
 248         return this.error;
 249     },
 250
 251 <span id='Ext-data-Operation-method-getRecords'>    /**
 252 </span>     * Returns an array of Ext.data.Model instances as set by the Proxy.
 253      * @return {Ext.data.Model[]} Any loaded Records
 254      */
 255     getRecords: function() {
 256         var resultSet = this.getResultSet();
 257
 258         return (resultSet === undefined ? this.records : resultSet.records);
 259     },
 260
 261 <span id='Ext-data-Operation-method-getResultSet'>    /**
 262 </span>     * Returns the ResultSet object (if set by the Proxy). This object will contain the {@link Ext.data.Model model}
 263      * instances as well as meta data such as number of instances fetched, number available etc
 264      * @return {Ext.data.ResultSet} The ResultSet object
 265      */
 266     getResultSet: function() {
 267         return this.resultSet;
 268     },
 269
 270 <span id='Ext-data-Operation-method-isStarted'>    /**
 271 </span>     * Returns true if the Operation has been started. Note that the Operation may have started AND completed, see
 272      * {@link #isRunning} to test if the Operation is currently running.
 273      * @return {Boolean} True if the Operation has started
 274      */
 275     isStarted: function() {
 276         return this.started === true;
 277     },
 278
 279 <span id='Ext-data-Operation-method-isRunning'>    /**
 280 </span>     * Returns true if the Operation has been started but has not yet completed.
 281      * @return {Boolean} True if the Operation is currently running
 282      */
 283     isRunning: function() {
 284         return this.running === true;
 285     },
 286
 287 <span id='Ext-data-Operation-method-isComplete'>    /**
 288 </span>     * Returns true if the Operation has been completed
 289      * @return {Boolean} True if the Operation is complete
 290      */
 291     isComplete: function() {
 292         return this.complete === true;
 293     },
 294
 295 <span id='Ext-data-Operation-method-wasSuccessful'>    /**
 296 </span>     * Returns true if the Operation has completed and was successful
 297      * @return {Boolean} True if successful
 298      */
 299     wasSuccessful: function() {
 300         return this.isComplete() &amp;&amp; this.success === true;
 301     },
 302
 303 <span id='Ext-data-Operation-method-setBatch'>    /**
 304 </span>     * @private
 305      * Associates this Operation with a Batch
 306      * @param {Ext.data.Batch} batch The batch
 307      */
 308     setBatch: function(batch) {
 309         this.batch = batch;
 310     },
 311
 312 <span id='Ext-data-Operation-method-allowWrite'>    /**
 313 </span>     * Checks whether this operation should cause writing to occur.
 314      * @return {Boolean} Whether the operation should cause a write to occur.
 315      */
 316     allowWrite: function() {
 317         return this.action != 'read';
 318     }
 319 });</pre>
 320 </body>
 321 </html>