com.azure.storage.blob

Class BlobContainerClient

java.lang.Object

com.azure.storage.blob.BlobContainerClient

public final class BlobContainerClient
extends Object

Client to a container. It may only be instantiated through a BlobContainerClientBuilder or via the method BlobServiceClient.getBlobContainerClient(String). This class does not hold any state about a particular container but is instead a convenient way of sending off appropriate requests to the resource on the service. It may also be used to construct URLs to blobs.

This client contains operations on a container. Operations on a blob are available on BlobClient through BlobContainerClient.getBlobClient(String), and operations on the service are available on BlobServiceClient.

Please refer to the Azure Docs for more information on containers.

Field Summary

Fields

Modifier and Type	Field and Description
static String	LOG_CONTAINER_NAME
static String	ROOT_CONTAINER_NAME
static String	STATIC_WEBSITE_CONTAINER_NAME

Method Summary

Modifier and Type	Method and Description
void	create() Creates a new container within a storage account.
Response<Void>	createWithResponse(Map<String,String> metadata, PublicAccessType accessType, Duration timeout, Context context) Creates a new container within a storage account.
void	delete() Marks the specified container for deletion.
Response<Void>	deleteWithResponse(BlobRequestConditions accessConditions, Duration timeout, Context context) Marks the specified container for deletion.
boolean	exists() Gets if the container this client represents exists in the cloud.
Response<Boolean>	existsWithResponse(Duration timeout, Context context) Gets if the container this client represents exists in the cloud.
BlobContainerAccessPolicies	getAccessPolicy() Returns the container's permissions.
Response<BlobContainerAccessPolicies>	getAccessPolicyWithResponse(String leaseId, Duration timeout, Context context) Returns the container's permissions.
StorageAccountInfo	getAccountInfo(Duration timeout) Returns the sku name and account kind for the account.
Response<StorageAccountInfo>	getAccountInfoWithResponse(Duration timeout, Context context) Returns the sku name and account kind for the account.
String	getAccountName() Get associated account name.
BlobClient	getBlobClient(String blobName) Initializes a new BlobClient object by concatenating blobName to the end of ContainerAsyncClient's URL.
BlobClient	getBlobClient(String blobName, String snapshot) Initializes a new BlobClient object by concatenating blobName to the end of ContainerAsyncClient's URL.
String	getBlobContainerName() Get the container name.
String	getBlobContainerUrl() Gets the URL of the container represented by this client.
CpkInfo	getCustomerProvidedKey() Gets the CpkInfo associated with this client that will be passed to BlobClients when getBlobClient is called.
HttpPipeline	getHttpPipeline() Gets the HttpPipeline powering this client.
BlobContainerProperties	getProperties() Returns the container's metadata and system properties.
Response<BlobContainerProperties>	getPropertiesWithResponse(String leaseId, Duration timeout, Context context) Returns the container's metadata and system properties.
BlobServiceVersion	getServiceVersion() Gets the service version the client is using.
PagedIterable<BlobItem>	listBlobs() Returns a lazy loaded list of blobs in this container, with folder structures flattened.
PagedIterable<BlobItem>	listBlobs(ListBlobsOptions options, Duration timeout) Returns a lazy loaded list of blobs in this container, with folder structures flattened.
PagedIterable<BlobItem>	listBlobsByHierarchy(String directory) Returns a reactive Publisher emitting all the blobs and directories (prefixes) under the given directory (prefix).
PagedIterable<BlobItem>	listBlobsByHierarchy(String delimiter, ListBlobsOptions options, Duration timeout) Returns a reactive Publisher emitting all the blobs and prefixes (directories) under the given prefix (directory).
void	setAccessPolicy(PublicAccessType accessType, List<BlobSignedIdentifier> identifiers) Sets the container's permissions.
Response<Void>	setAccessPolicyWithResponse(PublicAccessType accessType, List<BlobSignedIdentifier> identifiers, BlobRequestConditions accessConditions, Duration timeout, Context context) Sets the container's permissions.
void	setMetadata(Map<String,String> metadata) Sets the container's metadata.
Response<Void>	setMetadataWithResponse(Map<String,String> metadata, BlobRequestConditions accessConditions, Duration timeout, Context context) Sets the container's metadata.

Methods inherited from class java.lang.Object

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

Field Detail

ROOT_CONTAINER_NAME

public static final String ROOT_CONTAINER_NAME

See Also:

Constant Field Values

STATIC_WEBSITE_CONTAINER_NAME

public static final String STATIC_WEBSITE_CONTAINER_NAME

See Also:

Constant Field Values

LOG_CONTAINER_NAME

public static final String LOG_CONTAINER_NAME

See Also:

Constant Field Values

Method Detail

getBlobClient

public BlobClient getBlobClient(String blobName)

Initializes a new BlobClient object by concatenating blobName to the end of ContainerAsyncClient's URL. The new BlobClient uses the same request policy pipeline as the ContainerAsyncClient. To change the pipeline, create the BlobClient and then call its WithPipeline method passing in the desired pipeline object. Or, call this package's getBlobAsyncClient instead of calling this object's getBlobAsyncClient method.

Parameters:

blobName - A String representing the name of the blob.

Code Samples

BlobClient blobClient = client.getBlobClient(blobName);

Returns:

A new BlobClient object which references the blob with the specified name in this container.

getBlobClient

public BlobClient getBlobClient(String blobName,
                                String snapshot)

Initializes a new BlobClient object by concatenating blobName to the end of ContainerAsyncClient's URL. The new BlobClient uses the same request policy pipeline as the ContainerAsyncClient. To change the pipeline, create the BlobClient and then call its WithPipeline method passing in the desired pipeline object. Or, call this package's getBlobAsyncClient instead of calling this object's getBlobAsyncClient method.

Code Samples

BlobClient blobClient = client.getBlobClient(blobName, snapshot);

Parameters:

blobName - A String representing the name of the blob.

snapshot - the snapshot identifier for the blob.

Returns:

A new BlobClient object which references the blob with the specified name in this container.

getBlobContainerName

public String getBlobContainerName()

Get the container name.

Code Samples

String containerName = client.getBlobContainerName();
System.out.println("The name of the blob is " + containerName);

Returns:

The name of container.

getBlobContainerUrl

public String getBlobContainerUrl()

Gets the URL of the container represented by this client.

Returns:

the URL.

getAccountName

public String getAccountName()

Get associated account name.

Returns:

account name associated with this storage resource.

getServiceVersion

public BlobServiceVersion getServiceVersion()

Gets the service version the client is using.

Returns:

the service version the client is using.

getHttpPipeline

public HttpPipeline getHttpPipeline()

Gets the HttpPipeline powering this client.

Returns:

The pipeline.

getCustomerProvidedKey

public CpkInfo getCustomerProvidedKey()

Gets the CpkInfo associated with this client that will be passed to BlobClients when getBlobClient is called.

Returns:

the customer provided key used for encryption.

exists

public boolean exists()

Gets if the container this client represents exists in the cloud.

Code Samples

System.out.printf("Exists? %b%n", client.exists());

Returns:

true if the container exists, false if it doesn't

existsWithResponse

public Response<Boolean> existsWithResponse(Duration timeout,
                                            Context context)

Gets if the container this client represents exists in the cloud.

Code Samples

Context context = new Context("Key", "Value");
System.out.printf("Exists? %b%n", client.existsWithResponse(timeout, context).getValue());

Parameters:

timeout - An optional timeout value beyond which a RuntimeException will be raised.

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

true if the container exists, false if it doesn't

create

public void create()

Creates a new container within a storage account. If a container with the same name already exists, the operation fails. For more information, see the Azure Docs.

Code Samples

try {
    client.create();
    System.out.printf("Create completed%n");
} catch (BlobStorageException error) {
    if (error.getErrorCode().equals(BlobErrorCode.CONTAINER_ALREADY_EXISTS)) {
        System.out.printf("Can't create container. It already exists %n");
    }
}

createWithResponse

public Response<Void> createWithResponse(Map<String,String> metadata,
                                         PublicAccessType accessType,
                                         Duration timeout,
                                         Context context)

Creates a new container within a storage account. If a container with the same name already exists, the operation fails. For more information, see the Azure Docs.

Code Samples

Map<String, String> metadata = Collections.singletonMap("metadata", "value");
Context context = new Context("Key", "Value");

System.out.printf("Create completed with status %d%n",
    client.createWithResponse(metadata, PublicAccessType.CONTAINER, timeout, context).getStatusCode());

Parameters:

metadata - Metadata to associate with the container.

accessType - Specifies how the data in this container is available to the public. See the x-ms-blob-public-access header in the Azure Docs for more information. Pass null for no public access.

timeout - An optional timeout value beyond which a RuntimeException will be raised.

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

A response containing status code and HTTP headers

delete

public void delete()

Marks the specified container for deletion. The container and any blobs contained within it are later deleted during garbage collection. For more information, see the Azure Docs.

Code Samples

try {
    client.delete();
    System.out.printf("Delete completed%n");
} catch (BlobStorageException error) {
    if (error.getErrorCode().equals(BlobErrorCode.CONTAINER_NOT_FOUND)) {
        System.out.printf("Delete failed. Container was not found %n");
    }
}

deleteWithResponse

public Response<Void> deleteWithResponse(BlobRequestConditions accessConditions,
                                         Duration timeout,
                                         Context context)

Marks the specified container for deletion. The container and any blobs contained within it are later deleted during garbage collection. For more information, see the Azure Docs.

Code Samples

BlobRequestConditions accessConditions = new BlobRequestConditions()
    .setLeaseId(leaseId)
    .setIfUnmodifiedSince(OffsetDateTime.now().minusDays(3));
Context context = new Context("Key", "Value");

System.out.printf("Delete completed with status %d%n", client.deleteWithResponse(
    accessConditions, timeout, context).getStatusCode());

Parameters:

accessConditions - BlobRequestConditions

timeout - An optional timeout value beyond which a RuntimeException will be raised.

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

A response containing status code and HTTP headers

getProperties

public BlobContainerProperties getProperties()

Returns the container's metadata and system properties. For more information, see the Azure Docs.

Code Samples

BlobContainerProperties properties = client.getProperties();
System.out.printf("Public Access Type: %s, Legal Hold? %b, Immutable? %b%n",
    properties.getBlobPublicAccess(),
    properties.hasLegalHold(),
    properties.hasImmutabilityPolicy());

Returns:

The container properties.

getPropertiesWithResponse

public Response<BlobContainerProperties> getPropertiesWithResponse(String leaseId,
                                                                   Duration timeout,
                                                                   Context context)

Returns the container's metadata and system properties. For more information, see the Azure Docs.

Code Samples

Context context = new Context("Key", "Value");

BlobContainerProperties properties = client.getPropertiesWithResponse(leaseId, timeout, context)
    .getValue();
System.out.printf("Public Access Type: %s, Legal Hold? %b, Immutable? %b%n",
    properties.getBlobPublicAccess(),
    properties.hasLegalHold(),
    properties.hasImmutabilityPolicy());

Parameters:

leaseId - The lease ID the active lease on the container must match.

timeout - An optional timeout value beyond which a RuntimeException will be raised.

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

The container properties.

setMetadata

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

Sets the container's metadata. For more information, see the Azure Docs.

Code Samples

Map<String, String> metadata = Collections.singletonMap("metadata", "value");
try {
    client.setMetadata(metadata);
    System.out.printf("Set metadata completed with status %n");
} catch (UnsupportedOperationException error) {
    System.out.printf("Fail while setting metadata %n");
}

Parameters:

metadata - Metadata to associate with the container.

setMetadataWithResponse

public Response<Void> setMetadataWithResponse(Map<String,String> metadata,
                                              BlobRequestConditions accessConditions,
                                              Duration timeout,
                                              Context context)

Sets the container's metadata. For more information, see the Azure Docs.

Code Samples

Map<String, String> metadata = Collections.singletonMap("metadata", "value");
BlobRequestConditions accessConditions = new BlobRequestConditions()
    .setLeaseId(leaseId)
    .setIfUnmodifiedSince(OffsetDateTime.now().minusDays(3));
Context context = new Context("Key", "Value");

System.out.printf("Set metadata completed with status %d%n",
    client.setMetadataWithResponse(metadata, accessConditions, timeout, context).getStatusCode());

Parameters:

metadata - Metadata to associate with the container.

accessConditions - BlobRequestConditions

timeout - An optional timeout value beyond which a RuntimeException will be raised.

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

A response containing status code and HTTP headers

getAccessPolicy

public BlobContainerAccessPolicies getAccessPolicy()

Returns the container's permissions. The permissions indicate whether container's blobs may be accessed publicly. For more information, see the Azure Docs.

Code Samples

BlobContainerAccessPolicies accessPolicies = client.getAccessPolicy();
System.out.printf("Blob Access Type: %s%n", accessPolicies.getBlobAccessType());

for (BlobSignedIdentifier identifier : accessPolicies.getIdentifiers()) {
    System.out.printf("Identifier Name: %s, Permissions %s%n",
        identifier.getId(),
        identifier.getAccessPolicy().getPermissions());
}

Returns:

The container access policy.

getAccessPolicyWithResponse

public Response<BlobContainerAccessPolicies> getAccessPolicyWithResponse(String leaseId,
                                                                         Duration timeout,
                                                                         Context context)

Returns the container's permissions. The permissions indicate whether container's blobs may be accessed publicly. For more information, see the Azure Docs.

Code Samples

Context context = new Context("Key", "Value");
BlobContainerAccessPolicies accessPolicies = client.getAccessPolicyWithResponse(leaseId, timeout, context)
    .getValue();
System.out.printf("Blob Access Type: %s%n", accessPolicies.getBlobAccessType());

for (BlobSignedIdentifier identifier : accessPolicies.getIdentifiers()) {
    System.out.printf("Identifier Name: %s, Permissions %s%n",
        identifier.getId(),
        identifier.getAccessPolicy().getPermissions());
}

Parameters:

leaseId - The lease ID the active lease on the container must match.

timeout - An optional timeout value beyond which a RuntimeException will be raised.

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

The container access policy.

setAccessPolicy

public void setAccessPolicy(PublicAccessType accessType,
                            List<BlobSignedIdentifier> identifiers)

Sets the container's permissions. The permissions indicate whether blobs in a container may be accessed publicly. Note that, for each signed identifier, we will truncate the start and expiry times to the nearest second to ensure the time formatting is compatible with the service. For more information, see the Azure Docs.

Code Samples

BlobSignedIdentifier identifier = new BlobSignedIdentifier()
    .setId("name")
    .setAccessPolicy(new BlobAccessPolicy()
        .setStartsOn(OffsetDateTime.now())
        .setExpiresOn(OffsetDateTime.now().plusDays(7))
        .setPermissions("permissionString"));

try {
    client.setAccessPolicy(PublicAccessType.CONTAINER, Collections.singletonList(identifier));
    System.out.printf("Set Access Policy completed %n");
} catch (UnsupportedOperationException error) {
    System.out.printf("Set Access Policy completed %s%n", error);
}

Parameters:

accessType - Specifies how the data in this container is available to the public. See the x-ms-blob-public-access header in the Azure Docs for more information. Pass null for no public access.

identifiers - A list of BlobSignedIdentifier objects that specify the permissions for the container. Please see here for more information. Passing null will clear all access policies.

setAccessPolicyWithResponse

public Response<Void> setAccessPolicyWithResponse(PublicAccessType accessType,
                                                  List<BlobSignedIdentifier> identifiers,
                                                  BlobRequestConditions accessConditions,
                                                  Duration timeout,
                                                  Context context)

Sets the container's permissions. The permissions indicate whether blobs in a container may be accessed publicly. Note that, for each signed identifier, we will truncate the start and expiry times to the nearest second to ensure the time formatting is compatible with the service. For more information, see the Azure Docs.

Code Samples

BlobSignedIdentifier identifier = new BlobSignedIdentifier()
    .setId("name")
    .setAccessPolicy(new BlobAccessPolicy()
        .setStartsOn(OffsetDateTime.now())
        .setExpiresOn(OffsetDateTime.now().plusDays(7))
        .setPermissions("permissionString"));

BlobRequestConditions accessConditions = new BlobRequestConditions()
    .setLeaseId(leaseId)
    .setIfUnmodifiedSince(OffsetDateTime.now().minusDays(3));

Context context = new Context("Key", "Value");

System.out.printf("Set access policy completed with status %d%n",
    client.setAccessPolicyWithResponse(PublicAccessType.CONTAINER,
        Collections.singletonList(identifier),
        accessConditions,
        timeout,
        context).getStatusCode());

Parameters:

accessType - Specifies how the data in this container is available to the public. See the x-ms-blob-public-access header in the Azure Docs for more information. Pass null for no public access.

identifiers - A list of BlobSignedIdentifier objects that specify the permissions for the container. Please see here for more information. Passing null will clear all access policies.

accessConditions - BlobRequestConditions

timeout - An optional timeout value beyond which a RuntimeException will be raised.

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

A response containing status code and HTTP headers

listBlobs

public PagedIterable<BlobItem> listBlobs()

Returns a lazy loaded list of blobs in this container, with folder structures flattened. The returned PagedIterable can be consumed through while new items are automatically retrieved as needed.

Blob names are returned in lexicographic order.

For more information, see the Azure Docs.

Code Samples

client.listBlobs().forEach(blob ->
    System.out.printf("Name: %s, Directory? %b%n", blob.getName(), blob.isPrefix()));

Returns:

The listed blobs, flattened.

listBlobs

public PagedIterable<BlobItem> listBlobs(ListBlobsOptions options,
                                         Duration timeout)

Returns a lazy loaded list of blobs in this container, with folder structures flattened. The returned PagedIterable can be consumed through while new items are automatically retrieved as needed.

Blob names are returned in lexicographic order.

For more information, see the Azure Docs.

Code Samples

ListBlobsOptions options = new ListBlobsOptions()
    .setPrefix("prefixToMatch")
    .setDetails(new BlobListDetails()
        .setRetrieveDeletedBlobs(true)
        .setRetrieveSnapshots(true));

client.listBlobs(options, timeout).forEach(blob ->
    System.out.printf("Name: %s, Directory? %b, Deleted? %b, Snapshot ID: %s%n",
        blob.getName(),
        blob.isPrefix(),
        blob.isDeleted(),
        blob.getSnapshot()));

Parameters:

options - ListBlobsOptions

timeout - An optional timeout value beyond which a RuntimeException will be raised.

Returns:

The listed blobs, flattened.

listBlobsByHierarchy

public PagedIterable<BlobItem> listBlobsByHierarchy(String directory)

Returns a reactive Publisher emitting all the blobs and directories (prefixes) under the given directory (prefix). Directories will have BlobItem.isPrefix() set to true.

Blob names are returned in lexicographic order. For more information, see the Azure Docs.

E.g. listing a container containing a 'foo' folder, which contains blobs 'foo1' and 'foo2', and a blob on the root level 'bar', will return the following results when prefix=null:

• foo/ (isPrefix = true)
• bar (isPrefix = false)

will return the following results when prefix="foo/":

• foo/foo1 (isPrefix = false)
• foo/foo2 (isPrefix = false)

Code Samples

client.listBlobsByHierarchy("directoryName").forEach(blob ->
    System.out.printf("Name: %s, Directory? %b%n", blob.getName(), blob.isPrefix()));

Parameters:

directory - The directory to list blobs underneath

Returns:

A reactive response emitting the prefixes and blobs.

listBlobsByHierarchy

public PagedIterable<BlobItem> listBlobsByHierarchy(String delimiter,
                                                    ListBlobsOptions options,
                                                    Duration timeout)

Returns a reactive Publisher emitting all the blobs and prefixes (directories) under the given prefix (directory). Directories will have BlobItem.isPrefix() set to true.

Blob names are returned in lexicographic order. For more information, see the Azure Docs.

E.g. listing a container containing a 'foo' folder, which contains blobs 'foo1' and 'foo2', and a blob on the root level 'bar', will return the following results when prefix=null:

• foo/ (isPrefix = true)
• bar (isPrefix = false)

will return the following results when prefix="foo/":

• foo/foo1 (isPrefix = false)
• foo/foo2 (isPrefix = false)

Code Samples

ListBlobsOptions options = new ListBlobsOptions()
    .setPrefix("directoryName")
    .setDetails(new BlobListDetails()
        .setRetrieveDeletedBlobs(true)
        .setRetrieveSnapshots(true));

client.listBlobsByHierarchy("/", options, timeout).forEach(blob ->
    System.out.printf("Name: %s, Directory? %b, Deleted? %b, Snapshot ID: %s%n",
        blob.getName(),
        blob.isPrefix(),
        blob.isDeleted(),
        blob.getSnapshot()));

Parameters:

delimiter - The delimiter for blob hierarchy, "/" for hierarchy based on directories

options - ListBlobsOptions

timeout - An optional timeout value beyond which a RuntimeException will be raised.

Returns:

A reactive response emitting the prefixes and blobs.

getAccountInfo

public StorageAccountInfo getAccountInfo(Duration timeout)

Returns the sku name and account kind for the account. For more information, please see the Azure Docs.

Parameters:

timeout - An optional timeout value beyond which a RuntimeException will be raised.

Code Samples

StorageAccountInfo accountInfo = client.getAccountInfo(timeout);
System.out.printf("Account Kind: %s, SKU: %s%n", accountInfo.getAccountKind(), accountInfo.getSkuName());

Returns:

The account info.

getAccountInfoWithResponse

public Response<StorageAccountInfo> getAccountInfoWithResponse(Duration timeout,
                                                               Context context)

Returns the sku name and account kind for the account. For more information, please see the Azure Docs.

Code Samples

Context context = new Context("Key", "Value");
StorageAccountInfo accountInfo = client.getAccountInfoWithResponse(timeout, context).getValue();
System.out.printf("Account Kind: %s, SKU: %s%n", accountInfo.getAccountKind(), accountInfo.getSkuName());

Parameters:

timeout - An optional timeout value beyond which a RuntimeException will be raised.

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

The account info.