The
Batch defines an ordered list of of operations that must be executed at once on the persistent layer. If any of the modifications added to the batch fails, none of the other changes must be persisted, thus leaving the persistent layer unaffected.
The
Batch object is obtained by calling {@link RepositoryService#createBatch(SessionInfo,ItemId)}. The following methods can then be called on the returned
Batch object to queue the corresponding operations:
- addNode,
- addProperty,
- setValue,
- remove,
- reorderNodes,
- setMixins,
- move
The operations collected in a Batch are persisted upon a sucessful call to {@link RepositoryService#submit(Batch)}. The operations queued in the batch must be validated as a single unit and (if validation succeeds) applied to the persistent layer. If validation fails submitting the
Batch is aborted and an exception is thrown.
The Batch mechanism is required because there are sets of operations for which the following are both true:
- The set can only be validated and put into effect as a single logical unit.
For example, adding mutually referring reference properties. - The set contains operations that can only be validated on the persistent layer.
For example, operations that require a referential integrity check.
In addition the
Batch mechanism is desirable in order to minimize calls to the persistent layer, which enables client-server implementations to reduce the number of network roundtrips.
Since the batch records the delta of pending changes within the scope of an {@link javax.jcr.Item#save()} (or a {@link javax.jcr.Session#save()} it isintended to be constructed upon save (not before) and then submitted to the persistent layer as a single logical operation (see above).
Note however, that methods of the JCR API that have immediate effect on the persistent storage have to call that storage, validate and return. The batch does not play a role in these operations, instead they are covered by the {@link RepositoryService}.