3
<!--Copyright 1997-2002 by Sleepycat Software, Inc.-->
4
<!--All rights reserved.-->
5
<!--See the file LICENSE for redistribution information.-->
8
<title>Berkeley DB: Dbt</title>
9
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
10
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
13
<a name="2"><!--meow--></a>
14
<table width="100%"><tr valign=top>
19
<a href="../api_java/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
24
import com.sleepycat.db.*;
26
public class Dbt extends Object
28
public Dbt(byte[] data);
29
public Dbt(byte[] data, int off, int len);
31
public void set_data(byte[] data);
32
public byte[] get_data();
34
public Object get_object() throws java.io.IOException, java.lang.ClassNotFoundException;
35
public void set_object(Object serialobj) throws java.io.IOException;
37
public void set_recno_key_data(int recno);
38
public int get_recno_key_data();
40
public void set_offset(int off);
41
public int get_offset();
43
public int get_size();
44
public void set_size(int size);
46
public int get_ulen();
47
public void set_ulen(int ulen);
49
public int get_dlen();
50
public void set_dlen(int dlen);
52
public int get_doff();
53
public void set_doff(int doff);
55
public int get_flags();
56
public void set_flags(int flags);
60
<p>This manual page describes the specific details of the Dbt class,
61
used to encode keys and data items in a database.
62
<a name="3"><!--meow--></a>
63
<h3>Key/Data Pairs</h3>
64
<p>Storage and retrieval for the <a href="../api_java/db_class.html">Db</a> access methods are based on
65
key/data pairs. Both key and data items are represented by Dbt
66
objects. Key and data byte strings may refer to strings of zero length
67
up to strings of essentially unlimited length. See
68
<a href="../ref/am_misc/dbsizes.html">Database limits</a> for more
70
<p>The Dbt class provides simple access to an underlying data
71
structure, whose elements can be examined or changed using the
72
<b>set_</b> or <b>get_</b> methods. The remainder of the manual
73
page sometimes refers to these accesses using the underlying name; for
74
example, <b>ulen</b> rather than Dbt.get_ulen and
75
Dbt.set_ulen. Dbt can be subclassed, providing a way
76
to associate with it additional data or references to other
78
<p>The constructors set all elements of the underlying structure to zero.
79
The constructor with one argument has the effect of setting all elements
80
to zero except for the <b>data</b> and <b>size</b> elements. The
81
constructor with three arguments has the effect of setting all elements
82
to zero except for the <b>data</b>, <b>size</b> and <b>offset</b>
84
<p>In the case where the <b>flags</b> structure element is set to 0, when
85
being provided a key or data item by the application, the Berkeley DB package
86
expects the <b>data</b> object to be set to a byte array of
87
<b>size</b> bytes. When returning a key/data item to the application,
88
the Berkeley DB package will store into the <b>data</b> object a byte array
89
of <b>size</b> bytes. During a get operation, if none of the
90
Db.DB_DBT_MALLOC, Db.DB_DBT_REALLOC or Db.DB_DBT_USERMEM
91
flags are specified, the operation occurs as if Db.DB_DBT_MALLOC
93
<p>Access to Dbt objects is not re-entrant. In particular, if
94
multiple threads simultaneously access the same Dbt object using
95
<a href="../api_java/db_class.html">Db</a> API calls, the results are undefined, and may result in a
96
crash. One easy way to avoid problems is to use Dbt objects
98
created as local variables and not shared among threads.
99
<p>The elements of the structure underlying the Dbt class are defined as follows:
101
<p><dt>byte[] <a name="data">data</a>;<dd>A byte array containing the data.
102
This element is accessed using Dbt.get_data and
103
Dbt.set_data, and may be initialized using one
105
Note that the array data is not copied immediately, but only when the
107
<p>The Java API also provides helper methods Dbt.get_object and
108
Dbt.set_object to encode and decode objects using the Java
109
serialization API. These methods use <i>ObjectInputStream</i> and
110
<i>ObjectOutputStream</i> internally to manipulate an array of bytes
111
representing an object (and any connected objects). All of the rules of Java
112
Serialization apply. In particular, the object(s) must implement either the
113
<i>Serializable</i> or <i>Externalizable</i> interface. Note that the
114
serialized encoding trades efficiency for convenience.
115
<p><dt>int recno_key_data;<dd>The data representing a key used with a Recno database. Recno database
116
records are ordered by integer keys starting at 1. When the
117
Dbt.set_recno_key_data method is called, the data, size and offset
118
fields in the Dbt are implicitly set to hold a byte array representation
120
<p><dt>int offset;<dd>The number of bytes offset into the <b>data</b> array to determine the
121
portion of the array actually used. This element is accessed using
122
Dbt.get_offset and Dbt.set_offset. Although Java
123
normally maintains proper alignment of byte arrays, the set_offset
124
method can be used to specify unaligned addresses. Unaligned address
125
accesses that are not supported by the underlying hardware may be
126
reported as an exception, or may stop the running Java program.
127
<p><dt>int size;<dd>The length of <b>data</b>, in bytes.
128
This element is accessed using Dbt.get_size and
129
Dbt.set_size, and may be initialized
130
implicitly to the length of the data array with the constructor having
132
<p><dt>int ulen;<dd>The size of the user's buffer (referred to by <b>data</b>), in bytes.
133
This location is not written by the <a href="../api_java/db_class.html">Db</a> methods.
134
<p>Note that applications can determine the length of a record by setting
135
the <b>ulen</b> to 0 and checking the return value found in <b>size</b>.
136
See the Db.DB_DBT_USERMEM flag for more information.
137
<p>This element is accessed using
138
Dbt.get_ulen and Dbt.set_ulen.
139
<p><dt>int dlen;<dd>The length of the partial record being read or written by the application,
141
See the Db.DB_DBT_PARTIAL flag for more information.
142
This element is accessed using
143
Dbt.get_dlen, and Dbt.set_dlen.
144
<p><dt>int doff;<dd>The offset of the partial record being read or written by the application,
146
See the Db.DB_DBT_PARTIAL flag for more information.
147
This element is accessed using
148
Dbt.get_doff and Dbt.set_doff.
149
<p><dt>int flags;<dd>This element is accessed using Dbt.get_flags and
151
<p>The <b>flags</b> value must be set by bitwise inclusively <b>OR</b>'ing together one or more of
152
the following values:
154
<p><dt><a name="Db.DB_DBT_MALLOC">Db.DB_DBT_MALLOC</a><dd>When this flag is set, Berkeley DB will allocate memory for the returned key
156
and return a byte array containing the data in the <b>data</b> field of
157
the key or data Dbt object.
158
<p>If Db.DB_DBT_MALLOC is specified, Berkeley DB allocates a properly sized
159
byte array to contain the data. This can be convenient if you know little
160
about the nature of the data, specifically the size of data in the
161
database. However, if your application makes repeated calls to retrieve
162
keys or data, you may notice increased garbage collection due to this
163
allocation. If you know the maximum size of data you are retrieving, you
164
might decrease the memory burden and speed your application by allocating
165
your own byte array and using Db.DB_DBT_USERMEM. Even if you don't
166
know the maximum size, you can use this option and reallocate your array
167
whenever your retrieval API call
168
throws a <a href="../api_java/memp_class.html">DbMemoryException</a>.
169
<p>It is an error to specify more than one of Db.DB_DBT_MALLOC,
170
Db.DB_DBT_REALLOC, and Db.DB_DBT_USERMEM.
171
<p><dt><a name="Db.DB_DBT_REALLOC">Db.DB_DBT_REALLOC</a><dd>When this flag is set Berkeley DB
172
will return the data in the <b>data</b> field of the key or data
173
Dbt object, reusing the existing byte array if it is large
174
enough, or allocating a new one of the appropriate size.
175
<p>It is an error to specify more than one of Db.DB_DBT_MALLOC,
176
Db.DB_DBT_REALLOC, and Db.DB_DBT_USERMEM.
177
<p><dt><a name="Db.DB_DBT_USERMEM">Db.DB_DBT_USERMEM</a><dd>The <b>data</b> field of the key or data object must refer to memory
178
that is at least <b>ulen</b> bytes in length. If the length of the
179
requested item is less than or equal to that number of bytes, the item
180
is copied into the memory referred to by the <b>data</b> field.
181
Otherwise, the <b>size</b> field is set to the length needed for the
182
requested item, and the error ENOMEM is returned.
183
<p>If Db.DB_DBT_USERMEM is specified, the data field of the Dbt
184
must be set to an appropriately sized byte array.
185
<p>It is an error to specify more than one of Db.DB_DBT_MALLOC,
186
Db.DB_DBT_REALLOC, and Db.DB_DBT_USERMEM.
188
<p>If Db.DB_DBT_MALLOC or Db.DB_DBT_REALLOC is specified, Berkeley DB
189
allocates a properly sized byte array to contain the data. This can be
190
convenient if you know little about the nature of the data, specifically
191
the size of data in the database. However, if your application makes
192
repeated calls to retrieve keys or data, you may notice increased garbage
193
collection due to this allocation. If you know the maximum size of data
194
you are retrieving, you might decrease the memory burden and speed your
195
application by allocating your own byte array and using
196
Db.DB_DBT_USERMEM. Even if you don't know the maximum size, you can
197
use this option and reallocate your array whenever your retrieval API call
198
throws a <a href="../api_java/memp_class.html">DbMemoryException</a>.
200
<p><dt><a name="Db.DB_DBT_PARTIAL">Db.DB_DBT_PARTIAL</a><dd>Do partial retrieval or storage of an item. If the calling application
201
is doing a get, the <b>dlen</b> bytes starting <b>doff</b> bytes from
202
the beginning of the retrieved data record are returned as if they
203
comprised the entire record. If any or all of the specified bytes do
204
not exist in the record, the get is successful, and any existing bytes
206
<p>For example, if the data portion of a retrieved record was 100 bytes,
207
and a partial retrieval was done using a Dbt having a <b>dlen</b>
208
field of 20 and a <b>doff</b> field of 85, the get call would succeed,
209
the <b>data</b> field would refer to the last 15 bytes of the record,
210
and the <b>size</b> field would be set to 15.
211
<p>If the calling application is doing a put, the <b>dlen</b> bytes starting
212
<b>doff</b> bytes from the beginning of the specified key's data record
213
are replaced by the data specified by the <b>data</b> and <b>size</b>
215
If <b>dlen</b> is smaller than <b>size</b>, the record will grow; if
216
<b>dlen</b> is larger than <b>size</b>, the record will shrink.
217
If the specified bytes do not exist, the record will be extended using nul
218
bytes as necessary, and the put call will succeed.
219
<p>It is an error to attempt a partial put using the <a href="../api_java/db_put.html">Db.put</a>
220
method in a database that supports duplicate records.
221
Partial puts in databases supporting duplicate records must be done
222
using a <a href="../api_java/dbc_class.html">Dbc</a> method.
223
<p>It is an error to attempt a partial put with differing <b>dlen</b> and
224
<b>size</b> values in Queue or Recno databases with fixed-length records.
225
<p>For example, if the data portion of a retrieved record was 100 bytes,
226
and a partial put was done using a Dbt having a <b>dlen</b>
227
field of 20, a <b>doff</b> field of 85, and a <b>size</b> field of 30,
228
the resulting record would be 115 bytes in length, where the last 30
229
bytes would be those specified by the put call.
233
<table width="100%"><tr><td><br></td><td align=right>
234
<a href="../api_java/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
236
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
added
removed
libdb/docs/api_java/dbt_class.html
