Update individual request doc with new return row information semantics

Author: gmfeinberg

driver/src/main/java/oracle/nosql/driver/NoSQLHandle.java

@@ -133,7 +133,8 @@ public interface NoSQLHandle extends AutoCloseable {
      * by {@link DeleteRequest#setMatchVersion}.
      * <p>
      * It is also possible to return information about the existing
-     * row. The row, including it's {@link Version} can be optionally returned.
+     * row. The row, including it's {@link Version} and modification time
+     * can be optionally returned.
      * The existing row information will only be returned if
      * {@link DeleteRequest#setReturnRow} is true and one of the following
      * occurs:
@@ -211,7 +212,8 @@ public interface NoSQLHandle extends AutoCloseable {
      * </ul>
      * <p>
      * It is also possible to return information about the existing
-     * row. The row, including it's {@link Version} can be optionally returned.
+     * row. The existing row, including it's {@link Version} and modification
+     * time can be optionally returned.
      * The existing row information will only be returned if
      * {@link PutRequest#setReturnRow} is true and one of the following occurs:
      * <ul>

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

@@ -131,8 +131,9 @@ public int getTimeout() {
     }
 
     /**
-     * Returns whether information about the existing row should be returned on
-     * failure because of a version mismatch.
+     * Returns whether information about the existing row should be returned.
+     * See {@link DeleteRequest#setReturnRow} for details about what information
+     * is returned.
      *
      * @return true if information should be returned.
      */
@@ -194,10 +195,21 @@ public DeleteRequest setCompartment(String compartment) {
     }
 
     /**
-     * Sets whether information about the existing row should be returned on
-     * failure because of a version mismatch. If a match version has not been
-     * set via {@link #setMatchVersion} this parameter is ignored and there
-     * will be no return information. This parameter is optional and defaults
+     * Sets whether information about the existing row should be returned.
+     * The existing row information, including the value, version, and
+     * modification time, will only be returned if
+     * {@link DeleteRequest#setReturnRow} is true and one of the following
+     * occurs:
+     * <ul>
+     * <li> The {@link DeleteRequest#setMatchVersion} is used and the operation
+     * fails because the row exists and its version does not match.
+     * </li>
+     * <li> The {@link DeleteRequest#setMatchVersion} is not used and the
+     * operation succeeds provided that the server supports providing the
+     * existing row.
+     * </li>
+     * </ul>
+     * This parameter is optional and defaults
      * to false. It's use may incur additional cost.
      *
      * @param value set to true if information should be returned

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

@@ -15,10 +15,11 @@
  * Represents the result of a {@link NoSQLHandle#delete} operation.
  * <p>
  * If the delete succeeded {@link #getSuccess} returns true.
- * Information about the existing row on failure may be
- * available using {@link #getExistingValue} and
- *.{@link #getExistingVersion}, depending on the use of
- * {@link DeleteRequest#setReturnRow}.
+ * Information about the existing row may be
+ * available using {@link #getExistingValue},
+ *.{@link #getExistingVersion} and {@link #getExistingModificationTime},
+ * depending on the use of {@link DeleteRequest#setReturnRow} and the result
+ * of the operation.
  * @see NoSQLHandle#delete
  */
 public class DeleteResult extends WriteResult {
@@ -34,10 +35,9 @@ public boolean getSuccess() {
     }
 
     /**
-     * Returns the existing row {@link Version} if available. It will be
-     * available if the target row exists and the operation failed because of a
-     * {@link Version} mismatch and the corresponding {@link DeleteRequest} the
-     * method {@link DeleteRequest#setReturnRow} was called with a true value.
+     * Returns the existing row {@link Version} if available. This value will
+     * only be available if the conditions specified in
+     * {@link DeleteRequest#setReturnRow} are met.
      *
      * @return the Version
      */
@@ -46,10 +46,9 @@ public Version getExistingVersion() {
     }
 
     /**
-     * Returns the existing row value if available. It will be available if the
-     * target row exists and the operation failed because of a {@link Version}
-     * mismatch and the corresponding {@link DeleteRequest} the method {@link
-     * DeleteRequest#setReturnRow} was called with a true value.
+     * Returns the existing row value if available. This value will
+     * only be available if the conditions specified in
+     * {@link DeleteRequest#setReturnRow} are met.
      *
      * @return the value
      */
@@ -58,10 +57,9 @@ public MapValue getExistingValue() {
     }
 
     /**
-     * Returns the existing modification time if available. This is available
-     * only if the target row exists and the operation failed because of a
-     * {@link Version} mismatch and the corresponding {@link DeleteRequest}
-     * method {@link DeleteRequest#setReturnRow} was called with a true value.
+     * Returns the existing modification time if available. This value will
+     * only be available if the conditions specified in
+     * {@link DeleteRequest#setReturnRow} are met.
      *
      * @return the modification time in milliseconds since Jan 1, 1970
      *

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

@@ -268,11 +268,9 @@ public int getTimeout() {
     }
 
     /**
-     * Returns whether information about the exist row should be returned on
-     * failure because of a version mismatch or failure of an "if absent"
-     * operation. If no option is set via {@link #setOption} or the option is
-     * {@link Option#IfPresent} the value of this parameter is ignored and there
-     * will not be any return information.
+     * Returns whether information about the existing row should be returned.
+     * See {@link PutRequest#setReturnRow} for details on the return
+     * information.
      *
      * @return true if information should be returned.
      */
@@ -295,9 +293,27 @@ public PutRequest setTableName(String tableName) {
     }
 
     /**
-     * Sets whether information about the exist row should be returned on
-     * failure because of a version mismatch or failure of an "if absent"
-     * operation.
+     * Sets whether information about the existing row should be returned.
+     * The existing row information, including the value, Version, and
+     * modification time, will only be returned if
+     * {@link PutRequest#setReturnRow} is true and one of the following occurs:
+     * <ul>
+     * <li>The {@link Option#IfAbsent} is used and the operation fails because
+     * the row already exists.</li>
+     * <li>The {@link Option#IfVersion} is used and the operation fails because
+     * the row exists and its version does not match.
+     * </li>
+     * <li>The {@link Option#IfPresent} is used and the operation succeeds
+     * provided that the server supports providing the existing row.
+     * </li>
+     * <li>The {@link Option} is not used and put operation replaces the
+     * existing row provided that the server supports providing the existing
+     * row.
+     * </li>
+     * </ul>
+     *
+     * This setting is optional and defaults to false. If true the operation
+     * will incur additional cost.
      *
      * @param value set to true if information should be returned
      *

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

@@ -17,10 +17,10 @@
  * <p>
  * On a successful operation the value returned by {@link #getVersion} is
  * non-null. On failure that value is null. Information about the
- * existing row on failure may be available using
- * {@link #getExistingValue} and.{@link #getExistingVersion}, depending on the
- * use of {@link PutRequest#setReturnRow} and whether the put had an option set
- * using {@link PutRequest#setOption}.
+ * 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.
  * @see NoSQLHandle#put
  */
 public class PutResult extends WriteResult {
@@ -49,9 +49,8 @@ public PutResult setVersion(Version version) {
 
     /**
      * Returns the existing row {@link Version} if available. This value will
-     * only be available if the conditional put operation failed and the request
-     * specified that return information be returned using
-     * {@link PutRequest#setReturnRow}.
+     * only be available if the conditions specified in
+     * {@link PutRequest#setReturnRow} are met.
      *
      * @return the Version
      */
@@ -61,9 +60,8 @@ public Version getExistingVersion() {
 
     /**
      * Returns the existing row value if available. This value will
-     * only be available if the conditional put operation failed and the request
-     * specified that return information be returned using
-     * {@link PutRequest#setReturnRow}.
+     * only be available if the conditions specified in
+     * {@link PutRequest#setReturnRow} are met.
      *
      * @return the value
      */
@@ -73,9 +71,8 @@ public MapValue getExistingValue() {
 
     /**
      * Returns the existing modification time if available. This value will
-     * only be available if the conditional put operation failed and the request
-     * specified that return information be returned using
-     * {@link PutRequest#setReturnRow}.
+     * only be available if the conditions specified in
+     * {@link PutRequest#setReturnRow} are met.
      *
      * @return the existing modification time in milliseconds since Jan 1, 1970
      *

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

@@ -209,15 +209,15 @@ public Version getExistingVersion() {
         }
 
         /**
-         * Returns the previous row value associated with the key if available.
+         * Returns the existing row value associated with the key if available.
          * @return the existing value if set
          */
         public MapValue getExistingValue() {
             return super.getExistingValueInternal();
         }
 
         /**
-         * Returns the previous modification time associated with the key if
+         * Returns the existing modification time associated with the key if
          * available.
          * @return the modification time if set, in milliseconds sine Jan 1,
          * 1970