Batches

A batch accumulates and packages multiple operations (method calls) on objects. The batch is then run in a single operation.

Because a batch can significantly improve performance, consider creating a batch when application logic lends itself to running a series of operations that can be completed without application intervention between batch items. For example, an application might create a Folder object, create a Document object, and create a DynamicReferentialContainmentRelationship object for filing a document in a folder, all associated with a single UpdatingBatch object. The Content Engine server updates the objects in the same order as they appear in the list that is associated with the UpdatingBatch object. Batch processing is suitable for retrieving property values for multiple objects by using a RetrievingBatch object. Properties to be fetched are specified independently for each object, and all of the property fetches are run 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 run transactionally. IndependentlyPersistableObject references are accumulated, and an instance of the UpdatingBatch class is run 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 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 instance is run within a transaction, and the server-side metadata cache is not reloaded within a 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 run transactionally. IndependentObject references are accumulated, and each included object is either refreshed (retrieved) or receives its own exception. For single-operation object saves and retrievals, any changes to the retrieved objects are done in place, so that the existing IndependentObject references continue to be valid and reflect the changes.