public class WriteOptions
extends java.lang.Object
implements java.lang.Cloneable
When performing a 'put' operation, a TTL may be specified using
setTTL(int, TimeUnit)
or setTTL(int)
.
By default, the TTL property is zero, meaning there is no automatic
expiration. A non-zero TTL may be specified to cause an inserted record
to expire. The expiration time may also be changed for an existing
record by updating the record and specifying a different TTL, including
specifying zero to prevent the record from expiring. However, the TTL of
an existing record is updated only if setUpdateTTL(boolean)
is
explicitly set to true. When deleting a record, the TTL parameter is
ignored.
Records expire on day or hour boundaries, depending on the timeUnit
parameter. At the time of the write operation, the TTL
parameter is used to compute the record's expiration time by first
converting it from days (or hours) to milliseconds, and then adding it
to the current system time. If the resulting expiration time is not
evenly divisible by the number of milliseconds in one day (or hour), it
is rounded up to the nearest day (or hour).
Passing TimeUnit.DAYS, rather than TimeUnit.HOURS, for the timeUnit parameter is recommended to minimize storage requirements (memory and disk). Because the expiration time is stored in the JE Btree internally, when using the TTL feature, the additional memory and disk space required for storing Btree internal nodes (INs) is twice as much when using TimeUnit.HOURS as when using TimeUnit.DAYS. Using TimeUnit.DAYS adds about 5% to the space needed for INs, while TimeUnit.HOURS adds about 10%.
Note that JE stores the expiration time of the record and not the
original TTL value that was specified. The expiration time of a record
is available when reading (or writing) records via OperationResult.getExpirationTime()
.
A summary of the behavior of expired records is as follows.
A more detailed description is below, including some information on how expired records are handled internally.
EnvironmentConfig.CLEANER_MIN_UTILIZATION
threshold, as usual,
but taking into account expired data; andpartial
'data'
parameter), the operation may fail (return null)
because the pre-existing data cannot be read.
SecondaryIntegrityException
, as
would normally happen when an expected associated record is
missing.
foreign key
database
, the foreign key delete
action
will not be enforced. Therefore, setting a TTL for a
record in a foreign key database is not recommended. The same
is true when using the DPL and a foreign key database is
specified using SecondaryKey.relatedEntity()
.
EnvironmentConfig.ENV_TTL_CLOCK_TOLERANCE
(two hours, by default), JE treats the record as deleted and no
exception is thrown.
When an integrity error does cause an exception to be thrown, the record's expiration time will be included in the exception message and this can help to diagnose the problem. This includes the following exceptions:
SecondaryIntegrityException
EnvironmentFailureException
with
LOG_FILE_NOT_FOUND in the message.In cases where the clock has been changed by more than one hour
and integrity exceptions occur because of this, it may be possible
to avoid the exceptions by setting the EnvironmentConfig.ENV_TTL_CLOCK_TOLERANCE
configuration parameter
to a larger value.
In order to use the TTL feature in a ReplicatedEnvironment, all nodes must be upgraded to JE 7.0 or later. If one or more nodes in a group uses an earlier version, an IllegalStateException will be thrown when attempting a put operation with a non-zero TTL. Also, once records with a non-zero TTL have been written, a node using an earlier version of JE may not join the group; if this is attempted, the node will fail during open with an EnvironmentFailureException.
Constructor and Description |
---|
WriteOptions()
Constructs a WriteOptions object with default values for all properties.
|
Modifier and Type | Method and Description |
---|---|
WriteOptions |
clone() |
CacheMode |
getCacheMode()
Returns the
CacheMode to be used for the operation, or null
if the Cursor, Database or Environment default will be used. |
int |
getTTL()
Returns the Time-To-Live property for a 'put' operation.
|
java.util.concurrent.TimeUnit |
getTTLUnit()
Returns the Time-To-Live time unit for a 'put' operation.
|
boolean |
getUpdateTTL()
Returns the update-TTL property for a 'put' operation.
|
WriteOptions |
setCacheMode(CacheMode cacheMode)
Sets the
CacheMode to be used for the operation. |
WriteOptions |
setExpirationTime(long expirationTime,
java.util.concurrent.TimeUnit timeUnit)
A convenience method to set the TTL based on a given expiration time
and the current system time.
|
WriteOptions |
setTTL(int ttl)
Sets the Time-To-Live property for a 'put' operation, using
TimeUnit.Days as the TTL unit. |
WriteOptions |
setTTL(int ttl,
java.util.concurrent.TimeUnit timeUnit)
Sets the Time-To-Live property for a 'put' operation, using the given
TimeUnit . |
WriteOptions |
setUpdateTTL(boolean updateTtl)
Sets the update-TTL property for a 'put' operation.
|
public WriteOptions()
public WriteOptions clone()
clone
in class java.lang.Object
public WriteOptions setCacheMode(CacheMode cacheMode)
CacheMode
to be used for the operation.
By default this property is null, meaning that the default specified
using Cursor.setCacheMode(com.sleepycat.je.CacheMode)
,
DatabaseConfig.setCacheMode(com.sleepycat.je.CacheMode)
or
EnvironmentMutableConfig.setCacheMode(com.sleepycat.je.CacheMode)
will be used.
cacheMode
- is the CacheMode
used for the operation, or
null to use the Cursor, Database or Environment default.public CacheMode getCacheMode()
CacheMode
to be used for the operation, or null
if the Cursor, Database or Environment default will be used.setCacheMode(CacheMode)
public WriteOptions setTTL(int ttl)
TimeUnit.Days
as the TTL unit.ttl
- the number of days after the current time on which
the record will automatically expire, or zero for no automatic
expiration. May not be negative.public WriteOptions setTTL(int ttl, java.util.concurrent.TimeUnit timeUnit)
TimeUnit
.ttl
- the number of days or hours after the current time on which
the record will automatically expire, or zero for no automatic
expiration. May not be negative.timeUnit
- is TimeUnit.DAYS or TimeUnit.HOURS. TimeUnit.DAYS is
recommended to minimize storage requirements (memory and disk).public int getTTL()
setTTL(int)
public java.util.concurrent.TimeUnit getTTLUnit()
setTTL(int, TimeUnit)
public WriteOptions setUpdateTTL(boolean updateTtl)
If this property is true and the operation updates a record, the specified TTL will be used to assign a new expiration time for the record, or to clear the record's expiration time if the specified TTL is zero.
If this parameter is false and the operation updates a record, the record's expiration time will not be changed.
If the operation inserts a record, this parameter is ignored and the specified TTL is always applied.
By default, this property is false.
updateTtl
- is whether to assign (or clear) the expiration time
when updating an existing record.public boolean getUpdateTTL()
setUpdateTTL(boolean)
public WriteOptions setExpirationTime(long expirationTime, java.util.concurrent.TimeUnit timeUnit)
Given a desired expiration time and TimeUnit
(DAYS or HOURS),
sets the TTL to a value that will cause a record to expire at or after
the given time, if the record is stored at the current time. The
intended use case is to determine the TTL when writing a record and the
desired expiration time, rather than the TTL, is known.
This method determines the TTL by taking the difference between the current time and the given time, converting it from milliseconds to days (or hours), and rounding up if it is not evenly divisible by the number of milliseconds in one day (or hour).
A special use case is when the expiration time was previously obtained
from OperationResult.getExpirationTime()
, for example, when
performing an export followed by an import. To support this, null can be
passed for the timeUnit parameter and the time unit will be determined
as follows.
OperationResult.getExpirationTime()
, then it will be
evenly divisible by the number of milliseconds in one hour and no
rounding will occur.DAYS
is used; otherwise, HOURS
is used. For example,
when performing an import, if the original expiration time was
specified in DAYS
, and obtained by calling
OperationResult.getExpirationTime()
, the unit derived by this
method will also be DAYS
.
Note that when a particular time unit is desired, null should not be
passed for the timeUnit parameter. Normally TimeUnit.DAYS
is
recommended instead of TimeUnit.HOURS
, to minimize storage
requirements (memory and disk). When the desired unit is known, the unit
should be passed explicitly.
expirationTime
- is the desired expiration time in milliseconds
(UTC), or zero for no automatic expiration.timeUnit
- is TimeUnit.DAYS
or TimeUnit.HOURS
, or
null to derive the time unit as described above.java.lang.IllegalArgumentException
- if ttlUnits is not DAYS, HOURS or null.Copyright (c) 2002, 2017 Oracle and/or its affiliates. All rights reserved.