CreationTime feature

CHANGELOG.md

@@ -13,6 +13,10 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
   - QueryRequest.get/setNumberOfOperations()
   - QueryRequest.get/setOperationNumber()
 - Added new cloud region codes: hsg, abl, dfw, pbv, nbq, ibg, pcz, mez, den, kal
+- Added rowMetadata support, new API for Get/Put/Delete request and result
+  get/set RomMetadata.
+- Added row creation time support, new API Get/Delete Result getCreationTime(), 
+  Put/WriteMultiple Result getExistingCreationTime().
 
 ## [5.4.17] 2025-03-03
 

driver/src/main/java/oracle/nosql/driver/ops/DeleteResult.java

@@ -17,7 +17,8 @@
  * If the delete succeeded {@link #getSuccess} returns true.
  * Information about the existing row may be
  * available using {@link #getExistingValue},
- *.{@link #getExistingVersion} and {@link #getExistingModificationTime},
+ *.{@link #getExistingVersion}, {@link #getCreationTime} and
+ *  {@link #getExistingModificationTime},
  * depending on the use of {@link DeleteRequest#setReturnRow} and the result
  * of the operation.
  * @see NoSQLHandle#delete
@@ -56,6 +57,22 @@ public MapValue getExistingValue() {
         return super.getExistingValueInternal();
     }
 
+    /**
+     * Returns the creation time if available. This value will
+     * only be available if the conditions specified in
+     * {@link DeleteRequest#setReturnRow} are met.
+     *
+     * Note: If the row was written by a version of the system older than 25.3
+     * the creation time will not be available at all and will be zero.
+     *
+     * @return the creation time in milliseconds since Jan 1, 1970 GMT
+     *
+     * @since 5.4.18
+     */
+    public long getCreationTime() {
+        return super.getExistingCreationTimeInternal();
+    }
+
     /**
      * Returns the existing modification time if available. This value will
      * only be available if the conditions specified in
@@ -69,7 +86,6 @@ public long getExistingModificationTime() {
         return super.getExistingModificationTimeInternal();
     }
 
-
     /**
      * Returns the metadata of the returned row, or null if the row does not
      * exist or metadata was not set.

driver/src/main/java/oracle/nosql/driver/ops/GetResult.java

@@ -27,6 +27,7 @@ public class GetResult extends Result {
     private MapValue value;
     private Version version;
     private long expirationTime;
+    private long creationTime;
     private long modificationTime;
     private Client client;
     private String rowMetadata;
@@ -65,27 +66,49 @@ public Version getVersion() {
      * row does not expire. This value is valid only if the operation
      * successfully returned a row ({@link #getValue} returns non-null).
      *
-     * @return the expiration time in milliseconds since January 1, 1970,
+     * @return the expiration time in milliseconds since January 1, 1970 GMT,
      * or zero if the row never expires or the row does not exist
      */
     public long getExpirationTime() {
         return expirationTime;
     }
 
+    /**
+     * Returns the creation time of the row.
+     * This value is valid only if the operation
+     * successfully returned a row ({@link #getValue} returns non-null).
+     *
+     * Note: If the row was written by a version of the system older than 25.3
+     * the creation time will not be available at all and will be zero.
+     *
+     * @return the creation time in milliseconds since January 1, 1970 GMT,
+     * or zero if the row does not exist
+     *
+     * @since 5.4.18
+     */
+    public long getCreationTime() {
+        if (creationTime < 0 && client != null) {
+            client.oneTimeMessage("The requested feature is not supported by " +
+                "the connected server: getCreationTime");
+            return 0;
+        }
+        return creationTime;
+    }
+
     /**
      * Returns the modification time of the row.
      * This value is valid only if the operation
      * successfully returned a row ({@link #getValue} returns non-null).
      *
-     * @return the modification time in milliseconds since January 1, 1970,
+     * @return the modification time in milliseconds since January 1, 1970 GMT,
      * or zero if the row does not exist
      *
      * @since 5.3.0
      */
     public long getModificationTime() {
         if (modificationTime < 0 && client != null) {
             client.oneTimeMessage("The requested feature is not supported by " +
-                                  "the connected server: getModificationTime");
+                "the connected server: getModificationTime");
             return 0;
         }
         return modificationTime;
@@ -150,6 +173,21 @@ public GetResult setExpirationTime(long expirationTime) {
         return this;
     }
 
+    /**
+     * Internal use only.
+     *
+     * Sets the creation time.
+     *
+     * @param creationTime the creation time
+     *
+     * @return this
+     * @hidden
+     */
+    public GetResult setCreationTime(long creationTime) {
+        this.creationTime = creationTime;
+        return this;
+    }
+
     /**
      * Internal use only.
      *

driver/src/main/java/oracle/nosql/driver/ops/PutResult.java

@@ -18,9 +18,10 @@
  * On a successful operation the value returned by {@link #getVersion} is
  * non-null. On failure that value is null. Information about the
  * existing row may be available using
- * {@link #getExistingValue}, {@link #getExistingVersion}, and
- * {@link #getExistingModificationTime}, depending on the
- * use of {@link PutRequest#setReturnRow} and the results of the operation.
+ * {@link #getExistingValue}, {@link #getExistingVersion},
+ * {@link #getExistingCreationTime()} and {@link #getExistingModificationTime},
+ * depending on the use of {@link PutRequest#setReturnRow} and the results of
+ * the operation.
  * @see NoSQLHandle#put
  */
 public class PutResult extends WriteResult {
@@ -70,12 +71,28 @@ public MapValue getExistingValue() {
         return super.getExistingValueInternal();
     }
 
+    /**
+     * Returns the existing creation time if available. This value will
+     * only be available if the conditions specified in
+     * {@link PutRequest#setReturnRow} are met.
+     * Note: If the row was written by a version of the system older than 25.3
+     * the creation time will not be available at all and will be zero.
+     *
+     * @return the creation time in milliseconds since Jan 1, 1970 GMT
+     *
+     * @since 5.4.18
+     */
+    public long getExistingCreationTime() {
+        return super.getExistingCreationTimeInternal();
+    }
+
     /**
      * Returns the existing modification time if available. This value will
      * only be available if the conditions specified in
      * {@link PutRequest#setReturnRow} are met.
      *
      * @return the existing modification time in milliseconds since Jan 1, 1970
+     * GMT
      *
      * @since 5.3.0
      */

driver/src/main/java/oracle/nosql/driver/ops/WriteMultipleResult.java

@@ -216,11 +216,23 @@ public MapValue getExistingValue() {
             return super.getExistingValueInternal();
         }
 
+        /**
+         * Returns the creation time associated with the key if
+         * available.
+         * @return the creation time if set, in milliseconds sine Jan 1, 1970
+         * GMT
+         *
+         * @since 5.4.18
+         */
+        public long getCreationTime() {
+            return super.getExistingCreationTimeInternal();
+        }
+
         /**
          * Returns the existing modification time associated with the key if
          * available.
          * @return the modification time if set, in milliseconds sine Jan 1,
-         * 1970
+         * 1970 GMT
          *
          * @since 5.3.0
          */

driver/src/main/java/oracle/nosql/driver/ops/WriteResult.java

@@ -18,6 +18,7 @@
 public class WriteResult extends Result {
     private Version existingVersion;
     private MapValue existingValue;
+    private long existingCreationTime;
     private long existingModificationTime;
     private String existingRowMetadata;
     private Client client;
@@ -52,6 +53,20 @@ public MapValue getExistingValueInternal() {
         return existingValue;
     }
 
+    /**
+     * internal use only
+     * @return the creation time of the store row
+     * @hidden
+     */
+    public long getExistingCreationTimeInternal() {
+        if (existingCreationTime < 0 && client != null) {
+            client.oneTimeMessage("The requested feature is not supported by " +
+                          "the connected server: getExistingCreationTime");
+            return 0;
+        }
+        return existingCreationTime;
+    }
+
     /**
      * internal use only
      * @return the modification time
@@ -60,7 +75,7 @@ public MapValue getExistingValueInternal() {
     public long getExistingModificationTimeInternal() {
         if (existingModificationTime < 0 && client != null) {
             client.oneTimeMessage("The requested feature is not supported by " +
-                          "the connected server: getExistingModificationTime");
+                "the connected server: getExistingModificationTime");
             return 0;
         }
         return existingModificationTime;
@@ -92,6 +107,18 @@ public WriteResult setExistingValue(MapValue existingValue) {
         return this;
     }
 
+    /**
+     * internal use only
+     * @param creationTime the modification time
+     * @return this
+     * @hidden
+     */
+    public WriteResult setExistingCreationTime(
+        long creationTime) {
+        this.existingCreationTime = creationTime;
+        return this;
+    }
+
     /**
      * internal use only
      * @param existingModificationTime the modification time

driver/src/main/java/oracle/nosql/driver/ops/serde/BinaryProtocol.java

@@ -8,66 +8,7 @@
 package oracle.nosql.driver.ops.serde;
 
 import static oracle.nosql.driver.http.Client.trace;
-import static oracle.nosql.driver.util.BinaryProtocol.ABSOLUTE;
-import static oracle.nosql.driver.util.BinaryProtocol.ACTIVE;
-import static oracle.nosql.driver.util.BinaryProtocol.ON_DEMAND;
-import static oracle.nosql.driver.util.BinaryProtocol.BAD_PROTOCOL_MESSAGE;
-import static oracle.nosql.driver.util.BinaryProtocol.BATCH_OP_NUMBER_LIMIT_EXCEEDED;
-import static oracle.nosql.driver.util.BinaryProtocol.BATCH_REQUEST_SIZE_LIMIT;
-import static oracle.nosql.driver.util.BinaryProtocol.COMPLETE;
-import static oracle.nosql.driver.util.BinaryProtocol.CREATING;
-import static oracle.nosql.driver.util.BinaryProtocol.DROPPED;
-import static oracle.nosql.driver.util.BinaryProtocol.DROPPING;
-import static oracle.nosql.driver.util.BinaryProtocol.DURABILITY_SYNC;
-import static oracle.nosql.driver.util.BinaryProtocol.DURABILITY_NO_SYNC;
-import static oracle.nosql.driver.util.BinaryProtocol.DURABILITY_WRITE_NO_SYNC;
-import static oracle.nosql.driver.util.BinaryProtocol.DURABILITY_ALL;
-import static oracle.nosql.driver.util.BinaryProtocol.DURABILITY_NONE;
-import static oracle.nosql.driver.util.BinaryProtocol.DURABILITY_SIMPLE_MAJORITY;
-import static oracle.nosql.driver.util.BinaryProtocol.ETAG_MISMATCH;
-import static oracle.nosql.driver.util.BinaryProtocol.EVENTUAL;
-import static oracle.nosql.driver.util.BinaryProtocol.EVOLUTION_LIMIT_EXCEEDED;
-import static oracle.nosql.driver.util.BinaryProtocol.ILLEGAL_ARGUMENT;
-import static oracle.nosql.driver.util.BinaryProtocol.ILLEGAL_STATE;
-import static oracle.nosql.driver.util.BinaryProtocol.INDEX_EXISTS;
-import static oracle.nosql.driver.util.BinaryProtocol.INDEX_LIMIT_EXCEEDED;
-import static oracle.nosql.driver.util.BinaryProtocol.INDEX_NOT_FOUND;
-import static oracle.nosql.driver.util.BinaryProtocol.INSUFFICIENT_PERMISSION;
-import static oracle.nosql.driver.util.BinaryProtocol.INVALID_AUTHORIZATION;
-import static oracle.nosql.driver.util.BinaryProtocol.KEY_SIZE_LIMIT_EXCEEDED;
-import static oracle.nosql.driver.util.BinaryProtocol.OPERATION_LIMIT_EXCEEDED;
-import static oracle.nosql.driver.util.BinaryProtocol.OPERATION_NOT_SUPPORTED;
-import static oracle.nosql.driver.util.BinaryProtocol.PROVISIONED;
-import static oracle.nosql.driver.util.BinaryProtocol.READ_LIMIT_EXCEEDED;
-import static oracle.nosql.driver.util.BinaryProtocol.RECOMPILE_QUERY;
-import static oracle.nosql.driver.util.BinaryProtocol.REQUEST_SIZE_LIMIT;
-import static oracle.nosql.driver.util.BinaryProtocol.REQUEST_SIZE_LIMIT_EXCEEDED;
-import static oracle.nosql.driver.util.BinaryProtocol.REQUEST_TIMEOUT;
-import static oracle.nosql.driver.util.BinaryProtocol.RESOURCE_EXISTS;
-import static oracle.nosql.driver.util.BinaryProtocol.RESOURCE_NOT_FOUND;
-import static oracle.nosql.driver.util.BinaryProtocol.RETRY_AUTHENTICATION;
-import static oracle.nosql.driver.util.BinaryProtocol.ROW_SIZE_LIMIT_EXCEEDED;
-import static oracle.nosql.driver.util.BinaryProtocol.SECURITY_INFO_UNAVAILABLE;
-import static oracle.nosql.driver.util.BinaryProtocol.SERVER_ERROR;
-import static oracle.nosql.driver.util.BinaryProtocol.SERVICE_UNAVAILABLE;
-import static oracle.nosql.driver.util.BinaryProtocol.SIZE_LIMIT_EXCEEDED;
-import static oracle.nosql.driver.util.BinaryProtocol.TABLE_DEPLOYMENT_LIMIT_EXCEEDED;
-import static oracle.nosql.driver.util.BinaryProtocol.TABLE_EXISTS;
-import static oracle.nosql.driver.util.BinaryProtocol.TABLE_LIMIT_EXCEEDED;
-import static oracle.nosql.driver.util.BinaryProtocol.TABLE_NOT_FOUND;
-import static oracle.nosql.driver.util.BinaryProtocol.TABLE_NOT_READY;
-import static oracle.nosql.driver.util.BinaryProtocol.TENANT_DEPLOYMENT_LIMIT_EXCEEDED;
-import static oracle.nosql.driver.util.BinaryProtocol.TTL_DAYS;
-import static oracle.nosql.driver.util.BinaryProtocol.TTL_HOURS;
-import static oracle.nosql.driver.util.BinaryProtocol.UNKNOWN_ERROR;
-import static oracle.nosql.driver.util.BinaryProtocol.UNKNOWN_OPERATION;
-import static oracle.nosql.driver.util.BinaryProtocol.UNSUPPORTED_PROTOCOL;
-import static oracle.nosql.driver.util.BinaryProtocol.UNSUPPORTED_QUERY_VERSION;
-import static oracle.nosql.driver.util.BinaryProtocol.UPDATING;
-import static oracle.nosql.driver.util.BinaryProtocol.V2;
-import static oracle.nosql.driver.util.BinaryProtocol.V3;
-import static oracle.nosql.driver.util.BinaryProtocol.WORKING;
-import static oracle.nosql.driver.util.BinaryProtocol.WRITE_LIMIT_EXCEEDED;
+import static oracle.nosql.driver.util.BinaryProtocol.*;
 
 import java.io.IOException;
 
@@ -136,7 +77,7 @@ public class BinaryProtocol extends Nson {
      * Serialization
      *
      * Methods related to data come from Nson. Methods here refer
-     * to objects in the prototol other than data
+     * to objects in the protocol other than data
      */
 
     static void writeTimeout(ByteOutputStream out, int timeout)

driver/src/main/java/oracle/nosql/driver/ops/serde/nson/NsonProtocol.java

@@ -163,6 +163,7 @@ public class NsonProtocol {
 
     /* row metadata */
     public static String EXPIRATION = "xp";
+    public static String CREATION_TIME = "ct";
     public static String MODIFIED = "md";
     public static String ROW = "r";
     public static String ROW_METADATA = "mt";
@@ -326,6 +327,7 @@ public class NsonProtocol {
         {STORAGE_GB,"STORAGE_GB"},
         {WRITE_KB,"WRITE_KB"},
         {EXPIRATION,"EXPIRATION"},
+        {CREATION_TIME,"CREATION_TIME"},
         {MODIFIED,"MODIFIED"},
         {ROW,"ROW"},
         {ROW_METADATA,"ROW_METADATA"},

driver/src/main/java/oracle/nosql/driver/ops/serde/nson/NsonSerializerFactory.java

@@ -2779,11 +2779,16 @@ static int[] readNsonIntArray(ByteInputStream bis)
         static void readRow(ByteInputStream in, GetResult result)
             throws IOException {
 
+            result.setCreationTime(-1);
+
             MapWalker walker = new MapWalker(in);
             while (walker.hasNext()) {
                 walker.next();
                 String name = walker.getCurrentName();
-                if (name.equals(MODIFIED)) {
+                if (name.equals(CREATION_TIME)) {
+                    result.setCreationTime(Nson.readNsonLong(in));
+//                    System.out.println("    DBG: SDK < Proxy NsonSerializeFactory.readRow " + result.getCreationTime());
+                } else if (name.equals(MODIFIED)) {
                     result.setModificationTime(Nson.readNsonLong(in));
                 } else if (name.equals(EXPIRATION)) {
                     result.setExpirationTime(Nson.readNsonLong(in));
@@ -2818,7 +2823,10 @@ static void readReturnInfo(ByteInputStream in,
             while (walker.hasNext()) {
                 walker.next();
                 String name = walker.getCurrentName();
-                if (name.equals(EXISTING_MOD_TIME)) {
+                if (name.equals(CREATION_TIME)) {
+                    result.setExistingCreationTime(Nson.readNsonLong(in));
+//                    System.out.println("    DBG: SDK < Proxy NsonSerializeFactory.readReturnInfo " + result.getExistingCreationTimeInternal());
+                } else if (name.equals(EXISTING_MOD_TIME)) {
                     result.setExistingModificationTime(Nson.readNsonLong(in));
                 } else if (name.equals(EXISTING_VERSION)) {
                     result.setExistingVersion(Version.createVersion(