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:

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:

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

    • 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