Updated APIs with docs. Fixed few issues

sdk/cosmos/azure-cosmos-examples/src/main/java/com/azure/cosmos/examples/BasicDemo.java

@@ -129,7 +129,7 @@ private void queryWithContinuationToken() {
         log("+ Query with paging using continuation token");
         String query = "SELECT * from root r ";
         FeedOptions options = new FeedOptions();
-        options.setPopulateQueryMetrics(true);
+        options.setQueryMetricsEnabled(true);
         String continuation = null;
         do {
             CosmosPagedFlux<TestObject> queryFlux = container.queryItems(query, options, TestObject.class);

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

@@ -194,7 +194,7 @@ boolean isContentResponseOnWriteEnabled() {
      * @return a {@link Mono} containing the cosmos database response with the created or existing database or
      * an error.
      */
-    public Mono<CosmosAsyncDatabaseResponse> createDatabaseIfNotExists(CosmosDatabaseProperties databaseSettings) {
+    Mono<CosmosAsyncDatabaseResponse> createDatabaseIfNotExists(CosmosDatabaseProperties databaseSettings) {
         return createDatabaseIfNotExistsInternal(getDatabase(databaseSettings.getId()));
     }
 
@@ -229,6 +229,9 @@ private Mono<CosmosAsyncDatabaseResponse> createDatabaseIfNotExistsInternal(Cosm
     /**
      * Create a Database if it does not already exist on the service.
      * <p>
+     * The throughputProperties will only be used if the specified database
+     * does not exist and therefor a new database will be created with throughputProperties.
+     * <p>
      * The {@link Mono} upon successful completion will contain a single cosmos database response with the
      * created or existing database.
      *

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

@@ -62,7 +62,7 @@ public Mono<CosmosAsyncUserResponse> read() {
     }
 
     /**
-     * REPLACE a cosmos user
+     * Replace a cosmos user
      *
      * @param userSettings the user properties to use
      * @return a {@link Mono} containing the single resource response with the replaced user or an error.
@@ -226,7 +226,7 @@ String getLink() {
      *
      * @return the (@link CosmosAsyncDatabase)
      */
-    public CosmosAsyncDatabase getDatabase() {
+    CosmosAsyncDatabase getDatabase() {
         return database;
     }
 }

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

@@ -22,7 +22,7 @@
 
 /**
  * Provides a client-side logical representation of the Azure Cosmos DB service.
- * SyncClient is used to perform operations in a synchronous way
+ * Calls to CosmosClient API's are blocked for completion.
  */
 @ServiceClient(builder = CosmosClientBuilder.class)
 public final class CosmosClient implements Closeable {
@@ -38,12 +38,15 @@ public final class CosmosClient implements Closeable {
      * @param databaseProperties {@link CosmosDatabaseProperties} the database properties.
      * @return the {@link CosmosDatabaseResponse} with the created database.
      */
-    public CosmosDatabaseResponse createDatabaseIfNotExists(CosmosDatabaseProperties databaseProperties) {
+    CosmosDatabaseResponse createDatabaseIfNotExists(CosmosDatabaseProperties databaseProperties) {
         return mapDatabaseResponseAndBlock(asyncClientWrapper.createDatabaseIfNotExists(databaseProperties));
     }
 
     /**
      * Create a Database if it does not already exist on the service.
+     * <p>
+     * The throughputProperties will only be used if the specified database
+     * does not exist and therefor a new database will be created with throughputProperties.
      *
      * @param id the id of the database.
      * @param throughputProperties the throughputProperties.

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

@@ -16,12 +16,13 @@
 /**
  * Helper class to build CosmosAsyncClient {@link CosmosAsyncClient} and CosmosClient {@link CosmosClient}
  * instances as logical representation of the Azure Cosmos database service.
- *
+ * <p>
  * When building client, endpoint() and key() are mandatory APIs, without these the initialization will fail.
- *
+ * <p>
  * 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.
- *
+ * By default, account consistency level is used if none is provided.
+ * <p>
+ * By default, direct connection mode is used if none specified. 
  * <pre>
  *     Building Cosmos Async Client minimal APIs (without any customized configurations)
  * {@code

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

@@ -197,10 +197,8 @@ public <T> CosmosItemResponse<T> upsertItem(T item) {
      * @param options the options.
      * @return the Cosmos sync item response.
      */
-    @SuppressWarnings("unchecked")
-    // Note: @kushagraThapar and @moderakh to ensure this casting is valid
-    public <T> CosmosItemResponse<T> upsertItem(Object item, CosmosItemRequestOptions options) {
-        return (CosmosItemResponse<T>) this.mapItemResponseAndBlock(this.asyncContainer.upsertItem(item, options));
+    public <T> CosmosItemResponse<T> upsertItem(T item, CosmosItemRequestOptions options) {
+        return this.mapItemResponseAndBlock(this.asyncContainer.upsertItem(item, options));
     }
 
     /**

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

@@ -19,14 +19,14 @@ public final class ChangeFeedOptions {
     private Integer maxItemCount;
     private String requestContinuation;
     private PartitionKey partitionkey;
-    private final boolean populateQueryMetrics;
+    private final boolean queryMetricsEnabled;
     private Map<String, Object> properties;
 
     /**
      * Instantiates a new Change feed options.
      */
     public ChangeFeedOptions() {
-        this.populateQueryMetrics = false;
+        this.queryMetricsEnabled = false;
     }
 
     /**
@@ -41,7 +41,7 @@ public ChangeFeedOptions(ChangeFeedOptions options) {
         this.maxItemCount = options.maxItemCount;
         this.requestContinuation = options.requestContinuation;
         this.partitionkey = options.partitionkey;
-        this.populateQueryMetrics = options.populateQueryMetrics;
+        this.queryMetricsEnabled = options.queryMetricsEnabled;
     }
 
     /**

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

@@ -42,7 +42,7 @@ public String getOperationKind() {
      *
      * @return the resource type.
      */
-    public String getResouceType() {
+    public String getResourceType() {
         return super.getString(Constants.Properties.RESOURCE_TYPE);
     }
 

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

@@ -30,7 +30,7 @@ public class RequestOptions {
     private PartitionKey partitionkey;
     private String partitionKeyRangeId;
     private boolean scriptLoggingEnabled;
-    private boolean populateQuotaInfo;
+    private boolean quotaInfoEnabled;
     private Map<String, Object> properties;
     private ThroughputProperties throughputProperties;
 
@@ -279,25 +279,25 @@ public void setScriptLoggingEnabled(boolean scriptLoggingEnabled) {
     }
 
     /**
-     * Gets the PopulateQuotaInfo setting for document collection read requests in the Azure Cosmos DB database service.
-     * PopulateQuotaInfo is used to enable/disable getting document collection quota related stats for document
+     * Gets the quotaInfoEnabled setting for document collection read requests in the Azure Cosmos DB database service.
+     * quotaInfoEnabled is used to enable/disable getting document collection quota related stats for document
      * collection read requests.
      *
-     * @return true if PopulateQuotaInfo is enabled
+     * @return true if quotaInfoEnabled is enabled
      */
-    public boolean isPopulateQuotaInfo() {
-        return populateQuotaInfo;
+    public boolean isQuotaInfoEnabled() {
+        return quotaInfoEnabled;
     }
 
     /**
-     * Sets the PopulateQuotaInfo setting for document collection read requests in the Azure Cosmos DB database service.
-     * PopulateQuotaInfo is used to enable/disable getting document collection quota related stats for document
+     * Sets the quotaInfoEnabled setting for document collection read requests in the Azure Cosmos DB database service.
+     * quotaInfoEnabled is used to enable/disable getting document collection quota related stats for document
      * collection read requests.
      *
-     * @param populateQuotaInfo a boolean value indicating whether PopulateQuotaInfo is enabled or not
+     * @param quotaInfoEnabled a boolean value indicating whether quotaInfoEnabled is enabled or not
      */
-    public void setPopulateQuotaInfo(boolean populateQuotaInfo) {
-        this.populateQuotaInfo = populateQuotaInfo;
+    public void setQuotaInfoEnabled(boolean quotaInfoEnabled) {
+        this.quotaInfoEnabled = quotaInfoEnabled;
     }
 
     /**

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

@@ -958,7 +958,7 @@ private Map<String, String> getRequestHeaders(RequestOptions options, ResourceTy
             }
         }
 
-        if (options.isPopulateQuotaInfo()) {
+        if (options.isQuotaInfoEnabled()) {
             headers.put(HttpConstants.HttpHeaders.POPULATE_QUOTA_INFO, String.valueOf(true));
         }
 

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

@@ -65,7 +65,7 @@ private static ISessionToken getLocalSessionToken(
             String globalSessionToken,
             String partitionKeyRangeId) {
 
-        if (partitionKeyRangeId == null || partitionKeyRangeId.isEmpty()) {
+        if (partitionKeyRangeId == null) {
             // AddressCache/address resolution didn't produce partition key range id.
             // In this case it is a bug.
             throw new IllegalStateException("Partition key range Id is absent in the context.");

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

@@ -30,6 +30,7 @@
 import java.time.format.DateTimeFormatter;
 import java.util.ArrayList;
 import java.util.Base64;
+import java.util.Collection;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
@@ -290,6 +291,13 @@ public static String getCollectionName(String resourceFullName) {
         return resourceFullName;
     }
 
+    public static <T> int getCollectionSize(Collection<T> collection) {
+        if (collection == null) {
+            return 0;
+        }
+        return collection.size();
+    }
+
     public static Boolean isCollectionPartitioned(DocumentCollection collection) {
         if (collection == null) {
             throw new IllegalArgumentException("collection");

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/directconnectivity/AddressResolver.java

@@ -651,7 +651,7 @@ private PartitionKeyRange tryResolveServerPartitionByPartitionKey(
             throw new InternalServerErrorException(String.format("partition key is null"));
         }
 
-        if (partitionKey.equals(PartitionKeyInternal.Empty) || partitionKey.getComponents().size() == collection.getPartitionKey().getPaths().size()) {
+        if (partitionKey.equals(PartitionKeyInternal.Empty) || Utils.getCollectionSize(partitionKey.getComponents()) == collection.getPartitionKey().getPaths().size()) {
             // Although we can compute effective partition getKey here, in general case this GATEWAY can have outdated
             // partition getKey definition cached - like if collection with same getName but with RANGE partitioning is created.
             // In this case server will not pass x-ms-documentdb-collection-rid check and will return back InvalidPartitionException.
@@ -685,7 +685,7 @@ private PartitionKeyRange tryResolveServerPartitionByPartitionKey(
             logger.debug(
                 "Cannot compute effective partition getKey. Definition has '{}' getPaths, values supplied has '{}' getPaths. Will refresh cache and retry.",
                 collection.getPartitionKey().getPaths().size(),
-                partitionKey.getComponents().size());
+                Utils.getCollectionSize(partitionKey.getComponents()));
         }
 
         return null;

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/query/DocumentQueryExecutionContextBase.java

@@ -171,8 +171,8 @@ public Map<String, String> createCommonHeadersAsync(FeedOptions feedOptions) {
             requestHeaders.put(HttpConstants.HttpHeaders.CONSISTENCY_LEVEL, desiredConsistencyLevel.toString());
         }
 
-        if(feedOptions.isPopulateQueryMetrics()){
-            requestHeaders.put(HttpConstants.HttpHeaders.POPULATE_QUERY_METRICS, String.valueOf(feedOptions.isPopulateQueryMetrics()));
+        if(feedOptions.isQueryMetricsEnabled()){
+            requestHeaders.put(HttpConstants.HttpHeaders.POPULATE_QUERY_METRICS, String.valueOf(feedOptions.isQueryMetricsEnabled()));
         }
 
         return requestHeaders;

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/routing/PartitionKeyInternal.java

@@ -259,11 +259,14 @@ public void serialize(PartitionKeyInternal partitionKey, JsonGenerator writer, S
                     return;
                 }
 
-                writer.writeStartArray();
-                for (IPartitionKeyComponent componentValue : partitionKey.getComponents()) {
-                    componentValue.jsonEncode(writer);
+                //  PartitionKey.None has null components - which returns a null list
+                if (partitionKey.getComponents() != null) {
+                    writer.writeStartArray();
+                    for (IPartitionKeyComponent componentValue : partitionKey.getComponents()) {
+                        componentValue.jsonEncode(writer);
+                    }
+                    writer.writeEndArray();
                 }
-                writer.writeEndArray();
             } catch (IOException e) {
                 throw new IllegalStateException(e);
             }

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

@@ -49,6 +49,6 @@ public CosmosAsyncConflict getConflict() {
      * @return the conflict properties
      */
     public CosmosConflictProperties getProperties() {
-        return this.getProperties();
+        return super.getProperties();
     }
 }

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

@@ -46,8 +46,8 @@ public String getOperationKind() {
      *
      * @return the resource type.
      */
-    public String getResourceType() {
-        return this.conflict.getResouceType();
+    String getResourceType() {
+        return this.conflict.getResourceType();
     }
 
     Resource getResource() {

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

@@ -9,34 +9,34 @@
  * Encapsulates options that can be specified for a request issued to Cosmos container.
  */
 public final class CosmosContainerRequestOptions {
-    private boolean populateQuotaInfo;
+    private boolean quotaInfoEnabled;
     private ConsistencyLevel consistencyLevel;
     private String sessionToken;
     private String ifMatchETag;
     private String ifNoneMatchETag;
     private ThroughputProperties throughputProperties;
 
     /**
-     * Gets the PopulateQuotaInfo setting for cosmos container read requests in the Azure Cosmos DB database service.
-     * PopulateQuotaInfo is used to enable/disable getting cosmos container quota related stats for document
+     * Gets the quotaInfoEnabled setting for cosmos container read requests in the Azure Cosmos DB database service.
+     * quotaInfoEnabled is used to enable/disable getting cosmos container quota related stats for document
      * collection read requests.
      *
-     * @return true if PopulateQuotaInfo is enabled
+     * @return true if quotaInfoEnabled is enabled
      */
-    public boolean isQuotaInfoPopulated() {
-        return populateQuotaInfo;
+    public boolean isQuotaInfoEnabled() {
+        return quotaInfoEnabled;
     }
 
     /**
-     * Sets the PopulateQuotaInfo setting for cosmos container read requests in the Azure Cosmos DB database service.
-     * PopulateQuotaInfo is used to enable/disable getting cosmos container quota related stats for document
+     * Sets the quotaInfoEnabled setting for cosmos container read requests in the Azure Cosmos DB database service.
+     * quotaInfoEnabled is used to enable/disable getting cosmos container quota related stats for document
      * collection read requests.
      *
-     * @param populateQuotaInfo a boolean value indicating whether PopulateQuotaInfo is enabled or not
+     * @param quotaInfoEnabled a boolean value indicating whether quotaInfoEnabled is enabled or not
      * @return the current request options
      */
-    public CosmosContainerRequestOptions setQuotaInfoPopulated(boolean populateQuotaInfo) {
-        this.populateQuotaInfo = populateQuotaInfo;
+    public CosmosContainerRequestOptions setQuotaInfoEnabled(boolean quotaInfoEnabled) {
+        this.quotaInfoEnabled = quotaInfoEnabled;
         return this;
     }
 
@@ -129,7 +129,7 @@ RequestOptions toRequestOptions() {
         RequestOptions options = new RequestOptions();
         options.setIfMatchETag(getIfMatchETag());
         options.setIfNoneMatchETag(getIfNoneMatchETag());
-        options.setPopulateQuotaInfo(populateQuotaInfo);
+        options.setQuotaInfoEnabled(quotaInfoEnabled);
         options.setSessionToken(sessionToken);
         options.setConsistencyLevel(consistencyLevel);
         options.setThroughputProperties(this.throughputProperties);

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

@@ -20,7 +20,7 @@ public final class FeedOptions {
     private Integer maxItemCount;
     private String requestContinuation;
     private PartitionKey partitionkey;
-    private boolean populateQueryMetrics;
+    private boolean queryMetricsEnabled;
     private Map<String, Object> properties;
     private boolean emptyPagesAllowed;
 
@@ -46,7 +46,7 @@ public FeedOptions(FeedOptions options) {
         this.maxItemCount = options.maxItemCount;
         this.requestContinuation = options.requestContinuation;
         this.partitionkey = options.partitionkey;
-        this.populateQueryMetrics = options.populateQueryMetrics;
+        this.queryMetricsEnabled = options.queryMetricsEnabled;
         this.emptyPagesAllowed = options.emptyPagesAllowed;
     }
 
@@ -288,18 +288,18 @@ public FeedOptions setPartitionKey(PartitionKey partitionkey) {
      *
      * @return whether to enable populate query metrics
      */
-    public boolean isPopulateQueryMetrics() {
-        return populateQueryMetrics;
+    public boolean isQueryMetricsEnabled() {
+        return queryMetricsEnabled;
     }
 
     /**
      * Sets the option to enable/disable getting metrics relating to query execution on document query requests
      *
-     * @param populateQueryMetrics whether to enable or disable query metrics
+     * @param queryMetricsEnabled whether to enable or disable query metrics
      * @return the FeedOptionsBase.
      */
-    public FeedOptions setPopulateQueryMetrics(boolean populateQueryMetrics) {
-        this.populateQueryMetrics = populateQueryMetrics;
+    public FeedOptions setQueryMetricsEnabled(boolean queryMetricsEnabled) {
+        this.queryMetricsEnabled = queryMetricsEnabled;
         return this;
     }