A batch accumulates and packages multiple operations (method calls) on objects. The batch is then executed in a single operation.
A batch can significantly improve performance. You should consider using a batch when application logic lends itself to executing a series of operations that can be completed (or be in progress) independently, without reliance on either the state of another object included in the batch, or the result of another operation in the batch. For example, batch processing is suitable for retrieving some property values for each object in a collection of Document
objects. In this case, all of the property fetches are executed in a single roundtrip to the server.
Each operation included in a batch is referenced as a BatchItemHandle
instance. A batch is a subclass of the Batch
abstract class, and contains the list of BatchItemHandle
instances. Whether a batch is a transactional operation depends on its type:
This type of batch operation creates, updates, and deletes persisted objects, and is executed transactionally. IndependentlyPersistableObject
references are accumulated, and an instance of the UpdatingBatch
class is executed as a single transaction (by calling the updateBatch
method on the instance). The batch execution does not return a value: all of the pending commits must succeed, otherwise all of them will fail (at which point the transaction is rolled back and an exception is thrown).
Note
The following constraint applies to an UpdatingBatch operation: Updates to metadata within a single batch are not available to other batch items within the same batch. An UpdatingBatch
is executed within a transaction, and the server-side metadata cache is not reloaded within a given transaction. The batch operation must be committed before the metadata updates are available.
This type of batch operation retrieves independent objects, and is not executed transactionally. IndependentObject
references are accumulated, and each included object then is either refreshed (retrieved) or gets its own exception. As for single-operation object saves and retrievals, any changes to the retrieved objects are done in place, so the existing IndependentObject
references continue to be valid and reflect the changes.