Package oracle.nosql.driver.ops

# Class DeleteRequest

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

public class DeleteRequest extends WriteRequest
Represents the input to a `NoSQLHandle.delete(oracle.nosql.driver.ops.DeleteRequest)` operation. This request can be used to perform unconditional and conditional deletes:

- Delete any existing row. This is the default.
- Succeed only if the row exists and its `Version` matches a specific `Version`. Use `setMatchVersion(oracle.nosql.driver.Version)` for this case. Using this option in conjunction with using `setReturnRow(boolean)` allows information about the existing row to be returned if the operation fails because of a version mismatch. On success no information is returned. Using `setReturnRow(boolean)` may incur additional cost and affect operation latency.

The table name and key are required parameters. On a successful operation `DeleteResult.getSuccess()` returns true. Additional information, such as previous row information, may be available in `DeleteResult`.

See Also:
  - `NoSQLHandle.delete(oracle.nosql.driver.ops.DeleteRequest)`

- ## Constructor Summary

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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `MapValue`
  `getKey()`
  Returns the key of the row to be deleted.
  `Version`
  `getMatchVersion()`
  Returns the `Version` used for a match on a conditional delete.
  `boolean`
  `getReturnRow()`
  Returns whether information about the existing row should be returned.
  `int`
  `getTimeout()`
  Returns the timeout to use for the operation, in milliseconds.
  `String`
  `getTypeName()`
  Returns the type name of the request.
  `DeleteRequest`
  `setCompartment(String compartment)`
  Cloud service only.
  `DeleteRequest`
  `setDurability(Durability durability)`
  Sets the durability to use for the operation.
  `DeleteRequest`
  `setKey(MapValue key)`
  Sets the key to use for the delete operation.
  `DeleteRequest`
  `setKeyFromJson(String jsonValue, JsonOptions options)`
  Sets the key to use for the delete operation based on a JSON string.
  `DeleteRequest`
  `setMatchVersion(Version version)`
  Sets the `Version` to use for a conditional delete operation.
  `DeleteRequest`
  `setNamespace(String namespace)`
  Sets the optional namespace.
  `DeleteRequest`
  `setReturnRow(boolean value)`
  Sets whether information about the existing row should be returned.
  `DeleteRequest`
  `setTableName(String tableName)`
  Sets the table name to use for the operation.
  `DeleteRequest`
  `setTimeout(int timeoutMs)`
  Sets the optional request timeout value, in milliseconds.

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

  - ### DeleteRequest

    public DeleteRequest()
    Constructs an empty request

- ## Method Details

  - ### getKey

    public MapValue getKey()
    Returns the key of the row to be deleted. This is a required field.
    Returns:
      the key value, or null if not set

  - ### setKey

    public DeleteRequest setKey(MapValue key)
    Sets the key to use for the delete operation. This is a required field.
    Parameters:
      `key` - the key value
    Returns:
      this

  - ### setKeyFromJson

    public DeleteRequest setKeyFromJson(String jsonValue, JsonOptions options)
    Sets the key to use for the delete operation based on a JSON string. The string is parsed for validity and stored internally as a `MapValue`.
    Parameters:
      `jsonValue` - the key value as a JSON string
      `options` - optional configuration to specify how to map JSON data, may be null
    Returns:
      this

  - ### getMatchVersion

    public Version getMatchVersion()
    Returns the `Version` used for a match on a conditional delete.
    Returns:
      the Version or null if not set

  - ### setMatchVersion

    public DeleteRequest setMatchVersion(Version version)
    Sets the `Version` to use for a conditional delete operation. The Version is usually obtained from `GetResult.getVersion()` or other method that returns a Version. When set, the delete operation will succeed only if the row exists and its Version matches the one specified. Using this option will incur additional cost.
    Parameters:
      `version` - the Version to match
    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 about what information is returned.
    Returns:
      true if information should be returned.

  - ### setTableName

    public DeleteRequest setTableName(String tableName)
    Sets the table name to use for the operation. This is a required parameter.
    Parameters:
      `tableName` - the table name
    Returns:
      this

  - ### setDurability

    public DeleteRequest setDurability(Durability durability)
    Sets the durability to use for the operation. On-premises only.
    Parameters:
      `durability` - the durability value
    Returns:
      this
    Since:
      5.3.0

  - ### setCompartment

    public DeleteRequest 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

  - ### setReturnRow

    public DeleteRequest 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 `setMatchVersion(oracle.nosql.driver.Version)` is used and the operation fails because the row exists and its version does not match.
    - The `setMatchVersion(oracle.nosql.driver.Version)` is not used and the operation succeeds provided that the server supports providing the existing row.
    This parameter is optional and defaults to false. It's use may incur additional cost.
    Parameters:
      `value` - set to true if information should be returned
    Returns:
      this

  - ### setTimeout

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

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