More Changes for api review (Azure#27095)

* Change for api review

* Making classes final for api review

* Adding samples on clients and changefeed processor class doc

* fixing build error on change feed builder doc

* Adding closable on encryption clients

Author: simplynaveen20

sdk/cosmos/azure-cosmos-encryption/src/main/java/com/azure/cosmos/encryption/ChangeFeedEncryptionProcessorBuilder.java

@@ -18,10 +18,22 @@
 import java.util.stream.Collectors;
 
 /**
- * Helper class to build a encryption supported {@link ChangeFeedProcessor} instance.
+ * Helper class to build a {@link ChangeFeedProcessor} instance for encryption feed container.
  *
+ * <pre>
+ * ChangeFeedProcessor changeFeedProcessor = new ChangeFeedProcessorBuilder&#40;&#41;
+ *     .hostName&#40;hostName&#41;
+ *     .feedContainer&#40;feedContainer&#41; // {@link CosmosEncryptionAsyncContainer}
+ *     .leaseContainer&#40;leaseContainer&#41;
+ *     .handleChanges&#40;docs -&gt; &#123;
+ *         for &#40;JsonNode item : docs&#41; &#123;
+ *             &#47;&#47; Implementation for handling and processing of each JsonNode item goes here
+ *         &#125;
+ *     &#125;&#41;
+ *     .buildChangeFeedProcessor&#40;&#41;;
+ * </pre>
  */
-public class ChangeFeedEncryptionProcessorBuilder {
+public final class ChangeFeedEncryptionProcessorBuilder {
 
     private String hostName ;
     private ChangeFeedProcessorOptions changeFeedProcessorOptions;

sdk/cosmos/azure-cosmos-encryption/src/main/java/com/azure/cosmos/encryption/CosmosEncryptionAsyncClient.java

@@ -21,10 +21,20 @@
 import org.slf4j.LoggerFactory;
 import reactor.core.publisher.Mono;
 
+import java.io.Closeable;
+
 /**
- * CosmosClient with encryption support.
+ * CosmosAsyncClient with encryption support.
+ * We have static method in this class which will takes two inputs
+ * {@link CosmosAsyncClient} and {@link EncryptionKeyWrapProvider}  and creates cosmosEncryptionAsyncClient as shown below.
+ * <pre>
+ * {@code
+ * CosmosEncryptionAsyncClient cosmosEncryptionAsyncClient =
+ * CosmosEncryptionAsyncClient.createCosmosEncryptionAsyncClient(cosmosAsyncClient, encryptionKeyWrapProvider);
+ * }
+ * </pre>
  */
-public class CosmosEncryptionAsyncClient {
+public final class CosmosEncryptionAsyncClient implements Closeable {
     private final static Logger LOGGER = LoggerFactory.getLogger(CosmosEncryptionAsyncClient.class);
     private final CosmosAsyncClient cosmosAsyncClient;
     private final AsyncCache<String, CosmosContainerProperties> containerPropertiesCacheByContainerId;
@@ -175,6 +185,7 @@ public CosmosEncryptionAsyncDatabase getCosmosEncryptionAsyncDatabase(String dat
     /**
      * Close this {@link CosmosAsyncClient} instance and cleans up the resources.
      */
+    @Override
     public void close() {
         cosmosAsyncClient.close();
     }

sdk/cosmos/azure-cosmos-encryption/src/main/java/com/azure/cosmos/encryption/CosmosEncryptionAsyncContainer.java

@@ -30,8 +30,6 @@
 import com.azure.cosmos.models.CosmosBulkItemResponse;
 import com.azure.cosmos.models.CosmosBulkOperationResponse;
 import com.azure.cosmos.models.CosmosChangeFeedRequestOptions;
-import com.azure.cosmos.models.CosmosClientEncryptionKeyProperties;
-import com.azure.cosmos.models.CosmosContainerProperties;
 import com.azure.cosmos.models.CosmosItemOperation;
 import com.azure.cosmos.models.CosmosItemRequestOptions;
 import com.azure.cosmos.models.CosmosItemResponse;
@@ -68,7 +66,7 @@
 /**
  * CosmosAsyncContainer with encryption capabilities.
  */
-public class CosmosEncryptionAsyncContainer {
+public final class CosmosEncryptionAsyncContainer {
     private final Scheduler encryptionScheduler;
     private final CosmosResponseFactory responseFactory = new CosmosResponseFactory();
     private final CosmosAsyncContainer container;
@@ -226,7 +224,7 @@ public <T> Mono<CosmosItemResponse<Object>> deleteItem(T item, CosmosItemRequest
      * @param requestOptions the request options.
      * @return an {@link Mono} containing the Cosmos item resource response.
      */
-    @Beta(value = Beta.SinceVersion.V1, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
+    @Beta(value = Beta.SinceVersion.V1_0_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
     public Mono<CosmosItemResponse<Object>> deleteAllItemsByPartitionKey(PartitionKey partitionKey, CosmosItemRequestOptions requestOptions) {
         if (requestOptions == null) {
             requestOptions = new CosmosItemRequestOptions();
@@ -523,7 +521,7 @@ public <T> CosmosPagedFlux<T> queryItemsOnEncryptedProperties(SqlQuerySpecWithEn
      * @return a {@link CosmosPagedFlux} containing one or several feed response pages of the obtained
      * items or an error.
      */
-    @Beta(value = Beta.SinceVersion.V1, warningText =
+    @Beta(value = Beta.SinceVersion.V1_0_0, warningText =
         Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
     public <T> CosmosPagedFlux<T> queryChangeFeed(CosmosChangeFeedRequestOptions options, Class<T> classType) {
         checkNotNull(options, "Argument 'options' must not be null.");
@@ -955,8 +953,6 @@ public Function<CosmosPagedFluxOptions, Flux<FeedResponse<T>>> transform(Functio
      * Use {@link CosmosBatchResponse#isSuccessStatusCode} on the response returned to ensure that the
      * transactional batch succeeded.
      */
-    @Beta(value = Beta.SinceVersion.V1, warningText =
-        Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
     public Mono<CosmosBatchResponse> executeCosmosBatch(CosmosBatch cosmosBatch) {
         return this.executeCosmosBatch(cosmosBatch, new CosmosBatchRequestOptions());
     }

sdk/cosmos/azure-cosmos-encryption/src/main/java/com/azure/cosmos/encryption/CosmosEncryptionAsyncDatabase.java

@@ -25,7 +25,7 @@
 /**
  * CosmosEncryptionAsyncDatabase with encryption capabilities.
  */
-public class CosmosEncryptionAsyncDatabase {
+public final class CosmosEncryptionAsyncDatabase {
     private final CosmosAsyncDatabase cosmosAsyncDatabase;
     private final CosmosEncryptionAsyncClient cosmosEncryptionAsyncClient;
     private final static EncryptionImplementationBridgeHelpers.EncryptionKeyWrapProviderHelper.EncryptionKeyWrapProviderAccessor encryptionKeyWrapProviderAccessor =

sdk/cosmos/azure-cosmos-encryption/src/main/java/com/azure/cosmos/encryption/CosmosEncryptionClient.java

@@ -8,15 +8,25 @@
 import com.azure.cosmos.CosmosClient;
 import com.azure.cosmos.CosmosDatabase;
 import com.azure.cosmos.encryption.keyprovider.EncryptionKeyWrapProvider;
-import com.azure.cosmos.implementation.ImplementationBridgeHelpers.CosmosClientHelper.CosmosClientAccessor;
 import com.azure.cosmos.implementation.ImplementationBridgeHelpers.CosmosClientHelper;
+import com.azure.cosmos.implementation.ImplementationBridgeHelpers.CosmosClientHelper.CosmosClientAccessor;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import java.io.Closeable;
+
 /**
  * CosmosClient with encryption support.
+ * We have static method in this class which will takes two inputs
+ * {@link CosmosClient} and {@link EncryptionKeyWrapProvider}  and creates cosmosEncryptionClient as shown below.
+ * <pre>
+ * {@code
+ * CosmosEncryptionClient cosmosEncryptionClient =
+ * CosmosEncryptionClient.createCosmosEncryptionClient(cosmosClient, encryptionKeyWrapProvider);
+ * }
+ * </pre>
  */
-public class CosmosEncryptionClient {
+public final class CosmosEncryptionClient implements Closeable {
     private final static Logger LOGGER = LoggerFactory.getLogger(CosmosEncryptionAsyncClient.class);
     private final CosmosEncryptionAsyncClient cosmosEncryptionAsyncClient;
     private EncryptionKeyWrapProvider encryptionKeyWrapProvider;
@@ -89,4 +99,12 @@ public CosmosEncryptionDatabase getCosmosEncryptionDatabase(CosmosDatabase cosmo
     CosmosEncryptionAsyncClient getCosmosEncryptionAsyncClient() {
         return cosmosEncryptionAsyncClient;
     }
+
+    /**
+     * Close this {@link CosmosClient} instance and cleans up the resources.
+     */
+    @Override
+    public void close() {
+        cosmosClient.close();
+    }
 }

sdk/cosmos/azure-cosmos-encryption/src/main/java/com/azure/cosmos/encryption/CosmosEncryptionContainer.java

@@ -36,7 +36,7 @@
 /**
  * CosmosContainer with encryption capabilities.
  */
-public class CosmosEncryptionContainer {
+public final class CosmosEncryptionContainer {
     private final CosmosContainer cosmosContainer;
     private final CosmosEncryptionAsyncContainer cosmosEncryptionAsyncContainer;
 
@@ -124,7 +124,7 @@ public <T> CosmosItemResponse<Object> deleteItem(T item, CosmosItemRequestOption
      * @param options the options.
      * @return the Cosmos item response
      */
-    @Beta(value = Beta.SinceVersion.V1, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
+    @Beta(value = Beta.SinceVersion.V1_0_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
     public CosmosItemResponse<Object> deleteAllItemsByPartitionKey(PartitionKey partitionKey, CosmosItemRequestOptions options) {
         return this.blockDeleteItemResponse(this.cosmosEncryptionAsyncContainer.deleteAllItemsByPartitionKey(partitionKey, options));
     }
@@ -278,7 +278,7 @@ public <T> CosmosPagedIterable<T> queryItemsOnEncryptedProperties(SqlQuerySpecWi
      * @param classType the class type.
      * @return a {@link CosmosPagedFlux} containing one feed response page
      */
-    @Beta(value = Beta.SinceVersion.V1, warningText =
+    @Beta(value = Beta.SinceVersion.V1_0_0, warningText =
         Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
     public <T> CosmosPagedIterable<T> queryChangeFeed(
         CosmosChangeFeedRequestOptions options,

sdk/cosmos/azure-cosmos-encryption/src/main/java/com/azure/cosmos/encryption/CosmosEncryptionDatabase.java

@@ -16,7 +16,7 @@
 /**
  * CosmosEncryptionDatabase with encryption capabilities.
  */
-public class CosmosEncryptionDatabase {
+public final class CosmosEncryptionDatabase {
     private final CosmosDatabase cosmosDatabase;
     private final CosmosEncryptionAsyncDatabase cosmosEncryptionAsyncDatabase;
 

sdk/cosmos/azure-cosmos-encryption/src/main/java/com/azure/cosmos/encryption/keyprovider/AzureKeyVaultKeyWrapProvider.java

@@ -7,6 +7,7 @@
 import com.azure.cosmos.encryption.implementation.mdesrc.azurekeyvaultprovider.AzureKeyVaultKeyStoreProvider;
 import com.azure.cosmos.encryption.implementation.mdesrc.cryptography.KeyEncryptionKeyAlgorithm;
 import com.azure.cosmos.encryption.implementation.mdesrc.cryptography.MicrosoftDataEncryptionException;
+import com.azure.cosmos.encryption.models.KeyEncryptionAlgorithm;
 import com.azure.cosmos.implementation.HttpConstants;
 import com.azure.cosmos.implementation.ImplementationBridgeHelpers;
 
@@ -30,7 +31,7 @@
  * <p>
  * signature: Signature of the entire byte array. Signature is validated before decrypting the data encryption key.
  */
-public class AzureKeyVaultKeyWrapProvider extends EncryptionKeyWrapProvider {
+public final class AzureKeyVaultKeyWrapProvider extends EncryptionKeyWrapProvider {
     private AzureKeyVaultKeyStoreProvider azureKeyVaultKeyStoreProvider;
     private final static ImplementationBridgeHelpers.CosmosExceptionHelper.CosmosExceptionAccessor cosmosExceptionAccessor =
         ImplementationBridgeHelpers.CosmosExceptionHelper.getCosmosExceptionAccessor();
@@ -71,7 +72,7 @@ public String getProviderName() {
     @Override
     public byte[] unwrapKey(String encryptionKeyId, String cosmosKeyEncryptionKeyAlgorithm, byte[] encryptedKey) {
         try {
-            if (!com.azure.cosmos.encryption.models.KeyEncryptionKeyAlgorithm.RSA_OAEP.getName().equals(cosmosKeyEncryptionKeyAlgorithm)) {
+            if (!KeyEncryptionAlgorithm.RSA_OAEP.getName().equals(cosmosKeyEncryptionKeyAlgorithm)) {
                 throw new IllegalArgumentException("The specified KeyEncryptionAlgorithm is not supported. Please " +
                     "refer to https://aka.ms/CosmosClientEncryption for more details. ");
             }
@@ -93,7 +94,7 @@ public byte[] unwrapKey(String encryptionKeyId, String cosmosKeyEncryptionKeyAlg
     @Override
     public byte[] wrapKey(String encryptionKeyId, String cosmosKeyEncryptionKeyAlgorithm, byte[] key) {
         try {
-            if (!com.azure.cosmos.encryption.models.KeyEncryptionKeyAlgorithm.RSA_OAEP.getName().equals(cosmosKeyEncryptionKeyAlgorithm)) {
+            if (!KeyEncryptionAlgorithm.RSA_OAEP.getName().equals(cosmosKeyEncryptionKeyAlgorithm)) {
                 throw new IllegalArgumentException("The specified KeyEncryptionAlgorithm is not supported. Please " +
                     "refer to https://aka.ms/CosmosClientEncryption for more details. ");
             }

…on/models/KeyEncryptionKeyAlgorithm.java …ption/models/KeyEncryptionAlgorithm.javasdk/cosmos/azure-cosmos-encryption/src/main/java/com/azure/cosmos/encryption/models/KeyEncryptionKeyAlgorithm.java renamed to sdk/cosmos/azure-cosmos-encryption/src/main/java/com/azure/cosmos/encryption/models/KeyEncryptionAlgorithm.java sdk/cosmos/azure-cosmos-encryption/src/main/java/com/azure/cosmos/encryption/models/KeyEncryptionKeyAlgorithm.java renamed to sdk/cosmos/azure-cosmos-encryption/src/main/java/com/azure/cosmos/encryption/models/KeyEncryptionAlgorithm.java

@@ -11,16 +11,16 @@
  * Represents the encryption algorithms supported for key encryption.
  *
  */
-public enum KeyEncryptionKeyAlgorithm {
+public enum KeyEncryptionAlgorithm {
     /**
      * RSA public key cryptography algorithm with Optimal Asymmetric Encryption Padding (OAEP) padding.
      */
     RSA_OAEP("RSA_OAEP");
 
     private final String keyEncryptionKeyAlgorithmName;
-    private static final Map<String, KeyEncryptionKeyAlgorithm> ENUM_MAP;
+    private static final Map<String, KeyEncryptionAlgorithm> ENUM_MAP;
 
-    KeyEncryptionKeyAlgorithm(String keyEncryptionKeyAlgorithmName) {
+    KeyEncryptionAlgorithm(String keyEncryptionKeyAlgorithmName) {
         this.keyEncryptionKeyAlgorithmName = keyEncryptionKeyAlgorithmName;
     }
 
@@ -45,19 +45,19 @@ public String getName() {
     // Any Map impl can be used.
 
     static {
-        Map<String, KeyEncryptionKeyAlgorithm> map = new ConcurrentHashMap<>();
-        for (KeyEncryptionKeyAlgorithm instance : KeyEncryptionKeyAlgorithm.values()) {
+        Map<String, KeyEncryptionAlgorithm> map = new ConcurrentHashMap<>();
+        for (KeyEncryptionAlgorithm instance : KeyEncryptionAlgorithm.values()) {
             map.put(instance.getName(), instance);
         }
         ENUM_MAP = Collections.unmodifiableMap(map);
     }
 
     /**
-     *  Gets the KeyEncryptionKeyAlgorithm enum back from the string value
+     *  Gets the KeyEncryptionAlgorithm enum back from the string value
      * @param name the string value
-     * @return KeyEncryptionKeyAlgorithm enum
+     * @return KeyEncryptionAlgorithm enum
      */
-    public static KeyEncryptionKeyAlgorithm get(String name) {
+    public static KeyEncryptionAlgorithm get(String name) {
         return ENUM_MAP.get(name);
     }
 }

sdk/cosmos/azure-cosmos-encryption/src/main/java/com/azure/cosmos/encryption/util/Beta.java

@@ -38,13 +38,13 @@
     /**
      * @return the version number when the annotated API was first introduced to the library as in Beta
      */
-    SinceVersion value() default SinceVersion.V1;
+    SinceVersion value() default SinceVersion.V1_0_0;
 
     /**
      * Azure library version numbers
      */
     enum SinceVersion {
-        /** v1 */
-        V1
+        /** v1_0_0 */
+        V1_0_0
     }
 }