AppendBlobClient Class

Package:

com.azure.storage.blob.specialized

Maven Artifact:

com.azure:azure-storage-blob:12.28.1

• java.lang.Object
• • com.azure.storage.blob.specialized.BlobClientBase
  • • com.azure.storage.blob.specialized.AppendBlobClient

public final class AppendBlobClient
extends BlobClientBase

Client to an append blob. It may only be instantiated through a SpecializedBlobClientBuilder or via the method getAppendBlobClient(). 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 BlobContainerClient, and operations on the service are available on BlobServiceClient.

Please refer to the Azure Docs for more information.

Field Summary

Modifier and Type	Field and Description
static final int	MAX_APPEND_BLOCK_BYTES Deprecated use getMaxAppendBlockBytes(). Indicates the maximum number of bytes that can be sent in a call to appendBlock.
static final int	MAX_BLOCKS Deprecated use getMaxBlocks(). Indicates the maximum number of blocks allowed in an append blob.

Method Summary

Modifier and Type	Method and Description
AppendBlobItem	appendBlock(InputStream data, long length) Commits a new block of data to the end of the existing append blob.
AppendBlobItem	appendBlockFromUrl(String sourceUrl, BlobRange sourceRange) Commits a new block of data from another blob to the end of this append blob.
Response<AppendBlobItem>	appendBlockFromUrlWithResponse(AppendBlobAppendBlockFromUrlOptions options, Duration timeout, Context context) Commits a new block of data from another blob to the end of this append blob.
Response<AppendBlobItem>	appendBlockFromUrlWithResponse(String sourceUrl, BlobRange sourceRange, byte[] sourceContentMd5, AppendBlobRequestConditions destRequestConditions, BlobRequestConditions sourceRequestConditions, Duration timeout, Context context) Commits a new block of data from another blob to the end of this append blob.
Response<AppendBlobItem>	appendBlockWithResponse(InputStream data, long length, byte[] contentMd5, AppendBlobRequestConditions appendBlobRequestConditions, Duration timeout, Context context) Commits a new block of data to the end of the existing append blob.
AppendBlobItem	create() Creates a 0-length append blob.
AppendBlobItem	create(boolean overwrite) Creates a 0-length append blob.
AppendBlobItem	createIfNotExists() Creates a 0-length append blob if it does not exist.
Response<AppendBlobItem>	createIfNotExistsWithResponse(AppendBlobCreateOptions options, Duration timeout, Context context) Creates a 0-length append blob if it does not exist.
Response<AppendBlobItem>	createWithResponse(BlobHttpHeaders headers, Map<String,String> metadata, BlobRequestConditions requestConditions, Duration timeout, Context context) Creates a 0-length append blob.
Response<AppendBlobItem>	createWithResponse(AppendBlobCreateOptions options, Duration timeout, Context context) Creates a 0-length append blob.
BlobOutputStream	getBlobOutputStream() Creates and opens an output stream to write data to the append blob.
BlobOutputStream	getBlobOutputStream(boolean overwrite) Creates and opens an output stream to write data to the append blob.
BlobOutputStream	getBlobOutputStream(AppendBlobRequestConditions requestConditions) Creates and opens an output stream to write data to the append blob.
AppendBlobClient	getCustomerProvidedKeyClient(CustomerProvidedKey customerProvidedKey) Creates a new AppendBlobClient with the specified customerProvidedKey.
AppendBlobClient	getEncryptionScopeClient(String encryptionScope) Creates a new AppendBlobClient with the specified encryptionScope.
int	getMaxAppendBlockBytes() Get the max number of append block bytes based on service version being used.
int	getMaxBlocks() Get the maximum number of blocks allowed in an append blob.
void	seal() Seals an append blob, making it read only.
Response<Void>	sealWithResponse(AppendBlobSealOptions options, Duration timeout, Context context) Seals an append blob, making it read only.

Methods inherited from BlobClientBase

abortCopyFromUrl abortCopyFromUrlWithResponse beginCopy beginCopy beginCopy copyFromUrl copyFromUrlWithResponse copyFromUrlWithResponse createSnapshot createSnapshotWithResponse delete deleteIfExists deleteIfExistsWithResponse deleteImmutabilityPolicy deleteImmutabilityPolicyWithResponse deleteWithResponse download downloadContent downloadContentWithResponse downloadContentWithResponse downloadStream downloadStreamWithResponse downloadToFile downloadToFile downloadToFileWithResponse downloadToFileWithResponse downloadToFileWithResponse downloadWithResponse exists existsWithResponse generateSas generateSas generateSas generateUserDelegationSas generateUserDelegationSas generateUserDelegationSas getAccountInfo getAccountInfoWithResponse getAccountName getAccountUrl getBlobName getBlobUrl getContainerClient getContainerName getCustomerProvidedKey getCustomerProvidedKeyClient getEncryptionScope getEncryptionScopeClient getHttpPipeline getProperties getPropertiesWithResponse getServiceVersion getSnapshotClient getSnapshotId getTags getTagsWithResponse getVersionClient getVersionId isSnapshot openInputStream openInputStream openInputStream openInputStream openQueryInputStream openQueryInputStreamWithResponse openSeekableByteChannelRead query queryWithResponse setAccessTier setAccessTierWithResponse setAccessTierWithResponse setHttpHeaders setHttpHeadersWithResponse setImmutabilityPolicy setImmutabilityPolicyWithResponse setLegalHold setLegalHoldWithResponse setMetadata setMetadataWithResponse setTags setTagsWithResponse undelete undeleteWithResponse

Methods inherited from java.lang.Object

clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Details

MAX_APPEND_BLOCK_BYTES

@Deprecated
public static final int MAX_APPEND_BLOCK_BYTES

Deprecated

use getMaxAppendBlockBytes().

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

MAX_BLOCKS

@Deprecated
public static final int MAX_BLOCKS

Deprecated

use getMaxBlocks().

Indicates the maximum number of blocks allowed in an append blob.

Method Details

appendBlock

public AppendBlobItem appendBlock(InputStream data, long length)

Commits a new block of data to the end of the existing append blob.

Note that the data passed must be replayable if retries are enabled (the default). In other words, the Flux must produce the same data each time it is subscribed to. For service versions 2022-11-02 and later, the max block size is 100 MB. For previous versions, the max block size is 4 MB. For more information, see the Azure Docs.

Code Samples

System.out.printf("AppendBlob has %d committed blocks%n",
     client.appendBlock(data, length).getBlobCommittedBlockCount());

Parameters:

data - The data to write to the blob. The data must be markable. This is in order to support retries. If the data is not markable, consider using getBlobOutputStream() and writing to the returned OutputStream. Alternatively, consider wrapping your data source in a BufferedInputStream to add mark support.

length - The exact length of the data. It is important that this value match precisely the length of the data emitted by the Flux.

Returns:

The information of the append blob operation.

appendBlockFromUrl

public AppendBlobItem appendBlockFromUrl(String sourceUrl, BlobRange sourceRange)

Commits a new block of data from another blob to the end of this append blob.

Code Samples

System.out.printf("AppendBlob has %d committed blocks%n",
     client.appendBlockFromUrl(sourceUrl, new BlobRange(offset, count)).getBlobCommittedBlockCount());

Parameters:

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 - The source BlobRange to copy.

Returns:

The information of the append blob operation.

appendBlockFromUrlWithResponse

public Response appendBlockFromUrlWithResponse(AppendBlobAppendBlockFromUrlOptions options, Duration timeout, Context context)

Commits a new block of data from another blob to the end of this append blob.

Code Samples

AppendBlobRequestConditions appendBlobRequestConditions = new AppendBlobRequestConditions()
     .setAppendPosition(POSITION)
     .setMaxSize(maxSize);

 BlobRequestConditions modifiedRequestConditions = new BlobRequestConditions()
     .setIfUnmodifiedSince(OffsetDateTime.now().minusDays(3));

 Context context = new Context("key", "value");

 System.out.printf("AppendBlob has %d committed blocks%n",
     client.appendBlockFromUrlWithResponse(new AppendBlobAppendBlockFromUrlOptions(sourceUrl)
         .setSourceRange(new BlobRange(offset, count))
         .setDestinationRequestConditions(appendBlobRequestConditions)
         .setSourceRequestConditions(modifiedRequestConditions), timeout,
         context).getValue().getBlobCommittedBlockCount());

Parameters:

options - options for the operation

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 append blob operation.

appendBlockFromUrlWithResponse

public Response appendBlockFromUrlWithResponse(String sourceUrl, BlobRange sourceRange, byte[] sourceContentMd5, AppendBlobRequestConditions destRequestConditions, BlobRequestConditions sourceRequestConditions, Duration timeout, Context context)

Commits a new block of data from another blob to the end of this append blob.

Code Samples

AppendBlobRequestConditions appendBlobRequestConditions = new AppendBlobRequestConditions()
     .setAppendPosition(POSITION)
     .setMaxSize(maxSize);

 BlobRequestConditions modifiedRequestConditions = new BlobRequestConditions()
     .setIfUnmodifiedSince(OffsetDateTime.now().minusDays(3));

 Context context = new Context("key", "value");

 System.out.printf("AppendBlob has %d committed blocks%n",
     client.appendBlockFromUrlWithResponse(sourceUrl, new BlobRange(offset, count), null,
         appendBlobRequestConditions, modifiedRequestConditions, timeout,
         context).getValue().getBlobCommittedBlockCount());

Parameters:

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.

destRequestConditions - AppendBlobRequestConditions

sourceRequestConditions - BlobRequestConditions

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 append blob operation.

appendBlockWithResponse

public Response appendBlockWithResponse(InputStream data, long length, byte[] contentMd5, AppendBlobRequestConditions appendBlobRequestConditions, Duration timeout, Context context)

Commits a new block of data to the end of the existing append blob.

Note that the data passed must be replayable if retries are enabled (the default). In other words, the Flux must produce the same data each time it is subscribed to. For service versions 2022-11-02 and later, the max block size is 100 MB. For previous versions, the max block size is 4 MB. For more information, see the Azure Docs.

Code Samples

byte[] md5 = MessageDigest.getInstance("MD5").digest("data".getBytes(StandardCharsets.UTF_8));
 AppendBlobRequestConditions requestConditions = new AppendBlobRequestConditions()
     .setAppendPosition(POSITION)
     .setMaxSize(maxSize);
 Context context = new Context("key", "value");

 System.out.printf("AppendBlob has %d committed blocks%n",
     client.appendBlockWithResponse(data, length, md5, requestConditions, timeout, context)
         .getValue().getBlobCommittedBlockCount());

Parameters:

data - The data to write to the blob. The data must be markable. This is in order to support retries. If the data is not markable, consider using getBlobOutputStream() and writing to the returned OutputStream. Alternatively, consider wrapping your data source in a BufferedInputStream to add mark support.

length - The exact length of the data. It is important that this value match precisely the length of the data emitted by the Flux.

contentMd5 - An MD5 hash of the block content. This hash is used to verify the integrity of the block during transport. When this header is specified, the storage service compares the hash of the content that has arrived with this header value. Note that this MD5 hash is not stored with the blob. If the two hashes do not match, the operation will fail.

appendBlobRequestConditions - AppendBlobRequestConditions

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<T> whose value contains the append blob operation.

create

public AppendBlobItem create()

Creates a 0-length append blob. Call appendBlock to append data to an append blob. By default this method will not overwrite an existing blob.

Code Samples

System.out.printf("Created AppendBlob at %s%n", client.create().getLastModified());

Returns:

The information of the created appended blob.

create

public AppendBlobItem create(boolean overwrite)

Creates a 0-length append blob. Call appendBlock to append data to an append blob.

Code Samples

boolean overwrite = false; // Default value
 System.out.printf("Created AppendBlob at %s%n", client.create(overwrite).getLastModified());

Parameters:

overwrite - Whether or not to overwrite, should data exist on the blob.

Returns:

The information of the created appended blob.

createIfNotExists

public AppendBlobItem createIfNotExists()

Creates a 0-length append blob if it does not exist. Call appendBlock to append data to an append blob.

Code Samples

client.createIfNotExists();
 System.out.println("Created AppendBlob");

Returns:

AppendBlobItem containing information of the created appended blob.

createIfNotExistsWithResponse

public Response createIfNotExistsWithResponse(AppendBlobCreateOptions options, Duration timeout, Context context)

Creates a 0-length append blob if it does not exist. Call appendBlock to append data to an append blob.

Code Samples

BlobHttpHeaders headers = new BlobHttpHeaders()
     .setContentType("binary")
     .setContentLanguage("en-US");
 Map<String, String> metadata = Collections.singletonMap("metadata", "value");
 Map<String, String> tags = Collections.singletonMap("tags", "value");
 Context context = new Context("key", "value");

 Response<AppendBlobItem> response = client.createIfNotExistsWithResponse(new AppendBlobCreateOptions()
     .setHeaders(headers).setMetadata(metadata).setTags(tags), timeout, context);
 if (response.getStatusCode() == 409) {
     System.out.println("Already existed.");
 } else {
     System.out.printf("Create completed with status %d%n", response.getStatusCode());
 }

Parameters:

options - AppendBlobCreateOptions

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 reactive response Response<T> signaling completion, whose value contains the AppendBlobItem containing information about the append blob. If Response<T>'s status code is 201, a new append blob was successfully created. If status code is 409, an append blob already existed at this location.

createWithResponse

public Response createWithResponse(BlobHttpHeaders headers, Map metadata, BlobRequestConditions requestConditions, Duration timeout, Context context)

Creates a 0-length append blob. Call appendBlock to append data to an append blob.

To avoid overwriting, pass "*" to setIfNoneMatch(String ifNoneMatch).

Code Samples

BlobHttpHeaders headers = new BlobHttpHeaders()
     .setContentType("binary")
     .setContentLanguage("en-US");
 Map<String, String> metadata = Collections.singletonMap("metadata", "value");
 BlobRequestConditions requestConditions = new BlobRequestConditions()
     .setLeaseId(leaseId)
     .setIfUnmodifiedSince(OffsetDateTime.now().minusDays(3));
 Context context = new Context("key", "value");

 System.out.printf("Created AppendBlob at %s%n",
     client.createWithResponse(headers, metadata, requestConditions, timeout, context).getValue()
         .getLastModified());

Parameters:

headers - BlobHttpHeaders

metadata - Metadata to associate with the blob. If there is leading or trailing whitespace in any metadata key or value, it must be removed or encoded.

requestConditions - BlobRequestConditions

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<T> whose value contains the created appended blob.

createWithResponse

public Response createWithResponse(AppendBlobCreateOptions options, Duration timeout, Context context)

Creates a 0-length append blob. Call appendBlock to append data to an append blob.

To avoid overwriting, pass "*" to setIfNoneMatch(String ifNoneMatch).

Code Samples

BlobHttpHeaders headers = new BlobHttpHeaders()
     .setContentType("binary")
     .setContentLanguage("en-US");
 Map<String, String> metadata = Collections.singletonMap("metadata", "value");
 Map<String, String> tags = Collections.singletonMap("tags", "value");
 BlobRequestConditions requestConditions = new BlobRequestConditions()
     .setIfUnmodifiedSince(OffsetDateTime.now().minusDays(3));
 Context context = new Context("key", "value");

 System.out.printf("Created AppendBlob at %s%n",
     client.createWithResponse(new AppendBlobCreateOptions().setHeaders(headers).setMetadata(metadata)
         .setTags(tags).setRequestConditions(requestConditions), timeout, context).getValue()
         .getLastModified());

Parameters:

options - AppendBlobCreateOptions

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<T> whose value contains the created appended blob.

getBlobOutputStream

public BlobOutputStream getBlobOutputStream()

Creates and opens an output stream to write data to the append blob. If the blob already exists on the service, new data will get appended to the existing blob.

Returns:

A BlobOutputStream object used to write data to the blob.

getBlobOutputStream

public BlobOutputStream getBlobOutputStream(boolean overwrite)

Creates and opens an output stream to write data to the append blob. If overwrite is specified true, the existing blob will be deleted and recreated, should data exist on the blob. If overwrite is specified false, new data will get appended to the existing blob.

Parameters:

overwrite - Whether an existing blob should be deleted and recreated, should data exist on the blob.

Returns:

A BlobOutputStream object used to write data to the blob.

getBlobOutputStream

public BlobOutputStream getBlobOutputStream(AppendBlobRequestConditions requestConditions)

Creates and opens an output stream to write data to the append blob.

Parameters:

requestConditions - A BlobRequestConditions object that represents the access conditions for the blob.

Returns:

A BlobOutputStream object used to write data to the blob.

getCustomerProvidedKeyClient

public AppendBlobClient getCustomerProvidedKeyClient(CustomerProvidedKey customerProvidedKey)

Creates a new AppendBlobClient with the specified customerProvidedKey.

Overrides:

AppendBlobClient.getCustomerProvidedKeyClient(CustomerProvidedKey customerProvidedKey)

Parameters:

customerProvidedKey - the CustomerProvidedKey for the blob, pass null to use no customer provided key.

Returns:

a AppendBlobClient with the specified customerProvidedKey.

getEncryptionScopeClient

public AppendBlobClient getEncryptionScopeClient(String encryptionScope)

Creates a new AppendBlobClient with the specified encryptionScope.

Overrides:

AppendBlobClient.getEncryptionScopeClient(String encryptionScope)

Parameters:

encryptionScope - the encryption scope for the blob, pass null to use no encryption scope.

Returns:

a AppendBlobClient with the specified encryptionScope.

getMaxAppendBlockBytes

public int getMaxAppendBlockBytes()

Get the max number of append block bytes based on service version being used. Service versions 2022-11-02 and above support uploading block bytes up to 100MB, all older service versions support up to 4MB.

Returns:

the max number of block bytes that can be uploaded based on service version.

getMaxBlocks

public int getMaxBlocks()

Get the maximum number of blocks allowed in an append blob.

Returns:

the max number of blocks that can be uploaded in an append blob.

seal

public void seal()

Seals an append blob, making it read only. Any subsequent appends will fail.

Code Samples

client.seal();
 System.out.println("Sealed AppendBlob");

sealWithResponse

public Response sealWithResponse(AppendBlobSealOptions options, Duration timeout, Context context)

Seals an append blob, making it read only. Any subsequent appends will fail.

Code Samples

AppendBlobRequestConditions requestConditions = new AppendBlobRequestConditions().setLeaseId(leaseId)
     .setIfUnmodifiedSince(OffsetDateTime.now().minusDays(3));
 Context context = new Context("key", "value");

 client.sealWithResponse(new AppendBlobSealOptions().setRequestConditions(requestConditions), timeout, context);
 System.out.println("Sealed AppendBlob");

Parameters:

options - AppendBlobSealOptions

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 reactive response signalling completion.