Mark row metadata methods as EXPERIMENTAL and @hidden getCreationTime (#168)

* Update javadoc to mark row metadata methods as EXPERIMENTAL.
* Add @hidden on getCreationTime() method.

Author: cezarfx

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

@@ -260,20 +260,27 @@ public DeleteRequest setNamespace(String namespace) {
     }
 
     /**
-     * Sets the row metadata to use for this request. This is an optional
-     * parameter.<p>
+     * This method is **EXPERIMENTAL** and its behavior, signature, or
+     * even its existence may change without prior notice in future versions.
+     * Use with caution.<p>
+     *
+     * Sets the row metadata to use for this request.
+     * This is an optional parameter.<p>
      *
      * Row metadata is associated to a certain version of a row. Any subsequent
      * write operation will use its own row metadata value. If not specified
-     * null will be used by default.<p>
-     *
-     * The @parameter rowMetadata must be null or a valid JSON construct:
-     * object, array, string, number, true, false or null, otherwise an
-     * IllegalArgumentException is thrown.
+     * null will be used by default.
+     * NOTE that if you have previously written a record with metadata and a
+     * subsequent write does not supply metadata, the metadata associated with
+     * the row will be null. Therefore, if you wish to have metadata
+     * associated with every write operation, you must supply a valid JSON
+     * construct to this method.<p>
      *
-     * @param rowMetadata the row metadata
+     * @param rowMetadata the row metadata, must be null or a valid JSON
+     *    construct: object, array, string, number, true, false or null,
+     *    otherwise an IllegalArgumentException is thrown.
      * @throws IllegalArgumentException if rowMetadata not null and invalid
-     * JSON construct
+     *    JSON construct
      *
      * @since 5.4.18
      * @return this

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

@@ -86,6 +86,7 @@ public long getExpirationTime() {
      * or zero if the row does not exist
      *
      * @since 5.4.18
+     * @hidden
      */
     public long getCreationTime() {
         if (creationTime < 0 && client != null) {
@@ -131,6 +132,10 @@ public GetResult setValue(MapValue value) {
     }
 
     /**
+     * This method is **EXPERIMENTAL** and its behavior, signature, or
+     * even its existence may change without prior notice in future versions.
+     * Use with caution.<p>
+     *
      * Returns the metadata of the returned row, or null if the row does not
      * exist or metadata was not set.
      *
@@ -143,7 +148,11 @@ public String getRowMetadata() {
     }
 
     /**
-     * Internal use only.
+     * This method is **EXPERIMENTAL** and its behavior, signature, or
+     * even its existence may change without prior notice in future versions.
+     * Use with caution.<p>
+     *
+     * Internal use only.<p>
      *
      * Sets the rowMetadata of this object.
      *

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

@@ -235,20 +235,27 @@ public MultiDeleteRequest setNamespace(String namespace) {
     }
 
     /**
-     * Sets the row metadata to use for the operation. This is an optional
+     * This method is **EXPERIMENTAL** and its behavior, signature, or
+     * even its existence may change without prior notice in future versions.
+     * Use with caution.<p>
+     *
+     * Sets the row metadata to use for this request. This is an optional
      * parameter.<p>
      *
      * Row metadata is associated to a certain version of a row. Any subsequent
      * write operation will use its own row metadata value. If not specified
-     * null will be used by default.<p>
-     *
-     * The @parameter rowMetadata must be null or a valid JSON construct:
-     * object, array, string, number, true, false or null, otherwise an
-     * IllegalArgumentException is thrown.
-     *
-     * @param rowMetadata the row metadata
+     * null will be used by default.
+     * NOTE that if you have previously written a record with metadata and a
+     * subsequent write does not supply metadata, the metadata associated with
+     * the row will be null. Therefore, if you wish to have metadata
+     * associated with every write operation, you must supply a valid JSON
+     * construct to this method.<p>
+     *
+     * @param rowMetadata the row metadata, must be null or a valid JSON
+     *    construct: object, array, string, number, true, false or null,
+     *    otherwise an IllegalArgumentException is thrown.
      * @throws IllegalArgumentException if rowMetadata not null and invalid
-     * JSON construct
+     *    JSON construct
      *
      * @return this
      * @since 5.4.18

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

@@ -438,20 +438,27 @@ public int getIdentityCacheSize() {
     }
 
     /**
-     * Sets the row metadata to use for this request.
-     * This is an optional parameter.<p>
+     * This method is **EXPERIMENTAL** and its behavior, signature, or
+     * even its existence may change without prior notice in future versions.
+     * Use with caution.<p>
+     *
+     * Sets the row metadata to use for this request. This is an optional
+     * parameter.<p>
      *
      * Row metadata is associated to a certain version of a row. Any subsequent
      * write operation will use its own row metadata value. If not specified
-     * null will be used by default.<p>
-     *
-     * The @parameter rowMetadata must be null or a valid JSON construct:
-     * object, array, string, number, true, false or null, otherwise an
-     * IllegalArgumentException is thrown.
-     *
-     * @param rowMetadata the row metadata
+     * null will be used by default.
+     * NOTE that if you have previously written a record with metadata and a
+     * subsequent write does not supply metadata, the metadata associated with
+     * the row will be null. Therefore, if you wish to have metadata
+     * associated with every write operation, you must supply a valid JSON
+     * construct to this method.<p>
+     *
+     * @param rowMetadata the row metadata, must be null or a valid JSON
+     *    construct: object, array, string, number, true, false or null,
+     *    otherwise an IllegalArgumentException is thrown.
      * @throws IllegalArgumentException if rowMetadata not null and invalid
-     * JSON construct
+     *    JSON construct
      *
      * @since 5.4.18
      * @return this

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

@@ -925,23 +925,29 @@ public Consistency getConsistency() {
     }
 
     /**
+     * This method is **EXPERIMENTAL** and its behavior, signature, or
+     * even its existence may change without prior notice in future versions.
+     * Use with caution.<p>
+     *
      * Sets the row metadata to use for the operation. This setting is optional
      * and only applies if the query modifies or deletes any rows using an
      * INSERT, UPDATE, UPSERT or DELETE statement. If the query is read-only
-     * this setting is ignored.<p>
+     * this setting is ignored. This is an optional parameter.<p>
      *
      * Row metadata is associated to a certain version of a row. Any subsequent
      * write operation will use its own row metadata value. If not specified
-     * null will be used by default.<p>
-     *
-     * The @parameter rowMetadata must be null or a valid JSON construct:
-     * object, array, string, number, true, false or null, otherwise an
-     * IllegalArgumentException is thrown.
-     *
-     * @param rowMetadata the row metadata
+     * null will be used by default.
+     * NOTE that if you have previously written a record with metadata and a
+     * subsequent write does not supply metadata, the metadata associated with
+     * the row will be null. Therefore, if you wish to have metadata
+     * associated with every write operation, you must supply a valid JSON
+     * construct to this method.<p>
+     *
+     * @param rowMetadata the row metadata, must be null or a valid JSON
+     *    construct: object, array, string, number, true, false or null,
+     *    otherwise an IllegalArgumentException is thrown.
      * @throws IllegalArgumentException if rowMetadata not null and invalid
-     * JSON construct
-     *
+     *    JSON construct
      * @return this
      * @since 5.4.18
      */
@@ -957,6 +963,10 @@ public QueryRequest setRowMetadata(String rowMetadata) {
     }
 
     /**
+     * This method is **EXPERIMENTAL** and its behavior, signature, or
+     * even its existence may change without prior notice in future versions.
+     * Use with caution.<p>
+     *
      * Returns the row metadata set for this request, or null if not set.
      *
      * @return the row metadata

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

@@ -55,9 +55,13 @@ protected void validateWriteRequest(String requestName) {
     }
 
     /**
+     * This method is **EXPERIMENTAL** and its behavior, signature, or
+     * even its existence may change without prior notice in future versions.
+     * Use with caution.<p>
+     *
      * Returns the row metadata to be used for this request.
      *
-     * @return the metadata, or null if not set
+     * @return the row metadata, or null if not set
      *
      * @since 5.4.18
      */
@@ -66,20 +70,27 @@ public String getRowMetadata() {
     }
 
     /**
+     * This method is **EXPERIMENTAL** and its behavior, signature, or
+     * even its existence may change without prior notice in future versions.
+     * Use with caution.<p>
+     *
      * Sets the row metadata to use for this request.
      * This is an optional parameter.<p>
      *
      * Row metadata is associated to a certain version of a row. Any subsequent
      * write operation will use its own row metadata value. If not specified
-     * null will be used by default.<p>
-     *
-     * The @parameter rowMetadata must be null or in a valid JSON construct:
-     * object, array, string, number, true, false or null,
-     * otherwise an IllegalArgumentException is thrown.
+     * null will be used by default.
+     * NOTE that if you have previously written a record with metadata and a
+     * subsequent write does not supply metadata, the metadata associated with
+     * the row will be null. Therefore, if you wish to have metadata
+     * associated with every write operation, you must supply a valid JSON
+     * construct to this method.<p>
      *
-     * @param rowMetadata the row metadata
+     * @param rowMetadata the row metadata, must be null or a valid JSON
+     *    construct: object, array, string, number, true, false or null,
+     *    otherwise an IllegalArgumentException is thrown.
      * @throws IllegalArgumentException if rowMetadata not null and invalid
-     * JSON Object format
+     *    JSON construct
      *
      * @since 5.4.18
      * @return this