Package oracle.nosql.driver.ops

## Class PutRequest

- java.lang.Object
- - oracle.nosql.driver.ops.Request
  - - oracle.nosql.driver.ops.PutRequest

-     public class PutRequest
      extends Request

  Represents the input to a `NoSQLHandle.put(oracle.nosql.driver.ops.PutRequest)` operation. This request can be used to perform unconditional and conditional puts:
  - Overwrite any existing row. This is the default.
  - Succeed only if the row does not exist. Use `PutRequest.Option.IfAbsent` for this case.
  - Succeed only if the row exists. Use `PutRequest.Option.IfPresent` for this case
  - Succeed only if the row exists and its `Version` matches a specific `Version`. Use `PutRequest.Option.IfVersion` for this case and `setMatchVersion(oracle.nosql.driver.Version)` to specify the version to match

  Information about the existing row can be returned on failure of a put operation using `PutRequest.Option.IfVersion` or `PutRequest.Option.IfAbsent` by using `setReturnRow(boolean)`. Requesting this information incurs additional cost and may affect operation latency.

  On a successful operation the `Version` returned by `PutResult.getVersion()` is non-null. Additional information, such as previous row information, may be available in `PutResult`.

  See Also:
    `NoSQLHandle.put(oracle.nosql.driver.ops.PutRequest)`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `PutRequest.Option` | Specifies a condition for the put operation.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `PutRequest()` | Constructs an empty request

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `getExactMatch()` | Returns whether or not the value must be an exact match to the table schema or not.
    `int` | `getIdentityCacheSize()` | Gets the number of generated identity values that are requested from the server during a put if set in this request.
    `Version` | `getMatchVersion()` | Returns the `Version` used for a match on a conditional put.
    `PutRequest.Option` | `getOption()` | Returns the option specified for the put.
    `boolean` | `getReturnRow()` | Returns whether information about the exist row should be returned on failure because of a version mismatch or failure of an "if absent" operation.
    `int` | `getTimeout()` | Returns the timeout to use for the operation, in milliseconds.
    `TimeToLive` | `getTTL()` | Returns the `TimeToLive` value, if set.
    `boolean` | `getUseTableDefaultTTL()` | Returns whether or not to update the row's time to live (TTL) based on a table default value if the row exists.
    `MapValue` | `getValue()` | Returns the value of the row to be used.
    `PutRequest` | `setCompartment​(String compartment)` | Cloud service only.
    `PutRequest` | `setExactMatch​(boolean value)` | If true the value must be an exact match for the table schema or the operation will fail.
    `PutRequest` | `setIdentityCacheSize​(int size)` | Sets the number of generated identity values that are requested from the server during a put.
    `PutRequest` | `setMatchVersion​(Version version)` | Sets the `Version` to use for a conditional put operation.
    `PutRequest` | `setOption​(PutRequest.Option option)` | Sets the option for the put.
    `PutRequest` | `setReturnRow​(boolean value)` | Sets whether information about the exist row should be returned on failure because of a version mismatch or failure of an "if absent" operation.
    `PutRequest` | `setTableName​(String tableName)` | Sets the table name to use for the operation
    `PutRequest` | `setTimeout​(int timeoutMs)` | Sets the request timeout value, in milliseconds.
    `PutRequest` | `setTTL​(TimeToLive ttl)` | Sets the `TimeToLive` value, causing the time to live on the row to be set to the specified value on put.
    `PutRequest` | `setUseTableDefaultTTL​(boolean value)` | If true, and there is an existing row, causes the operation to update the time to live (TTL) value of the row based on the Table's default TTL if set.
    `PutRequest` | `setValue​(MapValue value)` | Sets the value to use for the put operation.
    `PutRequest` | `setValueFromJson​(String jsonValue, JsonOptions options)` | Sets the value to use for the put operation based on a JSON string.

    - ### Methods inherited from class oracle.nosql.driver.ops.Request

      `getCompartment, getReadRateLimiter, getRetryStats, getTableName, getWriteRateLimiter, setReadRateLimiter, setWriteRateLimiter`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### PutRequest

          public PutRequest()

      Constructs an empty request

  - ### Method Detail

    - #### setCompartment

          public PutRequest setCompartment​(String compartment)

      Cloud service only.

      Sets the name or id of a compartment to be used for this operation.

      The compartment may be specified as either a name (or path for nested compartments) or as an id (OCID). A name (vs id) can only be used when authenticated using a specific user identity. It is not available if authenticated as an Instance Principal which can be done when calling the service from a compute instance in the Oracle Cloud Infrastructure. See `SignatureProvider.createWithInstancePrincipal()`

      Parameters:
        `compartment` - the name or id. If using a nested compartment, specify the full compartment path `compartmentA.compartmentB`, but exclude the name of the root compartment (tenant).
      Returns:
        this

    - #### getValue

          public MapValue getValue()

      Returns the value of the row to be used.
      Returns:
        the value, or null if not set

    - #### setValue

          public PutRequest setValue​(MapValue value)

      Sets the value to use for the put operation. This is a required parameter and must be set using this method or `setValueFromJson(java.lang.String, oracle.nosql.driver.values.JsonOptions)`.
      Parameters:
        `value` - the row value
      Returns:
        this

    - #### setValueFromJson

          public PutRequest setValueFromJson​(String jsonValue,
                                             JsonOptions options)

      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 `MapValue`. This is a required parameter and must be set using this method or `setValue(oracle.nosql.driver.values.MapValue)`.
      Parameters:
        `jsonValue` - the row value as a JSON string
        `options` - optional configuration to specify how to map JSON data
      Returns:
        this

    - #### getTTL

          public TimeToLive getTTL()

      Returns the `TimeToLive` value, if set.
      Returns:
        the `TimeToLive` if set, null otherwise.

    - #### setTTL

          public PutRequest setTTL​(TimeToLive ttl)

      Sets the `TimeToLive` value, causing the time to live on the row to be set to the specified value on put. This value overrides any default time to live setting on the table.
      Parameters:
        `ttl` - the time to live
      Returns:
        this

    - #### setUseTableDefaultTTL

          public PutRequest setUseTableDefaultTTL​(boolean value)

      If true, and there is an existing row, causes the operation to update the time to live (TTL) value of the row based on the Table's default TTL if set. If the table has no default TTL this state has no effect. By default updating an existing row has no effect on its TTL.
      Parameters:
        `value` - true or false
      Returns:
        this

    - #### getUseTableDefaultTTL

          public boolean getUseTableDefaultTTL()

      Returns whether or not to update the row's time to live (TTL) based on a table default value if the row exists. By default updates of existing rows do not affect that row's TTL.
      Returns:
        the value

    - #### getMatchVersion

          public Version getMatchVersion()

      Returns the `Version` used for a match on a conditional put.
      Returns:
        the Version or null if not set

    - #### setMatchVersion

          public PutRequest setMatchVersion​(Version version)

      Sets the `Version` to use for a conditional put operation. The Version is usually obtained from `GetResult.getVersion()` or other method that returns a Version. When set, the put operation will succeed only if the row exists and its Version matches the one specified. This condition exists to allow an application to ensure that it is updating a row in an atomic read-modify-write cycle. Using this mechanism incurs additional cost.
      Parameters:
        `version` - the Version to match
      Returns:
        this

    - #### getOption

          public PutRequest.Option getOption()

      Returns the option specified for the put.
      Returns:
        the option specified.

    - #### setOption

          public PutRequest setOption​(PutRequest.Option option)

      Sets the option for the put.
      Parameters:
        `option` - the option to set.
      Returns:
        this

    - #### getTimeout

          public int getTimeout()

      Returns the timeout to use for the operation, in milliseconds. A value of 0 indicates that the timeout has not been set.
      Returns:
        the value

    - #### getReturnRow

          public boolean getReturnRow()

      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 `setOption(oracle.nosql.driver.ops.PutRequest.Option)` or the option is `PutRequest.Option.IfPresent` the value of this parameter is ignored and there will not be any return information.
      Returns:
        true if information should be returned.

    - #### setTableName

          public PutRequest setTableName​(String tableName)

      Sets the table name to use for the operation
      Parameters:
        `tableName` - the table name
      Returns:
        this

    - #### setReturnRow

          public PutRequest setReturnRow​(boolean value)

      Sets whether information about the exist row should be returned on failure because of a version mismatch or failure of an "if absent" operation.
      Parameters:
        `value` - set to true if information should be returned
      Returns:
        this

    - #### setTimeout

          public PutRequest setTimeout​(int timeoutMs)

      Sets the request timeout value, in milliseconds. This overrides any default value set in `NoSQLHandleConfig`. The value must be positive.
      Parameters:
        `timeoutMs` - the timeout value, in milliseconds
      Returns:
        this
      Throws:
        `IllegalArgumentException` - if the timeout value is less than or equal to 0

    - #### setExactMatch

          public PutRequest setExactMatch​(boolean value)

      If true the value must be an exact match for the table schema or the operation will fail. An exact match means that there are no required fields missing and that there are no extra, unknown fields. The default behavior is to not require an exact match.
      Parameters:
        `value` - true or false
      Returns:
        this
      Since:
        5.0.1

    - #### getExactMatch

          public boolean getExactMatch()

      Returns whether or not the value must be an exact match to the table schema or not.
      Returns:
        the value
      Since:
        5.0.1

    - #### setIdentityCacheSize

          public PutRequest setIdentityCacheSize​(int size)

      Sets the number of generated identity values that are requested from the server during a put. This takes precedence over the DDL identity CACHE option set during creation of the identity column. Any value equal or less than 0 means that the DDL identity CACHE value is used.
      Parameters:
        `size` - the size
      Returns:
        this
      Since:
        5.0.1

    - #### getIdentityCacheSize

          public int getIdentityCacheSize()

      Gets the number of generated identity values that are requested from the server during a put if set in this request.
      Returns:
        the value, or 0 if it has not been set.
      Since:
        5.0.1