com.azure.data.tables

Class TableBatch

java.lang.Object

com.azure.data.tables.TableBatch

public final class TableBatch
extends Object

Provides a batch object for asynchronously executing a transaction containing one or more operations on entities within a table in the Azure Tables service. The batch object represents a collection of one or more create, update, upsert, and/or delete operations on entities that share the same partition key within the table. When the batch is executed, all of the operations will be performed as part of a single transaction. As a result, either all operations in the batch will succeed, or if a failure occurs, all operations in the batch will be rolled back. Each operation in a batch must operate on a distinct row key. Attempting to add multiple operations to a batch that share the same row key will cause an exception to be thrown. Instances of this object are obtained by calling the TableClient.createBatch(String) method on a TableClient object.

Method Summary

Modifier and Type	Method and Description
TableBatch	createEntity(TableEntity entity) Inserts an entity into the table.
TableBatch	deleteEntity(String rowKey) Deletes an entity from the table.
TableBatch	deleteEntity(String rowKey, String eTag) Deletes an entity from the table.
List<com.azure.data.tables.implementation.models.BatchOperation>	getOperations() Gets an immutable list containing all operations added to this batch.
List<BatchOperationResponse>	submitTransaction() Executes all operations within The batch inside a transaction.
List<BatchOperationResponse>	submitTransaction(Duration timeout) Executes all operations within The batch inside a transaction.
com.azure.core.http.rest.Response<List<BatchOperationResponse>>	submitTransactionWithResponse(Duration timeout, com.azure.core.util.Context context) Executes all operations within The batch inside a transaction.
TableBatch	updateEntity(TableEntity entity) Updates an existing entity by merging the provided entity with the existing entity.
TableBatch	updateEntity(TableEntity entity, UpdateMode updateMode) Updates an existing entity using the specified update mode.
TableBatch	updateEntity(TableEntity entity, UpdateMode updateMode, boolean ifUnchanged) Updates an existing entity using the specified update mode.
TableBatch	upsertEntity(TableEntity entity) Inserts an entity into the table if it does not exist, or merges the entity with the existing entity otherwise.
TableBatch	upsertEntity(TableEntity entity, UpdateMode updateMode) Inserts an entity into the table if it does not exist, or updates the existing entity using the specified update mode otherwise.

Methods inherited from class java.lang.Object

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

Method Detail

createEntity

public TableBatch createEntity(TableEntity entity)

Inserts an entity into the table.

Parameters:

entity - The entity to insert.

Returns:

The updated TableBatch.

Throws:

IllegalArgumentException - if the entity's partition key does not match the partition key provided when creating this TableBatch object, if the entity's row key is null or empty, or if another operation with the same row key has already been added to the batch.

IllegalStateException - if this method is called after the batch has been submitted.

upsertEntity

public TableBatch upsertEntity(TableEntity entity)

Inserts an entity into the table if it does not exist, or merges the entity with the existing entity otherwise. If no entity exists within the table having the same partition key and row key as the provided entity, it will be inserted. Otherwise, the provided entity's properties will be merged into the existing entity.

Parameters:

entity - The entity to upsert.

Returns:

The updated TableBatch.

Throws:

IllegalArgumentException - if the entity's partition key does not match the partition key provided when creating this TableBatch object, if the entity's row key is null or empty, or if another operation with the same row key has already been added to the batch.

IllegalStateException - if this method is called after the batch has been submitted.

upsertEntity

public TableBatch upsertEntity(TableEntity entity,
                               UpdateMode updateMode)

Inserts an entity into the table if it does not exist, or updates the existing entity using the specified update mode otherwise. If no entity exists within the table having the same partition key and row key as the provided entity, it will be inserted. Otherwise, the existing entity will be updated according to the specified update mode. When the update mode is 'MERGE', the provided entity's properties will be merged into the existing entity. When the update mode is 'REPLACE', the provided entity's properties will completely replace those in the existing entity.

Parameters:

entity - The entity to upsert.

updateMode - The type of update to perform if the entity already exits.

Returns:

The updated TableBatch.

Throws:

IllegalArgumentException - if the entity's partition key does not match the partition key provided when creating this TableBatch object, if the entity's row key is null or empty, or if another operation with the same row key has already been added to the batch.

IllegalStateException - if this method is called after the batch has been submitted.

updateEntity

public TableBatch updateEntity(TableEntity entity)

Updates an existing entity by merging the provided entity with the existing entity.

Parameters:

entity - The entity to update.

Returns:

The updated TableBatch.

Throws:

IllegalArgumentException - if the entity's partition key does not match the partition key provided when creating this TableBatch object, if the entity's row key is null or empty, or if another operation with the same row key has already been added to the batch.

IllegalStateException - if this method is called after the batch has been submitted.

updateEntity

public TableBatch updateEntity(TableEntity entity,
                               UpdateMode updateMode)

Updates an existing entity using the specified update mode. When the update mode is 'MERGE', the provided entity's properties will be merged into the existing entity. When the update mode is 'REPLACE', the provided entity's properties will completely replace those in the existing entity.

Parameters:

entity - The entity to update.

updateMode - The type of update to perform.

Returns:

The updated TableBatch.

Throws:

IllegalArgumentException - if the entity's partition key does not match the partition key provided when creating this TableBatch object, if the entity's row key is null or empty, or if another operation with the same row key has already been added to the batch.

IllegalStateException - if this method is called after the batch has been submitted.

updateEntity

public TableBatch updateEntity(TableEntity entity,
                               UpdateMode updateMode,
                               boolean ifUnchanged)

Updates an existing entity using the specified update mode. When the update mode is 'MERGE', the provided entity's properties will be merged into the existing entity. When the update mode is 'REPLACE', the provided entity's properties will completely replace those in the existing entity.

Parameters:

entity - The entity to update.

updateMode - The type of update to perform.

ifUnchanged - When true, the eTag of the provided entity must match the eTag of the entity in the Table service. If the values do not match, the update will not occur and an exception will be thrown.

Returns:

The updated TableBatch.

Throws:

IllegalArgumentException - if the entity's partition key does not match the partition key provided when creating this TableBatch object, if the entity's row key is null or empty, or if another operation with the same row key has already been added to the batch.

IllegalStateException - if this method is called after the batch has been submitted.

deleteEntity

public TableBatch deleteEntity(String rowKey)

Deletes an entity from the table.

Parameters:

rowKey - The row key of the entity.

Returns:

The updated TableBatch.

Throws:

IllegalArgumentException - if the provided row key is null or empty, or if another operation with the same row key has already been added to the batch.

IllegalStateException - if this method is called after the batch has been submitted.

deleteEntity

public TableBatch deleteEntity(String rowKey,
                               String eTag)

Deletes an entity from the table.

Parameters:

rowKey - The row key of the entity.

eTag - The value to compare with the eTag of the entity in the Tables service. If the values do not match, the delete will not occur and an exception will be thrown.

Returns:

The updated TableBatch.

Throws:

IllegalArgumentException - if the provided row key is null or empty, or if another operation with the same row key has already been added to the batch.

IllegalStateException - if this method is called after the batch has been submitted.

getOperations

public List<com.azure.data.tables.implementation.models.BatchOperation> getOperations()

Gets an immutable list containing all operations added to this batch.

Returns:

An immutable list containing all operations added to this batch.

submitTransaction

public List<BatchOperationResponse> submitTransaction()

Executes all operations within The batch inside a transaction. When the call completes, either all operations in the batch will succeed, or if a failure occurs, all operations in the batch will be rolled back.

Returns:

A list of sub-responses for each operation in the batch.

Throws:

com.azure.data.tables.implementation.models.TableServiceErrorException - if any operation within the batch fails. See the documentation for the client methods in TableClient to understand the conditions that may cause a given operation to fail.

IllegalStateException - if no operations have been added to the batch.

submitTransaction

public List<BatchOperationResponse> submitTransaction(Duration timeout)

Executes all operations within The batch inside a transaction. When the call completes, either all operations in the batch will succeed, or if a failure occurs, all operations in the batch will be rolled back.

Parameters:

timeout - Duration to wait for the operation to complete.

Returns:

A list of sub-responses for each operation in the batch.

Throws:

com.azure.data.tables.implementation.models.TableServiceErrorException - if any operation within the batch fails. See the documentation for the client methods in TableClient to understand the conditions that may cause a given operation to fail.

IllegalStateException - if no operations have been added to the batch.

submitTransactionWithResponse

public com.azure.core.http.rest.Response<List<BatchOperationResponse>> submitTransactionWithResponse(Duration timeout,
                                                                                                     com.azure.core.util.Context context)

Executes all operations within The batch inside a transaction. When the call completes, either all operations in the batch will succeed, or if a failure occurs, all operations in the batch will be rolled back.

Parameters:

timeout - Duration to wait for the operation to complete.

context - Additional context that is passed through the HTTP pipeline during the service call.

Returns:

The HTTP response produced for the batch itself. The response's value will contain a list of sub-responses for each operation in the batch.

Throws:

com.azure.data.tables.implementation.models.TableServiceErrorException - if any operation within the batch fails. See the documentation for the client methods in TableClient to understand the conditions that may cause a given operation to fail.

IllegalStateException - if no operations have been added to the batch.