com.microsoft.azure.storage.blob

Class CloudBlockBlob

java.lang.Object

com.microsoft.azure.storage.blob.CloudBlob

com.microsoft.azure.storage.blob.CloudBlockBlob

All Implemented Interfaces:

ListBlobItem

public final class CloudBlockBlob
extends CloudBlob

Represents a blob that is uploaded as a set of blocks.

Constructor Summary

Constructors

Constructor and Description
CloudBlockBlob(CloudBlockBlob otherBlob) Creates an instance of the CloudBlockBlob class by copying values from another cloud block blob.
CloudBlockBlob(StorageUri blobAbsoluteUri) Creates an instance of the CloudBlockBlob class using the specified absolute StorageUri.
CloudBlockBlob(StorageUri blobAbsoluteUri, StorageCredentials credentials) Creates an instance of the CloudBlockBlob class using the specified absolute StorageUri and credentials.
CloudBlockBlob(StorageUri blobAbsoluteUri, String snapshotID, StorageCredentials credentials) Creates an instance of the CloudBlockBlob class using the specified absolute StorageUri, snapshot ID, and credentials.
CloudBlockBlob(URI blobAbsoluteUri) Creates an instance of the CloudBlockBlob class using the specified absolute URI.
CloudBlockBlob(URI blobAbsoluteUri, StorageCredentials credentials) Creates an instance of the CloudBlockBlob class using the specified absolute URI and credentials.
CloudBlockBlob(URI blobAbsoluteUri, String snapshotID, StorageCredentials credentials) Creates an instance of the CloudBlockBlob class using the specified absolute URI, snapshot ID, and credentials.

Method Summary

Methods

Modifier and Type	Method and Description
void	commitBlockList(Iterable<BlockEntry> blockList) Commits a block list to the storage service.
void	commitBlockList(Iterable<BlockEntry> blockList, AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Commits a block list to the storage service using the specified lease ID, request options, and operation context.
ArrayList<BlockEntry>	downloadBlockList() Downloads the committed block list from the block blob.
ArrayList<BlockEntry>	downloadBlockList(BlockListingFilter blockListingFilter, AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Downloads the block list from the block blob using the specified block listing filter, request options, and operation context.
String	downloadText() Downloads a blob to a string using the platform's default encoding.
String	downloadText(String charsetName, AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Downloads a blob to a string using the specified encoding.
boolean	isStreamWriteSizeModified() Gets the flag that indicates whether the default streamWriteSize was modified.
BlobOutputStream	openOutputStream() Creates and opens an output stream to write data to the block blob.
BlobOutputStream	openOutputStream(AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Creates and opens an output stream to write data to the block blob using the specified request options and operation context.
void	setStreamWriteSizeInBytes(int streamWriteSizeInBytes) Sets the number of bytes to buffer when writing to a BlobOutputStream.
String	startCopy(CloudBlockBlob sourceBlob) Requests the service to start copying a block blob's contents, properties, and metadata to a new block blob.
String	startCopy(CloudBlockBlob sourceBlob, AccessCondition sourceAccessCondition, AccessCondition destinationAccessCondition, BlobRequestOptions options, OperationContext opContext) Requests the service to start copying a block blob's contents, properties, and metadata to a new block blob, using the specified access conditions, lease ID, request options, and operation context.
String	startCopy(CloudFile sourceFile) Requests the service to start copying a file's contents, properties, and metadata to a new block blob.
String	startCopy(CloudFile sourceFile, AccessCondition sourceAccessCondition, AccessCondition destinationAccessCondition, BlobRequestOptions options, OperationContext opContext) Requests the service to start copying a file's contents, properties, and metadata to a new block blob, using the specified access conditions, lease ID, request options, and operation context.
void	upload(InputStream sourceStream, long length) Uploads the source stream data to the block blob.
void	upload(InputStream sourceStream, long length, AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Uploads the source stream data to the blob, using the specified lease ID, request options, and operation context.
void	uploadBlock(String blockId, InputStream sourceStream, long length) Uploads a block to be committed as part of the block blob, using the specified block ID.
void	uploadBlock(String blockId, InputStream sourceStream, long length, AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Uploads a block to be committed as part of the block blob, using the specified block ID, the specified lease ID, request options, and operation context.
void	uploadText(String content) Uploads a blob from a string using the platform's default encoding.
void	uploadText(String content, String charsetName, AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Uploads a blob from a string using the specified encoding.

Methods inherited from class com.microsoft.azure.storage.blob.CloudBlob

abortCopy, abortCopy, acquireLease, acquireLease, acquireLease, breakLease, breakLease, changeLease, changeLease, createSnapshot, createSnapshot, createSnapshot, delete, delete, deleteIfExists, deleteIfExists, download, download, downloadAttributes, downloadAttributes, downloadRange, downloadRange, downloadRangeToByteArray, downloadRangeToByteArray, downloadToByteArray, downloadToByteArray, downloadToFile, downloadToFile, exists, exists, generateSharedAccessSignature, generateSharedAccessSignature, generateSharedAccessSignature, getContainer, getCopyState, getMetadata, getName, getParent, getProperties, getQualifiedStorageUri, getQualifiedUri, getServiceClient, getSnapshotID, getSnapshotQualifiedStorageUri, getSnapshotQualifiedUri, getStorageUri, getStreamMinimumReadSizeInBytes, getStreamWriteSizeInBytes, getUri, isSnapshot, openInputStream, openInputStream, releaseLease, releaseLease, renewLease, renewLease, setMetadata, setStreamMinimumReadSizeInBytes, startCopy, startCopy, uploadFromByteArray, uploadFromByteArray, uploadFromFile, uploadFromFile, uploadMetadata, uploadMetadata, uploadProperties, uploadProperties

Methods inherited from class java.lang.Object

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

Constructor Detail

CloudBlockBlob

public CloudBlockBlob(URI blobAbsoluteUri)
               throws StorageException

Creates an instance of the CloudBlockBlob class using the specified absolute URI.

Parameters:

blobAbsoluteUri - A java.net.URI object that represents the absolute URI to the blob.

Throws:

StorageException - If a storage service error occurred.

CloudBlockBlob

public CloudBlockBlob(StorageUri blobAbsoluteUri)
               throws StorageException

Creates an instance of the CloudBlockBlob class using the specified absolute StorageUri.

Parameters:

blobAbsoluteUri - A StorageUri object that represents the absolute URI to the blob.

Throws:

StorageException - If a storage service error occurred.

CloudBlockBlob

public CloudBlockBlob(CloudBlockBlob otherBlob)

Creates an instance of the CloudBlockBlob class by copying values from another cloud block blob.

Parameters:

otherBlob - A CloudBlockBlob object that represents the block blob to copy.

CloudBlockBlob

public CloudBlockBlob(URI blobAbsoluteUri,
              StorageCredentials credentials)
               throws StorageException

Creates an instance of the CloudBlockBlob class using the specified absolute URI and credentials.

Parameters:

blobAbsoluteUri - A java.net.URI object that represents the absolute URI to the blob.

credentials - A StorageCredentials object used to authenticate access.

Throws:

StorageException - If a storage service error occurred.

CloudBlockBlob

public CloudBlockBlob(StorageUri blobAbsoluteUri,
              StorageCredentials credentials)
               throws StorageException

Creates an instance of the CloudBlockBlob class using the specified absolute StorageUri and credentials.

Parameters:

blobAbsoluteUri - A StorageUri object that represents the absolute StorageUri to the blob.

credentials - A StorageCredentials object used to authenticate access.

Throws:

StorageException - If a storage service error occurred.

CloudBlockBlob

public CloudBlockBlob(URI blobAbsoluteUri,
              String snapshotID,
              StorageCredentials credentials)
               throws StorageException

Creates an instance of the CloudBlockBlob class using the specified absolute URI, snapshot ID, and credentials.

Parameters:

blobAbsoluteUri - A java.net.URI object that represents the absolute URI to the blob.

snapshotID - A String that represents the snapshot version, if applicable.

credentials - A StorageCredentials object used to authenticate access.

Throws:

StorageException - If a storage service error occurred.

CloudBlockBlob

public CloudBlockBlob(StorageUri blobAbsoluteUri,
              String snapshotID,
              StorageCredentials credentials)
               throws StorageException

Creates an instance of the CloudBlockBlob class using the specified absolute StorageUri, snapshot ID, and credentials.

Parameters:

blobAbsoluteUri - A StorageUri object that represents the absolute StorageUri to the blob.

snapshotID - A String that represents the snapshot version, if applicable.

credentials - A StorageCredentials object used to authenticate access.

Throws:

StorageException - If a storage service error occurred.

Method Detail

startCopy

@DoesServiceRequest
public final String startCopy(CloudBlockBlob sourceBlob)
                       throws StorageException,
                              URISyntaxException

Requests the service to start copying a block blob's contents, properties, and metadata to a new block blob.

Parameters:

sourceBlob - A CloudBlockBlob object that represents the source blob to copy.

Returns:

A String which represents the copy ID associated with the copy operation.

Throws:

StorageException - If a storage service error occurred.

URISyntaxException

startCopy

@DoesServiceRequest
public final String startCopy(CloudBlockBlob sourceBlob,
                                  AccessCondition sourceAccessCondition,
                                  AccessCondition destinationAccessCondition,
                                  BlobRequestOptions options,
                                  OperationContext opContext)
                       throws StorageException,
                              URISyntaxException

Requests the service to start copying a block blob's contents, properties, and metadata to a new block blob, using the specified access conditions, lease ID, request options, and operation context.

Parameters:

sourceBlob - A CloudBlockBlob object that represents the source blob to copy.

sourceAccessCondition - An AccessCondition object that represents the access conditions for the source blob.

destinationAccessCondition - An AccessCondition object that represents the access conditions for the destination blob.

options - A BlobRequestOptions object that specifies any additional options for the request. Specifying null will use the default request options from the associated service client ( CloudBlobClient).

opContext - An OperationContext object that represents the context for the current operation. This object is used to track requests to the storage service, and to provide additional runtime information about the operation.

Returns:

A String which represents the copy ID associated with the copy operation.

Throws:

StorageException - If a storage service error occurred.

URISyntaxException

startCopy

@DoesServiceRequest
public final String startCopy(CloudFile sourceFile)
                       throws StorageException,
                              URISyntaxException

Requests the service to start copying a file's contents, properties, and metadata to a new block blob.

Parameters:

sourceFile - A CloudFile object that represents the source file to copy.

Returns:

A String which represents the copy ID associated with the copy operation.

Throws:

StorageException - If a storage service error occurred.

URISyntaxException

startCopy

@DoesServiceRequest
public final String startCopy(CloudFile sourceFile,
                                  AccessCondition sourceAccessCondition,
                                  AccessCondition destinationAccessCondition,
                                  BlobRequestOptions options,
                                  OperationContext opContext)
                       throws StorageException,
                              URISyntaxException

Requests the service to start copying a file's contents, properties, and metadata to a new block blob, using the specified access conditions, lease ID, request options, and operation context.

Parameters:

sourceFile - A CloudFile object that represents the source file to copy.

sourceAccessCondition - An AccessCondition object that represents the access conditions for the source file.

destinationAccessCondition - An AccessCondition object that represents the access conditions for the destination block blob.

options - A BlobRequestOptions object that specifies any additional options for the request. Specifying null will use the default request options from the associated service client (CloudBlobClient).

opContext - An OperationContext object that represents the context for the current operation. This object is used to track requests to the storage service, and to provide additional runtime information about the operation.

Returns:

A String which represents the copy ID associated with the copy operation.

Throws:

StorageException - If a storage service error occurred.

URISyntaxException - If the resource URI is invalid.

commitBlockList

@DoesServiceRequest
public void commitBlockList(Iterable<BlockEntry> blockList)
                     throws StorageException

Commits a block list to the storage service. In order to be written as part of a blob, a block must have been successfully written to the server in a prior uploadBlock operation.

Parameters:

blockList - An enumerable collection of BlockEntry objects that represents the list block items being committed. The size field is ignored.

Throws:

StorageException - If a storage service error occurred.

commitBlockList

@DoesServiceRequest
public void commitBlockList(Iterable<BlockEntry> blockList,
                                      AccessCondition accessCondition,
                                      BlobRequestOptions options,
                                      OperationContext opContext)
                     throws StorageException

Commits a block list to the storage service using the specified lease ID, request options, and operation context. In order to be written as part of a blob, a block must have been successfully written to the server in a prior uploadBlock operation.

Parameters:

blockList - An enumerable collection of BlockEntry objects that represents the list block items being committed. The size field is ignored.

accessCondition - An AccessCondition object that represents the access conditions for the blob.

options - A BlobRequestOptions object that specifies any additional options for the request. Specifying null will use the default request options from the associated service client ( CloudBlobClient).

opContext - An OperationContext object that represents the context for the current operation. This object is used to track requests to the storage service, and to provide additional runtime information about the operation.

Throws:

StorageException - If a storage service error occurred.

downloadBlockList

@DoesServiceRequest
public ArrayList<BlockEntry> downloadBlockList()
                                        throws StorageException

Downloads the committed block list from the block blob.

The committed block list includes the list of blocks that have been successfully committed to the block blob. The list of committed blocks is returned in the same order that they were committed to the blob. No block may appear more than once in the committed block list.

Returns:

An ArrayList object of BlockEntry objects that represent the committed list block items downloaded from the block blob.

Throws:

StorageException - If a storage service error occurred.

downloadBlockList

@DoesServiceRequest
public ArrayList<BlockEntry> downloadBlockList(BlockListingFilter blockListingFilter,
                                                         AccessCondition accessCondition,
                                                         BlobRequestOptions options,
                                                         OperationContext opContext)
                                        throws StorageException

Downloads the block list from the block blob using the specified block listing filter, request options, and operation context.

The committed block list includes the list of blocks that have been successfully committed to the block blob. The list of committed blocks is returned in the same order that they were committed to the blob. No block may appear more than once in the committed block list.

Parameters:

blockListingFilter - A BlockListingFilter value that specifies whether to download committed blocks, uncommitted blocks, or all blocks.

accessCondition - An AccessCondition object that represents the access conditions for the blob.

options - A BlobRequestOptions object that specifies any additional options for the request. Specifying null will use the default request options from the associated service client ( CloudBlobClient).

opContext - An OperationContext object that represents the context for the current operation. This object is used to track requests to the storage service, and to provide additional runtime information about the operation.

Returns:

An ArrayList object of BlockEntry objects that represent the list block items downloaded from the block blob.

Throws:

StorageException - If a storage service error occurred.

openOutputStream

public BlobOutputStream openOutputStream()
                                  throws StorageException

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.

To avoid overwriting and instead throw an error, please use the openOutputStream(AccessCondition, BlobRequestOptions, OperationContext) overload with the appropriate AccessCondition.

Returns:

A BlobOutputStream object used to write data to the blob.

Throws:

StorageException - If a storage service error occurred.

openOutputStream

public BlobOutputStream openOutputStream(AccessCondition accessCondition,
                                BlobRequestOptions options,
                                OperationContext opContext)
                                  throws StorageException

Creates and opens an output stream to write data to the block blob using the specified request options and operation context. If the blob already exists on the service, it will be overwritten.

To avoid overwriting and instead throw an error, please pass in an AccessCondition generated using AccessCondition.generateIfNotExistsCondition().

Parameters:

accessCondition - An AccessCondition object that represents the access conditions for the blob.

options - A BlobRequestOptions object that specifies any additional options for the request. Specifying null will use the default request options from the associated service client ( CloudBlobClient).

opContext - An OperationContext object that represents the context for the current operation. This object is used to track requests to the storage service, and to provide additional runtime information about the operation.

Returns:

A BlobOutputStream object used to write data to the blob.

Throws:

StorageException - If a storage service error occurred.

upload

@DoesServiceRequest
public void upload(InputStream sourceStream,
                             long length)
            throws StorageException,
                   IOException

Uploads the source stream data to the block blob. If the blob already exists on the service, it will be overwritten.

Specified by:

upload in class CloudBlob

Parameters:

sourceStream - An InputStream object that represents the input stream to write to the block blob.

length - A long which represents the length, in bytes, of the stream data, or -1 if unknown.

Throws:

IOException - If an I/O error occurred.

StorageException - If a storage service error occurred.

upload

@DoesServiceRequest
public void upload(InputStream sourceStream,
                             long length,
                             AccessCondition accessCondition,
                             BlobRequestOptions options,
                             OperationContext opContext)
            throws StorageException,
                   IOException

Uploads the source stream data to the blob, using the specified lease ID, request options, and operation context. If the blob already exists on the service, it will be overwritten.

Specified by:

upload in class CloudBlob

Parameters:

sourceStream - An InputStream object that represents the input stream to write to the block blob.

length - A long which represents the length, in bytes, of the stream data, or -1 if unknown.

accessCondition - An AccessCondition object that represents the access conditions for the blob.

options - A BlobRequestOptions object that specifies any additional options for the request. Specifying null will use the default request options from the associated service client ( CloudBlobClient).

opContext - An OperationContext object that represents the context for the current operation. This object is used to track requests to the storage service, and to provide additional runtime information about the operation.

Throws:

IOException - If an I/O error occurred.

StorageException - If a storage service error occurred.

uploadBlock

@DoesServiceRequest
public void uploadBlock(String blockId,
                                  InputStream sourceStream,
                                  long length)
                 throws StorageException,
                        IOException

Uploads a block to be committed as part of the block blob, using the specified block ID.

Parameters:

blockId - A String that represents the Base-64 encoded block ID. Note for a given blob the length of all Block IDs must be identical.

sourceStream - An InputStream object that represents the input stream to write to the block blob.

length - A long which represents the length, in bytes, of the stream data, or -1 if unknown.

Throws:

IOException - If an I/O error occurred.

StorageException - If a storage service error occurred.

uploadBlock

@DoesServiceRequest
public void uploadBlock(String blockId,
                                  InputStream sourceStream,
                                  long length,
                                  AccessCondition accessCondition,
                                  BlobRequestOptions options,
                                  OperationContext opContext)
                 throws StorageException,
                        IOException

Uploads a block to be committed as part of the block blob, using the specified block ID, the specified lease ID, request options, and operation context.

Parameters:

blockId - A String that represents the Base-64 encoded block ID. Note for a given blob the length of all Block IDs must be identical.

sourceStream - An InputStream object that represents the input stream to write to the block blob.

length - A long which represents the length, in bytes, of the stream data, or -1 if unknown.

accessCondition - An AccessCondition object that represents the access conditions for the blob.

options - A BlobRequestOptions object that specifies any additional options for the request. Specifying null will use the default request options from the associated service client ( CloudBlobClient).

opContext - An OperationContext object that represents the context for the current operation. This object is used to track requests to the storage service, and to provide additional runtime information about the operation.

Throws:

IOException - If an I/O error occurred.

StorageException - If a storage service error occurred.

uploadText

public void uploadText(String content)
                throws StorageException,
                       IOException

Uploads a blob from a string using the platform's default encoding. If the blob already exists on the service, it will be overwritten.

Parameters:

content - A String which represents the content that will be uploaded to the blob.

Throws:

StorageException - If a storage service error occurred.

IOException

uploadText

public void uploadText(String content,
              String charsetName,
              AccessCondition accessCondition,
              BlobRequestOptions options,
              OperationContext opContext)
                throws StorageException,
                       IOException

Uploads a blob from a string using the specified encoding. If the blob already exists on the service, it will be overwritten.

Parameters:

content - A String which represents the content that will be uploaded to the blob.

charsetName - A String which represents the name of the charset to use to encode the content. If null, the platform's default encoding is used.

accessCondition - An AccessCondition object that represents the access conditions for the blob.

options - A BlobRequestOptions object that specifies any additional options for the request. Specifying null will use the default request options from the associated service client ( CloudBlobClient).

opContext - An OperationContext object that represents the context for the current operation. This object is used to track requests to the storage service, and to provide additional runtime information about the operation.

Throws:

StorageException - If a storage service error occurred.

IOException

downloadText

public String downloadText()
                    throws StorageException,
                           IOException

Downloads a blob to a string using the platform's default encoding.

Returns:

A String which represents the blob's contents.

Throws:

StorageException - If a storage service error occurred.

IOException

downloadText

public String downloadText(String charsetName,
                  AccessCondition accessCondition,
                  BlobRequestOptions options,
                  OperationContext opContext)
                    throws StorageException,
                           IOException

Downloads a blob to a string using the specified encoding.

Parameters:

charsetName - A String which represents the name of the charset to use to encode the content. If null, the platform's default encoding is used.

accessCondition - An AccessCondition object that represents the access conditions for the blob.

options - A BlobRequestOptions object that specifies any additional options for the request. Specifying null will use the default request options from the associated service client ( CloudBlobClient).

opContext - An OperationContext object that represents the context for the current operation. This object is used to track requests to the storage service, and to provide additional runtime information about the operation.

Returns:

A String which represents the blob's contents.

Throws:

StorageException - If a storage service error occurred.

IOException

setStreamWriteSizeInBytes

public void setStreamWriteSizeInBytes(int streamWriteSizeInBytes)

Sets the number of bytes to buffer when writing to a BlobOutputStream.

Specified by:

setStreamWriteSizeInBytes in class CloudBlob

Parameters:

streamWriteSizeInBytes - An int which represents the maximum block size, in bytes, for writing to a block blob while using a BlobOutputStream object, ranging from 16 KB to 100 MB, inclusive.

Throws:

IllegalArgumentException - If streamWriteSizeInBytes is less than 16 KB or greater than 100 MB.

isStreamWriteSizeModified

public boolean isStreamWriteSizeModified()

Gets the flag that indicates whether the default streamWriteSize was modified.