com.microsoft.azure.storage.blob

Class CloudBlobContainer

java.lang.Object

com.microsoft.azure.storage.blob.CloudBlobContainer

public final class CloudBlobContainer
extends Object

Represents a container in the Microsoft Azure Blob service.

Containers hold directories, which are encapsulated as CloudBlobDirectory objects, and directories hold block blobs and page blobs. Directories can also contain sub-directories.

Field Summary

Fields

Modifier and Type	Field and Description
protected HashMap<String,String>	metadata Represents the container metadata.

Constructor Summary

Constructors

Modifier	Constructor and Description
	CloudBlobContainer(StorageUri storageUri) Creates an instance of the CloudBlobContainer class using the specified URI.
	CloudBlobContainer(StorageUri storageUri, StorageCredentials credentials) Creates an instance of the CloudBlobContainer class using the specified StorageUri and credentials.
protected	CloudBlobContainer(String containerName, CloudBlobClient client) Creates an instance of the CloudBlobContainer class using the specified name and client.
	CloudBlobContainer(URI uri) Creates an instance of the CloudBlobContainer class using the specified URI.
	CloudBlobContainer(URI uri, StorageCredentials credentials) Creates an instance of the CloudBlobContainer class using the specified URI and credentials.

Method Summary

Modifier and Type	Method and Description
String	acquireLease() Acquires a new infinite lease on the container.
String	acquireLease(Integer leaseTimeInSeconds, String proposedLeaseId) Acquires a new lease on the container 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 container 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.
void	create() Creates the container.
void	create(BlobContainerPublicAccessType accessType, BlobRequestOptions options, OperationContext opContext) Creates the container using the specified options and operation context.
void	create(BlobRequestOptions options, OperationContext opContext) Creates the container using the specified options and operation context.
boolean	createIfNotExists() Creates the container if it does not exist.
boolean	createIfNotExists(BlobContainerPublicAccessType accessType, BlobRequestOptions options, OperationContext opContext) Creates the container if it does not exist, using the specified request options and operation context.
boolean	createIfNotExists(BlobRequestOptions options, OperationContext opContext) Creates the container if it does not exist, using the specified request options and operation context.
void	delete() Deletes the container.
void	delete(AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Deletes the container using the specified request options and operation context.
boolean	deleteIfExists() Deletes the container if it exists.
boolean	deleteIfExists(AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Deletes the container if it exists using the specified request options and operation context.
void	downloadAttributes() Downloads the container's attributes, which consist of metadata and properties.
void	downloadAttributes(AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Downloads the container's attributes, which consist of metadata and properties, using the specified request options and operation context.
BlobContainerPermissions	downloadPermissions() Downloads the permission settings for the container.
BlobContainerPermissions	downloadPermissions(AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Downloads the permissions settings for the container using the specified request options and operation context.
boolean	exists() Returns a value that indicates whether the container exists.
boolean	exists(AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Returns a value that indicates whether the container exists, using the specified request options and operation context.
String	generateSharedAccessSignature(SharedAccessBlobPolicy policy, String groupPolicyIdentifier) Returns a shared access signature for the container.
String	generateSharedAccessSignature(SharedAccessBlobPolicy policy, String groupPolicyIdentifier, IPRange ipRange, SharedAccessProtocols protocols) Returns a shared access signature for the container.
CloudAppendBlob	getAppendBlobReference(String blobName) Returns a reference to a CloudAppendBlob object that represents an append blob in this container.
CloudAppendBlob	getAppendBlobReference(String blobName, String snapshotID) Returns a reference to a CloudAppendBlob object that represents an append blob in the container, using the specified snapshot ID.
CloudBlob	getBlobReferenceFromServer(String blobName) Gets a reference to a blob in this container.
CloudBlob	getBlobReferenceFromServer(String blobName, String snapshotID, AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Gets a reference to a blob in this container.
CloudBlockBlob	getBlockBlobReference(String blobName) Returns a reference to a CloudBlockBlob object that represents a block blob in this container.
CloudBlockBlob	getBlockBlobReference(String blobName, String snapshotID) Returns a reference to a CloudBlockBlob object that represents a block blob in this container, using the specified snapshot ID.
CloudBlobDirectory	getDirectoryReference(String directoryName) Returns a reference to a CloudBlobDirectory object that represents a virtual blob directory within this container.
HashMap<String,String>	getMetadata() Returns the metadata for the container.
String	getName() Returns the name of the container.
CloudPageBlob	getPageBlobReference(String blobName) Returns a reference to a CloudPageBlob object that represents a page blob in this container.
CloudPageBlob	getPageBlobReference(String blobName, String snapshotID) Returns a reference to a CloudPageBlob object that represents a page blob in the container, using the specified snapshot ID.
BlobContainerProperties	getProperties() Returns the properties for the container.
CloudBlobClient	getServiceClient() Returns the Blob service client associated with this container.
StorageUri	getStorageUri() Returns the list of URIs for all locations.
URI	getUri() Returns the URI for this container.
Iterable<ListBlobItem>	listBlobs() Returns an enumerable collection of blob items for the container.
Iterable<ListBlobItem>	listBlobs(String prefix) Returns an enumerable collection of blob items for the container whose names begin with the specified prefix.
Iterable<ListBlobItem>	listBlobs(String prefix, boolean useFlatBlobListing) Returns an enumerable collection of blob items for the container whose names begin with the specified prefix using the specified flat or hierarchical option.
Iterable<ListBlobItem>	listBlobs(String prefix, boolean useFlatBlobListing, EnumSet<BlobListingDetails> listingDetails, BlobRequestOptions options, OperationContext opContext) Returns an enumerable collection of blob items for the container whose names begin with the specified prefix, using the specified flat or hierarchical option, listing details options, request options, and operation context.
ResultSegment<ListBlobItem>	listBlobsSegmented() Returns a result segment of an enumerable collection of blob items in the container.
ResultSegment<ListBlobItem>	listBlobsSegmented(String prefix) Returns a result segment containing a collection of blob items whose names begin with the specified prefix.
ResultSegment<ListBlobItem>	listBlobsSegmented(String prefix, boolean useFlatBlobListing, EnumSet<BlobListingDetails> listingDetails, Integer maxResults, ResultContinuation continuationToken, BlobRequestOptions options, OperationContext opContext) Returns a result segment containing a collection of blob items whose names begin with the specified prefix, using the specified flat or hierarchical option, listing details options, request options, and operation context.
Iterable<CloudBlobContainer>	listContainers() Returns an enumerable collection of containers for the service client associated with this container.
Iterable<CloudBlobContainer>	listContainers(String prefix) Returns an enumerable collection of containers whose names begin with the specified prefix for the service client associated with this container.
Iterable<CloudBlobContainer>	listContainers(String prefix, ContainerListingDetails detailsIncluded, BlobRequestOptions options, OperationContext opContext) Returns an enumerable collection of containers whose names begin with the specified prefix for the service client associated with this container, using the specified details setting, request options, and operation context.
ResultSegment<CloudBlobContainer>	listContainersSegmented() Returns a result segment of an enumerable collection of containers for the service client associated with this container.
ResultSegment<CloudBlobContainer>	listContainersSegmented(String prefix) Returns a result segment of an enumerable collection of containers whose names begin with the specified prefix for the service client associated with this container.
ResultSegment<CloudBlobContainer>	listContainersSegmented(String prefix, ContainerListingDetails detailsIncluded, Integer maxResults, ResultContinuation continuationToken, BlobRequestOptions options, OperationContext opContext) Returns a result segment containing a collection of containers whose names begin with the specified prefix for the service client associated with this container, using the specified listing details options, request options, and operation context.
void	releaseLease(AccessCondition accessCondition) Releases the lease on the container.
void	releaseLease(AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Releases the lease on the container using the specified access conditions, request options, and operation context.
void	renewLease(AccessCondition accessCondition) Renews an existing lease with the specified access conditions.
void	renewLease(AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Renews an existing lease with the specified access conditions, request options, and operation context.
void	setMetadata(HashMap<String,String> metadata) Sets the metadata collection of name-value pairs to be set on the container with an uploadMetadata() call.
protected void	setProperties(BlobContainerProperties properties) Sets the properties for the container.
protected void	setStorageUri(StorageUri storageUri) Sets the list of URIs for all locations.
void	uploadMetadata() Uploads the container's metadata.
void	uploadMetadata(AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Uploads the container's metadata using the specified request options and operation context.
void	uploadPermissions(BlobContainerPermissions permissions) Uploads the container's permissions.
void	uploadPermissions(BlobContainerPermissions permissions, AccessCondition accessCondition, BlobRequestOptions options, OperationContext opContext) Uploads the container's permissions using the specified request options and operation context.

Methods inherited from class java.lang.Object

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

Field Detail

metadata

protected HashMap<String,String> metadata

Represents the container metadata.

Constructor Detail

CloudBlobContainer

public CloudBlobContainer(URI uri)
                   throws StorageException

Creates an instance of the CloudBlobContainer class using the specified URI. The blob URI should include a SAS token unless anonymous access is to be used.

Parameters:

uri - A java.net.URI object which represents the URI of the container.

Throws:

StorageException - If a storage service error occurred.

CloudBlobContainer

public CloudBlobContainer(StorageUri storageUri)
                   throws StorageException

Creates an instance of the CloudBlobContainer class using the specified URI. The blob URI should include a SAS token unless anonymous access is to be used.

Parameters:

storageUri - A StorageUri object which represents the URI of the container.

Throws:

StorageException - If a storage service error occurred.

CloudBlobContainer

public CloudBlobContainer(URI uri,
                          StorageCredentials credentials)
                   throws StorageException

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

Parameters:

uri - A java.net.URI object that represents the absolute URI of the container.

credentials - A StorageCredentials object used to authenticate access.

Throws:

StorageException - If a storage service error occurred.

CloudBlobContainer

public CloudBlobContainer(StorageUri storageUri,
                          StorageCredentials credentials)
                   throws StorageException

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

Parameters:

storageUri - A StorageUri object which represents the absolute StorageUri of the container.

credentials - A StorageCredentials object used to authenticate access.

Throws:

StorageException - If a storage service error occurred.

CloudBlobContainer

protected CloudBlobContainer(String containerName,
                             CloudBlobClient client)
                      throws URISyntaxException,
                             StorageException

Creates an instance of the CloudBlobContainer class using the specified name and client.

Parameters:

containerName - A String which represents the name of the container, which must adhere to container naming rules. The container name should not include any path separator characters (/). Container names must be lowercase, between 3-63 characters long and must start with a letter or number. Container names may contain only letters, numbers, and the dash (-) character.

client - A CloudBlobClient object that represents the associated service client, and that specifies the endpoint for the Blob service. *

Throws:

StorageException - If a storage service error occurred.

URISyntaxException - If the resource URI constructed based on the containerName is invalid.

See Also:

Naming and Referencing Containers, Blobs, and Metadata

Method Detail

create

@DoesServiceRequest
public void create()
                                throws StorageException

Creates the container.

Throws:

StorageException - If a storage service error occurred.

create

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

Creates the container using the specified options and operation context.

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.

create

@DoesServiceRequest
public void create(BlobContainerPublicAccessType accessType,
                                       BlobRequestOptions options,
                                       OperationContext opContext)
                                throws StorageException

Creates the container using the specified options and operation context.

Parameters:

accessType - A BlobContainerPublicAccessType object that specifies whether data in the container may be accessed publicly and what level of access is to be allowed.

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.

createIfNotExists

@DoesServiceRequest
public boolean createIfNotExists()
                                              throws StorageException

Creates the container if it does not exist.

Returns:

true if the container did not already exist and was created; otherwise, false.

Throws:

StorageException - If a storage service error occurred.

createIfNotExists

@DoesServiceRequest
public boolean createIfNotExists(BlobRequestOptions options,
                                                     OperationContext opContext)
                                              throws StorageException

Creates the container if it does not exist, using the specified request options and operation context.

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:

true if the container did not already exist and was created; otherwise, false.

Throws:

StorageException - If a storage service error occurred.

createIfNotExists

@DoesServiceRequest
public boolean createIfNotExists(BlobContainerPublicAccessType accessType,
                                                     BlobRequestOptions options,
                                                     OperationContext opContext)
                                              throws StorageException

Creates the container if it does not exist, using the specified request options and operation context.

Parameters:

accessType - A BlobContainerPublicAccessType object that specifies whether data in the container may be accessed publicly and what level of access is to be allowed.

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 container did not already exist and was created; otherwise, false.

Throws:

StorageException - If a storage service error occurred.

delete

@DoesServiceRequest
public void delete()
                                throws StorageException

Deletes the container.

Throws:

StorageException - If a storage service error occurred.

delete

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

Deletes the container using the specified request options and operation context.

Parameters:

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

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 boolean deleteIfExists()
                                           throws StorageException

Deletes the container if it exists.

Returns:

true if the container did not already exist and was created; otherwise, false.

Throws:

StorageException - If a storage service error occurred.

deleteIfExists

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

Deletes the container if it exists using the specified request options and operation context.

Parameters:

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

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 container existed and was deleted; otherwise, false.

Throws:

StorageException - If a storage service error occurred.

downloadAttributes

@DoesServiceRequest
public void downloadAttributes()
                                            throws StorageException

Downloads the container's attributes, which consist of metadata and properties.

Throws:

StorageException - If a storage service error occurred.

downloadAttributes

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

Downloads the container's attributes, which consist of metadata and properties, using the specified request options and operation context.

Parameters:

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

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.

downloadPermissions

@DoesServiceRequest
public BlobContainerPermissions downloadPermissions()
                                                                 throws StorageException

Downloads the permission settings for the container.

Returns:

A BlobContainerPermissions object that represents the container's permissions.

Throws:

StorageException - If a storage service error occurred.

downloadPermissions

@DoesServiceRequest
public BlobContainerPermissions downloadPermissions(AccessCondition accessCondition,
                                                                        BlobRequestOptions options,
                                                                        OperationContext opContext)
                                                                 throws StorageException

Downloads the permissions settings for the container using the specified request options and operation context.

Parameters:

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

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 BlobContainerPermissions object that represents the container's permissions.

Throws:

StorageException - If a storage service error occurred.

exists

@DoesServiceRequest
public boolean exists()
                                   throws StorageException

Returns a value that indicates whether the container exists.

Returns:

true if the container exists, otherwise false.

Throws:

StorageException - If a storage service error occurred.

exists

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

Returns a value that indicates whether the container exists, using the specified request options and operation context.

Parameters:

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

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 container exists, otherwise 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 container. Note this does not contain the leading "?".

Parameters:

policy - An SharedAccessBlobPolicy object that represents the access policy for the shared access signature.

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

Returns:

A String which represents a shared access signature for the container.

Throws:

StorageException - If a storage service error occurred.

InvalidKeyException - If the key is invalid.

generateSharedAccessSignature

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

Returns a shared access signature for the container. Note this does not contain the leading "?".

Parameters:

policy - An SharedAccessBlobPolicy object that represents the access policy for the shared access signature.

groupPolicyIdentifier - A String which 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 which represents a shared access signature for the container.

Throws:

StorageException - If a storage service error occurred.

InvalidKeyException - If the key is invalid.

getAppendBlobReference

public CloudAppendBlob getAppendBlobReference(String blobName)
                                       throws URISyntaxException,
                                              StorageException

Returns a reference to a CloudAppendBlob object that represents an append blob in this container.

Parameters:

blobName - A String that represents the name of the blob.

Returns:

A CloudAppendBlob object that represents a reference to the specified append blob.

Throws:

StorageException - If a storage service error occurred.

URISyntaxException - If the resource URI is invalid.

getAppendBlobReference

public CloudAppendBlob getAppendBlobReference(String blobName,
                                              String snapshotID)
                                       throws URISyntaxException,
                                              StorageException

Returns a reference to a CloudAppendBlob object that represents an append blob in the container, using the specified snapshot ID.

Parameters:

blobName - A String that represents the name of the blob.

snapshotID - A String that represents the snapshot ID of the blob.

Returns:

A CloudAppendBlob object that represents a reference to the specified append blob.

Throws:

StorageException - If a storage service error occurred.

URISyntaxException - If the resource URI is invalid.

getBlockBlobReference

public CloudBlockBlob getBlockBlobReference(String blobName)
                                     throws URISyntaxException,
                                            StorageException

Returns a reference to a CloudBlockBlob object that represents a block blob in this container.

Parameters:

blobName - A String that represents the name of the blob.

Returns:

A CloudBlockBlob object that represents a reference to the specified block blob.

Throws:

StorageException - If a storage service error occurred.

URISyntaxException - If the resource URI is invalid.

getBlockBlobReference

public CloudBlockBlob getBlockBlobReference(String blobName,
                                            String snapshotID)
                                     throws URISyntaxException,
                                            StorageException

Returns a reference to a CloudBlockBlob object that represents a block blob in this container, using the specified snapshot ID.

Parameters:

blobName - A String that represents the name of the blob.

snapshotID - A String that represents the snapshot ID of the blob.

Returns:

A CloudBlockBlob object that represents a reference to the specified block blob.

Throws:

StorageException - If a storage service error occurred.

URISyntaxException - If the resource URI is invalid.

getDirectoryReference

public CloudBlobDirectory getDirectoryReference(String directoryName)
                                         throws URISyntaxException

Returns a reference to a CloudBlobDirectory object that represents a virtual blob directory within this container.

Parameters:

directoryName - A String that represents the name of the virtual blob directory. If the root directory (the directory representing the container itself) is desired, use an empty string.

Returns:

A CloudBlobDirectory that represents a virtual blob directory within this container.

Throws:

URISyntaxException - If the resource URI is invalid.

getBlobReferenceFromServer

@DoesServiceRequest
public final CloudBlob getBlobReferenceFromServer(String blobName)
                                                               throws URISyntaxException,
                                                                      StorageException

Gets a reference to a blob in this container. The blob must already exist on the service. Unlike the other get*Reference methods, this method does a service request to retrieve the blob's metadata and properties. The returned blob may be used directly as a CloudBlob or cast using either instanceof or getProperties().getBlobType() to determine its subtype.

Parameters:

blobName - A String that represents the name of the blob.

Returns:

A CloudBlob object that represents a reference to the specified blob.

Throws:

StorageException - If a storage service error occurred.

URISyntaxException - If the resource URI is invalid.

getBlobReferenceFromServer

@DoesServiceRequest
public final CloudBlob getBlobReferenceFromServer(String blobName,
                                                                      String snapshotID,
                                                                      AccessCondition accessCondition,
                                                                      BlobRequestOptions options,
                                                                      OperationContext opContext)
                                                               throws URISyntaxException,
                                                                      StorageException

Gets a reference to a blob in this container. The blob must already exist on the service. Unlike the other get*Reference methods, this method does a service request to retrieve the blob's metadata and properties. The returned blob may be used directly as a CloudBlob or cast using either instanceof or getProperties().getBlobType() to determine its subtype.

Parameters:

blobName - A String that represents the name of the blob.

snapshotID - A String that represents the snapshot ID 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.

Returns:

A CloudBlob object that represents a reference to the specified blob.

Throws:

StorageException - If a storage service error occurred.

URISyntaxException - If the resource URI is invalid.

getMetadata

public HashMap<String,String> getMetadata()

Returns the metadata for the container. This value is initialized with the metadata from the queue by a call to downloadAttributes(), and is set on the queue with a call to uploadMetadata().

Returns:

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

getName

public String getName()

Returns the name of the container.

Returns:

A String that represents the name of the container.

getStorageUri

public StorageUri getStorageUri()

Returns the list of URIs for all locations.

Returns:

A StorageUri object which represents the list of URIs for all locations..

getPageBlobReference

public CloudPageBlob getPageBlobReference(String blobName)
                                   throws URISyntaxException,
                                          StorageException

Returns a reference to a CloudPageBlob object that represents a page blob in this container.

Parameters:

blobName - A String that represents the name of the blob.

Returns:

A CloudPageBlob object that represents a reference to the specified page blob.

Throws:

StorageException - If a storage service error occurred.

URISyntaxException - If the resource URI is invalid.

getPageBlobReference

public CloudPageBlob getPageBlobReference(String blobName,
                                          String snapshotID)
                                   throws URISyntaxException,
                                          StorageException

Returns a reference to a CloudPageBlob object that represents a page blob in the container, using the specified snapshot ID.

Parameters:

blobName - A String that represents the name of the blob.

snapshotID - A String that represents the snapshot ID of the blob.

Returns:

A CloudPageBlob object that represents a reference to the specified page blob.

Throws:

StorageException - If a storage service error occurred.

URISyntaxException - If the resource URI is invalid.

getProperties

public BlobContainerProperties getProperties()

Returns the properties for the container.

Returns:

A BlobContainerProperties object that represents the properties for the container.

getServiceClient

public CloudBlobClient getServiceClient()

Returns the Blob service client associated with this container.

Returns:

A CloudBlobClient object that represents the service client associated with this container.

getUri

public URI getUri()

Returns the URI for this container.

Returns:

The absolute URI to the container.

listBlobs

@DoesServiceRequest
public Iterable<ListBlobItem> listBlobs()

Returns an enumerable collection of blob items for the container.

Returns:

An enumerable collection of ListBlobItem objects retrieved lazily that represents the items in this container.

listBlobs

@DoesServiceRequest
public Iterable<ListBlobItem> listBlobs(String prefix)

Returns an enumerable collection of blob items for the container whose names begin with the specified prefix.

Parameters:

prefix - A String that represents the blob name prefix. This value must be preceded either by the name of the container or by the absolute path to the container.

Returns:

An enumerable collection of ListBlobItem objects retrieved lazily that represents the items whose names begin with the specified prefix in this container.

listBlobs

@DoesServiceRequest
public Iterable<ListBlobItem> listBlobs(String prefix,
                                                            boolean useFlatBlobListing)

Returns an enumerable collection of blob items for the container whose names begin with the specified prefix using the specified flat or hierarchical option.

Parameters:

prefix - A String that represents the blob name prefix. This value must be preceded either by the name of the container or by the absolute path to the container.

useFlatBlobListing - true to indicate that the returned list will be flat; false to indicate that the returned list will be hierarchical.

Returns:

An enumerable collection of ListBlobItem objects retrieved lazily that represents the items whose names begin with the specified prefix in this container.

listBlobs

@DoesServiceRequest
public Iterable<ListBlobItem> listBlobs(String prefix,
                                                            boolean useFlatBlobListing,
                                                            EnumSet<BlobListingDetails> listingDetails,
                                                            BlobRequestOptions options,
                                                            OperationContext opContext)

Returns an enumerable collection of blob items for the container whose names begin with the specified prefix, using the specified flat or hierarchical option, listing details options, request options, and operation context.

Parameters:

prefix - A String that represents the blob name prefix. This value must be preceded either by the name of the container or by the absolute path to the container.

useFlatBlobListing - true to indicate that the returned list will be flat; false to indicate that the returned list will be hierarchical.

listingDetails - A java.util.EnumSet object that contains BlobListingDetails values that indicate whether snapshots, metadata, and/or uncommitted blocks are returned. Committed blocks are always returned.

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 enumerable collection of ListBlobItem objects retrieved lazily that represents the items whose names begin with the specified prefix in this container.

listBlobsSegmented

@DoesServiceRequest
public ResultSegment<ListBlobItem> listBlobsSegmented()
                                                                   throws StorageException

Returns a result segment of an enumerable collection of blob items in the container.

Returns:

A ResultSegment object that contains a segment of the enumerable collection of ListBlobItem objects that represent the blob items in the container.

Throws:

StorageException - If a storage service error occurred.

listBlobsSegmented

@DoesServiceRequest
public ResultSegment<ListBlobItem> listBlobsSegmented(String prefix)
                                                                   throws StorageException

Returns a result segment containing a collection of blob items whose names begin with the specified prefix.

Parameters:

prefix - A String that represents the prefix of the blob name.

Returns:

A ResultSegment object that contains a segment of the enumerable collection of ListBlobItem objects that represent the blob items whose names begin with the specified prefix in the container.

Throws:

StorageException - If a storage service error occurred.

listBlobsSegmented

@DoesServiceRequest
public ResultSegment<ListBlobItem> listBlobsSegmented(String prefix,
                                                                          boolean useFlatBlobListing,
                                                                          EnumSet<BlobListingDetails> listingDetails,
                                                                          Integer maxResults,
                                                                          ResultContinuation continuationToken,
                                                                          BlobRequestOptions options,
                                                                          OperationContext opContext)
                                                                   throws StorageException

Returns a result segment containing a collection of blob items whose names begin with the specified prefix, using the specified flat or hierarchical option, listing details options, request options, and operation context.

Parameters:

prefix - A String that represents the prefix of the blob name.

useFlatBlobListing - true to indicate that the returned list will be flat; false to indicate that the returned list will be hierarchical.

listingDetails - A java.util.EnumSet object that contains BlobListingDetails values that indicate whether snapshots, metadata, and/or uncommitted blocks are returned. Committed blocks are always returned.

maxResults - The maximum number of results to retrieve. If null or greater than 5000, the server will return up to 5,000 items. Must be at least 1.

continuationToken - A ResultContinuation object that represents a continuation token returned by a previous listing operation.

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 ResultSegment object that contains a segment of the enumerable collection of ListBlobItem objects that represent the block items whose names begin with the specified prefix in the container.

Throws:

StorageException - If a storage service error occurred.

listContainers

@DoesServiceRequest
public Iterable<CloudBlobContainer> listContainers()

Returns an enumerable collection of containers for the service client associated with this container.

Returns:

An enumerable collection of CloudBlobContainer objects retrieved lazily that represent the containers for the service client associated with this container.

listContainers

@DoesServiceRequest
public Iterable<CloudBlobContainer> listContainers(String prefix)

Returns an enumerable collection of containers whose names begin with the specified prefix for the service client associated with this container.

Parameters:

prefix - A String that represents the container name prefix.

Returns:

An enumerable collection of CloudBlobContainer objects retrieved lazily that represent the containers whose names begin with the specified prefix for the service client associated with this container.

listContainers

@DoesServiceRequest
public Iterable<CloudBlobContainer> listContainers(String prefix,
                                                                       ContainerListingDetails detailsIncluded,
                                                                       BlobRequestOptions options,
                                                                       OperationContext opContext)

Returns an enumerable collection of containers whose names begin with the specified prefix for the service client associated with this container, using the specified details setting, request options, and operation context.

Parameters:

prefix - A String that represents the container name prefix.

detailsIncluded - A ContainerListingDetails value that indicates whether container metadata will be returned.

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 enumerable collection of CloudBlobContainer objects retrieved lazily that represents the containers for the service client associated with this container.

listContainersSegmented

@DoesServiceRequest
public ResultSegment<CloudBlobContainer> listContainersSegmented()
                                                                              throws StorageException

Returns a result segment of an enumerable collection of containers for the service client associated with this container.

Returns:

A ResultSegment object that contains a segment of the enumerable collection of CloudBlobContainer objects that represent the containers for the service client associated with this container.

Throws:

StorageException - If a storage service error occurred.

listContainersSegmented

@DoesServiceRequest
public ResultSegment<CloudBlobContainer> listContainersSegmented(String prefix)
                                                                              throws StorageException

Returns a result segment of an enumerable collection of containers whose names begin with the specified prefix for the service client associated with this container.

Parameters:

prefix - A String that represents the blob name prefix.

Returns:

A ResultSegment object that contains a segment of the enumerable collection of CloudBlobContainer objects that represent the containers whose names begin with the specified prefix for the service client associated with this container.

Throws:

StorageException - If a storage service error occurred.

listContainersSegmented

@DoesServiceRequest
public ResultSegment<CloudBlobContainer> listContainersSegmented(String prefix,
                                                                                     ContainerListingDetails detailsIncluded,
                                                                                     Integer maxResults,
                                                                                     ResultContinuation continuationToken,
                                                                                     BlobRequestOptions options,
                                                                                     OperationContext opContext)
                                                                              throws StorageException

Returns a result segment containing a collection of containers whose names begin with the specified prefix for the service client associated with this container, using the specified listing details options, request options, and operation context.

Parameters:

prefix - A String that represents the prefix of the container name.

detailsIncluded - A ContainerListingDetails object that indicates whether metadata is included.

maxResults - The maximum number of results to retrieve. If null or greater than 5000, the server will return up to 5,000 items. Must be at least 1.

continuationToken - A ResultContinuation object that represents a continuation token returned by a previous listing operation.

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 ResultSegment object that contains a segment of the enumerable collection of CloudBlobContainer objects that represent the containers whose names begin with the specified prefix for the service client associated with this container.

Throws:

StorageException - If a storage service error occurred.

setMetadata

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

Sets the metadata collection of name-value pairs to be set on the container with an uploadMetadata() call. This collection will overwrite any existing container metadata. If this is set to an empty collection, the container metadata will be cleared on an uploadMetadata() call.

Parameters:

metadata - A java.util.HashMap object that represents the metadata being assigned to the container.

setStorageUri

protected void setStorageUri(StorageUri storageUri)

Sets the list of URIs for all locations.

Parameters:

storageUri - A StorageUri object which represents the list of URIs for all locations.

setProperties

protected void setProperties(BlobContainerProperties properties)

Sets the properties for the container.

Parameters:

properties - A BlobContainerProperties object that represents the properties being assigned to the container.

uploadMetadata

@DoesServiceRequest
public void uploadMetadata()
                                        throws StorageException

Uploads the container's metadata.

Throws:

StorageException - If a storage service error occurred.

uploadMetadata

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

Uploads the container's metadata using the specified request options and operation context.

Parameters:

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

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.

uploadPermissions

@DoesServiceRequest
public void uploadPermissions(BlobContainerPermissions permissions)
                                           throws StorageException

Uploads the container's permissions.

Parameters:

permissions - A BlobContainerPermissions object that represents the permissions to upload.

Throws:

StorageException - If a storage service error occurred.

uploadPermissions

@DoesServiceRequest
public void uploadPermissions(BlobContainerPermissions permissions,
                                                  AccessCondition accessCondition,
                                                  BlobRequestOptions options,
                                                  OperationContext opContext)
                                           throws StorageException

Uploads the container's permissions using the specified request options and operation context.

Parameters:

permissions - A BlobContainerPermissions object that represents the permissions to upload.

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

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 container.

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 container 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 container 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 container.

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.

renewLease

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

Renews an existing lease with the specified access conditions.

Parameters:

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

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 with the specified access conditions, request options, and operation context.

Parameters:

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.

Throws:

StorageException - If a storage service error occurred.

releaseLease

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

Releases the lease on the container.

Parameters:

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

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 container using the specified access conditions, request options, and operation context.

Parameters:

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.

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

Returns:

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:

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. This cannot be null.

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.