All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.microsoft.azure.storage.blob.CloudBlobClient Maven / Gradle / Ivy

There is a newer version: 8.6.6
Show newest version
/**
 * Copyright Microsoft Corporation
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.microsoft.azure.storage.blob;

import java.net.HttpURLConnection;
import java.net.URI;
import java.net.URISyntaxException;

import com.microsoft.azure.storage.DoesServiceRequest;
import com.microsoft.azure.storage.OperationContext;
import com.microsoft.azure.storage.ResultContinuation;
import com.microsoft.azure.storage.ResultContinuationType;
import com.microsoft.azure.storage.ResultSegment;
import com.microsoft.azure.storage.ServiceClient;
import com.microsoft.azure.storage.ServiceProperties;
import com.microsoft.azure.storage.ServiceStats;
import com.microsoft.azure.storage.StorageCredentials;
import com.microsoft.azure.storage.StorageException;
import com.microsoft.azure.storage.StorageUri;
import com.microsoft.azure.storage.core.ExecutionEngine;
import com.microsoft.azure.storage.core.LazySegmentedIterable;
import com.microsoft.azure.storage.core.ListResponse;
import com.microsoft.azure.storage.core.ListingContext;
import com.microsoft.azure.storage.core.SegmentedStorageRequest;
import com.microsoft.azure.storage.core.StorageRequest;
import com.microsoft.azure.storage.core.Utility;

/**
 * Provides a client for accessing the Microsoft Azure Blob service.
 * 

* This class provides a point of access to the Blob service. The service client encapsulates the base URI for the Blob * service. If the service client will be used for authenticated access, it also encapsulates the credentials for * accessing the storage account. */ public final class CloudBlobClient extends ServiceClient { /** * Holds the default delimiter that may be used to create a virtual directory structure of blobs. */ private String directoryDelimiter = BlobConstants.DEFAULT_DELIMITER; /** * Holds the default request option values associated with this Service Client. */ private BlobRequestOptions defaultRequestOptions = new BlobRequestOptions(); /** * Creates an instance of the CloudBlobClient class using the specified Blob service endpoint and * anonymous credentials. * * @param baseUri * A java.net.URI object that represents the Blob service endpoint used to create the * client. */ public CloudBlobClient(final URI baseUri) { this(new StorageUri(baseUri), null /* credentials */); } /** * Creates an instance of the CloudBlobClient class using the specified Blob service endpoint and * anonymous credentials. * * @param baseUri * A {@link StorageUri} object that represents the Blob service endpoint used to create the * client. */ public CloudBlobClient(final StorageUri baseUri) { this(baseUri, null /* credentials */); } /** * Creates an instance of the CloudBlobClient class using the specified Blob service endpoint and * account credentials. * * @param baseUri * A java.net.URI object that represents the Blob service endpoint used to create the * client. * @param credentials * A {@link StorageCredentials} object that represents the account credentials. */ public CloudBlobClient(final URI baseUri, StorageCredentials credentials) { this(new StorageUri(baseUri), credentials); } /** * Creates an instance of the CloudBlobClient class using the specified Blob service endpoint and * account credentials. * * @param storageUri * A {@link StorageUri} object that represents the Blob service endpoint used to create the * client. * @param credentials * A {@link StorageCredentials} object that represents the account credentials. */ public CloudBlobClient(final StorageUri storageUri, StorageCredentials credentials) { super(storageUri, credentials); BlobRequestOptions.applyDefaults(this.defaultRequestOptions, BlobType.UNSPECIFIED); } /** * Gets a {@link CloudBlobContainer} object with the specified name. * * @param containerName * 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. * * @return A reference to a {@link CloudBlobContainer} object. * * @throws URISyntaxException * If the resource URI constructed based on the containerName is invalid. * @throws StorageException * If a storage service error occurred. * * @see Naming and Referencing Containers, Blobs, * and Metadata */ public CloudBlobContainer getContainerReference(final String containerName) throws URISyntaxException, StorageException { return new CloudBlobContainer(containerName, this); } /** * Returns the value for the default delimiter used for cloud blob directories. The default is '/'. * * @return A String which represents the value for the default delimiter. */ public String getDirectoryDelimiter() { return this.directoryDelimiter; } /** * Returns an enumerable collection of blob containers for this Blob service client. * * @return An enumerable collection of {@link CloudBlobContainer} objects retrieved lazily that represent the * containers for this client. */ @DoesServiceRequest public Iterable listContainers() { return this .listContainersWithPrefix(null, ContainerListingDetails.NONE, null /* options */, null /* opContext */); } /** * Returns an enumerable collection of blob containers whose names begin with the specified prefix for this Blob * service client. * * @param prefix * A String that represents the container name prefix. * * @return An enumerable collection of {@link CloudBlobContainer} objects retrieved lazily that represent the * containers for this client whose names begin with the specified prefix. */ @DoesServiceRequest public Iterable listContainers(final String prefix) { return this .listContainersWithPrefix(prefix, ContainerListingDetails.NONE, null /* options */, null /* opContext */); } /** * Returns an enumerable collection of blob containers whose names begin with the specified prefix for this Blob * service client, using the specified details setting, request options, and operation context. * * @param prefix * A String that represents the container name prefix. * @param detailsIncluded * A {@link ContainerListingDetails} value that indicates whether container metadata will be returned. * @param options * A {@link BlobRequestOptions} object that specifies any additional options for the request. Specifying * null will use the default request options from the associated service client ( * {@link CloudBlobClient}). * @param opContext * An {@link 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. * * @return An enumerable collection of {@link CloudBlobContainer} objects retrieved lazily that represents the * containers for this client. */ @DoesServiceRequest public Iterable listContainers(final String prefix, final ContainerListingDetails detailsIncluded, final BlobRequestOptions options, final OperationContext opContext) { return this.listContainersWithPrefix(prefix, detailsIncluded, options, opContext); } /** * Returns a result segment of an enumerable collection of blob containers for this Blob service client. * * @return A {@link ResultSegment} object that contains a segment of the enumerable collection of * {@link CloudBlobContainer} objects that represent the containers for this client. * * @throws StorageException * If a storage service error occurred. */ @DoesServiceRequest public ResultSegment listContainersSegmented() throws StorageException { return this.listContainersSegmented(null, ContainerListingDetails.NONE, null, null /* continuationToken */, null /* options */, null /* opContext */); } /** * Returns a result segment of an enumerable collection of blob containers whose names begin with the specified * prefix for this Blob service client. * * @param prefix * A String that represents the prefix of the container name. * * @return A {@link ResultSegment} object that contains a segment of the enumerable collection of * {@link CloudBlobContainer} objects that represent the containers whose names begin with the specified * prefix. * * @throws StorageException * If a storage service error occurred. */ @DoesServiceRequest public ResultSegment listContainersSegmented(final String prefix) throws StorageException { return this.listContainersWithPrefixSegmented(prefix, ContainerListingDetails.NONE, null, null /* continuationToken */, null /* options */, null /* opContext */); } /** * Returns a result segment of an enumerable collection of blob containers whose names begin with the specified * prefix for this Blob service client, using the specified listing details options, request options, and operation * context. * * @param prefix * A String that represents the prefix of the container name. * @param detailsIncluded * A {@link ContainerListingDetails} value that indicates whether container metadata will be returned. * @param 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. * @param continuationToken * A {@link ResultContinuation} object that represents a continuation token returned * by a previous listing operation. * @param options * A {@link BlobRequestOptions} object that specifies any additional options for the * request. Specifying null will use the default request options from * the associated service client ({@link CloudBlobClient}). * @param opContext * An {@link 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. * * @return A {@link ResultSegment} object that contains a segment of the enumerable collection of * {@link CloudBlobContainer} objects that represent the containers for this Blob service client. * * @throws StorageException * If a storage service error occurred. */ @DoesServiceRequest public ResultSegment listContainersSegmented(final String prefix, final ContainerListingDetails detailsIncluded, final Integer maxResults, final ResultContinuation continuationToken, final BlobRequestOptions options, final OperationContext opContext) throws StorageException { return this.listContainersWithPrefixSegmented(prefix, detailsIncluded, maxResults, continuationToken, options, opContext); } /** * Returns an enumerable collection of blob containers for this Blob service client whose names begin with the * specified prefix, using the * specified details setting, request options, and operation context. * * @param prefix * A String that represents the prefix of the container name. * @param detailsIncluded * A {@link ContainerListingDetails} value that indicates whether container metadata will be returned. * @param options * A {@link BlobRequestOptions} object that specifies any additional options for the request. Specifying * null will use the default request options from the associated service client ( * {@link CloudBlobClient}). * @param opContext * An {@link 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. * * @return An enumerable collection of {@link CloudBlobContainer} objects retrieved lazily that represent the * containers whose names begin with the specified prefix. */ private Iterable listContainersWithPrefix(final String prefix, final ContainerListingDetails detailsIncluded, BlobRequestOptions options, OperationContext opContext) { if (opContext == null) { opContext = new OperationContext(); } opContext.initialize(); options = BlobRequestOptions.populateAndApplyDefaults(options, BlobType.UNSPECIFIED, this); SegmentedStorageRequest segmentedRequest = new SegmentedStorageRequest(); return new LazySegmentedIterable( this.listContainersWithPrefixSegmentedImpl(prefix, detailsIncluded, null, options, segmentedRequest), this, null, options.getRetryPolicyFactory(), opContext); } /** * Returns a result segment of an enumerable collection of blob containers whose names begin with the specified * prefix for this Blob service client, using the specified listing details options, request options, and operation * context. * * @param prefix * A String that represents the prefix of the container name. * @param detailsIncluded * A {@link ContainerListingDetails} value that indicates whether container metadata will be returned. * @param 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. * @param continuationToken * A {@link ResultContinuation} object that represents a continuation token returned * by a previous listing operation. * @param options * A {@link BlobRequestOptions} object that specifies any additional options for the * request. Specifying null will use the default request options * from the associated service client ({@link CloudBlobClient}). * @param opContext * An {@link 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. * * @return A {@link ResultSegment} object that contains a segment of the enumerable collection of * {@link CloudBlobContainer} objects that represent the containers for this client. * * @throws StorageException * If a storage service error occurred. */ private ResultSegment listContainersWithPrefixSegmented(final String prefix, final ContainerListingDetails detailsIncluded, final Integer maxResults, final ResultContinuation continuationToken, BlobRequestOptions options, OperationContext opContext) throws StorageException { if (opContext == null) { opContext = new OperationContext(); } opContext.initialize(); options = BlobRequestOptions.populateAndApplyDefaults(options, BlobType.UNSPECIFIED, this); Utility.assertContinuationType(continuationToken, ResultContinuationType.CONTAINER); SegmentedStorageRequest segmentedRequest = new SegmentedStorageRequest(); segmentedRequest.setToken(continuationToken); return ExecutionEngine.executeWithRetry(this, null, this.listContainersWithPrefixSegmentedImpl(prefix, detailsIncluded, maxResults, options, segmentedRequest), options.getRetryPolicyFactory(), opContext); } private StorageRequest> listContainersWithPrefixSegmentedImpl( final String prefix, final ContainerListingDetails detailsIncluded, final Integer maxResults, final BlobRequestOptions options, final SegmentedStorageRequest segmentedRequest) { Utility.assertContinuationType(segmentedRequest.getToken(), ResultContinuationType.CONTAINER); final ListingContext listingContext = new ListingContext(prefix, maxResults); final StorageRequest> getRequest = new StorageRequest>( options, this.getStorageUri()) { @Override public void setRequestLocationMode() { this.setRequestLocationMode(Utility.getListingLocationMode(segmentedRequest.getToken())); } @Override public HttpURLConnection buildRequest(CloudBlobClient client, Void parentObject, OperationContext context) throws Exception { listingContext.setMarker(segmentedRequest.getToken() != null ? segmentedRequest.getToken() .getNextMarker() : null); return BlobRequest.listContainers( client.getCredentials().transformUri(client.getStorageUri()).getUri(this.getCurrentLocation()), options, context, listingContext, detailsIncluded); } @Override public void signRequest(HttpURLConnection connection, CloudBlobClient client, OperationContext context) throws Exception { StorageRequest.signBlobQueueAndFileRequest(connection, client, -1L, context); } @Override public ResultSegment preProcessResponse(Void parentObject, CloudBlobClient client, OperationContext context) throws Exception { if (this.getResult().getStatusCode() != HttpURLConnection.HTTP_OK) { this.setNonExceptionedRetryableFailure(true); } return null; } @Override public ResultSegment postProcessResponse(HttpURLConnection connection, Void container, CloudBlobClient client, OperationContext context, ResultSegment storageObject) throws Exception { final ListResponse response = ContainerListHandler.getContainerList(this .getConnection().getInputStream(), client); ResultContinuation newToken = null; if (response.getNextMarker() != null) { newToken = new ResultContinuation(); newToken.setNextMarker(response.getNextMarker()); newToken.setContinuationType(ResultContinuationType.CONTAINER); newToken.setTargetLocation(this.getResult().getTargetLocation()); } final ResultSegment resSegment = new ResultSegment( response.getResults(), response.getMaxResults(), newToken); // Important for listContainers because this is required by the lazy iterator between executions. segmentedRequest.setToken(resSegment.getContinuationToken()); return resSegment; } }; return getRequest; } /** * Queries the service for the {@link ServiceStats}. * * @return A {@link ServiceStats} object for the given storage service. * * @throws StorageException * If a storage service error occurred. */ @DoesServiceRequest public ServiceStats getServiceStats() throws StorageException { return this.getServiceStats(null /* options */, null /* opContext */); } /** * Queries the given storage service for the {@link ServiceStats}. * * @param options * A {@link BlobRequestOptions} object that specifies any additional options for the request. Specifying * null will use the default request options from the associated service client ( * {@link CloudBlobClient}). * @param opContext * An {@link 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. * * @return A {@link ServiceStats} object for the given storage service. * * @throws StorageException * If a storage service error occurred. */ @DoesServiceRequest public ServiceStats getServiceStats(BlobRequestOptions options, OperationContext opContext) throws StorageException { if (opContext == null) { opContext = new OperationContext(); } opContext.initialize(); options = BlobRequestOptions.populateAndApplyDefaults(options, BlobType.UNSPECIFIED, this); return ExecutionEngine.executeWithRetry(this, null, this.getServiceStatsImpl(options, false), options.getRetryPolicyFactory(), opContext); } /** * Retrieves the current {@link ServiceProperties} for the given storage service. This includes Logging, * HourMetrics, MinuteMetrics and CORS configurations. * * @return A {@link ServiceProperties} object representing the current configuration of the service. * * @throws StorageException * If a storage service error occurred. */ @DoesServiceRequest public final ServiceProperties downloadServiceProperties() throws StorageException { return this.downloadServiceProperties(null /* options */, null /* opContext */); } /** * Retrieves the current {@link ServiceProperties} for the given storage service. This includes Logging, * HourMetrics, MinuteMetrics and CORS configurations. * * @param options * A {@link BlobRequestOptions} object that specifies any additional options for the request. Specifying * null will use the default request options from the associated service client ( * {@link CloudBlobClient}). * @param opContext * An {@link 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. * * @return A {@link ServiceProperties} object representing the current configuration of the service. * * @throws StorageException * If a storage service error occurred. */ @DoesServiceRequest public final ServiceProperties downloadServiceProperties(BlobRequestOptions options, OperationContext opContext) throws StorageException { if (opContext == null) { opContext = new OperationContext(); } opContext.initialize(); options = BlobRequestOptions.populateAndApplyDefaults(options, BlobType.UNSPECIFIED, this); return ExecutionEngine.executeWithRetry(this, null, this.downloadServicePropertiesImpl(options, false), options.getRetryPolicyFactory(), opContext); } /** * Uploads a new {@link ServiceProperties} configuration to the given storage service. This includes Logging, * HourMetrics, MinuteMetrics and CORS configurations. * * @param properties * A {@link ServiceProperties} object which specifies the service properties to upload. * * @throws StorageException * If a storage service error occurred. */ @DoesServiceRequest public void uploadServiceProperties(final ServiceProperties properties) throws StorageException { this.uploadServiceProperties(properties, null /* options */, null /* opContext */); } /** * Uploads a new {@link ServiceProperties} configuration to the given storage service. This includes Logging, * HourMetrics, MinuteMetrics and CORS configurations. * * @param properties * A {@link ServiceProperties} object which specifies the service properties to upload. * @param options * A {@link BlobRequestOptions} object that specifies any additional options for the request. Specifying * null will use the default request options from the associated service client ( * {@link CloudBlobClient}). * @param opContext * An {@link 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. */ @DoesServiceRequest public void uploadServiceProperties(final ServiceProperties properties, BlobRequestOptions options, OperationContext opContext) throws StorageException { if (opContext == null) { opContext = new OperationContext(); } opContext.initialize(); options = BlobRequestOptions.populateAndApplyDefaults(options, BlobType.UNSPECIFIED, this); Utility.assertNotNull("properties", properties); ExecutionEngine.executeWithRetry(this, null, this.uploadServicePropertiesImpl(properties, options, opContext, false), options.getRetryPolicyFactory(), opContext); } /** * Sets the value for the default delimiter used for cloud blob directories. * * @param directoryDelimiter * A String that specifies the value for the default directory delimiter. */ public void setDirectoryDelimiter(final String directoryDelimiter) { Utility.assertNotNullOrEmpty("directoryDelimiter", directoryDelimiter); this.directoryDelimiter = directoryDelimiter; } /** * Gets the {@link BlobRequestOptions} that is used for requests associated with this CloudBlobClient * * @return The {@link BlobRequestOptions} object containing the values used by this CloudBlobClient */ @Override public BlobRequestOptions getDefaultRequestOptions() { return this.defaultRequestOptions; } /** * Sets the {@link BlobRequestOptions} that is used for any requests associated with this * CloudBlobClient object. * * @param defaultRequestOptions * A {@link BlobRequestOptions} object which specifies the options to use. */ public void setDefaultRequestOptions(BlobRequestOptions defaultRequestOptions) { Utility.assertNotNull("defaultRequestOptions", defaultRequestOptions); this.defaultRequestOptions = defaultRequestOptions; } /** * Indicates whether path-style URIs are being used. * * @return true if using path-style URIs; otherwise, false. */ @Override protected boolean isUsePathStyleUris() { return super.isUsePathStyleUris(); } }