/ext-4.0.7/src/data/Batch.js

  1/*
  2
  3This file is part of Ext JS 4
  4
  5Copyright (c) 2011 Sencha Inc
  6
  7Contact:  http://www.sencha.com/contact
  8
  9GNU General Public License Usage
 10This 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
 12If 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.Batch
 18 *
 19 * <p>Provides a mechanism to run one or more {@link Ext.data.Operation operations} in a given order. Fires the 'operationcomplete' event
 20 * after the completion of each Operation, and the 'complete' event when all Operations have been successfully executed. Fires an 'exception'
 21 * event if any of the Operations encounter an exception.</p>
 22 *
 23 * <p>Usually these are only used internally by {@link Ext.data.proxy.Proxy} classes</p>
 24 *
 25 */
 26Ext.define('Ext.data.Batch', {
 27    mixins: {
 28        observable: 'Ext.util.Observable'
 29    },
 30
 31    /**
 32     * @property {Boolean} autoStart
 33     * True to immediately start processing the batch as soon as it is constructed.
 34     */
 35    autoStart: false,
 36
 37    /**
 38     * @property {Number} current
 39     * The index of the current operation being executed
 40     */
 41    current: -1,
 42
 43    /**
 44     * @property {Number} total
 45     * The total number of operations in this batch. Read only
 46     */
 47    total: 0,
 48
 49    /**
 50     * @property {Boolean} isRunning
 51     * True if the batch is currently running
 52     */
 53    isRunning: false,
 54
 55    /**
 56     * @property {Boolean} isComplete
 57     * True if this batch has been executed completely
 58     */
 59    isComplete: false,
 60
 61    /**
 62     * @property {Boolean} hasException
 63     * True if this batch has encountered an exception. This is cleared at the start of each operation
 64     */
 65    hasException: false,
 66
 67    /**
 68     * @property {Boolean} pauseOnException
 69     * True to automatically pause the execution of the batch if any operation encounters an exception
 70     */
 71    pauseOnException: true,
 72
 73    /**
 74     * Creates new Batch object.
 75     * @param {Object} [config] Config object
 76     */
 77    constructor: function(config) {
 78        var me = this;
 79
 80        me.addEvents(
 81          /**
 82           * @event complete
 83           * Fired when all operations of this batch have been completed
 84           * @param {Ext.data.Batch} batch The batch object
 85           * @param {Object} operation The last operation that was executed
 86           */
 87          'complete',
 88
 89          /**
 90           * @event exception
 91           * Fired when a operation encountered an exception
 92           * @param {Ext.data.Batch} batch The batch object
 93           * @param {Object} operation The operation that encountered the exception
 94           */
 95          'exception',
 96
 97          /**
 98           * @event operationcomplete
 99           * Fired when each operation of the batch completes
100           * @param {Ext.data.Batch} batch The batch object
101           * @param {Object} operation The operation that just completed
102           */
103          'operationcomplete'
104        );
105
106        me.mixins.observable.constructor.call(me, config);
107
108        /**
109         * Ordered array of operations that will be executed by this batch
110         * @property {Ext.data.Operation[]} operations
111         */
112        me.operations = [];
113    },
114
115    /**
116     * Adds a new operation to this batch
117     * @param {Object} operation The {@link Ext.data.Operation Operation} object
118     */
119    add: function(operation) {
120        this.total++;
121
122        operation.setBatch(this);
123
124        this.operations.push(operation);
125    },
126
127    /**
128     * Kicks off the execution of the batch, continuing from the next operation if the previous
129     * operation encountered an exception, or if execution was paused
130     */
131    start: function() {
132        this.hasException = false;
133        this.isRunning = true;
134
135        this.runNextOperation();
136    },
137
138    /**
139     * @private
140     * Runs the next operation, relative to this.current.
141     */
142    runNextOperation: function() {
143        this.runOperation(this.current + 1);
144    },
145
146    /**
147     * Pauses execution of the batch, but does not cancel the current operation
148     */
149    pause: function() {
150        this.isRunning = false;
151    },
152
153    /**
154     * Executes a operation by its numeric index
155     * @param {Number} index The operation index to run
156     */
157    runOperation: function(index) {
158        var me = this,
159            operations = me.operations,
160            operation  = operations[index],
161            onProxyReturn;
162
163        if (operation === undefined) {
164            me.isRunning  = false;
165            me.isComplete = true;
166            me.fireEvent('complete', me, operations[operations.length - 1]);
167        } else {
168            me.current = index;
169
170            onProxyReturn = function(operation) {
171                var hasException = operation.hasException();
172
173                if (hasException) {
174                    me.hasException = true;
175                    me.fireEvent('exception', me, operation);
176                } else {
177                    me.fireEvent('operationcomplete', me, operation);
178                }
179
180                if (hasException && me.pauseOnException) {
181                    me.pause();
182                } else {
183                    operation.setCompleted();
184                    me.runNextOperation();
185                }
186            };
187
188            operation.setStarted();
189
190            me.proxy[operation.action](operation, onProxyReturn, me);
191        }
192    }
193});