feat: support increment (#63)

* feat: support increment of patch api

* docs: add increment in readme

* test: fix tests

* chore: bump version to 0.5.10

Author: thunderz99

README.md

@@ -227,6 +227,23 @@ db.updatePartial("Collection", user1.id, Map.of("lastName", "Hanks", "status", "
     */
 ```
 
+### Increment
+
+```java
+    // support incrementing a number field 
+    // see https://docs.microsoft.com/en-us/azure/cosmos-db/partial-document-update-getting-started?tabs=java
+
+    // increment age by 1
+    var result = db.increment("Collection1", "id1", "/age", 1, "Users");
+
+    // increment age by -5
+    var result = db.increment("Collection1", "id1", "/age", -5, "Users");
+
+    // 400 Bad Request Exception will be throw if the field is not an integer
+    var result = db.increment("Collection1", "id1", "/name", 1, "Users");
+    
+```
+
 ### Cross-partition queries
 
 ```java

pom.xml

@@ -4,7 +4,7 @@
     <groupId>com.github.thunderz99</groupId>
     <artifactId>java-cosmos</artifactId>
     <packaging>jar</packaging>
-    <version>0.5.9</version>
+    <version>0.5.10</version>
     <name>${project.groupId}:${project.artifactId}$</name>
     <description>A lightweight Azure CosmosDB client for Java</description>
     <url>https://github.com/thunderz99/java-cosmos</url>
@@ -88,7 +88,13 @@
             <artifactId>azure-documentdb</artifactId>
             <version>2.6.4</version>
         </dependency>
-        
+
+        <dependency>
+            <groupId>com.azure</groupId>
+            <artifactId>azure-cosmos</artifactId>
+            <version>4.29.1</version>
+        </dependency>
+
         <dependency>
             <groupId>io.github.cdimascio</groupId>
             <artifactId>java-dotenv</artifactId>

src/main/java/io/github/thunderz99/cosmos/Cosmos.java

@@ -3,11 +3,14 @@
 import java.util.List;
 import java.util.Objects;
 import java.util.Set;
-import java.util.regex.Pattern;
 import java.util.stream.Collectors;
 
+import com.azure.cosmos.CosmosClient;
+import com.azure.cosmos.CosmosClientBuilder;
 import com.microsoft.azure.documentdb.*;
 import io.github.thunderz99.cosmos.util.Checker;
+import io.github.thunderz99.cosmos.util.ConnectionStringUtil;
+import io.github.thunderz99.cosmos.util.EnvUtil;
 import org.apache.commons.collections4.CollectionUtils;
 import org.apache.commons.lang3.StringUtils;
 import org.apache.commons.lang3.tuple.Pair;
@@ -32,11 +35,11 @@ public class Cosmos {
 
     DocumentClient client;
 
-    String account;
+    CosmosClient clientV4;
 
-    static Pattern connectionStringPattern = Pattern.compile("AccountEndpoint=(?<endpoint>.+);AccountKey=(?<key>[^;]+);?");
+    String account;
 
-    public static final String JC_SDK_V4_ENABLE = "JC_SDK_V4_ENABLE";
+    public static final String COSMOS_SDK_V4_ENABLE = "COSMOS_SDK_V4_ENABLE";
 
     public static final String ETAG = "_etag";
 
@@ -46,13 +49,30 @@ public Cosmos(String connectionString) {
 
     public Cosmos(String connectionString, List<String> preferredRegions) {
 
-        Pair<String, String> pair = parseConnectionString(connectionString);
+        Pair<String, String> pair = ConnectionStringUtil.parseConnectionString(connectionString);
         var endpoint = pair.getLeft();
         var key = pair.getRight();
 
         this.client = new DocumentClient(endpoint, key, ConnectionPolicy.GetDefault(), ConsistencyLevel.Session);
 
-        //var v4Enable = Boolean.parseBoolean(EnvUtil.getOrDefault(Cosmos.JC_SDK_V4_ENABLE, "false"));
+        // default to true
+        var v4Enable = Boolean.parseBoolean(EnvUtil.getOrDefault(Cosmos.COSMOS_SDK_V4_ENABLE, "true"));
+
+        if (v4Enable) {
+            log.info("COSMOS_SDK_V4_ENABLE is enabled for endpoint:{}", endpoint);
+            this.clientV4 = new CosmosClientBuilder()
+                    .endpoint(endpoint)
+                    .key(key)
+                    .preferredRegions(preferredRegions)
+                    .consistencyLevel(com.azure.cosmos.ConsistencyLevel.SESSION)
+                    .contentResponseOnWriteEnabled(true)
+                    .buildClient();
+
+            Runtime.getRuntime().addShutdownHook(new Thread(() -> {
+                this.clientV4.close();
+            }));
+        }
+
 
     }
 
@@ -332,15 +352,36 @@ static UniqueKey toUniqueKey(String key) {
     }
 
 
-    static String getDatabaseLink(String db) {
+    /**
+     * Generate database link format used in cosmosdb
+     *
+     * @param db db name
+     * @return databaseLink
+     */
+    public static String getDatabaseLink(String db) {
         return String.format("/dbs/%s", db);
     }
 
-    static String getCollectionLink(String db, String coll) {
+    /**
+     * Generate database link format used in cosmosdb
+     *
+     * @param db   db name
+     * @param coll collection name
+     * @return collection link
+     */
+    public static String getCollectionLink(String db, String coll) {
         return String.format("/dbs/%s/colls/%s", db, coll);
     }
 
-    static String getDocumentLink(String db, String coll, String id) {
+    /**
+     * Generate document link format used in cosmosdb
+     *
+     * @param db   db name
+     * @param coll collection name
+     * @param id   document id
+     * @return document link
+     */
+    public static String getDocumentLink(String db, String coll, String id) {
         return String.format("/dbs/%s/colls/%s/docs/%s", db, coll, id);
     }
 
@@ -383,24 +424,4 @@ static String getAccount(DocumentClient client) throws DocumentClientException {
         return client.getDatabaseAccount().get("id").toString();
     }
 
-    static Pair<String, String> parseConnectionString(String connectionString) {
-
-        var matcher = connectionStringPattern.matcher(connectionString);
-        if (!matcher.find()) {
-            throw new IllegalStateException(
-                    "Make sure connectionString contains 'AccountEndpoint=' and 'AccountKey=' ");
-        }
-        String endpoint = matcher.group("endpoint");
-        String key = matcher.group("key");
-
-        Checker.check(StringUtils.isNotBlank(endpoint), "Make sure connectionString contains 'AccountEndpoint=' ");
-        Checker.check(StringUtils.isNotBlank(key), "Make sure connectionString contains 'AccountKey='");
-
-        if (log.isInfoEnabled()) {
-            log.info("endpoint:{}", endpoint);
-            log.info("key:{}...", key.substring(0, 3));
-        }
-
-        return Pair.of(endpoint, key);
-    }
 }

src/main/java/io/github/thunderz99/cosmos/CosmosDatabase.java

@@ -1,8 +1,11 @@
 package io.github.thunderz99.cosmos;
 
+import java.util.LinkedHashMap;
 import java.util.Map;
 import java.util.stream.Collectors;
 
+import com.azure.cosmos.CosmosClient;
+import com.azure.cosmos.models.CosmosPatchOperations;
 import com.microsoft.azure.documentdb.*;
 import io.github.thunderz99.cosmos.condition.Aggregate;
 import io.github.thunderz99.cosmos.condition.Condition;
@@ -33,12 +36,15 @@ public class CosmosDatabase {
 
     DocumentClient client;
 
+    CosmosClient clientV4;
+
     Cosmos cosmosAccount;
 
     CosmosDatabase(Cosmos cosmosAccount, String db) {
         this.cosmosAccount = cosmosAccount;
         this.db = db;
         this.client = cosmosAccount.client;
+        this.clientV4 = cosmosAccount.clientV4;
     }
 
 
@@ -767,6 +773,46 @@ public int count(String coll, Condition cond, String partition) throws Exception
 
     }
 
+    /**
+     * Increment a number field of a document using json path format(e.g. "/count")
+     *
+     * <p>
+     * see json patch format: <a href="http://jsonpatch.com/">json path</a>
+     * <br>
+     * see details of increment: <a href="https://docs.microsoft.com/en-us/azure/cosmos-db/partial-document-update#supported-operations">supported operations: increment</a>
+     * </p>
+     *
+     * @param coll
+     * @param id
+     * @param path
+     * @param value
+     * @param partition
+     * @return
+     * @throws Exception
+     */
+    public CosmosDocument increment(String coll, String id, String path, int value, String partition) throws Exception {
+
+        var documentLink = Cosmos.getDocumentLink(db, coll, id);
+
+        Checker.checkNotNull(this.clientV4, String.format("SDK v4 must be enabled to use increment method. docLink:%s", documentLink));
+
+        var container = this.clientV4.getDatabase(db).getContainer(coll);
+
+        var response = RetryUtil.executeWithRetry(() -> container.patchItem(
+                id,
+                new com.azure.cosmos.models.PartitionKey(partition),
+                CosmosPatchOperations
+                        .create()
+                        .increment(path, value),
+                LinkedHashMap.class
+        ));
+
+        var item = response.getItem();
+        log.info("increment Document:{}, partition:{}, account:{}", documentLink, partition, getAccount());
+
+        return new CosmosDocument(item);
+    }
+
     RequestOptions requestOptions(String partition) {
         var options = new RequestOptions();
         options.setPartitionKey(new PartitionKey(partition));

src/main/java/io/github/thunderz99/cosmos/CosmosException.java

@@ -1,5 +1,6 @@
 package io.github.thunderz99.cosmos;
 
+import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.microsoft.azure.documentdb.DocumentClientException;
 
 /**
@@ -9,28 +10,104 @@ public class CosmosException extends RuntimeException {
 
     static final long serialVersionUID = 1L;
 
+    @JsonIgnore
     private DocumentClientException dce;
 
+    @JsonIgnore
+    private com.azure.cosmos.CosmosException ce;
+
+    /**
+     * http status code
+     */
+    int statusCode;
+
+    /**
+     * String error code. e.g. Unauthorized / NotFound / etc
+     */
+    String code;
+
+    /**
+     * T time to retry suggested by the 429 exception in milliseconds. 0 if not 429 exception.
+     */
+    long retryAfterInMilliseconds;
+
+
+    /**
+     * Constructor using DocumentClientException;
+     *
+     * @param dce document client exception
+     */
     public CosmosException(DocumentClientException dce) {
         super(dce.getMessage(), dce);
         this.dce = dce;
+        this.statusCode = dce.getStatusCode();
+        this.code = dce.getError() == null ? "" : dce.getError().getCode();
+        this.retryAfterInMilliseconds = dce.getRetryAfterInMilliseconds();
+    }
+
+    public CosmosException(com.azure.cosmos.CosmosException ce) {
+        super(ce.getMessage(), ce);
+        this.ce = ce;
+        this.statusCode = ce.getStatusCode();
+        // can not get CosmosException's code yet.
+        this.code = "";
+        this.retryAfterInMilliseconds = ce.getRetryAfterDuration().toMillis();
+
+    }
+
+    /**
+     * Constructor using statusCode and message
+     *
+     * @param statusCode cosmos exception's httpStatusCode
+     * @param code       string error code
+     * @param message    detail message
+     */
+    public CosmosException(int statusCode, String code, String message) {
+        super(message);
+        this.statusCode = statusCode;
+        this.code = code;
+    }
+
+    /**
+     * Constructor using statusCode and message
+     *
+     * @param statusCode               cosmos exception's httpStatusCode
+     * @param code                     string error code
+     * @param message                  detail message
+     * @param retryAfterInMilliseconds amount of time should retry after in milliseconds
+     */
+    public CosmosException(int statusCode, String code, String message, long retryAfterInMilliseconds) {
+        super(message);
+        this.statusCode = statusCode;
+        this.code = code;
+        this.retryAfterInMilliseconds = retryAfterInMilliseconds;
     }
 
     /**
      * Get the exception's status code. e.g. 404 / 429 / 403
+     *
      * @return status code of exception.
      */
-    public int getStatusCode(){
-        return dce.getStatusCode();
+    public int getStatusCode() {
+        return statusCode;
+    }
+
+    /**
+     * Get the string code e.g. Unauthorized / NotFound / etc
+     *
+     * @return
+     */
+    public String getCode() {
+        return code;
     }
 
     /**
      * Get the time to retry suggested by the 429 exception in milliseconds. Return 0 if not 429 exception.
      *
      * @return time to retry in milliseconds
      */
-    public long getRetryAfterInMilliseconds(){
-        return dce.getRetryAfterInMilliseconds();
+    public long getRetryAfterInMilliseconds() {
+        return retryAfterInMilliseconds;
     }