Builder interfaces (Azure#26562)

* Update Log4j to 2.17.0

* First batch of TokenCredentialSupport.

* move package.

* trait?

* http options minus retry.

* fix build?

* ClientOptionsTrait

* revapi suppression.

* checkstyle.

* servicebus token cred.

* eventhub tokencredential.

* Amqp trait.

* sas credential trait.

* connection string trait.

* Key and Named Key.

* Named Key in Storage.

* Does this solve retry ?

* attestation post-merge.

* fix java 8 compilation...

* fix checkstyle warnings.

* this isn't necessary.

* checkstyle.

* undo services outside of spring scope.

* configuration trait.

* remove client options trait in favor of configuration.

* rename http and amqp

* aaa....

* retryOptions and retryPolicy mutually exclusive.

* tweaks.

* tweaks.

* client options and endpoint trait.

* the util.

* fixedretry options.

* allow null retry options.

* pr feedback.

* validate ExponentialBackoffOptions

* storage.

* remove these two.

* @throws

* traits comments.

* fix core build.

* fix kv build.

* fix tables. build.

* checkstyle..

* copy http client docs.

* aka.ms

* copy pipeline docs.

* copy addPolicy docs.

* update configuration trait docs.

* copy retry options docs.

* copy log options docs.

* copy client options docs.

* copy token credential docs.

* fix build.

* pr feedback.

* added KeyEncryptionKeyClientBuilderTest

Author: kasobol-msft

eng/versioning/version_client.txt

@@ -344,7 +344,7 @@ com.azure.tools:azure-sdk-archetype;1.0.0;1.0.0
 # note: The unreleased dependencies will not be manipulated with the automatic PR creation code.
 # In the pom, the version update tag after the version should name the unreleased package and the dependency version:
 # <!-- {x-version-update;unreleased_com.azure:azure-core;dependency} -->
-
+unreleased_com.azure:azure-core;1.25.0-beta.1
 unreleased_com.azure:azure-core-amqp;2.4.0-beta.1
 
 # Released Beta dependencies: Copy the entry from above, prepend "beta_", remove the current

sdk/appconfiguration/azure-data-appconfiguration/pom.xml

@@ -45,7 +45,7 @@
     <dependency>
       <groupId>com.azure</groupId>
       <artifactId>azure-core</artifactId>
-      <version>1.24.1</version> <!-- {x-version-update;com.azure:azure-core;dependency} -->
+      <version>1.25.0-beta.1</version> <!-- {x-version-update;unreleased_com.azure:azure-core;dependency} -->
     </dependency>
     <dependency>
       <groupId>com.azure</groupId>

sdk/appconfiguration/azure-data-appconfiguration/src/main/java/com/azure/data/appconfiguration/ConfigurationClientBuilder.java

@@ -7,9 +7,11 @@
 import com.azure.core.http.HttpClient;
 import com.azure.core.http.HttpPipelineBuilder;
 import com.azure.core.http.netty.NettyAsyncHttpClientBuilder;
+import com.azure.core.http.policy.ExponentialBackoffOptions;
 import com.azure.core.http.policy.FixedDelay;
 import com.azure.core.http.policy.HttpLogDetailLevel;
 import com.azure.core.http.policy.HttpLogOptions;
+import com.azure.core.http.policy.RetryOptions;
 import com.azure.core.http.policy.RetryPolicy;
 import com.azure.core.http.policy.TimeoutPolicy;
 import com.azure.core.test.TestBase;
@@ -128,6 +130,18 @@ public void timeoutPolicy() {
         assertThrows(RuntimeException.class, () -> client.setConfigurationSetting(key, null, value));
     }
 
+    @Test
+    @DoNotRecord
+    public void throwIfBothRetryOptionsAndRetryPolicyIsConfigured() {
+        final ConfigurationClientBuilder clientBuilder = new ConfigurationClientBuilder()
+            .connectionString(connectionString)
+            .retryOptions(new RetryOptions(new ExponentialBackoffOptions()))
+            .retryPolicy(new RetryPolicy())
+            .addPolicy(new TimeoutPolicy(Duration.ofMillis(1)));
+
+        assertThrows(IllegalStateException.class, clientBuilder::buildClient);
+    }
+
     @ParameterizedTest(name = DISPLAY_NAME_WITH_ARGUMENTS)
     @MethodSource("com.azure.data.appconfiguration.TestHelper#getTestParameters")
     public void nullServiceVersion(HttpClient httpClient) {

sdk/appconfiguration/azure-data-appconfiguration/src/test/java/com/azure/data/appconfiguration/ConfigurationClientBuilderTest.java

@@ -0,0 +1,61 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.core.amqp.client.traits;
+
+import com.azure.core.amqp.AmqpRetryOptions;
+import com.azure.core.amqp.AmqpTransportType;
+import com.azure.core.amqp.ProxyOptions;
+import com.azure.core.util.ClientOptions;
+
+/**
+ * An {@link com.azure.core.client.traits Azure SDK for Java trait} providing a consistent interface for configuration
+ * of AMQP-specific settings.
+ *
+ * @param <T> The concrete type that implements the trait. This is required so that fluent operations can continue
+ *           to return the concrete type, rather than the trait type.
+ * @see com.azure.core.amqp.client.traits
+ * @see com.azure.core.client.traits
+ * @see AmqpRetryOptions
+ * @see AmqpTransportType
+ * @see ProxyOptions
+ */
+public interface AmqpTrait<T extends AmqpTrait<T>> {
+    /**
+     * Sets the retry policy. If not specified, the default retry options are used.
+     *
+     * @param retryOptions The retry options to use.
+     * @return Returns the same concrete type with the appropriate properties updated, to allow for fluent chaining of
+     *      operations.
+     */
+    T retryOptions(AmqpRetryOptions retryOptions);
+
+    /**
+     * Sets the transport type by which all the communication with Azure service occurs. The default value is {@link
+     * AmqpTransportType#AMQP}.
+     *
+     * @param transport The transport type to use.
+     * @return Returns the same concrete type with the appropriate properties updated, to allow for fluent chaining of
+     *      operations.
+     */
+    T transportType(AmqpTransportType transport);
+
+    /**
+     * Sets the proxy configuration to use. When a proxy is configured, {@link
+     * AmqpTransportType#AMQP_WEB_SOCKETS} must be used for the transport type.
+     *
+     * @param proxyOptions The proxy configuration to use.
+     * @return Returns the same concrete type with the appropriate properties updated, to allow for fluent chaining of
+     *      operations.
+     */
+    T proxyOptions(ProxyOptions proxyOptions);
+
+    /**
+     * Allows for setting common properties such as application ID, headers, etc.
+     *
+     * @param clientOptions A configured instance of {@link ClientOptions}.
+     * @return Returns the same concrete type with the appropriate properties updated, to allow for fluent chaining of
+     *      operations.
+     */
+    T clientOptions(ClientOptions clientOptions);
+}

sdk/core/azure-core-amqp/src/main/java/com/azure/core/amqp/client/traits/AmqpTrait.java

@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+/**
+ * This package contains interfaces that represent common cross-cutting (and AMQP-related) aspects of functionality
+ * offered by libraries in the Azure SDK for Java. Each interface is referred to as a 'trait', and classes that
+ * implement the interface are said to have that trait. There are additional traits that are more general
+ * purpose in the {@link com.azure.core.client.traits} package.
+ *
+ * <p>The particular focus of traits in the Azure SDK for Java is to enable higher-level
+ * libraries the ability to more abstractly configure client libraries as part of their builders, prior to the client
+ * itself being instantiated. By doing this, these high-level libraries are able to reason about functionality more
+ * simply. It is important to appreciate that despite the availability of these cross-cutting traits, there is no
+ * promise that configuration of each builder can simply be a matter of providing the same arguments for all builders!
+ * Each builder must be configured appropriately for its requirements, or else runtime failures may occur when the
+ * builder is asked to create the associated client.</p>
+ *
+ * @see com.azure.core.client.traits
+ */
+package com.azure.core.amqp.client.traits;

sdk/core/azure-core-amqp/src/main/java/com/azure/core/amqp/client/traits/package-info.java

@@ -9,6 +9,7 @@
     requires transitive org.apache.qpid.proton.j;
 
     exports com.azure.core.amqp;
+    exports com.azure.core.amqp.client.traits;
     exports com.azure.core.amqp.models;
     exports com.azure.core.amqp.exception;
 

sdk/core/azure-core-amqp/src/main/java/module-info.java

@@ -0,0 +1,30 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.core.client.traits;
+
+import com.azure.core.credential.AzureKeyCredential;
+
+/**
+ * An {@link com.azure.core.client.traits Azure SDK for Java trait} providing a consistent interface for setting
+ * {@link AzureKeyCredential}. 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 AzureKeyCredential} type.
+ *
+ * @param <T> The concrete type that implements the trait. This is required so that fluent operations can continue
+ *           to return the concrete type, rather than the trait type.
+ * @see com.azure.core.client.traits
+ * @see AzureKeyCredential
+ */
+public interface AzureKeyCredentialTrait<T extends AzureKeyCredentialTrait<T>> {
+    /**
+     * Sets the {@link AzureKeyCredential} used for authentication. 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 AzureKeyCredential} type.
+     *
+     * @param credential the {@link AzureKeyCredential} to be used for authentication.
+     * @return Returns the same concrete type with the appropriate properties updated, to allow for fluent chaining of
+     *      operations.
+     */
+    T credential(AzureKeyCredential credential);
+}

sdk/core/azure-core/src/main/java/com/azure/core/client/traits/AzureKeyCredentialTrait.java

@@ -0,0 +1,30 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.core.client.traits;
+
+import com.azure.core.credential.AzureNamedKeyCredential;
+
+/**
+ * An {@link com.azure.core.client.traits Azure SDK for Java trait} providing a consistent interface for setting
+ * {@link AzureNamedKeyCredential}. 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 AzureNamedKeyCredential} type.
+ *
+ * @param <T> The concrete type that implements the trait. This is required so that fluent operations can continue
+ *           to return the concrete type, rather than the trait type.
+ * @see com.azure.core.client.traits
+ * @see AzureNamedKeyCredential
+ */
+public interface AzureNamedKeyCredentialTrait<T extends AzureNamedKeyCredentialTrait<T>> {
+    /**
+     * Sets the {@link AzureNamedKeyCredential} used for authentication. 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 AzureNamedKeyCredential} type.
+     *
+     * @param credential the {@link AzureNamedKeyCredential} to be used for authentication.
+     * @return Returns the same concrete type with the appropriate properties updated, to allow for fluent chaining of
+     *      operations.
+     */
+    T credential(AzureNamedKeyCredential credential);
+}

sdk/core/azure-core/src/main/java/com/azure/core/client/traits/AzureNamedKeyCredentialTrait.java

@@ -0,0 +1,30 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.core.client.traits;
+
+import com.azure.core.credential.AzureSasCredential;
+
+/**
+ * An {@link com.azure.core.client.traits Azure SDK for Java trait} providing a consistent interface for setting
+ * {@link AzureSasCredential}. 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 AzureSasCredential} type.
+ *
+ * @param <T> The concrete type that implements the trait. This is required so that fluent operations can continue
+ *           to return the concrete type, rather than the trait type.
+ * @see com.azure.core.client.traits
+ * @see AzureSasCredential
+ */
+public interface AzureSasCredentialTrait<T extends AzureSasCredentialTrait<T>> {
+    /**
+     * Sets the {@link AzureSasCredential} used for authentication. 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 AzureSasCredential} type.
+     *
+     * @param credential the {@link AzureSasCredential} to be used for authentication.
+     * @return Returns the same concrete type with the appropriate properties updated, to allow for fluent chaining of
+     *      operations.
+     */
+    T credential(AzureSasCredential credential);
+}