Added code snippets for Key Vault Administration clients and builders. (Azure#22341)

* Added classes containing code snippets for AccessControl and Backup clients.

* Added code snippets to clients and client builders.

* Updated KV Administration README and added embedded samples.

* Updated embedme paths in README.

* Removed localization in link.

* Fixed JavaDoc line length issue.

* Fixed CheckStyle issue.

Author: vcolin7

sdk/keyvault/azure-security-keyvault-administration/README.md

@@ -42,18 +42,13 @@
  * <p> The minimal configuration options required by {@link KeyVaultAccessControlClientBuilder} to build an
  * an {@link KeyVaultAccessControlAsyncClient} are {@link String vaultUrl} and {@link TokenCredential credential}.</p>
  *
- * <p>The {@link HttpLogDetailLevel}, multiple custom {@link HttpLoggingPolicy policies} and custom
- * {@link HttpClient} can be optionally configured in the {@link KeyVaultAccessControlClientBuilder}.</p>
+ * <p><strong>Samples to construct a sync client</strong></p>
+ * {@codesnippet com.azure.security.keyvault.administration.keyVaultAccessControlClient.instantiation}
+ * <p><strong>Samples to construct an async client</strong></p>
+ * {@codesnippet com.azure.security.keyvault.administration.keyVaultAccessControlAsyncClient.instantiation}
  *
- * <p>Alternatively, a custom {@link HttpPipeline} with custom {@link HttpPipelinePolicy} policies and {@link String
- * vaultUrl} can be specified. It provides finer control over the construction of
- * {@link KeyVaultAccessControlAsyncClient} and {@link KeyVaultAccessControlClient} instances.</p>
- *
- * <p> The minimal configuration options required by {@link KeyVaultAccessControlClientBuilder} to build an
- * {@link KeyVaultAccessControlClient} are {@link String vaultUrl} and {@link TokenCredential credential}. </p>
- *
- * @see KeyVaultAccessControlAsyncClient
  * @see KeyVaultAccessControlClient
+ * @see KeyVaultAccessControlAsyncClient
  */
 @ServiceClientBuilder(serviceClients = {KeyVaultAccessControlClient.class, KeyVaultAccessControlAsyncClient.class})
 public final class KeyVaultAccessControlClientBuilder {

sdk/keyvault/azure-security-keyvault-administration/src/main/java/com/azure/security/keyvault/administration/KeyVaultAccessControlAsyncClient.java

@@ -52,6 +52,14 @@
 /**
  * The {@link KeyVaultBackupAsyncClient} provides asynchronous methods to perform full backup and restore of an Azure
  * Key Vault.
+ *
+ * <p>Instances of this client are obtained by calling the {@link KeyVaultBackupClientBuilder#buildAsyncClient()}
+ * method on a {@link KeyVaultBackupClientBuilder} object.</p>
+ *
+ * <p><strong>Samples to construct an async client</strong></p>
+ * {@codesnippet com.azure.security.keyvault.administration.keyVaultBackupAsyncClient.instantiation}
+ *
+ * @see KeyVaultBackupClientBuilder
  */
 @ServiceClient(builder = KeyVaultBackupClientBuilder.class, isAsync = true)
 public final class KeyVaultBackupAsyncClient {
@@ -129,6 +137,12 @@ HttpPipeline getHttpPipeline() {
     /**
      * Initiates a full backup of the Key Vault.
      *
+     * <p><strong>Code Samples</strong></p>
+     * <p>Starts a {@link KeyVaultBackupOperation backup operation}, polls for its status and waits for it to complete.
+     * Prints out the details of the operation's final result in case of success or prints out details of an error in
+     * case the operation fails.</p>
+     * {@codesnippet com.azure.security.keyvault.administration.keyVaultBackupAsyncClient.beginBackup#String-String}
+     *
      * @param blobStorageUrl The URL for the Blob Storage resource where the backup will be located.
      * @param sasToken A Shared Access Signature (SAS) token to authorize access to the blob.
      *
@@ -286,6 +300,11 @@ private static LongRunningOperationStatus toLongRunningOperationStatus(String op
     /**
      * Initiates a full restore of the Key Vault.
      *
+     * <p><strong>Code Samples</strong></p>
+     * <p>Starts a {@link KeyVaultRestoreOperation restore operation}, polls for its status and waits for it to
+     * complete. Prints out error details in case the operation fails.</p>
+     * {@codesnippet com.azure.security.keyvault.administration.keyVaultBackupAsyncClient.beginRestore#String-String}
+     *
      * @param folderUrl The URL for the Blob Storage resource where the backup is located, including the path to
      * the blob container where the backup resides. This would be the exact value that is returned as the result of a
      * backup operation. An example of such a URL may look like the following:
@@ -427,6 +446,11 @@ private static Mono<PollResponse<KeyVaultRestoreOperation>> processRestoreOperat
      * Restores all versions of a given key using the supplied SAS token pointing to a previously stored Azure Blob
      * storage backup folder.
      *
+     * <p><strong>Code Samples</strong></p>
+     * <p>Starts a {@link KeyVaultSelectiveKeyRestoreOperation selective key restore operation}, polls for its status
+     * and waits for it to complete. Prints out error details in case the operation fails.</p>
+     * {@codesnippet com.azure.security.keyvault.administration.keyVaultBackupAsyncClient.beginSelectiveKeyRestore#String-String-String}
+     *
      * @param keyName The name of the key to be restored.
      * @param folderUrl The URL for the Blob Storage resource where the backup is located, including the path to
      * the blob container where the backup resides. This would be the exact value that is returned as the result of a

sdk/keyvault/azure-security-keyvault-administration/src/main/java/com/azure/security/keyvault/administration/KeyVaultAccessControlClient.java

@@ -15,8 +15,16 @@
 import com.azure.security.keyvault.administration.models.KeyVaultSelectiveKeyRestoreResult;
 
 /**
- * The {@link KeyVaultBackupClient} provides synchronous methods to perform full backup and restore of an Azure Key
- * Vault.
+ * The {@link KeyVaultBackupClient} provides synchronous methods to perform backup and restore operations of an Azure
+ * Key Vault.
+ *
+ * <p>Instances of this client are obtained by calling the {@link KeyVaultBackupClientBuilder#buildClient()}
+ * method on a {@link KeyVaultBackupClientBuilder} object.</p>
+ *
+ * <p><strong>Samples to construct a sync client</strong></p>
+ * {@codesnippet com.azure.security.keyvault.administration.keyVaultBackupClient.instantiation}
+ *
+ * @see KeyVaultBackupClientBuilder
  */
 @ServiceClient(builder = KeyVaultBackupClientBuilder.class)
 public final class KeyVaultBackupClient {
@@ -43,6 +51,12 @@ public String getVaultUrl() {
     /**
      * Initiates a full backup of the Key Vault.
      *
+     * <p><strong>Code Samples</strong></p>
+     * <p>Starts a {@link KeyVaultBackupOperation backup operation}, polls for its status and waits for it to complete.
+     * Prints out the details of the operation's final result in case of success or prints out error details in case the
+     * operation fails.</p>
+     * {@codesnippet com.azure.security.keyvault.administration.keyVaultBackupClient.beginBackup#String-String}
+     *
      * @param blobStorageUrl The URL for the Blob Storage resource where the backup will be located.
      * @param sasToken A Shared Access Signature (SAS) token to authorize access to the blob.
      *
@@ -59,6 +73,11 @@ public SyncPoller<KeyVaultBackupOperation, String> beginBackup(String blobStorag
     /**
      * Initiates a full restore of the Key Vault.
      *
+     * <p><strong>Code Samples</strong></p>
+     * <p>Starts a {@link KeyVaultRestoreOperation restore operation}, polls for its status and waits for it to
+     * complete. Prints out error details in case the operation fails.</p>
+     * {@codesnippet com.azure.security.keyvault.administration.keyVaultBackupClient.beginBackup#String-String}
+     *
      * @param folderUrl The URL for the Blob Storage resource where the backup is located, including the path to
      * the blob container where the backup resides. This would be the exact value that is returned as the result of a
      * backup operation. An example of such a URL may look like the following:
@@ -79,6 +98,11 @@ public SyncPoller<KeyVaultRestoreOperation, KeyVaultRestoreResult> beginRestore(
      * Restores all versions of a given key using the supplied SAS token pointing to a previously stored Azure Blob
      * storage backup folder.
      *
+     * <p><strong>Code Samples</strong></p>
+     * <p>Starts a {@link KeyVaultSelectiveKeyRestoreOperation selective key restore operation}, polls for its status
+     * and waits for it to complete. Prints out error details in case the operation fails.</p>
+     * {@codesnippet com.azure.security.keyvault.administration.keyVaultBackupClient.beginSelectiveKeyRestore#String-String-String}
+     *
      * @param keyName The name of the key to be restored.
      * @param folderUrl The URL for the Blob Storage resource where the backup is located, including the path to
      * the blob container where the backup resides. This would be the exact value that is returned as the result of a

sdk/keyvault/azure-security-keyvault-administration/src/main/java/com/azure/security/keyvault/administration/KeyVaultAccessControlClientBuilder.java

@@ -41,18 +41,13 @@
  * <p> The minimal configuration options required by {@link KeyVaultBackupClientBuilder} to build an
  * an {@link KeyVaultBackupAsyncClient} are {@link String vaultUrl} and {@link TokenCredential credential}.</p>
  *
- * <p>The {@link HttpLogDetailLevel}, multiple custom {@link HttpLoggingPolicy policies} and custom
- * {@link HttpClient} can be optionally configured in the {@link KeyVaultBackupClientBuilder}.</p>
+ * <p><strong>Samples to construct a sync client</strong></p>
+ * {@codesnippet com.azure.security.keyvault.administration.keyVaultBackupClient.instantiation}
+ * <p><strong>Samples to construct an async client</strong></p>
+ * {@codesnippet com.azure.security.keyvault.administration.keyVaultBackupAsyncClient.instantiation}
  *
- * <p>Alternatively, a custom {@link HttpPipeline} with custom {@link HttpPipelinePolicy} policies and {@link String
- * vaultUrl} can be specified. It provides finer control over the construction of {@link KeyVaultBackupAsyncClient}
- * and {@link KeyVaultBackupClient} instances.</p>
- *
- * <p> The minimal configuration options required by {@link KeyVaultBackupClientBuilder} to build an
- * {@link KeyVaultBackupClient} are {@link String vaultUrl} and {@link TokenCredential credential}. </p>
- *
- * @see KeyVaultBackupAsyncClient
  * @see KeyVaultBackupClient
+ * @see KeyVaultBackupAsyncClient
  */
 @ServiceClientBuilder(serviceClients = {KeyVaultBackupClient.class, KeyVaultBackupAsyncClient.class})
 public final class KeyVaultBackupClientBuilder {