Support for row metadata

Add support for RowMetadata. 
Add new API in PutRequest, PutResponse, GetResponse, DeleteRequest, DeleteResult, QueryRequest.

Author: cezarfx

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

@@ -259,6 +259,24 @@ public DeleteRequest setNamespace(String namespace) {
         return this;
     }
 
+    /**
+     * Sets the row metadata to use for this request.
+     * This is an optional parameter.
+     * The @parameter rowMetadata must be in a JSON Object format or null,
+     * otherwise an IllegalArgumentException is thrown.
+     *
+     * @param rowMetadata the row metadata
+     * @throws IllegalArgumentException if rowMetadata not null and invalid
+     * JSON Object format
+     *
+     * @since 5.4.18
+     * @return this
+     */
+    public DeleteRequest setRowMetadata(String rowMetadata) {
+        super.setRowMetadata(rowMetadata);
+        return this;
+    }
+
     /**
      * @hidden
      */

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

@@ -69,6 +69,18 @@ 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.
+     *
+     * @return the metadata of the row, or null if row does not exist or not set
+     * @since 5.4.18
+     */
+    public String getExistingRowMetadata() {
+        return super.getExistingRowMetadataInternal();
+    }
+
     /* from Result */
 
     /**

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

@@ -29,6 +29,7 @@ public class GetResult extends Result {
     private long expirationTime;
     private long modificationTime;
     private Client client;
+    private String rowMetadata;
 
     /**
      * Returns the value of the returned row, or null if the row does not exist
@@ -105,6 +106,35 @@ public GetResult setValue(MapValue value) {
         return this;
     }
 
+    /**
+     * Returns the metadata of the returned row, or null if the row does not
+     * exist or metadata was not set.
+     *
+     * @return the metadata of the row, or null if row does not exist or not set
+     *
+     * @since 5.4.18
+     */
+    public String getRowMetadata() {
+        return rowMetadata;
+    }
+
+    /**
+     * Internal use only.
+     *
+     * Sets the rowMetadata of this object.
+     *
+     * @param rowMetadata the row metadata
+     *
+     * @return this
+     *
+     * @since 5.4.18
+     * @hidden
+     */
+    public GetResult setRowMetadata(String rowMetadata) {
+        this.rowMetadata = rowMetadata;
+        return this;
+    }
+
     /**
      * Internal use only.
      *

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

@@ -127,7 +127,7 @@ public PutRequest setValue(MapValue value) {
         return this;
     }
 
-     /**
+    /**
      * Sets the value to use for the put operation based on a JSON string.
      * The string is parsed for validity and stored internally as a
      * {@link MapValue}.
@@ -437,6 +437,24 @@ public int getIdentityCacheSize() {
         return identityCacheSize;
     }
 
+    /**
+     * Sets the row metadata to use for this request.
+     * This is an optional parameter.
+     * The @parameter rowMetadata must be in a JSON Object format or null,
+     * otherwise an IllegalArgumentException is thrown.
+     *
+     * @param rowMetadata the row metadata
+     * @throws IllegalArgumentException if rowMetadata not null and invalid
+     * JSON Object format
+     *
+     * @since 5.4.18
+     * @return this
+     */
+    public PutRequest setRowMetadata(String rowMetadata) {
+        super.setRowMetadata(rowMetadata);
+        return this;
+    }
+
     /**
      * Internal use only
      *

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

@@ -83,6 +83,18 @@ 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.
+     *
+     * @return the metadata of the row, or null if row does not exist or not set
+     *
+     * @since 5.4.18
+     */
+    public String getExistingRowMetadata() {
+        return super.getExistingRowMetadataInternal();
+    }
+
     /* from Result */
 
     /**

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

@@ -22,6 +22,7 @@
 import oracle.nosql.driver.ops.serde.SerializerFactory;
 import oracle.nosql.driver.query.QueryDriver;
 import oracle.nosql.driver.query.VirtualScan;
+import oracle.nosql.driver.values.JsonUtils;
 
 /**
  * A request that represents a query. A query may be specified as either a
@@ -155,6 +156,8 @@ public class QueryRequest extends DurableRequest implements AutoCloseable {
 
     private Consistency consistency;
 
+    private String rowMetadata;
+
     private String statement;
 
     private PreparedStatement preparedStatement;
@@ -225,6 +228,7 @@ public QueryRequest copyInternal() {
         internalReq.maxServerMemoryConsumption = maxServerMemoryConsumption;
         internalReq.mathContext = mathContext;
         internalReq.consistency = consistency;
+        internalReq.rowMetadata = rowMetadata;
         internalReq.preparedStatement = preparedStatement;
         internalReq.isInternal = true;
         internalReq.driver = driver;
@@ -243,6 +247,7 @@ public QueryRequest copyInternal() {
     public QueryRequest copy() {
         QueryRequest internalReq = copyInternal();
         internalReq.statement = statement;
+        internalReq.rowMetadata = rowMetadata;
         internalReq.isInternal = false;
         internalReq.shardId = -1;
         internalReq.driver = null;
@@ -919,6 +924,41 @@ public Consistency getConsistency() {
         return consistency;
     }
 
+    /**
+     * Sets the row metadata to use for the operation. This setting only applies
+     * if the query modifies any rows using an INSERT, UPDATE or UPSERT statement.
+     * If the query is read-only this option is ignored.
+     * The @parameter rowMetadata must be in a JSON Object format or null,
+     * otherwise an IllegalArgumentException is thrown.
+     *
+     * @param rowMetadata the row metadata
+     * @throws IllegalArgumentException if rowMetadata not null and invalid
+     * JSON Object format
+     *
+     * @return this
+     * @since 5.4.18
+     */
+    public QueryRequest setRowMetadata(String rowMetadata) {
+        if (rowMetadata == null) {
+            this.rowMetadata = null;
+            return this;
+        }
+
+        JsonUtils.validateJsonObject(rowMetadata);
+        this.rowMetadata = rowMetadata;
+        return this;
+    }
+
+    /**
+     * Returns the consistency set for this request, or null if not set.
+     *
+     * @return the consistency
+     * @since 5.4.18
+     */
+    public String getRowMetadata() {
+        return rowMetadata;
+    }
+
     /**
      * Sets the request timeout value, in milliseconds. This overrides any
      * default value set with {@link NoSQLHandleConfig#setRequestTimeout}.

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

@@ -9,6 +9,7 @@
 
 import oracle.nosql.driver.NoSQLHandle;
 import oracle.nosql.driver.NoSQLHandleConfig;
+import oracle.nosql.driver.values.JsonUtils;
 
 /**
  * Represents a base class for the single row modifying operations
@@ -17,6 +18,7 @@
 public abstract class WriteRequest extends DurableRequest {
 
     private boolean returnRow;
+    private String rowMetadata;
 
     protected WriteRequest() {}
 
@@ -51,4 +53,39 @@ protected void validateWriteRequest(String requestName) {
                  " requires table name"));
         }
     }
+
+    /**
+     * Returns the row metadata to be used for this request.
+     *
+     * @return the metadata, or null if not set
+     *
+     * @since 5.4.18
+     */
+    public String getRowMetadata() {
+        return rowMetadata;
+    }
+
+    /**
+     * Sets the row metadata to use for this request.
+     * This is an optional parameter.
+     * The @parameter rowMetadata must be in a JSON Object format or null,
+     * otherwise an IllegalArgumentException is thrown.
+     *
+     * @param rowMetadata the row metadata
+     * @throws IllegalArgumentException if rowMetadata not null and invalid
+     * JSON Object format
+     *
+     * @since 5.4.18
+     * @return this
+     */
+    public WriteRequest setRowMetadata(String rowMetadata) {
+        if (rowMetadata == null) {
+            this.rowMetadata = null;
+            return this;
+        }
+
+        JsonUtils.validateJsonObject(rowMetadata);
+        this.rowMetadata = rowMetadata;
+        return this;
+    }
 }

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

@@ -19,6 +19,7 @@ public class WriteResult extends Result {
     private Version existingVersion;
     private MapValue existingValue;
     private long existingModificationTime;
+    private String existingRowMetadata;
     private Client client;
 
     protected WriteResult() {}
@@ -32,6 +33,16 @@ public Version getExistingVersionInternal() {
         return existingVersion;
     }
 
+    /**
+     * Returns the associated row metadata
+     * @return the row metadata or null
+     * @since 5.4.18
+     * @hidden
+     */
+    public String getExistingRowMetadataInternal() {
+        return existingRowMetadata;
+    }
+
     /**
      * internal use only
      * @return the value or null
@@ -93,6 +104,19 @@ public WriteResult setExistingModificationTime(
         return this;
     }
 
+    /**
+     * Internal use only.
+     *
+     * @param existingRowMetadata the row metadata
+     * @return this
+     * @since 5.4.18
+     * @hidden
+     */
+    public WriteResult setExistingRowMetadata(String existingRowMetadata) {
+        this.existingRowMetadata = existingRowMetadata;
+        return this;
+    }
+
     /**
      * for internal use
      * @param client the client

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

@@ -165,12 +165,14 @@ public class NsonProtocol {
     public static String EXPIRATION = "xp";
     public static String MODIFIED = "md";
     public static String ROW = "r";
+    public static String ROW_METADATA = "mt";
     public static String ROW_VERSION = "rv";
 
     /* operation metadata */
     public static String EXISTING_MOD_TIME = "em";
     public static String EXISTING_VALUE = "el";
     public static String EXISTING_VERSION = "ev";
+    public static String EXISTING_ROW_METADATA = "ed";
     public static String GENERATED = "gn";
     public static String RETURN_INFO = "ri";
 
@@ -326,10 +328,12 @@ public class NsonProtocol {
         {EXPIRATION,"EXPIRATION"},
         {MODIFIED,"MODIFIED"},
         {ROW,"ROW"},
+        {ROW_METADATA,"ROW_METADATA"},
         {ROW_VERSION,"ROW_VERSION"},
         {EXISTING_MOD_TIME,"EXISTING_MOD_TIME"},
         {EXISTING_VALUE,"EXISTING_VALUE"},
         {EXISTING_VERSION,"EXISTING_VERSION"},
+        {EXISTING_ROW_METADATA,"EXISTING_ROW_METADATA"},
         {GENERATED,"GENERATED"},
         {RETURN_INFO,"RETURN_INFO"},
         {DRIVER_QUERY_PLAN,"DRIVER_QUERY_PLAN"},