mirror of
https://github.com/berkeleydb/je.git
synced 2024-07-06 18:07:18 +00:00
319 lines
12 KiB
HTML
319 lines
12 KiB
HTML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
||
<title>Using Time to Live</title>
|
||
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
|
||
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
|
||
<link rel="start" href="index.html" title="Getting Started with Berkeley DB Java Edition" />
|
||
<link rel="up" href="DBEntry.html" title="Chapter 8. Database Records" />
|
||
<link rel="prev" href="usingDbt.html" title="Reading and Writing Database Records" />
|
||
<link rel="next" href="bindAPI.html" title="Using the BIND APIs" />
|
||
</head>
|
||
<body>
|
||
<div xmlns="" class="navheader">
|
||
<div class="libver">
|
||
<p>Library Version 12.2.7.5</p>
|
||
</div>
|
||
<table width="100%" summary="Navigation header">
|
||
<tr>
|
||
<th colspan="3" align="center">Using Time to Live</th>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" align="left"><a accesskey="p" href="usingDbt.html">Prev</a> </td>
|
||
<th width="60%" align="center">Chapter 8. Database Records</th>
|
||
<td width="20%" align="right"> <a accesskey="n" href="bindAPI.html">Next</a></td>
|
||
</tr>
|
||
</table>
|
||
<hr />
|
||
</div>
|
||
<div class="sect1" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h2 class="title" style="clear: both"><a id="timetolive"></a>Using Time to Live</h2>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="toc">
|
||
<dl>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="timetolive.html#ttl-specify">Specifying a TTL Value</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="timetolive.html#ttl-update">Updating a TTL Value</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="timetolive.html#ttl-remove">Deleting TTL Expiration</a>
|
||
</span>
|
||
</dt>
|
||
</dl>
|
||
</div>
|
||
<span>
|
||
<p>
|
||
Time to Live (TTL) is a mechanism that allows you to automatically
|
||
expire
|
||
|
||
<span>database records.</span>
|
||
TTL is expressed as the amount of time data is allowed to live in
|
||
the
|
||
|
||
<span>database.</span>
|
||
Data which has reached its expiration timeout value can no longer
|
||
be retrieved, and will not appear in any
|
||
|
||
<span>database</span>
|
||
statistics. Whether the data is physically removed from the
|
||
|
||
<span>database</span>
|
||
is determined by an internal mechanism that is not
|
||
user-controllable.
|
||
</p>
|
||
<p>
|
||
TTL represents a minimum guaranteed time to live. Data expires on
|
||
hour or day boundaries. This means that with a one hour TTL, there
|
||
can be as much as two hours worth of unexpired data. For example
|
||
(using a time format of hour:minute:second), given a one hour TTL,
|
||
data written between 00:00:00.000 and 00:59:59.999 will expire at
|
||
02:00:00.000 because the data is guaranteed to expire no less than
|
||
one hour from when it is written.
|
||
</p>
|
||
<p>
|
||
Expired data is invisible to queries and
|
||
|
||
<span>database</span>
|
||
statistics, but even so it is using disk space until it has been
|
||
purged. The expired data is purged from disk at some point in
|
||
time after its expiration date. The exact time when the data is
|
||
purged is driven by internal mechanisms and the workload on your
|
||
|
||
<span>database.</span>
|
||
</p>
|
||
<p>
|
||
The TTL value for a
|
||
|
||
<span>database record</span>
|
||
can be updated at any time before the expiration value has been
|
||
reached. Data that has expired can no longer be modified, and this
|
||
includes its TTL value.
|
||
</p>
|
||
<p>
|
||
TTL is more efficient than manual user-deletion of the
|
||
|
||
<span>record</span>
|
||
because it avoids the overhead of writing a database log entry for
|
||
the data deletion. The deletion also does not appear in the
|
||
replication stream.
|
||
</p>
|
||
<p>
|
||
The following provides a brief introduction to using Time to Live.
|
||
For a more complete description of this mechanism, see the
|
||
<a class="ulink" href="../java/com/sleepycat/je/WriteOptions.html" target="_top">
|
||
com.sleepycat.je.WriteOptions javadoc.
|
||
</a>
|
||
</p>
|
||
</span>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="ttl-specify"></a>Specifying a TTL Value</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
TTL values are specified on a record by record basis using
|
||
the <code class="classname">WriteOptions</code> class, which can
|
||
but used by various <code class="methodname">put()</code> methods
|
||
when writing to the database. For example, variations of
|
||
<code class="methodname">Database.put()</code>,
|
||
<code class="methodname">PrimaryIndex.put()</code>, and
|
||
<code class="methodname">Cursor.put()</code> exist that accept a
|
||
<code class="classname">WriteOptions</code> class instance.
|
||
</p>
|
||
<p>
|
||
<code class="classname">WriteOptions</code> allows
|
||
you to identify the number of days or hours the record will exist
|
||
in the database before expiring. A duration interval specified in
|
||
days is recommended because this results in the least amount of
|
||
storage consumed in the store. However, if you want a TTL value
|
||
that is not an even multiple of days, then specify the TTL
|
||
value in hours.
|
||
</p>
|
||
<p>
|
||
The code example from
|
||
<a class="xref" href="usingDbt.html#databaseWrite" title="Writing Records to the Database">Writing Records to the Database</a>
|
||
can be extended to specify a TTL value of 5 days like this:
|
||
</p>
|
||
<pre class="programlisting">package je.gettingStarted;
|
||
|
||
import com.sleepycat.je.Database;
|
||
import com.sleepycat.je.DatabaseEntry;
|
||
<strong class="userinput"><code>import com.sleepycat.je.Put;
|
||
import com.sleepycat.je.WriteOptions;</code></strong>
|
||
|
||
|
||
...
|
||
|
||
// Environment and database opens omitted for clarity.
|
||
// Environment and database must NOT be opened read-only.
|
||
|
||
String aKey = "myFirstKey";
|
||
String aData = "myFirstData";
|
||
|
||
try {
|
||
DatabaseEntry theKey = new DatabaseEntry(aKey.getBytes("UTF-8"));
|
||
DatabaseEntry theData = new DatabaseEntry(aData.getBytes("UTF-8"));
|
||
|
||
<strong class="userinput"><code>WriteOptions wo = new WriteOptions();
|
||
// This sets the TTL using day units. Another variation
|
||
// of setTTL() exists that accepts a TimeUnit class instance.
|
||
wo.setTTL(5);
|
||
myDatabase.put(null, // Transaction handle.
|
||
theKey, // Record's key.
|
||
theData, // Record's data.
|
||
Put.NO_OVERWRITE, // If the record exists,
|
||
// do not overwrite it.
|
||
wo); // WriteOptions instance.</code></strong>
|
||
|
||
} catch (Exception e) {
|
||
// Exception handling goes here
|
||
} </pre>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="ttl-update"></a>Updating a TTL Value</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
To update the expiration time for a record, you update the
|
||
record as normal, and at the same time specify the new expiration
|
||
time. However, you must also indicate that the expiration time
|
||
is to be updated. By default, you can modify the record and
|
||
the expiration time will not be modified, even if you specify a
|
||
new TTL value for the record.
|
||
</p>
|
||
<p>
|
||
To indicate that the the expiration time is to be updated,
|
||
specify <code class="literal">true</code> to the
|
||
<code class="methodname">WriteOptions.setUpdateTTL()</code>
|
||
method. For example, using the previous example, to change
|
||
the TTL value to 10 days, do the following:
|
||
</p>
|
||
<pre class="programlisting">package je.gettingStarted;
|
||
|
||
import com.sleepycat.je.Database;
|
||
import com.sleepycat.je.DatabaseEntry;
|
||
import com.sleepycat.je.Put;
|
||
import com.sleepycat.je.WriteOptions;
|
||
|
||
|
||
...
|
||
|
||
// Environment and database opens omitted for clarity.
|
||
// Environment and database must NOT be opened read-only.
|
||
|
||
String aKey = "myFirstKey";
|
||
String aData = "myFirstData";
|
||
|
||
try {
|
||
DatabaseEntry theKey = new DatabaseEntry(aKey.getBytes("UTF-8"));
|
||
DatabaseEntry theData = new DatabaseEntry(aData.getBytes("UTF-8"));
|
||
|
||
WriteOptions wo = new WriteOptions();
|
||
// This sets the TTL using day units. Another variation
|
||
// of setTTL() exists that accepts a TimeUnit class instance.
|
||
wo.setTTL(5);
|
||
<strong class="userinput"><code>// If the record currently exists, update the TTL value
|
||
wo.setUpdateTTL(true);</code></strong>
|
||
myDatabase.put(null, // Transaction handle.
|
||
theKey, // Record's key.
|
||
theData, // Record's data.
|
||
<strong class="userinput"><code>Put.OVERWRITE, // If the record exists,
|
||
// overwrite it.</code></strong>
|
||
wo); // WriteOptions instance.
|
||
|
||
} catch (Exception e) {
|
||
// Exception handling goes here
|
||
} </pre>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="ttl-remove"></a>Deleting TTL Expiration</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
If you have set a TTL value for a record and you later decide you
|
||
do not want it to ever automatically expire, you can turn off
|
||
TTL by setting a TTL value of <code class="literal">0</code>:
|
||
</p>
|
||
<pre class="programlisting">package je.gettingStarted;
|
||
|
||
import com.sleepycat.je.Database;
|
||
import com.sleepycat.je.DatabaseEntry;
|
||
import com.sleepycat.je.Put;
|
||
import com.sleepycat.je.WriteOptions;
|
||
|
||
|
||
...
|
||
|
||
// Environment and database opens omitted for clarity.
|
||
// Environment and database must NOT be opened read-only.
|
||
|
||
String aKey = "myFirstKey";
|
||
String aData = "myFirstData";
|
||
|
||
try {
|
||
DatabaseEntry theKey = new DatabaseEntry(aKey.getBytes("UTF-8"));
|
||
DatabaseEntry theData = new DatabaseEntry(aData.getBytes("UTF-8"));
|
||
|
||
WriteOptions wo = new WriteOptions();
|
||
<strong class="userinput"><code>// Turn off automatic expiration of this record.
|
||
wo.setTTL(0);</code></strong>
|
||
wo.setUpdateTTL(true);
|
||
myDatabase.put(null, // Transaction handle.
|
||
theKey, // Record's key.
|
||
theData, // Record's data.
|
||
Put.OVERWRITE, // If the record exists,
|
||
// overwrite it.
|
||
wo); // WriteOptions instance.
|
||
|
||
} catch (Exception e) {
|
||
// Exception handling goes here
|
||
} </pre>
|
||
</div>
|
||
</div>
|
||
<div class="navfooter">
|
||
<hr />
|
||
<table width="100%" summary="Navigation footer">
|
||
<tr>
|
||
<td width="40%" align="left"><a accesskey="p" href="usingDbt.html">Prev</a> </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="u" href="DBEntry.html">Up</a>
|
||
</td>
|
||
<td width="40%" align="right"> <a accesskey="n" href="bindAPI.html">Next</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="40%" align="left" valign="top">Reading and Writing Database Records </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="h" href="index.html">Home</a>
|
||
</td>
|
||
<td width="40%" align="right" valign="top"> Using the BIND APIs</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html>
|