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