[DE-784] external versioning (#547)

rashtao · rashtao · commit 6661207165cb · 2024-03-21T21:16:37.000+01:00
* versionAttribute in document API

* tests fix
diff --git a/core/src/main/java/com/arangodb/internal/InternalArangoCollection.java b/core/src/main/java/com/arangodb/internal/InternalArangoCollection.java
@@ -51,6 +51,7 @@ public abstract class InternalArangoCollection extends ArangoExecuteable {
     private static final String MERGE_OBJECTS = "mergeObjects";
     private static final String KEEP_NULL = "keepNull";
     private static final String REFILL_INDEX_CACHES = "refillIndexCaches";
+    private static final String VERSION_ATTRIBUTE = "versionAttribute";
     private static final String IGNORE_REVS = "ignoreRevs";
     private static final String RETURN_NEW = "returnNew";
     private static final String RETURN_OLD = "returnOld";
@@ -103,6 +104,7 @@ private InternalRequest createInsertDocumentRequest(final DocumentCreateOptions
         request.putQueryParam(MERGE_OBJECTS, params.getMergeObjects());
         request.putQueryParam(KEEP_NULL, params.getKeepNull());
         request.putQueryParam(REFILL_INDEX_CACHES, params.getRefillIndexCaches());
+        request.putQueryParam(VERSION_ATTRIBUTE, params.getVersionAttribute());
         request.putHeaderParam(TRANSACTION_ID, params.getStreamTransactionId());
         return request;
     }
@@ -241,6 +243,7 @@ private InternalRequest createReplaceDocumentRequest(final DocumentReplaceOption
         request.putQueryParam(RETURN_OLD, params.getReturnOld());
         request.putQueryParam(SILENT, params.getSilent());
         request.putQueryParam(REFILL_INDEX_CACHES, params.getRefillIndexCaches());
+        request.putQueryParam(VERSION_ATTRIBUTE, params.getVersionAttribute());
         return request;
     }
 
@@ -303,6 +306,7 @@ private InternalRequest createUpdateDocumentRequest(final DocumentUpdateOptions
         request.putQueryParam(RETURN_OLD, params.getReturnOld());
         request.putQueryParam(SILENT, params.getSilent());
         request.putQueryParam(REFILL_INDEX_CACHES, params.getRefillIndexCaches());
+        request.putQueryParam(VERSION_ATTRIBUTE, params.getVersionAttribute());
         return request;
     }
 
diff --git a/core/src/main/java/com/arangodb/model/DocumentCreateOptions.java b/core/src/main/java/com/arangodb/model/DocumentCreateOptions.java
@@ -37,6 +37,7 @@ public final class DocumentCreateOptions {
     private Boolean mergeObjects;
     private Boolean keepNull;
     private Boolean refillIndexCaches;
+    private String versionAttribute;
 
     public DocumentCreateOptions() {
         super();
@@ -177,4 +178,34 @@ public DocumentCreateOptions refillIndexCaches(Boolean refillIndexCaches) {
         this.refillIndexCaches = refillIndexCaches;
         return this;
     }
+
+    public String getVersionAttribute() {
+        return versionAttribute;
+    }
+
+    /**
+     * Only applicable if {@link #overwriteMode(OverwriteMode)} is set to {@link OverwriteMode#update} or
+     * {@link OverwriteMode#replace}.
+     * You can use the {@code versionAttribute} option for external versioning support.
+     * If set, the attribute with the name specified by the option is looked up in the stored document and the attribute
+     * value is compared numerically to the value of the versioning attribute in the supplied document that is supposed
+     * to update/replace it.
+     * If the version number in the new document is higher (rounded down to a whole number) than in the document that
+     * already exists in the database, then the update/replace operation is performed normally. This is also the case if
+     * the new versioning attribute has a non-numeric value, if it is a negative number, or if the attribute doesn't
+     * exist in the supplied or stored document.
+     * If the version number in the new document is lower or equal to what exists in the database, the operation is not
+     * performed and the existing document thus not changed. No error is returned in this case.
+     * The attribute can only be a top-level attribute.
+     * You can check if _oldRev (if present) and _rev are different to determine if the document has been changed.
+     *
+     * @param versionAttribute the attribute name to use for versioning
+     * @return options
+     * @since ArangoDB 3.12
+     */
+    public DocumentCreateOptions versionAttribute(String versionAttribute) {
+        this.versionAttribute = versionAttribute;
+        return this;
+    }
+
 }
diff --git a/core/src/main/java/com/arangodb/model/DocumentReplaceOptions.java b/core/src/main/java/com/arangodb/model/DocumentReplaceOptions.java
@@ -36,6 +36,7 @@ public final class DocumentReplaceOptions {
     private Boolean silent;
     private String streamTransactionId;
     private Boolean refillIndexCaches;
+    private String versionAttribute;
 
     public DocumentReplaceOptions() {
         super();
@@ -154,4 +155,32 @@ public DocumentReplaceOptions refillIndexCaches(Boolean refillIndexCaches) {
         this.refillIndexCaches = refillIndexCaches;
         return this;
     }
+
+    public String getVersionAttribute() {
+        return versionAttribute;
+    }
+
+    /**
+     * You can use the {@code versionAttribute} option for external versioning support.
+     * If set, the attribute with the name specified by the option is looked up in the stored document and the attribute
+     * value is compared numerically to the value of the versioning attribute in the supplied document that is supposed
+     * to update/replace it.
+     * If the version number in the new document is higher (rounded down to a whole number) than in the document that
+     * already exists in the database, then the update/replace operation is performed normally. This is also the case if
+     * the new versioning attribute has a non-numeric value, if it is a negative number, or if the attribute doesn't
+     * exist in the supplied or stored document.
+     * If the version number in the new document is lower or equal to what exists in the database, the operation is not
+     * performed and the existing document thus not changed. No error is returned in this case.
+     * The attribute can only be a top-level attribute.
+     * You can check if _oldRev (if present) and _rev are different to determine if the document has been changed.
+     *
+     * @param versionAttribute the attribute name to use for versioning
+     * @return options
+     * @since ArangoDB 3.12
+     */
+    public DocumentReplaceOptions versionAttribute(String versionAttribute) {
+        this.versionAttribute = versionAttribute;
+        return this;
+    }
+
 }
diff --git a/core/src/main/java/com/arangodb/model/DocumentUpdateOptions.java b/core/src/main/java/com/arangodb/model/DocumentUpdateOptions.java
@@ -38,6 +38,7 @@ public final class DocumentUpdateOptions {
     private Boolean silent;
     private String streamTransactionId;
     private Boolean refillIndexCaches;
+    private String versionAttribute;
 
     public DocumentUpdateOptions() {
         super();
@@ -190,4 +191,31 @@ public DocumentUpdateOptions refillIndexCaches(Boolean refillIndexCaches) {
         return this;
     }
 
+    public String getVersionAttribute() {
+        return versionAttribute;
+    }
+
+    /**
+     * You can use the {@code versionAttribute} option for external versioning support.
+     * If set, the attribute with the name specified by the option is looked up in the stored document and the attribute
+     * value is compared numerically to the value of the versioning attribute in the supplied document that is supposed
+     * to update/replace it.
+     * If the version number in the new document is higher (rounded down to a whole number) than in the document that
+     * already exists in the database, then the update/replace operation is performed normally. This is also the case if
+     * the new versioning attribute has a non-numeric value, if it is a negative number, or if the attribute doesn't
+     * exist in the supplied or stored document.
+     * If the version number in the new document is lower or equal to what exists in the database, the operation is not
+     * performed and the existing document thus not changed. No error is returned in this case.
+     * The attribute can only be a top-level attribute.
+     * You can check if _oldRev (if present) and _rev are different to determine if the document has been changed.
+     *
+     * @param versionAttribute the attribute name to use for versioning
+     * @return options
+     * @since ArangoDB 3.12
+     */
+    public DocumentUpdateOptions versionAttribute(String versionAttribute) {
+        this.versionAttribute = versionAttribute;
+        return this;
+    }
+
 }
diff --git a/driver/src/test/java/com/arangodb/ArangoCollectionAsyncTest.java b/driver/src/test/java/com/arangodb/ArangoCollectionAsyncTest.java
diff --git a/driver/src/test/java/com/arangodb/ArangoCollectionTest.java b/driver/src/test/java/com/arangodb/ArangoCollectionTest.java
