/*
|
This file is part of Ext JS 4.2
|
|
Copyright (c) 2011-2013 Sencha Inc
|
|
Contact: http://www.sencha.com/contact
|
|
GNU General Public License Usage
|
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.
|
|
If you are unsure which license is appropriate for your use, please contact the sales department
|
at http://www.sencha.com/contact.
|
|
Build date: 2013-05-16 14:36:50 (f9be68accb407158ba2b1be2c226a6ce1f649314)
|
*/
|
/**
|
* @author Ed Spencer
|
* @class Ext.data.Batch
|
*
|
* <p>Provides a mechanism to run one or more {@link Ext.data.Operation operations} in a given order. Fires the 'operationcomplete' event
|
* after the completion of each Operation, and the 'complete' event when all Operations have been successfully executed. Fires an 'exception'
|
* event if any of the Operations encounter an exception.</p>
|
*
|
* <p>Usually these are only used internally by {@link Ext.data.proxy.Proxy} classes</p>
|
*
|
*/
|
Ext.define('Ext.data.Batch', {
|
mixins: {
|
observable: 'Ext.util.Observable'
|
},
|
|
/**
|
* @cfg {Boolean} autoStart
|
* True to immediately start processing the batch as soon as it is constructed (defaults to false)
|
*/
|
autoStart: false,
|
|
/**
|
* @cfg {Boolean} pauseOnException
|
* True to pause the execution of the batch if any operation encounters an exception
|
* (defaults to false). If you set this to true you are responsible for implementing the appropriate
|
* handling logic and restarting or discarding the batch as needed. There are different ways you could
|
* do this, e.g. by handling the batch's {@link #exception} event directly, or perhaps by overriding
|
* {@link Ext.data.AbstractStore#onBatchException onBatchException} at the store level. If you do pause
|
* and attempt to handle the exception you can call {@link #retry} to process the same operation again.
|
*
|
* Note that {@link Ext.data.Operation operations} are atomic, so any operations that may have succeeded
|
* prior to an exception (and up until pausing the batch) will be finalized at the server level and will
|
* not be automatically reversible. Any transactional / rollback behavior that might be desired would have
|
* to be implemented at the application level. Pausing on exception will likely be most beneficial when
|
* used in coordination with such a scheme, where an exception might actually affect subsequent operations
|
* in the same batch and so should be handled before continuing with the next operation.
|
*
|
* If you have not implemented transactional operation handling then this option should typically be left
|
* to the default of false (e.g. process as many operations as possible, and handle any exceptions
|
* asynchronously without holding up the rest of the batch).
|
*/
|
pauseOnException: false,
|
|
/**
|
* @property {Number} current
|
* The index of the current operation being executed. Read only
|
*/
|
current: -1,
|
|
/**
|
* @property {Number} total
|
* The total number of operations in this batch. Read only
|
*/
|
total: 0,
|
|
/**
|
* @property {Boolean} isRunning
|
* True if the batch is currently running. Read only
|
*/
|
isRunning: false,
|
|
/**
|
* @property {Boolean} isComplete
|
* True if this batch has been executed completely. Read only
|
*/
|
isComplete: false,
|
|
/**
|
* @property {Boolean} hasException
|
* True if this batch has encountered an exception. This is cleared at the start of each operation. Read only
|
*/
|
hasException: false,
|
|
/**
|
* Creates new Batch object.
|
* @param {Object} [config] Config object
|
*/
|
constructor: function(config) {
|
var me = this;
|
|
/**
|
* @event complete
|
* Fired when all operations of this batch have been completed
|
* @param {Ext.data.Batch} batch The batch object
|
* @param {Object} operation The last operation that was executed
|
*/
|
|
/**
|
* @event exception
|
* Fired when a operation encountered an exception
|
* @param {Ext.data.Batch} batch The batch object
|
* @param {Object} operation The operation that encountered the exception
|
*/
|
|
/**
|
* @event operationcomplete
|
* Fired when each operation of the batch completes
|
* @param {Ext.data.Batch} batch The batch object
|
* @param {Object} operation The operation that just completed
|
*/
|
|
me.mixins.observable.constructor.call(me, config);
|
|
/**
|
* Ordered array of operations that will be executed by this batch
|
* @property {Ext.data.Operation[]} operations
|
*/
|
me.operations = [];
|
|
/**
|
* Ordered array of operations that raised an exception during the most recent
|
* batch execution and did not successfully complete
|
* @property {Ext.data.Operation[]} exceptions
|
*/
|
me.exceptions = [];
|
},
|
|
/**
|
* Adds a new operation to this batch at the end of the {@link #operations} array
|
* @param {Object} operation The {@link Ext.data.Operation Operation} object
|
* @return {Ext.data.Batch} this
|
*/
|
add: function(operation) {
|
this.total++;
|
|
operation.setBatch(this);
|
|
this.operations.push(operation);
|
|
return this;
|
},
|
|
/**
|
* Kicks off execution of the batch, continuing from the next operation if the previous
|
* operation encountered an exception, or if execution was paused. Use this method to start
|
* the batch for the first time or to restart a paused batch by skipping the current
|
* unsuccessful operation.
|
*
|
* To retry processing the current operation before continuing to the rest of the batch (e.g.
|
* because you explicitly handled the operation's exception), call {@link #retry} instead.
|
*
|
* Note that if the batch is already running any call to start will be ignored.
|
*
|
* @return {Ext.data.Batch} this
|
*/
|
start: function(/* private */ index) {
|
var me = this;
|
|
if (me.isRunning) {
|
return me;
|
}
|
|
me.exceptions.length = 0;
|
me.hasException = false;
|
me.isRunning = true;
|
|
return me.runOperation(Ext.isDefined(index) ? index : me.current + 1);
|
},
|
|
/**
|
* Kicks off execution of the batch, continuing from the current operation. This is intended
|
* for restarting a {@link #pause paused} batch after an exception, and the operation that raised
|
* the exception will now be retried. The batch will then continue with its normal processing until
|
* all operations are complete or another exception is encountered.
|
*
|
* Note that if the batch is already running any call to retry will be ignored.
|
*
|
* @return {Ext.data.Batch} this
|
*/
|
retry: function() {
|
return this.start(this.current);
|
},
|
|
/**
|
* @private
|
* Runs the next operation, relative to this.current.
|
* @return {Ext.data.Batch} this
|
*/
|
runNextOperation: function() {
|
return this.runOperation(this.current + 1);
|
},
|
|
/**
|
* Pauses execution of the batch, but does not cancel the current operation
|
* @return {Ext.data.Batch} this
|
*/
|
pause: function() {
|
this.isRunning = false;
|
return this;
|
},
|
|
/**
|
* Executes an operation by its numeric index in the {@link #operations} array
|
* @param {Number} index The operation index to run
|
* @return {Ext.data.Batch} this
|
*/
|
runOperation: function(index) {
|
var me = this,
|
operations = me.operations,
|
operation = operations[index],
|
onProxyReturn;
|
|
if (operation === undefined) {
|
me.isRunning = false;
|
me.isComplete = true;
|
me.fireEvent('complete', me, operations[operations.length - 1]);
|
} else {
|
me.current = index;
|
|
onProxyReturn = function(operation) {
|
var hasException = operation.hasException();
|
|
if (hasException) {
|
me.hasException = true;
|
me.exceptions.push(operation);
|
me.fireEvent('exception', me, operation);
|
}
|
|
if (hasException && me.pauseOnException) {
|
me.pause();
|
} else {
|
operation.setCompleted();
|
me.fireEvent('operationcomplete', me, operation);
|
me.runNextOperation();
|
}
|
};
|
|
operation.setStarted();
|
|
me.proxy[operation.action](operation, onProxyReturn, me);
|
}
|
|
return me;
|
}
|
});
|
