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 aNoSQLHandle.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 specificVersion
. UsePutRequest.Option.IfVersion
for this case andsetMatchVersion(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
orPutRequest.Option.IfAbsent
by usingsetReturnRow(boolean)
. Requesting this information incurs additional cost and may affect operation latency.On a successful operation the
Version
returned byPutResult.getVersion()
is non-null. Additional information, such as previous row information, may be available inPutResult
.
-
-
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 theVersion
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 theTimeToLive
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 theVersion
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 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 operationPutRequest
setTimeout(int timeoutMs)
Sets the request timeout value, in milliseconds.PutRequest
setTTL(TimeToLive ttl)
Sets theTimeToLive
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, setRateLimitDelayedMs, setReadRateLimiter, setWriteRateLimiter
-
-
-
-
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 pathcompartmentA.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 orsetValueFromJson(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 aMapValue
. This is a required parameter and must be set using this method orsetValue(oracle.nosql.driver.values.MapValue)
.- Parameters:
jsonValue
- the row value as a JSON stringoptions
- optional configuration to specify how to map JSON data- Returns:
- this
-
getTTL
public TimeToLive getTTL()
Returns theTimeToLive
value, if set.- Returns:
- the
TimeToLive
if set, null otherwise.
-
setTTL
public PutRequest setTTL(TimeToLive ttl)
Sets theTimeToLive
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 theVersion
used for a match on a conditional put.- Returns:
- the Version or null if not set
-
setMatchVersion
public PutRequest setMatchVersion(Version version)
Sets theVersion
to use for a conditional put operation. The Version is usually obtained fromGetResult.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 viasetOption(oracle.nosql.driver.ops.PutRequest.Option)
or the option isPutRequest.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 withNoSQLHandleConfig.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 withNoSQLHandleConfig.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 classRequest
- Returns:
- the type name of the request
-
-