Add Traits to Search builders.

sdk/search/azure-search-documents/CHANGELOG.md

@@ -3,6 +3,8 @@
 ## 11.5.0-beta.6 (Unreleased)
 
 ### Features Added
+- Added interfaces from `com.azure.core.client.traits` to `SearchIndexerClientBuilder`, `SearchIndexClientBuilder` 
+  and `SearchClientBuilder`
 
 ### Breaking Changes
 

sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/util/Utility.java

@@ -19,13 +19,15 @@
 import com.azure.core.http.policy.HttpPipelinePolicy;
 import com.azure.core.http.policy.HttpPolicyProviders;
 import com.azure.core.http.policy.RequestIdPolicy;
+import com.azure.core.http.policy.RetryOptions;
 import com.azure.core.http.policy.RetryPolicy;
 import com.azure.core.http.policy.UserAgentPolicy;
 import com.azure.core.http.rest.Response;
 import com.azure.core.util.ClientOptions;
 import com.azure.core.util.Configuration;
 import com.azure.core.util.Context;
 import com.azure.core.util.CoreUtils;
+import com.azure.core.util.builder.ClientBuilderUtil;
 import com.azure.core.util.logging.ClientLogger;
 import com.azure.core.util.serializer.JacksonAdapter;
 import com.azure.core.util.serializer.SerializerAdapter;
@@ -104,9 +106,10 @@ public static <T> T convertValue(Object initialValue, Class<T> newValueType) thr
     }
 
     public static HttpPipeline buildHttpPipeline(ClientOptions clientOptions, HttpLogOptions logOptions,
-        Configuration configuration, RetryPolicy retryPolicy, AzureKeyCredential azureKeyCredential,
-        TokenCredential tokenCredential, List<HttpPipelinePolicy> perCallPolicies,
-        List<HttpPipelinePolicy> perRetryPolicies, HttpClient httpClient, ClientLogger logger) {
+        Configuration configuration, RetryPolicy retryPolicy, RetryOptions retryOptions,
+        AzureKeyCredential azureKeyCredential, TokenCredential tokenCredential,
+        List<HttpPipelinePolicy> perCallPolicies, List<HttpPipelinePolicy> perRetryPolicies, HttpClient httpClient,
+        ClientLogger logger) {
         Configuration buildConfiguration = (configuration == null)
             ? Configuration.getGlobalConfiguration()
             : configuration;
@@ -125,7 +128,7 @@ public static HttpPipeline buildHttpPipeline(ClientOptions clientOptions, HttpLo
 
         httpPipelinePolicies.addAll(perCallPolicies);
         HttpPolicyProviders.addBeforeRetryPolicies(httpPipelinePolicies);
-        httpPipelinePolicies.add(retryPolicy == null ? new RetryPolicy() : retryPolicy);
+        httpPipelinePolicies.add(ClientBuilderUtil.validateAndGetRetryPolicy(retryPolicy, retryOptions));
 
         httpPipelinePolicies.add(new AddDatePolicy());
 

sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/indexes/SearchIndexClientBuilder.java

@@ -3,16 +3,24 @@
 package com.azure.search.documents.indexes;
 
 import com.azure.core.annotation.ServiceClientBuilder;
+import com.azure.core.client.traits.AzureKeyCredentialTrait;
+import com.azure.core.client.traits.ConfigurationTrait;
+import com.azure.core.client.traits.EndpointTrait;
+import com.azure.core.client.traits.HttpTrait;
+import com.azure.core.client.traits.TokenCredentialTrait;
 import com.azure.core.credential.AzureKeyCredential;
 import com.azure.core.credential.TokenCredential;
 import com.azure.core.http.HttpClient;
 import com.azure.core.http.HttpPipeline;
 import com.azure.core.http.HttpPipelinePosition;
+import com.azure.core.http.policy.HttpLogDetailLevel;
 import com.azure.core.http.policy.HttpLogOptions;
 import com.azure.core.http.policy.HttpPipelinePolicy;
+import com.azure.core.http.policy.RetryOptions;
 import com.azure.core.http.policy.RetryPolicy;
 import com.azure.core.util.ClientOptions;
 import com.azure.core.util.Configuration;
+import com.azure.core.util.HttpClientOptions;
 import com.azure.core.util.logging.ClientLogger;
 import com.azure.core.util.serializer.JsonSerializer;
 import com.azure.search.documents.SearchServiceVersion;
@@ -63,7 +71,12 @@
  * @see SearchIndexAsyncClient
  */
 @ServiceClientBuilder(serviceClients = {SearchIndexClient.class, SearchIndexAsyncClient.class})
-public final class SearchIndexClientBuilder {
+public final class SearchIndexClientBuilder implements
+    AzureKeyCredentialTrait<SearchIndexClientBuilder>,
+    ConfigurationTrait<SearchIndexClientBuilder>,
+    EndpointTrait<SearchIndexClientBuilder>,
+    HttpTrait<SearchIndexClientBuilder>,
+    TokenCredentialTrait<SearchIndexClientBuilder> {
     private final ClientLogger logger = new ClientLogger(SearchIndexClientBuilder.class);
 
     private final List<HttpPipelinePolicy> perCallPolicies = new ArrayList<>();
@@ -80,6 +93,7 @@ public final class SearchIndexClientBuilder {
     private ClientOptions clientOptions;
     private Configuration configuration;
     private RetryPolicy retryPolicy;
+    private RetryOptions retryOptions;
     private JsonSerializer jsonSerializer;
 
     /**
@@ -98,6 +112,8 @@ public SearchIndexClientBuilder() {
      *
      * @return A SearchIndexClient with the options set from the builder.
      * @throws NullPointerException If {@code endpoint} are {@code null}.
+     * @throws IllegalStateException If both {@link #retryOptions(RetryOptions)}
+     * and {@link #retryPolicy(RetryPolicy)} have been set.
      */
     public SearchIndexClient buildClient() {
         return new SearchIndexClient(buildAsyncClient());
@@ -112,6 +128,8 @@ public SearchIndexClient buildClient() {
      *
      * @return A SearchIndexAsyncClient with the options set from the builder.
      * @throws NullPointerException If {@code endpoint} are {@code null}.
+     * @throws IllegalStateException If both {@link #retryOptions(RetryOptions)}
+     * and {@link #retryPolicy(RetryPolicy)} have been set.
      */
     public SearchIndexAsyncClient buildAsyncClient() {
         Objects.requireNonNull(endpoint, "'endpoint' cannot be null.");
@@ -125,7 +143,7 @@ public SearchIndexAsyncClient buildAsyncClient() {
         }
 
         HttpPipeline pipeline = Utility.buildHttpPipeline(clientOptions, httpLogOptions, configuration, retryPolicy,
-            azureKeyCredential, tokenCredential, perCallPolicies, perRetryPolicies, httpClient, logger);
+            retryOptions, azureKeyCredential, tokenCredential, perCallPolicies, perRetryPolicies, httpClient, logger);
 
         return new SearchIndexAsyncClient(endpoint, buildVersion, pipeline, jsonSerializer);
     }
@@ -137,6 +155,7 @@ public SearchIndexAsyncClient buildAsyncClient() {
      * @return The updated SearchIndexClientBuilder object.
      * @throws IllegalArgumentException If {@code endpoint} is null or it cannot be parsed into a valid URL.
      */
+    @Override
     public SearchIndexClientBuilder endpoint(String endpoint) {
         try {
             new URL(endpoint);
@@ -153,30 +172,42 @@ public SearchIndexClientBuilder endpoint(String endpoint) {
      * @param credential The {@link AzureKeyCredential} used to authenticate HTTP requests.
      * @return The updated SearchIndexClientBuilder object.
      */
+    @Override
     public SearchIndexClientBuilder credential(AzureKeyCredential credential) {
         this.azureKeyCredential = credential;
         return this;
     }
 
     /**
-     * Sets the {@link TokenCredential} used to authenticate HTTP requests.
+     * Sets the {@link TokenCredential} used to authorize requests sent to the service. Refer to the Azure SDK for Java
+     * <a href="https://aka.ms/azsdk/java/docs/identity">identity and authentication</a>
+     * documentation for more details on proper usage of the {@link TokenCredential} type.
      *
-     * @param credential The {@link TokenCredential} used to authenticate HTTP requests.
+     * @param credential {@link TokenCredential} used to authorize requests sent to the service.
      * @return The updated SearchIndexClientBuilder object.
      */
+    @Override
     public SearchIndexClientBuilder credential(TokenCredential credential) {
         this.tokenCredential = credential;
         return this;
     }
 
     /**
-     * Sets the logging configuration for HTTP requests and responses.
-     * <p>
-     * If logging configurations aren't provided HTTP requests and responses won't be logged.
+     * Sets the {@link HttpLogOptions logging configuration} to use when sending and receiving requests to and from
+     * the service. If a {@code logLevel} is not provided, default value of {@link HttpLogDetailLevel#NONE} is set.
+     *
+     * <p><strong>Note:</strong> It is important to understand the precedence order of the HttpTrait APIs. In
+     * particular, if a {@link HttpPipeline} is specified, this takes precedence over all other APIs in the trait, and
+     * they will be ignored. If no {@link HttpPipeline} is specified, a HTTP pipeline will be constructed internally
+     * based on the settings provided to this trait. Additionally, there may be other APIs in types that implement this
+     * trait that are also ignored if an {@link HttpPipeline} is specified, so please be sure to refer to the
+     * documentation of types that implement this trait to understand the full set of implications.</p>
      *
-     * @param logOptions The logging configuration for HTTP requests and responses.
+     * @param logOptions The {@link HttpLogOptions logging configuration} to use when sending and receiving requests to
+     * and from the service.
      * @return The updated SearchIndexClientBuilder object.
      */
+    @Override
     public SearchIndexClientBuilder httpLogOptions(HttpLogOptions logOptions) {
         httpLogOptions = logOptions;
         return this;
@@ -192,26 +223,44 @@ public static HttpLogOptions getDefaultLogOptions() {
     }
 
     /**
-     * Sets the client options such as application ID and custom headers to set on a request.
+     * Allows for setting common properties such as application ID, headers, proxy configuration, etc. Note that it is
+     * recommended that this method be called with an instance of the {@link HttpClientOptions}
+     * class (a subclass of the {@link ClientOptions} base class). The HttpClientOptions subclass provides more
+     * configuration options suitable for HTTP clients, which is applicable for any class that implements this HttpTrait
+     * interface.
+     *
+     * <p><strong>Note:</strong> It is important to understand the precedence order of the HttpTrait APIs. In
+     * particular, if a {@link HttpPipeline} is specified, this takes precedence over all other APIs in the trait, and
+     * they will be ignored. If no {@link HttpPipeline} is specified, a HTTP pipeline will be constructed internally
+     * based on the settings provided to this trait. Additionally, there may be other APIs in types that implement this
+     * trait that are also ignored if an {@link HttpPipeline} is specified, so please be sure to refer to the
+     * documentation of types that implement this trait to understand the full set of implications.</p>
      *
-     * @param clientOptions The client options.
+     * @param clientOptions A configured instance of {@link HttpClientOptions}.
      * @return The updated SearchIndexClientBuilder object.
+     * @see HttpClientOptions
      */
+    @Override
     public SearchIndexClientBuilder clientOptions(ClientOptions clientOptions) {
         this.clientOptions = clientOptions;
         return this;
     }
 
     /**
-     * Adds a pipeline policy to apply to each request sent.
-     * <p>
-     * This method may be called multiple times, each time it is called the policy will be added to the end of added
-     * policy list. All policies will be added after the retry policy.
+     * Adds a {@link HttpPipelinePolicy pipeline policy} to apply on each request sent.
+     *
+     * <p><strong>Note:</strong> It is important to understand the precedence order of the HttpTrait APIs. In
+     * particular, if a {@link HttpPipeline} is specified, this takes precedence over all other APIs in the trait, and
+     * they will be ignored. If no {@link HttpPipeline} is specified, a HTTP pipeline will be constructed internally
+     * based on the settings provided to this trait. Additionally, there may be other APIs in types that implement this
+     * trait that are also ignored if an {@link HttpPipeline} is specified, so please be sure to refer to the
+     * documentation of types that implement this trait to understand the full set of implications.</p>
      *
-     * @param policy The pipeline policies to added to the policy list.
+     * @param policy A {@link HttpPipelinePolicy pipeline policy}.
      * @return The updated SearchIndexClientBuilder object.
      * @throws NullPointerException If {@code policy} is {@code null}.
      */
+    @Override
     public SearchIndexClientBuilder addPolicy(HttpPipelinePolicy policy) {
         Objects.requireNonNull(policy, "'policy' cannot be null.");
 
@@ -237,11 +286,19 @@ public SearchIndexClientBuilder serializer(JsonSerializer jsonSerializer) {
     }
 
     /**
-     * Sets the HTTP client to use for sending requests and receiving responses.
+     * Sets the {@link HttpClient} to use for sending and receiving requests to and from the service.
      *
-     * @param client The HTTP client that will handle sending requests and receiving responses.
+     * <p><strong>Note:</strong> It is important to understand the precedence order of the HttpTrait APIs. In
+     * particular, if a {@link HttpPipeline} is specified, this takes precedence over all other APIs in the trait, and
+     * they will be ignored. If no {@link HttpPipeline} is specified, a HTTP pipeline will be constructed internally
+     * based on the settings provided to this trait. Additionally, there may be other APIs in types that implement this
+     * trait that are also ignored if an {@link HttpPipeline} is specified, so please be sure to refer to the
+     * documentation of types that implement this trait to understand the full set of implications.</p>
+     *
+     * @param client The {@link HttpClient} to use for requests.
      * @return The updated SearchIndexClientBuilder object.
      */
+    @Override
     public SearchIndexClientBuilder httpClient(HttpClient client) {
         if (this.httpClient != null && client == null) {
             logger.info("HttpClient is being set to 'null' when it was previously configured.");
@@ -252,14 +309,22 @@ public SearchIndexClientBuilder httpClient(HttpClient client) {
     }
 
     /**
-     * Sets the HTTP pipeline to use for the service client.
+     * Sets the {@link HttpPipeline} to use for the service client.
+     *
+     * <p><strong>Note:</strong> It is important to understand the precedence order of the HttpTrait APIs. In
+     * particular, if a {@link HttpPipeline} is specified, this takes precedence over all other APIs in the trait, and
+     * they will be ignored. If no {@link HttpPipeline} is specified, a HTTP pipeline will be constructed internally
+     * based on the settings provided to this trait. Additionally, there may be other APIs in types that implement this
+     * trait that are also ignored if an {@link HttpPipeline} is specified, so please be sure to refer to the
+     * documentation of types that implement this trait to understand the full set of implications.</p>
      * <p>
      * If {@code pipeline} is set, all other settings are ignored, aside from {@link #endpoint(String) endpoint} when
      * building a {@link SearchIndexClient} or {@link SearchIndexAsyncClient}.
      *
-     * @param httpPipeline The HTTP pipeline to use for sending service requests and receiving responses.
+     * @param httpPipeline {@link HttpPipeline} to use for sending service requests and receiving responses.
      * @return The updated SearchIndexClientBuilder object.
      */
+    @Override
     public SearchIndexClientBuilder pipeline(HttpPipeline httpPipeline) {
         if (this.httpPipeline != null && httpPipeline == null) {
             logger.info("HttpPipeline is being set to 'null' when it was previously configured.");
@@ -278,6 +343,7 @@ public SearchIndexClientBuilder pipeline(HttpPipeline httpPipeline) {
      * @param configuration The configuration store that will be used.
      * @return The updated SearchIndexClientBuilder object.
      */
+    @Override
     public SearchIndexClientBuilder configuration(Configuration configuration) {
         this.configuration = configuration;
         return this;
@@ -287,6 +353,8 @@ public SearchIndexClientBuilder configuration(Configuration configuration) {
      * Sets the {@link HttpPipelinePolicy} that will attempt to retry requests when needed.
      * <p>
      * A default retry policy will be supplied if one isn't provided.
+     * <p>
+     * Setting this is mutually exclusive with using {@link #retryOptions(RetryOptions)}.
      *
      * @param retryPolicy The {@link RetryPolicy} that will attempt to retry requests when needed.
      * @return The updated SearchIndexClientBuilder object.
@@ -296,6 +364,27 @@ public SearchIndexClientBuilder retryPolicy(RetryPolicy retryPolicy) {
         return this;
     }
 
+    /**
+     * Sets the {@link RetryOptions} for all the requests made through the client.
+     *
+     * <p><strong>Note:</strong> It is important to understand the precedence order of the HttpTrait APIs. In
+     * particular, if a {@link HttpPipeline} is specified, this takes precedence over all other APIs in the trait, and
+     * they will be ignored. If no {@link HttpPipeline} is specified, a HTTP pipeline will be constructed internally
+     * based on the settings provided to this trait. Additionally, there may be other APIs in types that implement this
+     * trait that are also ignored if an {@link HttpPipeline} is specified, so please be sure to refer to the
+     * documentation of types that implement this trait to understand the full set of implications.</p>
+     * <p>
+     * Setting this is mutually exclusive with using {@link #retryPolicy(RetryPolicy)}.
+     *
+     * @param retryOptions The {@link RetryOptions} to use for all the requests made through the client.
+     * @return The updated SearchIndexClientBuilder object.
+     */
+    @Override
+    public SearchIndexClientBuilder retryOptions(RetryOptions retryOptions) {
+        this.retryOptions = retryOptions;
+        return this;
+    }
+
     /**
      * Sets the {@link SearchServiceVersion} that is used when making API requests.
      * <p>