com.azure.storage.blob

Class BlockBlobClient

java.lang.Object

com.azure.storage.blob.BlobClient

com.azure.storage.blob.BlockBlobClient

public final class BlockBlobClient
extends BlobClient

Client to a block blob. It may only be instantiated through a BlobClientBuilder, via the method BlobClient.asBlockBlobClient(), or via the method ContainerClient.getBlockBlobClient(String). This class does not hold any state about a particular blob, but is instead a convenient way of sending appropriate requests to the resource on the service.

This client contains operations on a blob. Operations on a container are available on ContainerClient, and operations on the service are available on BlobServiceClient.

Please refer to the Azure Docs for more information.

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAX_BLOCKS Indicates the maximum number of blocks allowed in a block blob.
static int	MAX_STAGE_BLOCK_BYTES Indicates the maximum number of bytes that can be sent in a call to stageBlock.
static int	MAX_UPLOAD_BLOB_BYTES Indicates the maximum number of bytes that can be sent in a call to upload.

Method Summary

Modifier and Type	Method and Description
BlockBlobItem	commitBlockList(java.util.List<java.lang.String> base64BlockIDs) Writes a blob by specifying the list of block IDs that are to make up the blob.
Response<BlockBlobItem>	commitBlockListWithResponse(java.util.List<java.lang.String> base64BlockIDs, BlobHTTPHeaders headers, Metadata metadata, AccessTier tier, BlobAccessConditions accessConditions, java.time.Duration timeout, Context context) Writes a blob by specifying the list of block IDs that are to make up the blob.
BlobOutputStream	getBlobOutputStream() Creates and opens an output stream to write data to the block blob.
BlobOutputStream	getBlobOutputStream(BlobAccessConditions accessConditions) Creates and opens an output stream to write data to the block blob.
BlockList	listBlocks(BlockListType listType) Returns the list of blocks that have been uploaded as part of a block blob using the specified block list filter.
Response<BlockList>	listBlocksWithResponse(BlockListType listType, LeaseAccessConditions leaseAccessConditions, java.time.Duration timeout, Context context) Returns the list of blocks that have been uploaded as part of a block blob using the specified block list filter.
void	stageBlock(java.lang.String base64BlockID, java.io.InputStream data, long length) Uploads the specified block to the block blob's "staging area" to be later committed by a call to commitBlockList.
void	stageBlockFromURL(java.lang.String base64BlockID, java.net.URL sourceURL, BlobRange sourceRange) Creates a new block to be committed as part of a blob where the contents are read from a URL.
VoidResponse	stageBlockFromURLWithResponse(java.lang.String base64BlockID, java.net.URL sourceURL, BlobRange sourceRange, byte[] sourceContentMD5, LeaseAccessConditions leaseAccessConditions, SourceModifiedAccessConditions sourceModifiedAccessConditions, java.time.Duration timeout, Context context) Creates a new block to be committed as part of a blob where the contents are read from a URL.
VoidResponse	stageBlockWithResponse(java.lang.String base64BlockID, java.io.InputStream data, long length, LeaseAccessConditions leaseAccessConditions, java.time.Duration timeout, Context context) Uploads the specified block to the block blob's "staging area" to be later committed by a call to commitBlockList.
BlockBlobItem	upload(java.io.InputStream data, long length) Creates a new block blob, or updates the content of an existing block blob.
void	uploadFromFile(java.lang.String filePath) Creates a new block blob, or updates the content of an existing block blob.
void	uploadFromFile(java.lang.String filePath, BlobHTTPHeaders headers, Metadata metadata, AccessTier tier, BlobAccessConditions accessConditions, java.time.Duration timeout) Creates a new block blob, or updates the content of an existing block blob.
Response<BlockBlobItem>	uploadWithResponse(java.io.InputStream data, long length, BlobHTTPHeaders headers, Metadata metadata, AccessTier tier, BlobAccessConditions accessConditions, java.time.Duration timeout, Context context) Creates a new block blob, or updates the content of an existing block blob.

Methods inherited from class com.azure.storage.blob.BlobClient

abortCopyFromURL, abortCopyFromURLWithResponse, asAppendBlobClient, asBlockBlobClient, asPageBlobClient, copyFromURL, copyFromURLWithResponse, createSnapshot, createSnapshotWithResponse, delete, deleteWithResponse, download, downloadToFile, downloadToFile, downloadWithResponse, exists, existsWithResponse, generateSAS, generateSAS, generateSAS, generateSAS, generateUserDelegationSAS, generateUserDelegationSAS, generateUserDelegationSAS, getAccountInfo, getAccountInfoWithResponse, getBlobUrl, getContainerClient, getHttpPipeline, getProperties, getPropertiesWithResponse, getSnapshotClient, getSnapshotId, isSnapshot, openInputStream, openInputStream, setHTTPHeaders, setHTTPHeadersWithResponse, setMetadata, setMetadataWithResponse, setTier, setTierWithResponse, startCopyFromURL, startCopyFromURLWithResponse, undelete, undeleteWithResponse

Methods inherited from class java.lang.Object

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

Field Detail

MAX_UPLOAD_BLOB_BYTES

public static final int MAX_UPLOAD_BLOB_BYTES

Indicates the maximum number of bytes that can be sent in a call to upload.

See Also:

Constant Field Values

MAX_STAGE_BLOCK_BYTES

public static final int MAX_STAGE_BLOCK_BYTES

Indicates the maximum number of bytes that can be sent in a call to stageBlock.

See Also:

Constant Field Values

MAX_BLOCKS

public static final int MAX_BLOCKS

Indicates the maximum number of blocks allowed in a block blob.

See Also:

Constant Field Values

Method Detail

getBlobOutputStream

public BlobOutputStream getBlobOutputStream()

Creates and opens an output stream to write data to the block blob. If the blob already exists on the service, it will be overwritten.

Returns:

A BlobOutputStream object used to write data to the blob.

Throws:

StorageException - If a storage service error occurred.

getBlobOutputStream

public BlobOutputStream getBlobOutputStream(BlobAccessConditions accessConditions)

Creates and opens an output stream to write data to the block blob. If the blob already exists on the service, it will be overwritten.

Parameters:

accessConditions - A BlobAccessConditions object that represents the access conditions for the blob.

Returns:

A BlobOutputStream object used to write data to the blob.

Throws:

StorageException - If a storage service error occurred.

upload

public BlockBlobItem upload(java.io.InputStream data,
                            long length)
                     throws java.io.IOException

Creates a new block blob, or updates the content of an existing block blob. Updating an existing block blob overwrites any existing metadata on the blob. Partial updates are not supported with PutBlob; the content of the existing blob is overwritten with the new content. To perform a partial update of a block blob's, use PutBlock and PutBlockList. For more information, see the Azure Docs.

Code Samples

System.out.printf("Uploaded BlockBlob MD5 is %s%n",
    Base64.getEncoder().encodeToString(client.upload(data, length).getContentMD5()));

Parameters:

data - The data to write to the blob.

length - The exact length of the data. It is important that this value match precisely the length of the data provided in the InputStream.

Returns:

The information of the uploaded block blob.

Throws:

java.io.IOException - If an I/O error occurs

uploadWithResponse

public Response<BlockBlobItem> uploadWithResponse(java.io.InputStream data,
                                                  long length,
                                                  BlobHTTPHeaders headers,
                                                  Metadata metadata,
                                                  AccessTier tier,
                                                  BlobAccessConditions accessConditions,
                                                  java.time.Duration timeout,
                                                  Context context)
                                           throws java.io.IOException

Creates a new block blob, or updates the content of an existing block blob. Updating an existing block blob overwrites any existing metadata on the blob. Partial updates are not supported with PutBlob; the content of the existing blob is overwritten with the new content. To perform a partial update of a block blob's, use PutBlock and PutBlockList. For more information, see the Azure Docs.

Code Samples

BlobHTTPHeaders headers = new BlobHTTPHeaders()
    .setBlobContentMD5("data".getBytes(StandardCharsets.UTF_8))
    .setBlobContentLanguage("en-US")
    .setBlobContentType("binary");

Metadata metadata = new Metadata(Collections.singletonMap("metadata", "value"));
BlobAccessConditions accessConditions = new BlobAccessConditions()
    .setLeaseAccessConditions(new LeaseAccessConditions().setLeaseId(leaseId))
    .setModifiedAccessConditions(new ModifiedAccessConditions()
        .setIfUnmodifiedSince(OffsetDateTime.now().minusDays(3)));
Context context = new Context("key", "value");

System.out.printf("Uploaded BlockBlob MD5 is %s%n", Base64.getEncoder()
    .encodeToString(client.uploadWithResponse(data, length, headers, metadata, AccessTier.HOT,
        accessConditions, timeout, context)
        .getValue()
        .getContentMD5()));

Parameters:

data - The data to write to the blob.

length - The exact length of the data. It is important that this value match precisely the length of the data provided in the InputStream.

headers - BlobHTTPHeaders

metadata - Metadata

tier - AccessTier for the destination blob.

accessConditions - BlobAccessConditions

timeout - An optional timeout value beyond which a RuntimeException will be raised.

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

Returns:

The information of the uploaded block blob.

Throws:

UnexpectedLengthException - when the length of data does not match the input length.

java.lang.NullPointerException - if the input data is null.

java.io.IOException - If an I/O error occurs

uploadFromFile

public void uploadFromFile(java.lang.String filePath)
                    throws java.io.IOException

Creates a new block blob, or updates the content of an existing block blob.

Code Samples

try {
    client.uploadFromFile(filePath);
    System.out.println("Upload from file succeeded");
} catch (UncheckedIOException ex) {
    System.err.printf("Failed to upload from file %s%n", ex.getMessage());
}

Parameters:

filePath - Path of the file to upload

Throws:

java.io.IOException - If an I/O error occurs

uploadFromFile

public void uploadFromFile(java.lang.String filePath,
                           BlobHTTPHeaders headers,
                           Metadata metadata,
                           AccessTier tier,
                           BlobAccessConditions accessConditions,
                           java.time.Duration timeout)
                    throws java.io.IOException

Creates a new block blob, or updates the content of an existing block blob.

Code Samples

BlobHTTPHeaders headers = new BlobHTTPHeaders()
    .setBlobContentMD5("data".getBytes(StandardCharsets.UTF_8))
    .setBlobContentLanguage("en-US")
    .setBlobContentType("binary");

Metadata metadata = new Metadata(Collections.singletonMap("metadata", "value"));
BlobAccessConditions accessConditions = new BlobAccessConditions()
    .setLeaseAccessConditions(new LeaseAccessConditions().setLeaseId(leaseId))
    .setModifiedAccessConditions(new ModifiedAccessConditions()
        .setIfUnmodifiedSince(OffsetDateTime.now().minusDays(3)));

try {
    client.uploadFromFile(filePath, headers, metadata, AccessTier.HOT, accessConditions, timeout);
    System.out.println("Upload from file succeeded");
} catch (UncheckedIOException ex) {
    System.err.printf("Failed to upload from file %s%n", ex.getMessage());
}

Parameters:

filePath - Path of the file to upload

headers - BlobHTTPHeaders

metadata - Metadata

tier - AccessTier for the uploaded blob

accessConditions - BlobAccessConditions

timeout - An optional timeout value beyond which a RuntimeException will be raised.

Throws:

java.io.IOException - If an I/O error occurs

stageBlock

public void stageBlock(java.lang.String base64BlockID,
                       java.io.InputStream data,
                       long length)

Uploads the specified block to the block blob's "staging area" to be later committed by a call to commitBlockList. For more information, see the Azure Docs.

Code Samples

client.stageBlock(base64BlockID, data, length);

Parameters:

base64BlockID - A Base64 encoded String that specifies the ID for this block. Note that all block ids for a given blob must be the same length.

data - The data to write to the block.

length - The exact length of the data. It is important that this value match precisely the length of the data provided in the InputStream.

stageBlockWithResponse

public VoidResponse stageBlockWithResponse(java.lang.String base64BlockID,
                                           java.io.InputStream data,
                                           long length,
                                           LeaseAccessConditions leaseAccessConditions,
                                           java.time.Duration timeout,
                                           Context context)

Uploads the specified block to the block blob's "staging area" to be later committed by a call to commitBlockList. For more information, see the Azure Docs.

Code Samples

LeaseAccessConditions accessConditions = new LeaseAccessConditions().setLeaseId(leaseId);
Context context = new Context("key", "value");
System.out.printf("Staging block completed with status %d%n",
    client.stageBlockWithResponse(base64BlockID, data, length, accessConditions, timeout, context).getStatusCode());

Parameters:

base64BlockID - A Base64 encoded String that specifies the ID for this block. Note that all block ids for a given blob must be the same length.

data - The data to write to the block.

length - The exact length of the data. It is important that this value match precisely the length of the data provided in the InputStream.

leaseAccessConditions - By setting lease access conditions, requests will fail if the provided lease does not match the active lease on the blob.

timeout - An optional timeout value beyond which a RuntimeException will be raised.

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

Returns:

A response containing status code and HTTP headers

Throws:

UnexpectedLengthException - when the length of data does not match the input length.

java.lang.NullPointerException - if the input data is null.

stageBlockFromURL

public void stageBlockFromURL(java.lang.String base64BlockID,
                              java.net.URL sourceURL,
                              BlobRange sourceRange)

Creates a new block to be committed as part of a blob where the contents are read from a URL. For more information, see the Azure Docs.

Code Samples

client.stageBlockFromURL(base64BlockID, sourceURL, new BlobRange(offset, count));

Parameters:

base64BlockID - A Base64 encoded String that specifies the ID for this block. Note that all block ids for a given blob must be the same length.

sourceURL - The url to the blob that will be the source of the copy. A source blob in the same storage account can be authenticated via Shared Key. However, if the source is a blob in another account, the source blob must either be public or must be authenticated via a shared access signature. If the source blob is public, no authentication is required to perform the operation.

sourceRange - BlobRange

stageBlockFromURLWithResponse

public VoidResponse stageBlockFromURLWithResponse(java.lang.String base64BlockID,
                                                  java.net.URL sourceURL,
                                                  BlobRange sourceRange,
                                                  byte[] sourceContentMD5,
                                                  LeaseAccessConditions leaseAccessConditions,
                                                  SourceModifiedAccessConditions sourceModifiedAccessConditions,
                                                  java.time.Duration timeout,
                                                  Context context)

Creates a new block to be committed as part of a blob where the contents are read from a URL. For more information, see the Azure Docs.

Code Samples

LeaseAccessConditions leaseAccessConditions = new LeaseAccessConditions().setLeaseId(leaseId);
SourceModifiedAccessConditions sourceModifiedAccessConditions = new SourceModifiedAccessConditions()
    .setSourceIfUnmodifiedSince(OffsetDateTime.now().minusDays(3));
Context context = new Context("key", "value");

System.out.printf("Staging block from URL completed with status %d%n",
    client.stageBlockFromURLWithResponse(base64BlockID, sourceURL, new BlobRange(offset, count), null,
        leaseAccessConditions, sourceModifiedAccessConditions, timeout, context).getStatusCode());

Parameters:

base64BlockID - A Base64 encoded String that specifies the ID for this block. Note that all block ids for a given blob must be the same length.

sourceURL - The url to the blob that will be the source of the copy. A source blob in the same storage account can be authenticated via Shared Key. However, if the source is a blob in another account, the source blob must either be public or must be authenticated via a shared access signature. If the source blob is public, no authentication is required to perform the operation.

sourceRange - BlobRange

sourceContentMD5 - An MD5 hash of the block content from the source blob. If specified, the service will calculate the MD5 of the received data and fail the request if it does not match the provided MD5.

leaseAccessConditions - By setting lease access conditions, requests will fail if the provided lease does not match the active lease on the blob.

sourceModifiedAccessConditions - SourceModifiedAccessConditions

timeout - An optional timeout value beyond which a RuntimeException will be raised.

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

Returns:

A response containing status code and HTTP headers

listBlocks

public BlockList listBlocks(BlockListType listType)

Returns the list of blocks that have been uploaded as part of a block blob using the specified block list filter. For more information, see the Azure Docs.

Code Samples

BlockList block = client.listBlocks(BlockListType.ALL);

System.out.println("Committed Blocks:");
block.getCommittedBlocks().forEach(b -> System.out.printf("Name: %s, Size: %d", b.getName(), b.getSize()));

System.out.println("Uncommitted Blocks:");
block.getUncommittedBlocks().forEach(b -> System.out.printf("Name: %s, Size: %d", b.getName(), b.getSize()));

Parameters:

listType - Specifies which type of blocks to return.

Returns:

The list of blocks.

listBlocksWithResponse

public Response<BlockList> listBlocksWithResponse(BlockListType listType,
                                                  LeaseAccessConditions leaseAccessConditions,
                                                  java.time.Duration timeout,
                                                  Context context)

Returns the list of blocks that have been uploaded as part of a block blob using the specified block list filter. For more information, see the Azure Docs.

Code Samples

LeaseAccessConditions accessConditions = new LeaseAccessConditions().setLeaseId(leaseId);
Context context = new Context("key", "value");
BlockList block = client.listBlocksWithResponse(BlockListType.ALL, accessConditions, timeout, context).getValue();

System.out.println("Committed Blocks:");
block.getCommittedBlocks().forEach(b -> System.out.printf("Name: %s, Size: %d", b.getName(), b.getSize()));

System.out.println("Uncommitted Blocks:");
block.getUncommittedBlocks().forEach(b -> System.out.printf("Name: %s, Size: %d", b.getName(), b.getSize()));

Parameters:

listType - Specifies which type of blocks to return.

leaseAccessConditions - By setting lease access conditions, requests will fail if the provided lease does not match the active lease on the blob.

timeout - An optional timeout value beyond which a RuntimeException will be raised.

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

Returns:

The list of blocks.

commitBlockList

public BlockBlobItem commitBlockList(java.util.List<java.lang.String> base64BlockIDs)

Writes a blob by specifying the list of block IDs that are to make up the blob. In order to be written as part of a blob, a block must have been successfully written to the server in a prior stageBlock operation. You can call commitBlockList to update a blob by uploading only those blocks that have changed, then committing the new and existing blocks together. Any blocks not specified in the block list and permanently deleted. For more information, see the Azure Docs.

Code Samples

System.out.printf("Committing block list completed. Last modified: %s%n",
    client.commitBlockList(Collections.singletonList(base64BlockID)).getLastModified());

Parameters:

base64BlockIDs - A list of base64 encode Strings that specifies the block IDs to be committed.

Returns:

The information of the block blob.

commitBlockListWithResponse

public Response<BlockBlobItem> commitBlockListWithResponse(java.util.List<java.lang.String> base64BlockIDs,
                                                           BlobHTTPHeaders headers,
                                                           Metadata metadata,
                                                           AccessTier tier,
                                                           BlobAccessConditions accessConditions,
                                                           java.time.Duration timeout,
                                                           Context context)

Writes a blob by specifying the list of block IDs that are to make up the blob. In order to be written as part of a blob, a block must have been successfully written to the server in a prior stageBlock operation. You can call commitBlockList to update a blob by uploading only those blocks that have changed, then committing the new and existing blocks together. Any blocks not specified in the block list and permanently deleted. For more information, see the Azure Docs.

Code Samples

BlobHTTPHeaders headers = new BlobHTTPHeaders()
    .setBlobContentMD5("data".getBytes(StandardCharsets.UTF_8))
    .setBlobContentLanguage("en-US")
    .setBlobContentType("binary");

Metadata metadata = new Metadata(Collections.singletonMap("metadata", "value"));
BlobAccessConditions accessConditions = new BlobAccessConditions()
    .setLeaseAccessConditions(new LeaseAccessConditions().setLeaseId(leaseId))
    .setModifiedAccessConditions(new ModifiedAccessConditions()
        .setIfUnmodifiedSince(OffsetDateTime.now().minusDays(3)));
Context context = new Context("key", "value");

System.out.printf("Committing block list completed with status %d%n",
    client.commitBlockListWithResponse(Collections.singletonList(base64BlockID), headers, metadata,
        AccessTier.HOT, accessConditions, timeout, context).getStatusCode());

Parameters:

base64BlockIDs - A list of base64 encode Strings that specifies the block IDs to be committed.

headers - BlobHTTPHeaders

metadata - Metadata

tier - AccessTier for the destination blob.

accessConditions - BlobAccessConditions

timeout - An optional timeout value beyond which a RuntimeException will be raised.

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

Returns:

The information of the block blob.