Updated cosmos client builder docs and other docs

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/CosmosAsyncContainer.java

@@ -71,7 +71,7 @@ public Mono<CosmosAsyncContainerResponse> read() {
     }
 
     /**
-     * Reads the document container by the container link.
+     * Reads the container
      * <p>
      * After subscription the operation will be performed. The {@link Mono} upon
      * successful completion will contain a single cosmos container response with

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/CosmosAsyncPermission.java

@@ -27,7 +27,7 @@ public class CosmosAsyncPermission {
      *
      * @return the id of the {@link CosmosAsyncPermission}
      */
-    public String id() {
+    public String getId() {
         return id;
     }
 
@@ -37,7 +37,7 @@ public String id() {
      * @param id the id of the {@link CosmosAsyncPermission}
      * @return the same {@link CosmosAsyncPermission} that had the id set
      */
-    CosmosAsyncPermission id(String id) {
+    CosmosAsyncPermission setId(String id) {
         this.id = id;
         return this;
     }
@@ -122,7 +122,7 @@ String getLink() {
         builder.append("/");
         builder.append(getURIPathSegment());
         builder.append("/");
-        builder.append(id());
+        builder.append(getId());
         return builder.toString();
     }
 }

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/CosmosAsyncStoredProcedure.java

@@ -31,7 +31,7 @@ public class CosmosAsyncStoredProcedure {
      *
      * @return the id of the {@link CosmosAsyncStoredProcedure}
      */
-    public String id() {
+    public String getId() {
         return id;
     }
 
@@ -41,13 +41,13 @@ public String id() {
      * @param id the id of the {@link CosmosAsyncStoredProcedure}
      * @return the same {@link CosmosAsyncStoredProcedure} that had the id set
      */
-    CosmosAsyncStoredProcedure id(String id) {
+    CosmosAsyncStoredProcedure setId(String id) {
         this.id = id;
         return this;
     }
 
     /**
-     * Read a stored procedure by the stored procedure link.
+     * Read a stored procedure
      * <p>
      * After subscription the operation will be performed.
      * The {@link Mono} upon successful completion will contain a single resource response with the read stored
@@ -61,7 +61,7 @@ public Mono<CosmosAsyncStoredProcedureResponse> read() {
     }
 
     /**
-     * Read a stored procedure by the stored procedure link.
+     * Read a stored procedure
      * <p>
      * After subscription the operation will be performed.
      * The {@link Mono} upon successful completion will contain a single resource response with the read stored
@@ -81,7 +81,7 @@ public Mono<CosmosAsyncStoredProcedureResponse> read(CosmosStoredProcedureReques
     }
 
     /**
-     * Deletes a stored procedure by the stored procedure link.
+     * Deletes a stored procedure
      * <p>
      * After subscription the operation will be performed.
      * The {@link Mono} upon successful completion will contain a single resource response for the deleted stored
@@ -95,7 +95,7 @@ public Mono<CosmosAsyncStoredProcedureResponse> delete() {
     }
 
     /**
-     * Deletes a stored procedure by the stored procedure link.
+     * Deletes a stored procedure
      * <p>
      * After subscription the operation will be performed.
      * The {@link Mono} upon successful completion will contain a single resource response for the deleted stored
@@ -117,7 +117,7 @@ public Mono<CosmosAsyncStoredProcedureResponse> delete(CosmosStoredProcedureRequ
     }
 
     /**
-     * Executes a stored procedure by the stored procedure link.
+     * Executes a stored procedure
      * <p>
      * After subscription the operation will be performed.
      * The {@link Mono} upon successful completion will contain a single resource response with the stored procedure
@@ -195,7 +195,7 @@ String getLink() {
         builder.append("/");
         builder.append(getURIPathSegment());
         builder.append("/");
-        builder.append(id());
+        builder.append(getId());
         return builder.toString();
     }
 }

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/CosmosAsyncTrigger.java

@@ -43,7 +43,7 @@ CosmosAsyncTrigger setId(String id) {
     }
 
     /**
-     * Reads a cosmos trigger by the trigger link.
+     * Reads a cosmos trigger
      * <p>
      * After subscription the operation will be performed.
      * The {@link Mono} upon successful completion will contain a single resource response for the read trigger.

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/CosmosClientBuilder.java

@@ -14,19 +14,65 @@
 import java.util.List;
 
 /**
- * Helper class to buildAsyncClient {@link CosmosAsyncClient} instances
- * as logical representation of the Azure Cosmos database service.
+ * Helper class to build CosmosAsyncClient {@link CosmosAsyncClient} and CosmosClient {@link CosmosClient}
+ * instances as logical representation of the Azure Cosmos database service.
+ *
+ * When building client, endpoint() and key() are mandatory APIs, without these the initialization will fail.
+ *
+ * Though consistencyLevel is not mandatory, but we strongly suggest to pay attention to this API when building client.
+ * By default, database account level consistency level is used if none is provided.
+ *
+ * <pre>
+ *     Building Cosmos Async Client minimal APIs (without any customized configurations)
+ * {@code
+ * CosmosAsyncClient client = new CosmosClientBuilder()
+ *         .endpoint(serviceEndpoint)
+ *         .key(key)
+ *         .buildAsyncClient();
+ * }
+ * </pre>
  *
  * <pre>
+ *     Building Cosmos Async Client with customizations
  * {@code
  * CosmosAsyncClient client = new CosmosClientBuilder()
  *         .endpoint(serviceEndpoint)
  *         .key(key)
- *         .directMode()
+ *         .directMode(directConnectionConfig, gatewayConnectionConfig)
  *         .consistencyLevel(ConsistencyLevel.SESSION)
+ *         .connectionSharingAcrossClientsEnabled(true)
+ *         .contentResponseOnWriteEnabled(true)
+ *         .userAgentSuffix("my-application1-client")
+ *         .preferredRegions(Collections.singletonList("West US", "East US"))
  *         .buildAsyncClient();
  * }
  * </pre>
+ *
+ * <pre>
+ *     Building Cosmos Sync Client minimal APIs (without any customized configurations)
+ * {@code
+ * CosmosClient client = new CosmosClientBuilder()
+ *         .endpoint(serviceEndpoint)
+ *         .key(key)
+ *         .buildClient();
+ * }
+ * </pre>
+ *
+ * <pre>
+ *     Building Cosmos Sync Client with customizations
+ * {@code
+ * CosmosClient client = new CosmosClientBuilder()
+ *         .endpoint(serviceEndpoint)
+ *         .key(key)
+ *         .directMode(directConnectionConfig, gatewayConnectionConfig)
+ *         .consistencyLevel(ConsistencyLevel.SESSION)
+ *         .connectionSharingAcrossClientsEnabled(true)
+ *         .contentResponseOnWriteEnabled(true)
+ *         .userAgentSuffix("my-application1-client")
+ *         .preferredRegions(Collections.singletonList("West US", "East US"))
+ *         .buildClient();
+ * }
+ * </pre>
  */
 @ServiceClientBuilder(serviceClients = {CosmosClient.class, CosmosAsyncClient.class})
 public class CosmosClientBuilder {
@@ -94,15 +140,13 @@ boolean isSessionCapturingOverrideEnabled() {
      * CosmosAsyncClient client1 = new CosmosClientBuilder()
      *         .endpoint(serviceEndpoint1)
      *         .key(key1)
-     *         .directMode()
      *         .consistencyLevel(ConsistencyLevel.SESSION)
      *         .connectionSharingAcrossClientsEnabled(true)
      *         .buildAsyncClient();
      *
      * CosmosAsyncClient client2 = new CosmosClientBuilder()
      *         .endpoint(serviceEndpoint2)
      *         .key(key2)
-     *         .directMode()
      *         .consistencyLevel(ConsistencyLevel.SESSION)
      *         .connectionSharingAcrossClientsEnabled(true)
      *         .buildAsyncClient();
@@ -247,6 +291,8 @@ public CosmosClientBuilder permissions(List<CosmosPermissionProperties> permissi
     /**
      * Gets the {@link ConsistencyLevel} to be used
      *
+     * By default, {@link ConsistencyLevel#SESSION} consistency will be used.
+     *
      * @return the consistency level
      */
     ConsistencyLevel getConsistencyLevel() {
@@ -256,6 +302,8 @@ ConsistencyLevel getConsistencyLevel() {
     /**
      * Sets the {@link ConsistencyLevel} to be used
      *
+     * By default, {@link ConsistencyLevel#SESSION} consistency will be used.
+     *
      * @param desiredConsistencyLevel {@link ConsistencyLevel}
      * @return current Builder
      */
@@ -352,6 +400,8 @@ public CosmosClientBuilder gatewayMode(GatewayConnectionConfig gatewayConnection
     /**
      * Sets the default DIRECT connection configuration to be used.
      *
+     * By default, the builder is initialized with directMode()
+     *
      * @return current CosmosClientBuilder
      */
     public CosmosClientBuilder directMode() {
@@ -362,6 +412,8 @@ public CosmosClientBuilder directMode() {
     /**
      * Sets the DIRECT connection configuration to be used.
      *
+     * By default, the builder is initialized with directMode()
+     *
      * @param directConnectionConfig direct connection configuration
      * @return current CosmosClientBuilder
      */
@@ -464,8 +516,8 @@ public CosmosClientBuilder endpointDiscoveryEnabled(boolean endpointDiscoveryEna
      * to true has no effect until EnableMultipleWriteRegions in DatabaseAccount
      * is also set to true.
      * <p>
-     * DEFAULT value is false indicating that writes are only directed to
-     * first region in PreferredRegions property.
+     * DEFAULT value is true indicating that writes are directed to
+     * available writable regions of geo-replicated database account.
      *
      * @param multipleWriteRegionsEnabled flag to enable writes on any regions for geo-replicated
      * database accounts.
@@ -585,7 +637,7 @@ boolean isReadRequestsFallbackEnabled() {
     }
 
     /**
-     * Builds a cosmos configuration object with the provided properties
+     * Builds a cosmos async client with the provided properties
      *
      * @return CosmosAsyncClient
      */
@@ -597,7 +649,7 @@ public CosmosAsyncClient buildAsyncClient() {
     }
 
     /**
-     * Builds a cosmos sync client object with the provided properties
+     * Builds a cosmos sync client with the provided properties
      *
      * @return CosmosClient
      */
@@ -610,17 +662,15 @@ public CosmosClient buildClient() {
 
     //  Connection policy has to be built before it can be used by this builder
     private void buildConnectionPolicy() {
-        if (this.directConnectionConfig == null && this.gatewayConnectionConfig == null) {
-            throw new IllegalArgumentException("cannot build connection policy without direct or gateway connection config");
-        } else if (this.directConnectionConfig != null) {
+        if (this.directConnectionConfig != null) {
             this.connectionPolicy = new ConnectionPolicy(directConnectionConfig);
             //  Check if the user passed additional gateway connection configuration
             if (this.gatewayConnectionConfig != null) {
                 this.connectionPolicy.setMaxConnectionPoolSize(this.gatewayConnectionConfig.getMaxConnectionPoolSize());
                 this.connectionPolicy.setRequestTimeout(this.gatewayConnectionConfig.getRequestTimeout());
                 this.connectionPolicy.setIdleConnectionTimeout(this.gatewayConnectionConfig.getIdleConnectionTimeout());
             }
-        } else {
+        } else if (gatewayConnectionConfig != null) {
             this.connectionPolicy = new ConnectionPolicy(gatewayConnectionConfig);
         }
         this.connectionPolicy.setPreferredRegions(this.preferredRegions);
@@ -640,8 +690,6 @@ private void validateConfig() {
                 + "azure key credential");
         ifThrowIllegalArgException(credential != null && StringUtils.isEmpty(credential.getKey()),
             "cannot buildAsyncClient client without key credential");
-        ifThrowIllegalArgException(directConnectionConfig == null && gatewayConnectionConfig == null,
-            "cannot buildAsyncClient client without connection config");
     }
 
     Configs configs() {

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/CosmosScripts.java

@@ -266,7 +266,7 @@ CosmosStoredProcedureResponse mapStoredProcedureResponseAndBlock(
      */
     CosmosStoredProcedureResponse convertResponse(CosmosAsyncStoredProcedureResponse response) {
         if (response.getStoredProcedure() != null) {
-            return ModelBridgeInternal.createCosmosStoredProcedureResponse(response, getStoredProcedure(response.getStoredProcedure().id()));
+            return ModelBridgeInternal.createCosmosStoredProcedureResponse(response, getStoredProcedure(response.getStoredProcedure().getId()));
         } else {
             return ModelBridgeInternal.createCosmosStoredProcedureResponse(response, null);
         }

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/AsyncDocumentClient.java

@@ -399,7 +399,7 @@ Mono<ResourceResponse<DocumentCollection>> createCollection(String databaseLink,
     Mono<ResourceResponse<DocumentCollection>> replaceCollection(DocumentCollection collection, RequestOptions options);
 
     /**
-     * Deletes a document collection by the collection link.
+     * Deletes a document collection
      * <p>
      * After subscription the operation will be performed.
      * The {@link Mono} upon successful completion will contain a single resource response for the deleted database.
@@ -412,7 +412,7 @@ Mono<ResourceResponse<DocumentCollection>> createCollection(String databaseLink,
     Mono<ResourceResponse<DocumentCollection>> deleteCollection(String collectionLink, RequestOptions options);
 
     /**
-     * Reads a document collection by the collection link.
+     * Reads a document collection
      * <p>
      * After subscription the operation will be performed.
      * The {@link Mono} upon successful completion will contain a single resource response with the read collection.
@@ -525,7 +525,7 @@ Mono<ResourceResponse<Document>> upsertDocument(String collectionLink, Object do
     Mono<ResourceResponse<Document>> replaceDocument(Document document, RequestOptions options);
 
     /**
-     * Deletes a document by the document link.
+     * Deletes a document
      * <p>
      * After subscription the operation will be performed.
      * The {@link Mono} upon successful completion will contain a single resource response for the deleted document.
@@ -538,7 +538,7 @@ Mono<ResourceResponse<Document>> upsertDocument(String collectionLink, Object do
     Mono<ResourceResponse<Document>> deleteDocument(String documentLink, RequestOptions options);
 
     /**
-     * Reads a document by the document link.
+     * Reads a document
      * <p>
      * After subscription the operation will be performed.
      * The {@link Mono} upon successful completion will contain a single resource response with the read document.
@@ -661,7 +661,7 @@ Mono<ResourceResponse<StoredProcedure>> upsertStoredProcedure(String collectionL
     Mono<ResourceResponse<StoredProcedure>> replaceStoredProcedure(StoredProcedure storedProcedure, RequestOptions options);
 
     /**
-     * Deletes a stored procedure by the stored procedure link.
+     * Deletes a stored procedure
      * <p>
      * After subscription the operation will be performed.
      * The {@link Mono} upon successful completion will contain a single resource response for the deleted stored procedure.
@@ -674,7 +674,7 @@ Mono<ResourceResponse<StoredProcedure>> upsertStoredProcedure(String collectionL
     Mono<ResourceResponse<StoredProcedure>> deleteStoredProcedure(String storedProcedureLink, RequestOptions options);
 
     /**
-     * READ a stored procedure by the stored procedure link.
+     * READ a stored procedure
      * <p>
      * After subscription the operation will be performed.
      * The {@link Mono} upon successful completion will contain a single resource response with the read stored procedure.
@@ -729,7 +729,7 @@ Flux<FeedResponse<StoredProcedure>> queryStoredProcedures(String collectionLink,
                                                                     FeedOptions options);
 
     /**
-     * Executes a stored procedure by the stored procedure link.
+     * Executes a stored procedure
      * <p>
      * After subscription the operation will be performed.
      * The {@link Mono} upon successful completion will contain a single resource response with the stored procedure response.
@@ -742,7 +742,7 @@ Flux<FeedResponse<StoredProcedure>> queryStoredProcedures(String collectionLink,
     Mono<StoredProcedureResponse> executeStoredProcedure(String storedProcedureLink, List<Object> procedureParams);
 
     /**
-     * Executes a stored procedure by the stored procedure link.
+     * Executes a stored procedure
      * <p>
      * After subscription the operation will be performed.
      * The {@link Mono} upon successful completion will contain a single resource response with the stored procedure response.
@@ -811,7 +811,7 @@ Mono<StoredProcedureResponse> executeStoredProcedure(String storedProcedureLink,
     Mono<ResourceResponse<Trigger>> deleteTrigger(String triggerLink, RequestOptions options);
 
     /**
-     * Reads a trigger by the trigger link.
+     * Reads a trigger
      * <p>
      * After subscription the operation will be performed.
      * The {@link Mono} upon successful completion will contain a single resource response for the read trigger.

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/models/CosmosAsyncStoredProcedureResponse.java

@@ -98,7 +98,7 @@ public int getStatusCode() {
     }
 
     /**
-     * Gets the number of index paths (terms) generated by the operation.
+     * Gets the number of normalized requests charged.
      *
      * @return the request charge.
      */