com.microsoft.azure.storage.blob

Class CloudBlob

java.lang.Object

com.microsoft.azure.storage.blob.CloudBlob

All Implemented Interfaces:

ListBlobItem

Direct Known Subclasses:

CloudAppendBlob, CloudBlockBlob, CloudPageBlob

public abstract class CloudBlob
extends Object
implements ListBlobItem

Represents a Microsoft Azure blob. This is the base class for the CloudBlockBlob and CloudPageBlob classes.

Method Summary

Methods

Modifier and Type	Method and Description
void	abortCopy(String copyId) Aborts an ongoing blob copy operation.
void	abortCopy(String copyId, AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Aborts an ongoing blob copy operation.
String	acquireLease() Acquires a new infinite lease on the blob.
String	acquireLease(Integer leaseTimeInSeconds, String proposedLeaseId) Acquires a new lease on the blob with the specified lease time and proposed lease ID.
String	acquireLease(Integer leaseTimeInSeconds, String proposedLeaseId, AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Acquires a new lease on the blob with the specified lease time, proposed lease ID, request options, and operation context.
long	breakLease(Integer breakPeriodInSeconds) Breaks the lease and ensures that another client cannot acquire a new lease until the current lease period has expired.
long	breakLease(Integer breakPeriodInSeconds, AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Breaks the existing lease, using the specified request options and operation context, and ensures that another client cannot acquire a new lease until the current lease period has expired.
String	changeLease(String proposedLeaseId, AccessCondition accessCondition) Changes the existing lease ID to the proposed lease ID.
String	changeLease(String proposedLeaseId, AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Changes the existing lease ID to the proposed lease Id with the specified access conditions, request options, and operation context.
CloudBlob	createSnapshot() Creates a snapshot of the blob.
CloudBlob	createSnapshot(AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Creates a snapshot of the blob using the specified request options and operation context.
CloudBlob	createSnapshot(HashMap<String,String> metadata, AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Creates a snapshot of the blob using the specified request options and operation context.
void	delete() Deletes the blob.
void	delete(DeleteSnapshotsOption deleteSnapshotsOption, AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Deletes the blob using the specified snapshot and request options, and operation context.
boolean	deleteIfExists() Deletes the blob if it exists.
boolean	deleteIfExists(DeleteSnapshotsOption deleteSnapshotsOption, AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Deletes the blob if it exists, using the specified snapshot and request options, and operation context.
void	download(OutputStream outStream) Downloads the contents of a blob to a stream.
void	download(OutputStream outStream, AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Downloads the contents of a blob to a stream using the specified request options and operation context.
AccountInformation	downloadAccountInfo() Gets information related to the storage account in which this blob resides.
AccountInformation	downloadAccountInfo(BlobRequestOptions options, OperationContext opContext) Gets information related to the storage account in which this blob resides.
void	downloadAttributes() Populates a blob's properties and metadata.
void	downloadAttributes(AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Populates a blob's properties and metadata using the specified request options and operation context.
void	downloadRange(long offset, Long length, OutputStream outStream) Downloads the contents of a blob to a stream.
void	downloadRange(long offset, Long length, OutputStream outStream, AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Downloads the contents of a blob to a stream using the specified request options and operation context.
int	downloadRangeToByteArray(long offset, Long length, byte[] buffer, int bufferOffset) Downloads a range of bytes from the blob to the given byte buffer.
int	downloadRangeToByteArray(long offset, Long length, byte[] buffer, int bufferOffset, AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Downloads a range of bytes from the blob to the given byte buffer, using the specified request options and operation context.
int	downloadToByteArray(byte[] buffer, int bufferOffset) Downloads a range of bytes from the blob to the given byte buffer.
int	downloadToByteArray(byte[] buffer, int bufferOffset, AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Downloads a range of bytes from the blob to the given byte buffer, using the specified request options and operation context.
void	downloadToFile(String path) Downloads a blob, storing the contents in a file.
void	downloadToFile(String path, AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Downloads a blob, storing the contents in a file.
boolean	exists() Checks to see if the blob exists.
boolean	exists(AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Checks to see if the blob exists, using the specified request options and operation context.
String	generateSharedAccessSignature(SharedAccessBlobPolicy policy, SharedAccessBlobHeaders headers, String groupPolicyIdentifier) Returns a shared access signature for the blob using the specified group policy identifier and operation context.
String	generateSharedAccessSignature(SharedAccessBlobPolicy policy, SharedAccessBlobHeaders headers, String groupPolicyIdentifier, IPRange ipRange, SharedAccessProtocols protocols) Returns a shared access signature for the blob using the specified group policy identifier and operation context.
String	generateSharedAccessSignature(SharedAccessBlobPolicy policy, String groupPolicyIdentifier) Returns a shared access signature for the blob using the specified group policy identifier and operation context.
CloudBlobContainer	getContainer() Returns the blob's container.
CopyState	getCopyState() Returns the blob's copy state.
HashMap<String,String>	getMetadata() Returns the metadata for the blob.
String	getName() Returns the name of the blob.
CloudBlobDirectory	getParent() Returns the blob item's parent.
BlobProperties	getProperties() Returns the blob's properties.
StorageUri	getQualifiedStorageUri() Deprecated. use getSnapshotQualifiedStorageUri() instead.
URI	getQualifiedUri() Deprecated. use getSnapshotQualifiedUri() instead.
CloudBlobClient	getServiceClient() Returns the Blob service client associated with the blob.
String	getSnapshotID() Gets the Blob Snapshot ID.
StorageUri	getSnapshotQualifiedStorageUri() Returns the blob's URI for both the primary and secondary locations, including query string information if the blob is a snapshot.
URI	getSnapshotQualifiedUri() Returns the absolute URI to the blob, including query string information if the blob is a snapshot.
StorageUri	getStorageUri() Returns the list of URIs for all locations.
int	getStreamMinimumReadSizeInBytes() Returns the minimum read size when using a BlobInputStream.
int	getStreamWriteSizeInBytes() Gets the number of bytes to buffer when writing to a BlobOutputStream (block and page blobs).
URI	getUri() Returns the URI for this blob.
boolean	isSnapshot() Indicates whether this blob is a snapshot.
BlobInputStream	openInputStream() Opens a blob input stream to download the blob.
BlobInputStream	openInputStream(AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Opens a blob input stream to download the blob using the specified request options and operation context.
void	releaseLease(AccessCondition accessCondition) Releases the lease on the blob.
void	releaseLease(AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Releases the lease on the blob using the specified request options and operation context.
void	renewLease(AccessCondition accessCondition) Renews an existing lease.
void	renewLease(AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Renews an existing lease using the specified request options and operation context.
void	setMetadata(HashMap<String,String> metadata) Sets the metadata for the blob.
void	setStreamMinimumReadSizeInBytes(int minimumReadSize) Sets the minimum read size when using a BlobInputStream.
abstract void	setStreamWriteSizeInBytes(int streamWriteSizeInBytes) Sets the number of bytes to buffer when writing to a BlobOutputStream (block and page blobs).
String	startCopy(URI source) Requests the service to start copying a URI's contents, properties, and metadata to a new blob.
String	startCopy(URI source, AccessCondition sourceAccessCondition, AccessCondition destinationAccessCondition, BlobRequestOptions options, OperationContext opContext) Requests the service to start copying a URI's contents, properties, and metadata to a new blob, using the specified access conditions, lease ID, request options, and operation context.
void	undelete() Un-deletes a blob and all its snapshots that have been soft-deleted.
void	undelete(BlobRequestOptions options, OperationContext opContext) Un-deletes a blob that has been soft-deleted, using the specified request options, and operation context.
abstract void	upload(InputStream sourceStream, long length) Uploads the source stream data to the blob.
abstract 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	uploadFromByteArray(byte[] buffer, int offset, int length) Uploads a blob from data in a byte array.
void	uploadFromByteArray(byte[] buffer, int offset, int length, AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Uploads a blob from data in a byte array.
void	uploadFromFile(String path) Uploads a blob from a file.
void	uploadFromFile(String path, AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Uploads a blob from a file.
void	uploadMetadata() Uploads the blob's metadata to the storage service.
void	uploadMetadata(AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Uploads the blob's metadata to the storage service using the specified lease ID, request options, and operation context.
void	uploadProperties() Updates the blob's properties to the storage service.
void	uploadProperties(AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Updates the blob's properties using the specified lease ID, request options, and operation context.

Methods inherited from class java.lang.Object

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

Method Detail

abortCopy

@DoesServiceRequest
public final void abortCopy(String copyId)
                     throws StorageException

Aborts an ongoing blob copy operation.

Parameters:

copyId - A String object that identifying the copy operation.

Throws:

StorageException - If a storage service error occurred.

abortCopy

@DoesServiceRequest
public final void abortCopy(String copyId,
                                AccessCondition accessCondition,
                                BlobRequestOptions options,
                                OperationContext opContext)
                     throws StorageException

Aborts an ongoing blob copy operation.

Parameters:

copyId - A String object that identifying the copy operation.

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.

acquireLease

@DoesServiceRequest
public final String acquireLease()
                          throws StorageException

Acquires a new infinite lease on the blob.

Returns:

A String that represents the lease ID.

Throws:

StorageException - If a storage service error occurred.

acquireLease

@DoesServiceRequest
public final String acquireLease(Integer leaseTimeInSeconds,
                                     String proposedLeaseId)
                          throws StorageException

Acquires a new lease on the blob with the specified lease time and proposed lease ID.

Parameters:

leaseTimeInSeconds - An Integer which specifies the span of time for which to acquire the lease, in seconds. If null, an infinite lease will be acquired. If not null, the value must be greater than zero.

proposedLeaseId - A String that represents the proposed lease ID for the new lease, or null if no lease ID is proposed.

Returns:

A String that represents the lease ID.

Throws:

StorageException - If a storage service error occurred.

acquireLease

@DoesServiceRequest
public final String acquireLease(Integer leaseTimeInSeconds,
                                     String proposedLeaseId,
                                     AccessCondition accessCondition,
                                     BlobRequestOptions options,
                                     OperationContext opContext)
                          throws StorageException

Acquires a new lease on the blob with the specified lease time, proposed lease ID, request options, and operation context.

Parameters:

leaseTimeInSeconds - An Integer which specifies the span of time for which to acquire the lease, in seconds. If null, an infinite lease will be acquired. If not null, the value must be greater than zero.

proposedLeaseId - A String that represents the proposed lease ID for the new lease, or null if no lease ID is proposed.

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. The context is used to track requests to the storage service, and to provide additional runtime information about the operation.

Returns:

A String that represents the lease ID.

Throws:

StorageException - If a storage service error occurred.

breakLease

@DoesServiceRequest
public final long breakLease(Integer breakPeriodInSeconds)
                      throws StorageException

Breaks the lease and ensures that another client cannot acquire a new lease until the current lease period has expired.

Parameters:

breakPeriodInSeconds - Specifies the time to wait, in seconds, until the current lease is broken. If null, the break period is the remainder of the current lease, or zero for infinite leases.

Returns:

An long which specifies the time, in seconds, remaining in the lease period.

Throws:

StorageException - If a storage service error occurred.

breakLease

@DoesServiceRequest
public final long breakLease(Integer breakPeriodInSeconds,
                                 AccessCondition accessCondition,
                                 BlobRequestOptions options,
                                 OperationContext opContext)
                      throws StorageException

Breaks the existing lease, using the specified request options and operation context, and ensures that another client cannot acquire a new lease until the current lease period has expired.

Parameters:

breakPeriodInSeconds - An Integer which specifies the time to wait, in seconds, until the current lease is broken. If null, the break period is the remainder of the current lease, or zero for infinite leases.

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. The context is used to track requests to the storage service, and to provide additional runtime information about the operation.

Returns:

An long which represents the time, in seconds, remaining in the lease period.

Throws:

StorageException - If a storage service error occurred.

changeLease

@DoesServiceRequest
public final String changeLease(String proposedLeaseId,
                                    AccessCondition accessCondition)
                         throws StorageException

Changes the existing lease ID to the proposed lease ID.

Parameters:

proposedLeaseId - A String that represents the proposed lease ID for the new lease, or null if no lease ID is proposed.

accessCondition - An AccessCondition object that represents the access conditions for the blob. The lease ID is required to be set with an access condition.

Returns:

A String that represents the new lease ID.

Throws:

StorageException - If a storage service error occurred.

changeLease

@DoesServiceRequest
public final String changeLease(String proposedLeaseId,
                                    AccessCondition accessCondition,
                                    BlobRequestOptions options,
                                    OperationContext opContext)
                         throws StorageException

Changes the existing lease ID to the proposed lease Id with the specified access conditions, request options, and operation context.

Parameters:

proposedLeaseId - A String that represents the proposed lease ID for the new lease, or null if no lease ID is proposed.

accessCondition - An AccessCondition object that represents the access conditions for the blob. The lease ID is required to be set with an access condition.

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. The context is used to track requests to the storage service, and to provide additional runtime information about the operation.

Returns:

A String that represents the new lease ID.

Throws:

StorageException - If a storage service error occurred.

startCopy

@DoesServiceRequest
public final String startCopy(URI source)
                       throws StorageException

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

Parameters:

source - A java.net.URI The source URI. URIs for resources outside of Azure may only be copied into block blobs.

Returns:

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

Throws:

StorageException - If a storage service error occurred.

startCopy

@DoesServiceRequest
public final String startCopy(URI source,
                                  AccessCondition sourceAccessCondition,
                                  AccessCondition destinationAccessCondition,
                                  BlobRequestOptions options,
                                  OperationContext opContext)
                       throws StorageException

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

Parameters:

source - A java.net.URI The source URI. URIs for resources outside of Azure may only be copied into block blobs.

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

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

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.

createSnapshot

@DoesServiceRequest
public final CloudBlob createSnapshot()
                               throws StorageException

Creates a snapshot of the blob.

Returns:

A CloudBlob object that represents the snapshot of the blob.

Throws:

StorageException - If a storage service error occurred.

createSnapshot

@DoesServiceRequest
public final CloudBlob createSnapshot(AccessCondition accessCondition,
                                          BlobRequestOptions options,
                                          OperationContext opContext)
                               throws StorageException

Creates a snapshot of the blob using the specified request options and operation context.

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 CloudBlob object that represents the snapshot of the blob.

Throws:

StorageException - If a storage service error occurred.

createSnapshot

@DoesServiceRequest
public final CloudBlob createSnapshot(HashMap<String,String> metadata,
                                          AccessCondition accessCondition,
                                          BlobRequestOptions options,
                                          OperationContext opContext)
                               throws StorageException

Creates a snapshot of the blob using the specified request options and operation context.

Parameters:

metadata - A collection of name-value pairs defining the metadata of the snapshot, or null.

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 CloudBlob object that represents the snapshot of the blob.

Throws:

StorageException - If a storage service error occurred.

delete

@DoesServiceRequest
public final void delete()
                  throws StorageException

Deletes the blob. If a delete retention policy is enabled on the service, the blob will be retained for a specified period of time, before being removed permanently by garbage collection.

Throws:

StorageException - If a storage service error occurred.

delete

@DoesServiceRequest
public final void delete(DeleteSnapshotsOption deleteSnapshotsOption,
                             AccessCondition accessCondition,
                             BlobRequestOptions options,
                             OperationContext opContext)
                  throws StorageException

Deletes the blob using the specified snapshot and request options, and operation context. If a delete retention policy is enabled on the service, the blob will be retained for a specified period of time, before being removed permanently by garbage collection.

A blob that has snapshots cannot be deleted unless the snapshots are also deleted. If a blob has snapshots, use the DeleteSnapshotsOption.DELETE_SNAPSHOTS_ONLY or DeleteSnapshotsOption.INCLUDE_SNAPSHOTS value in the deleteSnapshotsOption parameter to specify how the snapshots should be handled when the blob is deleted.

Parameters:

deleteSnapshotsOption - A DeleteSnapshotsOption object that indicates whether to delete only snapshots, or the blob and its snapshots.

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.

undelete

@DoesServiceRequest
public final void undelete()
                    throws StorageException

Un-deletes a blob and all its snapshots that have been soft-deleted.

Throws:

StorageException - If a storage service error occurred.

undelete

@DoesServiceRequest
public final void undelete(BlobRequestOptions options,
                               OperationContext opContext)
                    throws StorageException

Un-deletes a blob that has been soft-deleted, using the specified request options, and operation context.

The un-delete Blob operation restores the contents and metadata of soft deleted blob and all its snapshots. Attempting to undelete a blob or snapshot that is not soft deleted will succeed without any changes.

Parameters:

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.

deleteIfExists

@DoesServiceRequest
public final boolean deleteIfExists()
                             throws StorageException

Deletes the blob if it exists.

A blob that has snapshots cannot be deleted unless the snapshots are also deleted. If a blob has snapshots, use the DeleteSnapshotsOption.DELETE_SNAPSHOTS_ONLY or DeleteSnapshotsOption.INCLUDE_SNAPSHOTS value in the deleteSnapshotsOption parameter to specify how the snapshots should be handled when the blob is deleted.

Returns:

true if the blob was deleted; otherwise, false.

Throws:

StorageException - If a storage service error occurred.

deleteIfExists

@DoesServiceRequest
public final boolean deleteIfExists(DeleteSnapshotsOption deleteSnapshotsOption,
                                        AccessCondition accessCondition,
                                        BlobRequestOptions options,
                                        OperationContext opContext)
                             throws StorageException

Deletes the blob if it exists, using the specified snapshot and request options, and operation context.

A blob that has snapshots cannot be deleted unless the snapshots are also deleted. If a blob has snapshots, use the DeleteSnapshotsOption.DELETE_SNAPSHOTS_ONLY or DeleteSnapshotsOption.INCLUDE_SNAPSHOTS value in the deleteSnapshotsOption parameter to specify how the snapshots should be handled when the blob is deleted.

Parameters:

deleteSnapshotsOption - A DeleteSnapshotsOption object that indicates whether to delete only snapshots, or the blob and its snapshots.

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:

true if the blob existed and was deleted; otherwise, false

Throws:

StorageException - If a storage service error occurred.

download

@DoesServiceRequest
public final void download(OutputStream outStream)
                    throws StorageException

Downloads the contents of a blob to a stream.

Parameters:

outStream - An OutputStream object that represents the target stream.

Throws:

StorageException - If a storage service error occurred.

download

@DoesServiceRequest
public final void download(OutputStream outStream,
                               AccessCondition accessCondition,
                               BlobRequestOptions options,
                               OperationContext opContext)
                    throws StorageException

Downloads the contents of a blob to a stream using the specified request options and operation context.

Parameters:

outStream - An OutputStream object that represents the target stream.

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.

downloadRange

@DoesServiceRequest
public final void downloadRange(long offset,
                                    Long length,
                                    OutputStream outStream)
                         throws StorageException

Downloads the contents of a blob to a stream.

Parameters:

offset - A long which represents the offset to use as the starting point for the source.

length - A Long which represents the number of bytes to read or null.

outStream - An OutputStream object that represents the target stream.

Throws:

StorageException - If a storage service error occurred.

downloadRange

@DoesServiceRequest
public final void downloadRange(long offset,
                                    Long length,
                                    OutputStream outStream,
                                    AccessCondition accessCondition,
                                    BlobRequestOptions options,
                                    OperationContext opContext)
                         throws StorageException

Downloads the contents of a blob to a stream using the specified request options and operation context.

Parameters:

offset - A long which represents the offset to use as the starting point for the source.

length - A Long which represents the number of bytes to read or null.

outStream - An OutputStream object that represents the target stream.

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.

downloadAttributes

@DoesServiceRequest
public final void downloadAttributes()
                              throws StorageException

Populates a blob's properties and metadata.

This method populates the blob's system properties and user-defined metadata. Before reading or modifying a blob's properties or metadata, call this method or its overload to retrieve the latest values for the blob's properties and metadata from the Microsoft Azure storage service.

Throws:

StorageException - If a storage service error occurred.

downloadAttributes

@DoesServiceRequest
public final void downloadAttributes(AccessCondition accessCondition,
                                         BlobRequestOptions options,
                                         OperationContext opContext)
                              throws StorageException

Populates a blob's properties and metadata using the specified request options and operation context.

This method populates the blob's system properties and user-defined metadata. Before reading or modifying a blob's properties or metadata, call this method or its overload to retrieve the latest values for the blob's properties and metadata from the Microsoft Azure storage service.

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.

Throws:

StorageException - If a storage service error occurred.

downloadRangeToByteArray

@DoesServiceRequest
public final int downloadRangeToByteArray(long offset,
                                              Long length,
                                              byte[] buffer,
                                              int bufferOffset)
                                   throws StorageException

Downloads a range of bytes from the blob to the given byte buffer.

Parameters:

offset - A long which represents the byte offset to use as the starting point for the source.

length - A Long which represents the number of bytes to read or null.

buffer - A byte array which represents the buffer to which the blob bytes are downloaded.

bufferOffset - An int which represents the byte offset to use as the starting point for the target.

Returns:

The total number of bytes read into the buffer.

Throws:

StorageException

downloadRangeToByteArray

@DoesServiceRequest
public final int downloadRangeToByteArray(long offset,
                                              Long length,
                                              byte[] buffer,
                                              int bufferOffset,
                                              AccessCondition accessCondition,
                                              BlobRequestOptions options,
                                              OperationContext opContext)
                                   throws StorageException

Downloads a range of bytes from the blob to the given byte buffer, using the specified request options and operation context.

Parameters:

offset - A long which represents the byte offset to use as the starting point for the source.

length - A Long which represents the number of bytes to read or null.

buffer - A byte array which represents the buffer to which the blob bytes are downloaded.

bufferOffset - An int which represents the byte offset to use as the starting point for the target.

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:

The total number of bytes read into the buffer.

Throws:

StorageException - If a storage service error occurred.

downloadToByteArray

@DoesServiceRequest
public final int downloadToByteArray(byte[] buffer,
                                         int bufferOffset)
                              throws StorageException

Downloads a range of bytes from the blob to the given byte buffer.

Parameters:

buffer - A byte array which represents the buffer to which the blob bytes are downloaded.

bufferOffset - An int which represents the byte offset to use as the starting point for the target.

Throws:

StorageException - If a storage service error occurred.

downloadToByteArray

@DoesServiceRequest
public final int downloadToByteArray(byte[] buffer,
                                         int bufferOffset,
                                         AccessCondition accessCondition,
                                         BlobRequestOptions options,
                                         OperationContext opContext)
                              throws StorageException

Downloads a range of bytes from the blob to the given byte buffer, using the specified request options and operation context.

Parameters:

buffer - A byte array which represents the buffer to which the blob bytes are downloaded.

bufferOffset - A long which represents the byte offset to use as the starting point for the target.

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.

uploadFromByteArray

public void uploadFromByteArray(byte[] buffer,
                       int offset,
                       int length)
                         throws StorageException,
                                IOException

Uploads a blob from data in a byte array. If the blob already exists on the service, it will be overwritten.

Parameters:

buffer - A byte array which represents the data to write to the blob.

offset - A int which represents the offset of the byte array from which to start the data upload.

length - An int which represents the number of bytes to upload from the input buffer.

Throws:

StorageException - If a storage service error occurred.

IOException

uploadFromByteArray

public void uploadFromByteArray(byte[] buffer,
                       int offset,
                       int length,
                       AccessCondition accessCondition,
                       BlobRequestOptions options,
                       OperationContext opContext)
                         throws StorageException,
                                IOException

Uploads a blob from data in a byte array. If the blob already exists on the service, it will be overwritten.

Parameters:

buffer - A byte array which represents the data to write to the blob.

offset - A int which represents the offset of the byte array from which to start the data upload.

length - An int which represents the number of bytes to upload from the input buffer.

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

uploadFromFile

public void uploadFromFile(String path)
                    throws StorageException,
                           IOException

Uploads a blob from a file. If the blob already exists on the service, it will be overwritten.

Parameters:

path - A String which represents the path to the file to be uploaded.

Throws:

StorageException - If a storage service error occurred.

IOException

uploadFromFile

public void uploadFromFile(String path,
                  AccessCondition accessCondition,
                  BlobRequestOptions options,
                  OperationContext opContext)
                    throws StorageException,
                           IOException

Uploads a blob from a file. If the blob already exists on the service, it will be overwritten.

Parameters:

path - A String which represents the path to the file to be uploaded.

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

downloadToFile

public void downloadToFile(String path)
                    throws StorageException,
                           IOException

Downloads a blob, storing the contents in a file.

Parameters:

path - A String which represents the path to the file that will be created with the contents of the blob.

Throws:

StorageException - If a storage service error occurred.

IOException

downloadToFile

public void downloadToFile(String path,
                  AccessCondition accessCondition,
                  BlobRequestOptions options,
                  OperationContext opContext)
                    throws StorageException,
                           IOException

Downloads a blob, storing the contents in a file.

Parameters:

path - A String which represents the path to the file that will be created with the contents of the blob.

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

exists

@DoesServiceRequest
public final boolean exists()
                     throws StorageException

Checks to see if the blob exists.

Returns:

true if the blob exists, otherwise false.

Throws:

StorageException - If a storage service error occurred.

exists

@DoesServiceRequest
public final boolean exists(AccessCondition accessCondition,
                                BlobRequestOptions options,
                                OperationContext opContext)
                     throws StorageException

Checks to see if the blob exists, using the specified request options and operation context.

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:

true if the blob exists, other wise false.

Throws:

StorageException - If a storage service error occurred.

generateSharedAccessSignature

public String generateSharedAccessSignature(SharedAccessBlobPolicy policy,
                                   String groupPolicyIdentifier)
                                     throws InvalidKeyException,
                                            StorageException

Returns a shared access signature for the blob using the specified group policy identifier and operation context. Note this does not contain the leading "?".

Parameters:

policy - A SharedAccessPolicy object that represents the access policy for the shared access signature.

groupPolicyIdentifier - A String that represents the container-level access policy.

Returns:

A String that represents the shared access signature.

Throws:

IllegalArgumentException - If the credentials are invalid or the blob is a snapshot.

InvalidKeyException - If the credentials are invalid.

StorageException - If a storage service error occurred.

generateSharedAccessSignature

public String generateSharedAccessSignature(SharedAccessBlobPolicy policy,
                                   SharedAccessBlobHeaders headers,
                                   String groupPolicyIdentifier)
                                     throws InvalidKeyException,
                                            StorageException

Returns a shared access signature for the blob using the specified group policy identifier and operation context. Note this does not contain the leading "?".

Parameters:

policy - A SharedAccessPolicy object that represents the access policy for the shared access signature.

headers - A SharedAccessBlobHeaders object that represents the optional header values to set for a blob accessed with this shared access signature.

groupPolicyIdentifier - A String that represents the container-level access policy.

Returns:

A String that represents the shared access signature.

Throws:

IllegalArgumentException - If the credentials are invalid or the blob is a snapshot.

InvalidKeyException - If the credentials are invalid.

StorageException - If a storage service error occurred.

generateSharedAccessSignature

public String generateSharedAccessSignature(SharedAccessBlobPolicy policy,
                                   SharedAccessBlobHeaders headers,
                                   String groupPolicyIdentifier,
                                   IPRange ipRange,
                                   SharedAccessProtocols protocols)
                                     throws InvalidKeyException,
                                            StorageException

Returns a shared access signature for the blob using the specified group policy identifier and operation context. Note this does not contain the leading "?".

Parameters:

policy - A SharedAccessPolicy object that represents the access policy for the shared access signature.

headers - A SharedAccessBlobHeaders object that represents the optional header values to set for a blob accessed with this shared access signature.

groupPolicyIdentifier - A String that represents the container-level access policy.

ipRange - A IPRange object containing the range of allowed IP addresses.

protocols - A SharedAccessProtocols representing the allowed Internet protocols.

Returns:

A String that represents the shared access signature.

Throws:

IllegalArgumentException - If the credentials are invalid or the blob is a snapshot.

InvalidKeyException - If the credentials are invalid.

StorageException - If a storage service error occurred.

getContainer

public final CloudBlobContainer getContainer()
                                      throws StorageException,
                                             URISyntaxException

Returns the blob's container.

Specified by:

getContainer in interface ListBlobItem

Returns:

A CloudBlobContainer object that represents the container of the blob.

Throws:

StorageException - If a storage service error occurred.

URISyntaxException - If the resource URI is invalid.

getMetadata

public final HashMap<String,String> getMetadata()

Returns the metadata for the blob.

Returns:

A java.util.HashMap object that represents the metadata for the blob.

getName

public final String getName()

Returns the name of the blob.

Returns:

A String that represents the name of the blob.

getParent

public final CloudBlobDirectory getParent()
                                   throws URISyntaxException,
                                          StorageException

Returns the blob item's parent.

Specified by:

getParent in interface ListBlobItem

Returns:

A CloudBlobDirectory object that represents the parent directory for the blob.

Throws:

StorageException - If a storage service error occurred.

URISyntaxException - If the resource URI is invalid.

getProperties

public final BlobProperties getProperties()

Returns the blob's properties.

Returns:

A BlobProperties object that represents the properties of the blob.

getCopyState

public CopyState getCopyState()

Returns the blob's copy state.

Returns:

A CopyState object that represents the copy state of the blob.

getSnapshotQualifiedStorageUri

public final StorageUri getSnapshotQualifiedStorageUri()
                                                throws URISyntaxException,
                                                       StorageException

Returns the blob's URI for both the primary and secondary locations, including query string information if the blob is a snapshot.

Returns:

A StorageUri object containing the blob's URIs for both the primary and secondary locations, including snapshot query information if the blob is a snapshot.

Throws:

StorageException - If a storage service error occurred.

URISyntaxException - If the resource URI is invalid.

getSnapshotQualifiedUri

public final URI getSnapshotQualifiedUri()
                                  throws URISyntaxException,
                                         StorageException

Returns the absolute URI to the blob, including query string information if the blob is a snapshot.

Returns:

A java.net.URI object specifying the absolute URI to the blob, including snapshot query information if the blob is a snapshot.

Throws:

StorageException - If a storage service error occurred.

URISyntaxException - If the resource URI is invalid.

getQualifiedStorageUri

@Deprecated
public final StorageUri getQualifiedStorageUri()
                                        throws URISyntaxException,
                                               StorageException

Deprecated. use getSnapshotQualifiedStorageUri() instead.

Returns the snapshot and/or shared access signature qualified URI for this blob.

Returns:

A StorageUri object that represents the snapshot or shared access signature.

Throws:

StorageException - If a storage service error occurred.

URISyntaxException - If the resource URI is invalid.

getQualifiedUri

@Deprecated
public final URI getQualifiedUri()
                          throws URISyntaxException,
                                 StorageException

Deprecated. use getSnapshotQualifiedUri() instead.

Returns the snapshot or shared access signature qualified URI for this blob.

Returns:

A java.net.URI object that represents the snapshot or shared access signature.

Throws:

StorageException - If a storage service error occurred.

URISyntaxException - If the resource URI is invalid.

getServiceClient

public final CloudBlobClient getServiceClient()

Returns the Blob service client associated with the blob.

Returns:

A CloudBlobClient object that represents the client.

getSnapshotID

public final String getSnapshotID()

Gets the Blob Snapshot ID.

Returns:

A String which represents the Blob Snapshot ID.

getStorageUri

public final StorageUri getStorageUri()

Returns the list of URIs for all locations.

Specified by:

getStorageUri in interface ListBlobItem

Returns:

A StorageUri that represents the list of URIs for all locations..

getStreamWriteSizeInBytes

public final int getStreamWriteSizeInBytes()

Gets the number of bytes to buffer when writing to a BlobOutputStream (block and page blobs).

Returns:

A int which represents the number of bytes to buffer or the size of a block, in bytes.

getStreamMinimumReadSizeInBytes

public final int getStreamMinimumReadSizeInBytes()

Returns the minimum read size when using a BlobInputStream.

Returns:

A int which represents the minimum read size, in bytes, when using a BlobInputStream object.

getUri

public final URI getUri()

Returns the URI for this blob.

Specified by:

getUri in interface ListBlobItem

Returns:

A java.net.URI object that represents the URI for the blob.

isSnapshot

public final boolean isSnapshot()

Indicates whether this blob is a snapshot.

Returns:

true if the blob is a snapshot, otherwise false.

See Also:

DeleteSnapshotsOption

openInputStream

@DoesServiceRequest
public final BlobInputStream openInputStream()
                                      throws StorageException

Opens a blob input stream to download the blob.

Use setStreamMinimumReadSizeInBytes(int) to configure the read size.

Returns:

An InputStream object that represents the stream to use for reading from the blob.

Throws:

StorageException - If a storage service error occurred.

openInputStream

@DoesServiceRequest
public final BlobInputStream openInputStream(AccessCondition accessCondition,
                                                 BlobRequestOptions options,
                                                 OperationContext opContext)
                                      throws StorageException

Opens a blob input stream to download the blob using the specified request options and operation context.

Use setStreamMinimumReadSizeInBytes(int) to configure the read size.

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:

An InputStream object that represents the stream to use for reading from the blob.

Throws:

StorageException - If a storage service error occurred.

releaseLease

@DoesServiceRequest
public final void releaseLease(AccessCondition accessCondition)
                        throws StorageException

Releases the lease on the blob.

Parameters:

accessCondition - An AccessCondition object that represents the access conditions for the blob. The LeaseID is required to be set on the AccessCondition.

Throws:

StorageException - If a storage service error occurred.

releaseLease

@DoesServiceRequest
public final void releaseLease(AccessCondition accessCondition,
                                   BlobRequestOptions options,
                                   OperationContext opContext)
                        throws StorageException

Releases the lease on the blob using the specified request options and operation context.

Parameters:

accessCondition - An AccessCondition object that represents the access conditions for the blob.The LeaseID is required to be set on the AccessCondition.

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.

renewLease

@DoesServiceRequest
public final void renewLease(AccessCondition accessCondition)
                      throws StorageException

Renews an existing lease.

Parameters:

accessCondition - An AccessCondition object that represents the access conditions for the blob. The LeaseID is required to be set on the AccessCondition.

Throws:

StorageException - If a storage service error occurred.

renewLease

@DoesServiceRequest
public final void renewLease(AccessCondition accessCondition,
                                 BlobRequestOptions options,
                                 OperationContext opContext)
                      throws StorageException

Renews an existing lease using the specified request options and operation context.

Parameters:

accessCondition - An AccessCondition object that represents the access conditions for the blob. The LeaseID is required to be set on the AccessCondition.

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.

setMetadata

public final void setMetadata(HashMap<String,String> metadata)

Sets the metadata for the blob.

Parameters:

metadata - A java.util.HashMap object that contains the metadata being assigned to the blob.

setStreamWriteSizeInBytes

public abstract void setStreamWriteSizeInBytes(int streamWriteSizeInBytes)

Sets the number of bytes to buffer when writing to a BlobOutputStream (block and page blobs).

Parameters:

streamWriteSizeInBytes - An int that represents the number of bytes to buffer or the size of a block, in bytes.

setStreamMinimumReadSizeInBytes

public void setStreamMinimumReadSizeInBytes(int minimumReadSize)

Sets the minimum read size when using a BlobInputStream.

Parameters:

minimumReadSize - An int that represents the minimum block size, in bytes, for reading from a blob while using a BlobInputStream object. Must be greater than or equal to 16 KB.

Throws:

IllegalArgumentException - If minimumReadSize is less than 16 KB.

upload

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

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

Parameters:

sourceStream - An InputStream object that represents the source stream to upload.

length - An long that represents the length of the stream data in bytes, or -1 if unknown. The length must be greater than zero and a multiple of 512 for page blobs.

Throws:

IOException - If an I/O exception occurred.

StorageException - If a storage service error occurred.

upload

@DoesServiceRequest
public abstract 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.

Parameters:

sourceStream - An InputStream object that represents the source stream to upload.

length - The length of the stream data in bytes, or -1 if unknown. The length must be greater than zero and a multiple of 512 for page blobs.

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 exception occurred.

StorageException - If a storage service error occurred.

uploadMetadata

@DoesServiceRequest
public final void uploadMetadata()
                          throws StorageException

Uploads the blob's metadata to the storage service.

Use downloadAttributes() to retrieve the latest values for the blob's properties and metadata from the Microsoft Azure storage service.

Throws:

StorageException - If a storage service error occurred.

uploadMetadata

@DoesServiceRequest
public final void uploadMetadata(AccessCondition accessCondition,
                                     BlobRequestOptions options,
                                     OperationContext opContext)
                          throws StorageException

Uploads the blob's metadata to the storage service using the specified lease ID, request options, and operation context.

Use downloadAttributes() to retrieve the latest values for the blob's properties and metadata from the Microsoft Azure storage service.

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.

Throws:

StorageException - If a storage service error occurred.

uploadProperties

@DoesServiceRequest
public final void uploadProperties()
                            throws StorageException

Updates the blob's properties to the storage service.

Use downloadAttributes() to retrieve the latest values for the blob's properties and metadata from the Microsoft Azure storage service.

Throws:

StorageException - If a storage service error occurred.

uploadProperties

@DoesServiceRequest
public final void uploadProperties(AccessCondition accessCondition,
                                       BlobRequestOptions options,
                                       OperationContext opContext)
                            throws StorageException

Updates the blob's properties using the specified lease ID, request options, and operation context.

Use downloadAttributes() to retrieve the latest values for the blob's properties and metadata from the Microsoft Azure storage service.

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.

Throws:

StorageException - If a storage service error occurred.

downloadAccountInfo

@DoesServiceRequest
public AccountInformation downloadAccountInfo()
                                       throws StorageException

Gets information related to the storage account in which this blob resides.

Returns:

A AccountInformation object for the given storage account.

Throws:

StorageException - If a storage service error occurred.

downloadAccountInfo

@DoesServiceRequest
public AccountInformation downloadAccountInfo(BlobRequestOptions options,
                                                        OperationContext opContext)
                                       throws StorageException

Gets information related to the storage account in which this blob resides.

Parameters:

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 AccountInformation object for the given storage account.

Throws:

StorageException - If a storage service error occurred.