com.azure.storage.blob

Class BlobAsyncClient

java.lang.Object

com.azure.storage.blob.specialized.BlobAsyncClientBase

com.azure.storage.blob.BlobAsyncClient

public class BlobAsyncClient
extends BlobAsyncClientBase

This class provides a client that contains generic blob operations for Azure Storage Blobs. Operations allowed by the client are downloading and copying a blob, retrieving and setting metadata, retrieving and setting HTTP headers, and deleting and un-deleting a blob.

This client is instantiated through BlobClientBuilder or retrieved via getBlobAsyncClient.

For operations on a specific blob type (i.e append, block, or page) use getAppendBlobAsyncClient, getBlockBlobAsyncClient, or getPageBlobAsyncClient to construct a client that allows blob specific operations.

Please refer to the Azure Docs for more information.

Field Summary

Fields

Modifier and Type	Field and Description
static int	BLOB_DEFAULT_UPLOAD_BLOCK_SIZE

Fields inherited from class com.azure.storage.blob.specialized.BlobAsyncClientBase

accountName, azureBlobStorage

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	BlobAsyncClient(com.azure.storage.blob.implementation.AzureBlobStorageImpl azureBlobStorage, String snapshot, CpkInfo cpk, String accountName) Constructor for use by BlobClientBuilder.

Method Summary

Modifier and Type	Method and Description
AppendBlobAsyncClient	getAppendBlobAsyncClient() Creates a new AppendBlobAsyncClient associated to this blob.
BlockBlobAsyncClient	getBlockBlobAsyncClient() Creates a new BlockBlobAsyncClient associated to this blob.
PageBlobAsyncClient	getPageBlobAsyncClient() Creates a new PageBlobAsyncClient associated to this blob.
BlobAsyncClient	getSnapshotClient(String snapshot) Creates a new BlobAsyncClient linked to the snapshot of this blob resource.
Mono<BlockBlobItem>	upload(Flux<ByteBuffer> data, ParallelTransferOptions parallelTransferOptions) Creates a new block blob, or updates the content of an existing block blob.
protected AsynchronousFileChannel	uploadFileResourceSupplier(String filePath) Resource Supplier for UploadFile
Mono<Void>	uploadFromFile(String filePath) Creates a new block blob, or updates the content of an existing block blob, with the content of the specified file.
Mono<Void>	uploadFromFile(String filePath, ParallelTransferOptions parallelTransferOptions, BlobHTTPHeaders headers, Map<String,String> metadata, AccessTier tier, BlobAccessConditions accessConditions) Creates a new block blob, or updates the content of an existing block blob, with the content of the specified file.
Mono<Response<BlockBlobItem>>	uploadWithResponse(Flux<ByteBuffer> data, ParallelTransferOptions parallelTransferOptions, BlobHTTPHeaders headers, Map<String,String> metadata, AccessTier tier, BlobAccessConditions accessConditions) Creates a new block blob, or updates the content of an existing block blob.

Methods inherited from class com.azure.storage.blob.specialized.BlobAsyncClientBase

abortCopyFromURL, abortCopyFromURLWithResponse, copyFromURL, copyFromURLWithResponse, createSnapshot, createSnapshotWithResponse, delete, deleteWithResponse, download, downloadToFile, downloadToFileWithResponse, downloadWithResponse, exists, existsWithResponse, getAccountInfo, getAccountInfoWithResponse, getAccountName, getBlobName, getBlobUrl, getContainerName, getCustomerProvidedKey, getHttpPipeline, getProperties, getPropertiesWithResponse, getSnapshotId, isSnapshot, setAccessTier, setAccessTierWithResponse, setHTTPHeaders, setHTTPHeadersWithResponse, setMetadata, setMetadataWithResponse, startCopyFromURL, startCopyFromURLWithResponse, undelete, undeleteWithResponse

Methods inherited from class java.lang.Object

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

Field Detail

BLOB_DEFAULT_UPLOAD_BLOCK_SIZE

public static final int BLOB_DEFAULT_UPLOAD_BLOCK_SIZE

See Also:

Constant Field Values

Constructor Detail

BlobAsyncClient

protected BlobAsyncClient(com.azure.storage.blob.implementation.AzureBlobStorageImpl azureBlobStorage,
                          String snapshot,
                          CpkInfo cpk,
                          String accountName)

Constructor for use by BlobClientBuilder.

Parameters:

azureBlobStorage - the API client for blob storage

snapshot - The optional snapshot id of the snapshot blob

cpk - The optional client provided key

accountName - The account name

Method Detail

getSnapshotClient

public BlobAsyncClient getSnapshotClient(String snapshot)

Creates a new BlobAsyncClient linked to the snapshot of this blob resource.

Overrides:

getSnapshotClient in class BlobAsyncClientBase

Parameters:

snapshot - the identifier for a specific snapshot of this blob

Returns:

a BlobAsyncClient used to interact with the specific snapshot.

getAppendBlobAsyncClient

public AppendBlobAsyncClient getAppendBlobAsyncClient()

Creates a new AppendBlobAsyncClient associated to this blob.

Returns:

a AppendBlobAsyncClient associated to this blob.

getBlockBlobAsyncClient

public BlockBlobAsyncClient getBlockBlobAsyncClient()

Creates a new BlockBlobAsyncClient associated to this blob.

Returns:

a BlockBlobAsyncClient associated to this blob.

getPageBlobAsyncClient

public PageBlobAsyncClient getPageBlobAsyncClient()

Creates a new PageBlobAsyncClient associated to this blob.

Returns:

a PageBlobAsyncClient associated to this blob.

upload

public Mono<BlockBlobItem> upload(Flux<ByteBuffer> data,
                                  ParallelTransferOptions parallelTransferOptions)

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 this method; the content of the existing blob is overwritten with the new content. To perform a partial update of a block blob's, use stageBlock and BlockBlobAsyncClient.commitBlockList(List). For more information, see the Azure Docs for Put Block and the Azure Docs for Put Block List.

The data passed need not support multiple subscriptions/be replayable as is required in other upload methods when retries are enabled, and the length of the data need not be known in advance. Therefore, this method should support uploading any arbitrary data source, including network streams. This behavior is possible because this method will perform some internal buffering as configured by the blockSize and numBuffers parameters, so while this method may offer additional convenience, it will not be as performant as other options, which should be preferred when possible.

Typically, the greater the number of buffers used, the greater the possible parallelism when transferring the data. Larger buffers means we will have to stage fewer blocks and therefore require fewer IO operations. The trade-offs between these values are context-dependent, so some experimentation may be required to optimize inputs for a given scenario.

Code Samples

ParallelTransferOptions parallelTransferOptions = new ParallelTransferOptions()
    .setBlockSize(blockSize)
    .setNumBuffers(numBuffers);
client.upload(data, parallelTransferOptions).subscribe(response ->
    System.out.printf("Uploaded BlockBlob MD5 is %s%n",
        Base64.getEncoder().encodeToString(response.getContentMD5())));

Parameters:

data - The data to write to the blob. Unlike other upload methods, this method does not require that the Flux be replayable. In other words, it does not have to support multiple subscribers and is not expected to produce the same values across subscriptions.

parallelTransferOptions - ParallelTransferOptions used to configure buffered uploading.

Returns:

A reactive response containing the information of the uploaded block blob.

uploadWithResponse

public Mono<Response<BlockBlobItem>> uploadWithResponse(Flux<ByteBuffer> data,
                                                        ParallelTransferOptions parallelTransferOptions,
                                                        BlobHTTPHeaders headers,
                                                        Map<String,String> metadata,
                                                        AccessTier tier,
                                                        BlobAccessConditions accessConditions)

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 this method; the content of the existing blob is overwritten with the new content. To perform a partial update of a block blob's, use stageBlock and BlockBlobAsyncClient.commitBlockList(List), which this method uses internally. For more information, see the Azure Docs for Put Block and the Azure Docs for Put Block List.

The data passed need not support multiple subscriptions/be replayable as is required in other upload methods when retries are enabled, and the length of the data need not be known in advance. Therefore, this method should support uploading any arbitrary data source, including network streams. This behavior is possible because this method will perform some internal buffering as configured by the blockSize and numBuffers parameters, so while this method may offer additional convenience, it will not be as performant as other options, which should be preferred when possible.

Typically, the greater the number of buffers used, the greater the possible parallelism when transferring the data. Larger buffers means we will have to stage fewer blocks and therefore require fewer IO operations. The trade-offs between these values are context-dependent, so some experimentation may be required to optimize inputs for a given scenario.

Code Samples

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

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

ParallelTransferOptions parallelTransferOptions = new ParallelTransferOptions()
    .setBlockSize(blockSize)
    .setNumBuffers(numBuffers);

client.uploadWithResponse(data, parallelTransferOptions, headers, metadata, AccessTier.HOT, accessConditions)
    .subscribe(response -> System.out.printf("Uploaded BlockBlob MD5 is %s%n",
        Base64.getEncoder().encodeToString(response.getValue().getContentMD5())));

Using Progress Reporting

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

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

ParallelTransferOptions parallelTransferOptions = new ParallelTransferOptions()
    .setBlockSize(blockSize)
    .setNumBuffers(numBuffers)
    .setProgressReceiver(bytesTransferred -> System.out.printf(
        "Upload progress: %s bytes sent", bytesTransferred));

client.uploadWithResponse(data, parallelTransferOptions, headers, metadata, AccessTier.HOT, accessConditions)
    .subscribe(response -> System.out.printf("Uploaded BlockBlob MD5 is %s%n",
        Base64.getEncoder().encodeToString(response.getValue().getContentMD5())));

Parameters:

data - The data to write to the blob. Unlike other upload methods, this method does not require that the Flux be replayable. In other words, it does not have to support multiple subscribers and is not expected to produce the same values across subscriptions.

parallelTransferOptions - ParallelTransferOptions used to configure buffered uploading.

headers - BlobHTTPHeaders

metadata - Metadata to associate with the blob.

tier - AccessTier for the destination blob.

accessConditions - BlobAccessConditions

Returns:

A reactive response containing the information of the uploaded block blob.

uploadFromFile

public Mono<Void> uploadFromFile(String filePath)

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

Code Samples

client.uploadFromFile(filePath)
    .doOnError(throwable -> System.err.printf("Failed to upload from file %s%n", throwable.getMessage()))
    .subscribe(completion -> System.out.println("Upload from file succeeded"));

Parameters:

filePath - Path to the upload file

Returns:

An empty response

uploadFromFile

public Mono<Void> uploadFromFile(String filePath,
                                 ParallelTransferOptions parallelTransferOptions,
                                 BlobHTTPHeaders headers,
                                 Map<String,String> metadata,
                                 AccessTier tier,
                                 BlobAccessConditions accessConditions)

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

Code Samples

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

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

client.uploadFromFile(filePath,
    new ParallelTransferOptions().setBlockSize(BlobAsyncClient.BLOB_MAX_UPLOAD_BLOCK_SIZE),
    headers, metadata, AccessTier.HOT, accessConditions)
    .doOnError(throwable -> System.err.printf("Failed to upload from file %s%n", throwable.getMessage()))
    .subscribe(completion -> System.out.println("Upload from file succeeded"));

Parameters:

filePath - Path to the upload file

parallelTransferOptions - ParallelTransferOptions to use to upload from file. Number of parallel transfers parameter is ignored.

headers - BlobHTTPHeaders

metadata - Metadata to associate with the blob.

tier - AccessTier for the destination blob.

accessConditions - BlobAccessConditions

Returns:

An empty response

Throws:

IllegalArgumentException - If blockSize is less than 0 or greater than 100MB

UncheckedIOException - If an I/O error occurs

uploadFileResourceSupplier

protected AsynchronousFileChannel uploadFileResourceSupplier(String filePath)

Resource Supplier for UploadFile

Parameters:

filePath - The path for the file

Returns:

AsynchronousFileChannel

Throws:

IOException - an input output exception.