public class WriteOptions extends java.lang.Object implements java.lang.Cloneable
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
explicitly set to true. When deleting a record, the TTL parameter is
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
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_UTILIZATIONthreshold, as usual, but taking into account expired data; and
partial'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 actionwill 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
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:
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|
Constructs a WriteOptions object with default values for all properties.
|Modifier and Type||Method and Description|
Returns the Time-To-Live property for a 'put' operation.
Returns the Time-To-Live time unit for a 'put' operation.
Returns the update-TTL property for a 'put' operation.
A convenience method to set the TTL based on a given expiration time and the current system time.
Sets the Time-To-Live property for a 'put' operation, using
Sets the Time-To-Live property for a 'put' operation, using the given
Sets the update-TTL property for a 'put' operation.
public WriteOptions clone()
public WriteOptions setCacheMode(CacheMode cacheMode)
CacheModeto be used for the operation.
By default this property is null, meaning that the default specified
EnvironmentMutableConfig.setCacheMode(com.sleepycat.je.CacheMode) will be used.
cacheMode- is the
CacheModeused for the operation, or null to use the Cursor, Database or Environment default.
public CacheMode getCacheMode()
CacheModeto be used for the operation, or null if the Cursor, Database or Environment default will be used.
public WriteOptions setTTL(int ttl)
TimeUnit.Daysas 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)
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()
public java.util.concurrent.TimeUnit getTTLUnit()
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()
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
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
OperationResult.getExpirationTime(), then it will be evenly divisible by the number of milliseconds in one hour and no rounding will occur.
DAYSis used; otherwise,
HOURSis 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
Note that when a particular time unit is desired, null should not be
passed for the timeUnit parameter. Normally
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.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.