Batches

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. Consider using a batch when application logic lends itself to executing a series of operations that can be completed without application intervention between batch items. For example, an application could create a Folder, create a Document, and create a DynamicReferentialContainmentRelationship object for filing the Document in the Folder, all within a single UpdatingBatch. The Content Engine server performs updates to the objects in the same order as they appear in an UpdatingBatch. Batch processing is suitable for retrieving property values for multiple objects via a RetrievingBatch. In that case, properties to be fetched are specified independently for each object, and all of the property fetches are executed in a single round trip 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:

• UpdatingBatch Operation

  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.

• Batch Retrievals

  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.