Merge Storage Blob Client Builders

storage/client/blob/src/main/java/com/azure/storage/blob/BlobClientBuilder.java

@@ -17,13 +17,17 @@
 import com.azure.core.util.configuration.Configuration;
 import com.azure.core.util.configuration.ConfigurationManager;
 import com.azure.storage.blob.implementation.AzureBlobStorageBuilder;
+import com.azure.storage.blob.models.PageRange;
 import com.azure.storage.common.credentials.SASTokenCredential;
 import com.azure.storage.common.credentials.SharedKeyCredential;
 import com.azure.storage.common.policy.RequestRetryOptions;
 import com.azure.storage.common.policy.RequestRetryPolicy;
 import com.azure.storage.common.policy.SASTokenCredentialPolicy;
 import com.azure.storage.common.policy.SharedKeyCredentialPolicy;
+import reactor.core.publisher.Flux;
 
+import java.io.InputStream;
+import java.io.OutputStream;
 import java.net.MalformedURLException;
 import java.net.URL;
 import java.util.ArrayList;
@@ -128,6 +132,10 @@ private AzureBlobStorageBuilder buildImpl() {
     }
 
     /**
+     * Creates a {@link BlobClient} based on options set in the Builder. BlobClients are used to perform generic blob
+     * methods such as {@link BlobClient#download(OutputStream) download} and
+     * {@link BlobClient#getProperties() get properties}, use this when the blob type is unknown.
+     *
      * @return a {@link BlobClient} created from the configurations in this builder.
      * @throws NullPointerException If {@code endpoint}, {@code containerName}, or {@code blobName} is {@code null}.
      */
@@ -136,6 +144,10 @@ public BlobClient buildBlobClient() {
     }
 
     /**
+     * Creates a {@link BlobAsyncClient} based on options set in the Builder. BlobAsyncClients are used to perform
+     * generic blob methods such as {@link BlobAsyncClient#download() download} and
+     * {@link BlobAsyncClient#getProperties()}, use this when the blob type is unknown.
+     *
      * @return a {@link BlobAsyncClient} created from the configurations in this builder.
      * @throws NullPointerException If {@code endpoint}, {@code containerName}, or {@code blobName} is {@code null}.
      */
@@ -144,6 +156,10 @@ public BlobAsyncClient buildBlobAsyncClient() {
     }
 
     /**
+     * Creates a {@link AppendBlobClient} based on options set in the Builder. AppendBlobClients are used to perform
+     * append blob specific actions such as {@link AppendBlobClient#appendBlock(InputStream, long) append block},
+     * only use this when the blob is known to be an append blob.
+     *
      * @return a {@link AppendBlobClient} created from the configurations in this builder.
      * @throws NullPointerException If {@code endpoint}, {@code containerName}, or {@code blobName} is {@code null}.
      */
@@ -152,6 +168,10 @@ public AppendBlobClient buildAppendBlobClient() {
     }
 
     /**
+     * Creates a {@link AppendBlobAsyncClient} based on options set in the Builder. AppendBlobAsyncClients are used to
+     * perform append blob specific actions such as {@link AppendBlobAsyncClient#appendBlock(Flux, long)}, only use this
+     * when the blob is known to be an append blob.
+     *
      * @return a {@link AppendBlobAsyncClient} created from the configurations in this builder.
      * @throws NullPointerException If {@code endpoint}, {@code containerName}, or {@code blobName} is {@code null}.
      */
@@ -160,6 +180,10 @@ public AppendBlobAsyncClient buildAppendBlobAsyncClient() {
     }
 
     /**
+     * Creates a {@link BlockBlobClient} based on options set in the Builder. BlockBlobClients are used to perform block
+     * blob specific actions such as {@link BlockBlobClient#stageBlock(String, InputStream, long) stage block} and
+     * {@link BlockBlobClient#commitBlockList(List)}, only use this when the blob is known to be a block blob.
+     *
      * @return a {@link BlockBlobClient} created from the configurations in this builder.
      * @throws NullPointerException If {@code endpoint}, {@code containerName}, or {@code blobName} is {@code null}.
      */
@@ -168,6 +192,11 @@ public BlockBlobClient buildBlockBlobClient() {
     }
 
     /**
+     * Creates a {@link BlockBlobAsyncClient} based on options set in the Builder. BlockBlobAsyncClients are used to
+     * perform block blob specific actions such as {@link BlockBlobAsyncClient#stageBlock(String, Flux, long) stage block}
+     * and {@link BlockBlobAsyncClient#commitBlockList(List) commit block list}, only use this when the blob is known to
+     * be a block blob.
+     *
      * @return a {@link BlockBlobAsyncClient} created from the configurations in this builder.
      * @throws NullPointerException If {@code endpoint}, {@code containerName}, or {@code blobName} is {@code null}.
      */
@@ -176,6 +205,10 @@ public BlockBlobAsyncClient buildBlockBlobAsyncClient() {
     }
 
     /**
+     * Creates a {@link PageBlobClient} based on options set in the Builder. PageBlobClients are used to perform page
+     * blob specific tasks such as {@link PageBlobClient#uploadPages(PageRange, InputStream) upload pages} and
+     * {@link PageBlobClient#clearPages(PageRange) clear pages}, only use this when the blob is known to be a page blob.
+     *
      * @return a {@link PageBlobClient} created from the configurations in this builder.
      * @throws NullPointerException If {@code endpoint}, {@code containerName}, or {@code blobName} is {@code null}.
      */
@@ -184,6 +217,11 @@ public PageBlobClient buildPageBlobClient() {
     }
 
     /**
+     * Creates a {@link PageBlobAsyncClient} based on options set in the Builder. PageBlobAsyncClients are used to
+     * perform page blob specific tasks such as {@link PageBlobAsyncClient#uploadPages(PageRange, Flux) upload pages}
+     * and {@link PageBlobAsyncClient#clearPages(PageRange) clear pages}, only use this when the blob is known to be a
+     * page blob.
+     *
      * @return a {@link PageBlobAsyncClient} created from the configurations in this builder.
      * @throws NullPointerException If {@code endpoint}, {@code containerName}, or {@code blobName} is {@code null}.
      */
@@ -201,23 +239,16 @@ public BlobClientBuilder endpoint(String endpoint) {
         try {
             URL url = new URL(endpoint);
             BlobURLParts parts = URLParser.parse(url);
-            this.endpoint = parts.scheme() + "://" + parts.host();
-
-            if (parts.containerName() != null) {
-                this.containerName = parts.containerName();
-            }
-
-            if (parts.blobName() != null) {
-                this.blobName = parts.blobName();
-            }
-
-            if (parts.snapshot() != null) {
-                this.snapshot = parts.snapshot();
-            }
 
-            SASTokenCredential credential = SASTokenCredential.fromQuery(url.getQuery());
-            if (credential != null) {
-                this.credential(credential);
+            this.endpoint = parts.scheme() + "://" + parts.host();
+            this.containerName = parts.containerName();
+            this.blobName = parts.blobName();
+            this.snapshot = parts.snapshot();
+
+            this.sasTokenCredential = SASTokenCredential.fromQueryParameters(parts.sasQueryParameters());
+            if (this.sasTokenCredential != null) {
+                this.tokenCredential = null;
+                this.sharedKeyCredential = null;
             }
         } catch (MalformedURLException ex) {
             throw new IllegalArgumentException("The Azure Storage Blob endpoint url is malformed.");

storage/client/blob/src/main/java/com/azure/storage/blob/ContainerClientBuilder.java

@@ -122,14 +122,20 @@ private AzureBlobStorageBuilder buildImpl() {
     }
 
     /**
+     * Creates a {@link ContainerClient} based on options set in the Builder.
+     *
      * @return a {@link ContainerClient} created from the configurations in this builder.
+     * @throws NullPointerException If {@code endpoint} is {@code null} or {@code containerName} is {@code null}.
      */
     public ContainerClient buildClient() {
         return new ContainerClient(buildAsyncClient());
     }
 
     /**
+     * Creates a {@link ContainerAsyncClient} based on options set in the Builder.
+     *
      * @return a {@link ContainerAsyncClient} created from the configurations in this builder.
+     * @throws NullPointerException If {@code endpoint} is {@code null} or {@code containerName} is {@code null}.
      */
     public ContainerAsyncClient buildAsyncClient() {
         return new ContainerAsyncClient(buildImpl());
@@ -139,32 +145,25 @@ public ContainerAsyncClient buildAsyncClient() {
      * Sets the service endpoint, additionally parses it for information (SAS token, container name)
      * @param endpoint URL of the service
      * @return the updated ContainerClientBuilder object
-     * @throws IllegalArgumentException If {@code endpoint} is a malformed URL.
+     * @throws IllegalArgumentException If {@code endpoint} is {@code null} or is a malformed URL.
      */
     public ContainerClientBuilder endpoint(String endpoint) {
-        Objects.requireNonNull(endpoint);
-        URL url;
         try {
-            url = new URL(endpoint);
-            this.endpoint = url.getProtocol() + "://" + url.getAuthority();
-            String path = url.getPath();
-            if (path != null && !path.isEmpty() && !path.equals("/")) {
-                path = path.replaceAll("^/", "").replaceAll("/$", "");
-                if (path.contains("/")) {
-                    throw new IllegalArgumentException("Endpoint should contain exactly 0 or 1 path segments");
-                } else {
-                    this.containerName = path;
-                }
+            URL url = new URL(endpoint);
+            BlobURLParts parts = URLParser.parse(url);
+
+            this.endpoint = parts.scheme() + "://" + parts.host();
+            this.containerName = parts.containerName();
+
+            this.sasTokenCredential = SASTokenCredential.fromQueryParameters(parts.sasQueryParameters());
+            if (this.sasTokenCredential != null) {
+                this.tokenCredential = null;
+                this.sharedKeyCredential = null;
             }
         } catch (MalformedURLException ex) {
             throw new IllegalArgumentException("The Azure Storage Blob endpoint url is malformed.");
         }
 
-        SASTokenCredential credential = SASTokenCredential.fromQuery(url.getQuery());
-        if (credential != null) {
-            this.credential(credential);
-        }
-
         return this;
     }
 
@@ -186,9 +185,10 @@ String endpoint() {
      * Sets the credential used to authorize requests sent to the service
      * @param credential authorization credential
      * @return the updated ContainerClientBuilder object
+     * @throws NullPointerException If {@code credential} is {@code null}.
      */
     public ContainerClientBuilder credential(SharedKeyCredential credential) {
-        this.sharedKeyCredential = credential;
+        this.sharedKeyCredential = Objects.requireNonNull(credential);
         this.tokenCredential = null;
         this.sasTokenCredential = null;
         return this;
@@ -198,9 +198,10 @@ public ContainerClientBuilder credential(SharedKeyCredential credential) {
      * Sets the credential used to authorize requests sent to the service
      * @param credential authorization credential
      * @return the updated ContainerClientBuilder object
+     * @throws NullPointerException If {@code credential} is {@code null}.
      */
     public ContainerClientBuilder credential(TokenCredential credential) {
-        this.tokenCredential = credential;
+        this.tokenCredential = Objects.requireNonNull(credential);
         this.sharedKeyCredential = null;
         this.sasTokenCredential = null;
         return this;
@@ -210,9 +211,10 @@ public ContainerClientBuilder credential(TokenCredential credential) {
      * Sets the credential used to authorize requests sent to the service
      * @param credential authorization credential
      * @return the updated ContainerClientBuilder object
+     * @throws NullPointerException If {@code credential} is {@code null}.
      */
     public ContainerClientBuilder credential(SASTokenCredential credential) {
-        this.sasTokenCredential = credential;
+        this.sasTokenCredential = Objects.requireNonNull(credential);
         this.sharedKeyCredential = null;
         this.tokenCredential = null;
         return this;
@@ -266,19 +268,21 @@ public ContainerClientBuilder connectionString(String connectionString) {
      * Sets the http client used to send service requests
      * @param httpClient http client to send requests
      * @return the updated ContainerClientBuilder object
+     * @throws NullPointerException If {@code httpClient} is {@code null}.
      */
     public ContainerClientBuilder httpClient(HttpClient httpClient) {
-        this.httpClient = httpClient;
+        this.httpClient = Objects.requireNonNull(httpClient);
         return this;
     }
 
     /**
      * Adds a pipeline policy to apply on each request sent
      * @param pipelinePolicy a pipeline policy
      * @return the updated ContainerClientBuilder object
+     * @throws NullPointerException If {@code pipelinePolicy} is {@code null}.
      */
     public ContainerClientBuilder addPolicy(HttpPipelinePolicy pipelinePolicy) {
-        this.policies.add(pipelinePolicy);
+        this.policies.add(Objects.requireNonNull(pipelinePolicy));
         return this;
     }
 
@@ -307,9 +311,10 @@ public ContainerClientBuilder configuration(Configuration configuration) {
      * Sets the request retry options for all the requests made through the client.
      * @param retryOptions the options to configure retry behaviors
      * @return the updated ContainerClientBuilder object
+     * @throws NullPointerException If {@code retryOptions} is {@code null}.
      */
     public ContainerClientBuilder retryOptions(RequestRetryOptions retryOptions) {
-        this.retryOptions = retryOptions;
+        this.retryOptions = Objects.requireNonNull(retryOptions);
         return this;
     }
 }

storage/client/blob/src/main/java/com/azure/storage/blob/SASQueryParameters.java

@@ -19,7 +19,7 @@
  * are existing query parameters, which might affect the appropriate means of appending these query parameters).
  * NOTE: Instances of this class are immutable to ensure thread safety.
  */
-final class SASQueryParameters {
+public final class SASQueryParameters {
 
     private final String version;