com.azure.cosmos

Class TransactionalBatch

java.lang.Object

com.azure.cosmos.TransactionalBatch

@Beta(value=V4_7_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public final class TransactionalBatch
extends Object

Represents a batch of operations against items with the same PartitionKey in a container that will be performed in a transactional manner at the Azure Cosmos DB service.

Use TransactionalBatch.createTransactionalBatch(PartitionKey) to create an instance of TransactionalBatch. Example This example atomically modifies a set of items as a batch.

 public class ToDoActivity {
     public final String type;
     public final String id;
     public final String status;
     public ToDoActivity(String type, String id, String status) {
         this.type = type;
         this.id = id;
         this.status = status;
     }
 }

 String activityType = "personal";

 ToDoActivity test1 = new ToDoActivity(activityType, "learning", "ToBeDone");
 ToDoActivity test2 = new ToDoActivity(activityType, "shopping", "Done");
 ToDoActivity test3 = new ToDoActivity(activityType, "swimming", "ToBeDone");

 TransactionalBatch batch = TransactionalBatch.createTransactionalBatch(new Cosmos.PartitionKey(activityType));
 batch.createItemOperation<ToDoActivity>(test1);
 batch.replaceItemOperation<ToDoActivity>(test2.id, test2);
 batch.upsertItemOperation<ToDoActivity>(test3);
 batch.deleteItemOperation("reading");

 TransactionalBatchResponse response = container.executeTransactionalBatch(batch);

 if (!response.isSuccessStatusCode()) {
      // Handle and log exception
      return;
 }

 // Look up interested results - e.g., via typed access on operation results

 TransactionalBatchOperationResult result = response.get(0);
 ToDoActivity readActivity = result.getItem(ToDoActivity.class);

 

Example

This example atomically reads a set of items as a batch.

 String activityType = "personal";

 TransactionalBatch batch = TransactionalBatch.createTransactionalBatch(new Cosmos.PartitionKey(activityType));
 batch.readItemOperation("playing");
 batch.readItemOperation("walking");
 batch.readItemOperation("jogging");
 batch.readItemOperation("running");

 TransactionalBatchResponse response = container.executeTransactionalBatch(batch);
 List<ToDoActivity> resultItems = new ArrayList<ToDoActivity>();

 for (int i = 0; i < response.size(); i++) {
     TransactionalBatchOperationResult result = response.get(0);
     resultItems.add(result.getItem(ToDoActivity.class));
 }

 

See: Limits on TransactionalBatch requests.

Method Summary

Modifier and Type	Method and Description
<T> CosmosItemOperation	createItemOperation(T item) Adds an operation to create an item into the batch.
<T> CosmosItemOperation	createItemOperation(T item, TransactionalBatchItemRequestOptions requestOptions) Adds an operation to create an item into the batch.
static TransactionalBatch	createTransactionalBatch(PartitionKey partitionKey) Initializes a new instance of TransactionalBatch that will contain operations to be performed across multiple items in the container with the provided partition key in a transactional manner
CosmosItemOperation	deleteItemOperation(String id) Adds an operation to delete an item into the batch.
CosmosItemOperation	deleteItemOperation(String id, TransactionalBatchItemRequestOptions requestOptions) Adds an operation to delete an item into the batch.
List<CosmosItemOperation>	getOperations() Return the list of operation in an unmodifiable instance so no one can change it in the down path.
PartitionKey	getPartitionKeyValue() Return the partition key for this batch.
CosmosItemOperation	patchItemOperation(String id, CosmosPatchOperations cosmosPatchOperations) Adds a patch operations for an item into the batch.
CosmosItemOperation	patchItemOperation(String id, CosmosPatchOperations cosmosPatchOperations, TransactionalBatchPatchItemRequestOptions requestOptions) Adds a patch operations for an item into the batch.
CosmosItemOperation	readItemOperation(String id) Adds an operation to read an item into the batch.
CosmosItemOperation	readItemOperation(String id, TransactionalBatchItemRequestOptions requestOptions) Adds an operation to read an item into the batch.
<T> CosmosItemOperation	replaceItemOperation(String id, T item) Adds an operation to replace an item into the batch.
<T> CosmosItemOperation	replaceItemOperation(String id, T item, TransactionalBatchItemRequestOptions requestOptions) Adds an operation to replace an item into the batch.
<T> CosmosItemOperation	upsertItemOperation(T item) Adds an operation to upsert an item into the batch.
<T> CosmosItemOperation	upsertItemOperation(T item, TransactionalBatchItemRequestOptions requestOptions) Adds an operation to upsert an item into the batch.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

createTransactionalBatch

@Beta(value=V4_7_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public static TransactionalBatch createTransactionalBatch(PartitionKey partitionKey)

Initializes a new instance of TransactionalBatch that will contain operations to be performed across multiple items in the container with the provided partition key in a transactional manner

Parameters:

partitionKey - the partition key for all items in the batch.

Returns:

A new instance of TransactionalBatch.

createItemOperation

@Beta(value=V4_7_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public <T> CosmosItemOperation createItemOperation(T item)

Adds an operation to create an item into the batch.

Type Parameters:

T - The type of item to be created.

Parameters:

item - A JSON serializable object that must contain an id property.

Returns:

The transactional batch instance with the operation added.

createItemOperation

@Beta(value=V4_7_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public <T> CosmosItemOperation createItemOperation(T item,
                                                                                                                                                            TransactionalBatchItemRequestOptions requestOptions)

Adds an operation to create an item into the batch.

Type Parameters:

T - The type of item to be created.

Parameters:

item - A JSON serializable object that must contain an id property.

requestOptions - The options for the item request.

Returns:

The transactional batch instance with the operation added.

deleteItemOperation

@Beta(value=V4_7_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public CosmosItemOperation deleteItemOperation(String id)

Adds an operation to delete an item into the batch.

Parameters:

id - The unique id of the item.

Returns:

The transactional batch instance with the operation added.

deleteItemOperation

@Beta(value=V4_7_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public CosmosItemOperation deleteItemOperation(String id,
                                                                                                                                                        TransactionalBatchItemRequestOptions requestOptions)

Adds an operation to delete an item into the batch.

Parameters:

id - The unique id of the item.

requestOptions - The options for the item request.

Returns:

The transactional batch instance with the operation added.

readItemOperation

@Beta(value=V4_7_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public CosmosItemOperation readItemOperation(String id)

Adds an operation to read an item into the batch.

Parameters:

id - The unique id of the item.

Returns:

The transactional batch instance with the operation added.

readItemOperation

@Beta(value=V4_7_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public CosmosItemOperation readItemOperation(String id,
                                                                                                                                                      TransactionalBatchItemRequestOptions requestOptions)

Adds an operation to read an item into the batch.

Parameters:

id - The unique id of the item.

requestOptions - The options for the item request.

Returns:

The transactional batch instance with the operation added.

replaceItemOperation

@Beta(value=V4_7_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public <T> CosmosItemOperation replaceItemOperation(String id,
                                                                                                                                                             T item)

Adds an operation to replace an item into the batch.

Type Parameters:

T - The type of item to be replaced.

Parameters:

id - The unique id of the item.

item - A JSON serializable object that must contain an id property.

Returns:

The transactional batch instance with the operation added.

replaceItemOperation

@Beta(value=V4_7_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public <T> CosmosItemOperation replaceItemOperation(String id,
                                                                                                                                                             T item,
                                                                                                                                                             TransactionalBatchItemRequestOptions requestOptions)

Adds an operation to replace an item into the batch.

Type Parameters:

T - The type of item to be replaced.

Parameters:

id - The unique id of the item.

item - A JSON serializable object that must contain an id property.

requestOptions - The options for the item request.

Returns:

The transactional batch instance with the operation added.

upsertItemOperation

@Beta(value=V4_7_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public <T> CosmosItemOperation upsertItemOperation(T item)

Adds an operation to upsert an item into the batch.

Type Parameters:

T - The type of item to be upserted.

Parameters:

item - A JSON serializable object that must contain an id property.

Returns:

The transactional batch instance with the operation added.

upsertItemOperation

@Beta(value=V4_7_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public <T> CosmosItemOperation upsertItemOperation(T item,
                                                                                                                                                            TransactionalBatchItemRequestOptions requestOptions)

Adds an operation to upsert an item into the batch.

Type Parameters:

T - The type of item to be upserted.

Parameters:

item - A JSON serializable object that must contain an id property.

requestOptions - The options for the item request.

Returns:

The transactional batch instance with the operation added.

patchItemOperation

@Beta(value=V4_11_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public CosmosItemOperation patchItemOperation(String id,
                                                                                                                                                        CosmosPatchOperations cosmosPatchOperations)

Adds a patch operations for an item into the batch.

Parameters:

id - the item id.

cosmosPatchOperations - Represents a container having list of operations to be sequentially applied to the referred Cosmos item.

Returns:

The added operation.

patchItemOperation

@Beta(value=V4_11_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public CosmosItemOperation patchItemOperation(String id,
                                                                                                                                                        CosmosPatchOperations cosmosPatchOperations,
                                                                                                                                                        TransactionalBatchPatchItemRequestOptions requestOptions)

Adds a patch operations for an item into the batch.

Parameters:

id - the item id.

cosmosPatchOperations - Represents a container having list of operations to be sequentially applied to the referred Cosmos item.

requestOptions - The options for the item request.

Returns:

The added operation.

getOperations

@Beta(value=V4_7_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public List<CosmosItemOperation> getOperations()

Return the list of operation in an unmodifiable instance so no one can change it in the down path.

Returns:

The list of operations which are to be executed.

getPartitionKeyValue

@Beta(value=V4_7_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public PartitionKey getPartitionKeyValue()

Return the partition key for this batch.

Returns:

The partition key for this batch.