Package oracle.nosql.driver.ops

# Class PutRequest

java.lang.Object
oracle.nosql.driver.ops.Request
oracle.nosql.driver.ops.DurableRequest
oracle.nosql.driver.ops.WriteRequest
oracle.nosql.driver.ops.PutRequest

public class PutRequest extends WriteRequest
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 enum`
  `PutRequest.Option`
  Specifies a condition for the put operation.

- ## Constructor Summary

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

- ## Method Summary

  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 existing row should be returned.
  `int`
  `getTimeout()`
  Returns the timeout to use for the operation, in milliseconds.
  `TimeToLive`
  `getTTL()`
  Returns the `TimeToLive` value, if set.
  `String`
  `getTypeName()`
  Returns the type name of the request.
  `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`
  `setDurability(Durability durability)`
  Sets the durability to use for the operation.
  `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`
  `setNamespace(String namespace)`
  Sets the optional namespace.
  `PutRequest`
  `setOption(PutRequest.Option option)`
  Sets the option for the put.
  `PutRequest`
  `setReturnRow(boolean value)`
  Sets whether information about the existing row should be returned.
  `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.DurableRequest

  `getDurability`

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

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

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

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

- ## Constructor Details

  - ### PutRequest

    public PutRequest()
    Constructs an empty request

- ## Method Details

  - ### 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 existing row should be returned. See `setReturnRow(boolean)` for details on the 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 existing row should be returned. The existing row information, including the value, Version, and modification time, will only be returned if `setReturnRow(boolean)` is true and one of the following occurs:
    - The `PutRequest.Option.IfAbsent` is used and the operation fails because the row already exists.
    - The `PutRequest.Option.IfVersion` is used and the operation fails because the row exists and its version does not match.
    - The `PutRequest.Option.IfPresent` is used and the operation succeeds provided that the server supports providing the existing row.
    - The `PutRequest.Option` is not used and put operation replaces the existing row provided that the server supports providing the existing row.
    This setting is optional and defaults to false. If true the operation will incur additional cost.
    Parameters:
      `value` - set to true if information should be returned
    Returns:
      this

  - ### setDurability

    public PutRequest setDurability(Durability durability)
    Sets the durability to use for the operation. On-premises only.
    Parameters:
      `durability` - the durability value. Set to null for the default durability setting on the server.
    Returns:
      this
    Since:
      5.3.0

  - ### setTimeout

    public PutRequest setTimeout(int timeoutMs)
    Sets the request timeout value, in milliseconds. This overrides any default value set in with `NoSQLHandleConfig.setRequestTimeout(int)`. 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

  - ### setNamespace

    public PutRequest setNamespace(String namespace)
    Sets the optional namespace. On-premises only. This overrides any default value set with `NoSQLHandleConfig.setDefaultNamespace(java.lang.String)`. Note: if a namespace is specified in the table name for the request (using the namespace:tablename format), that value will override this setting.
    Parameters:
      `namespace` - the namespace to use for the operation
    Returns:
      this
    Since:
      5.4.10

  - ### 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

  - ### getTypeName

    public String getTypeName()
    Description copied from class: `Request`
    Returns the type name of the request. This is used for stats.
    Specified by:
      `getTypeName` in class `Request`
    Returns:
      the type name of the request