|
|
|
Berkeley DB version 4.4.20 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object com.sleepycat.db.DatabaseEntry
Encodes database key and data items as a byte array.
Storage and retrieval for the Database
and Cursor
methods
are based on key/data pairs. Both key and data items are represented by
DatabaseEntry objects. Key and data byte arrays may refer to arrays of zero
length up to arrays of essentially unlimited length.
The DatabaseEntry class provides simple access to an underlying object whose elements can be examined or changed. DatabaseEntry objects can be subclassed, providing a way to associate with it additional data or references to other structures.
Access to DatabaseEntry objects is not re-entrant. In particular, if
multiple threads simultaneously access the same DatabaseEntry object using
Database
or Cursor
methods, the results are undefined.
DatabaseEntry objects may be used in conjunction with the object mapping
support provided in the com.sleepycat.bind
package.
DatabaseEntry objects are used for both input data (when writing to a
database or specifying a search parameter) and output data (when reading
from a database). For certain methods, one parameter may be an input
parameter and another may be an output parameter. For example, the
Database.get(com.sleepycat.db.Transaction, com.sleepycat.db.DatabaseEntry, com.sleepycat.db.DatabaseEntry, com.sleepycat.db.LockMode)
method has an input key parameter and an output
data parameter. The documentation for each method describes whether its
parameters are input or output parameters.
For DatabaseEntry input parameters, the caller is responsible for initializing the data array of the DatabaseEntry. For DatabaseEntry output parameters, the method called will initialize the data array.
For DatabaseEntry output parameters, by default the method called will
reuse the byte array in the DatabaseEntry, if the data returned fits in
the byte array. This behavior can be configured with setReuseBuffer(boolean)
or setUserBuffer(int, boolean)
. If an entry is configured
to not reuse the byte array, a new array is allocated each time the
entry is used as an output parameter, so
the application can safely keep a reference to the byte array returned
by getData()
without danger that the array will be overwritten in
a subsequent call.
By default the Offset property is zero and the Size property is the length of the byte array. However, to allow for optimizations involving the partial use of a byte array, the Offset and Size may be set to non-default values.
For DatabaseEntry output parameters, the Size will always be set to the length of the returned data and the Offset will always be set to zero.
However, for DatabaseEntry input parameters the Offset and Size are set to non-default values by the built-in tuple and serial bindings. For example, with a tuple or serial binding the byte array is grown dynamically as data is output, and the Size is set to the number of bytes actually used. For a serial binding, the Offset is set to a non-zero value in order to implement an optimization having to do with the serialization stream header.
Therefore, for output DatabaseEntry parameters the application can assume that the Offset is zero and the Size is the length of the byte array. However, for input DatabaseEntry parameters the application should not make this assumption. In general, it is safest for the application to always honor the Size and Offset properties, rather than assuming they have default values.
By default the specified data (byte array, offset and size) corresponds to
the full stored key or data item. Optionally, the Partial property can be
set to true, and the PartialOffset and PartialLength properties are used to
specify the portion of the key or data item to be read or written. For
details, see the setPartial(int,int,boolean)
method.
Note that the Partial properties are set only by the caller. They will never be set by a Database or Cursor method, nor will they every be set by bindings. Therefore, the application can assume that the Partial properties are not set, unless the application itself sets them explicitly.
Constructor Summary | |
DatabaseEntry()
Construct a DatabaseEntry with null data. |
|
DatabaseEntry(byte[] data)
Construct a DatabaseEntry with a given byte array. |
|
DatabaseEntry(byte[] data,
int offset,
int size)
Constructs a DatabaseEntry with a given byte array, offset and size. |
Method Summary | |
byte[] |
getData()
Return the byte array. |
int |
getOffset()
Return the byte offset into the data array. |
boolean |
getPartial()
Return whether this DatabaseEntry is configured to read or write partial records. |
int |
getPartialLength()
Return the byte length of the partial record being read or written by the application, in bytes. |
int |
getPartialOffset()
Return the offset of the partial record being read or written by the application, in bytes. |
int |
getRecordNumber()
Return the record number encoded in this entry's buffer. |
boolean |
getReuseBuffer()
Return true if the whether the entry is configured to reuse the buffer. |
int |
getSize()
Return the byte size of the data array. |
boolean |
getUserBuffer()
Return true if the whether the buffer in this entry is owned by the application. |
int |
getUserBufferLength()
Return the length of the application's buffer. |
void |
setData(byte[] data)
Sets the byte array. |
void |
setData(byte[] data,
int offset,
int size)
Sets the byte array, offset and size. |
void |
setOffset(int offset)
Set the byte offset into the data array. |
void |
setPartial(boolean partial)
Configure this DatabaseEntry to read or write partial records. |
void |
setPartial(int doff,
int dlen,
boolean partial)
Configures this DatabaseEntry to read or write partial records. |
void |
setPartialLength(int dlen)
Set the byte length of the partial record being read or written by the application, in bytes. |
void |
setPartialOffset(int doff)
Set the offset of the partial record being read or written by the application, in bytes. |
void |
setRecordNumber(int recno)
Initialize the entry from a logical record number. |
void |
setReuseBuffer(boolean reuse)
Configures the entry to try to reuse the buffer before allocating a new one. |
void |
setSize(int size)
Set the byte size of the data array. |
void |
setUserBuffer(int length,
boolean usermem)
Configures the entry with an application-owned buffer. |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
public DatabaseEntry()
public DatabaseEntry(byte[] data)
data
- Byte array wrapped by the DatabaseEntry.public DatabaseEntry(byte[] data, int offset, int size)
data
- Byte array wrapped by the DatabaseEntry.offset
- Offset in the first byte in the byte array to be included.size
- Number of bytes in the byte array to be included.Method Detail |
public byte[] getData()
For a DatabaseEntry that is used as an output parameter, the byte array will always be a newly allocated array. The byte array specified by the caller will not be used and may be null.
public void setData(byte[] data)
data
- Byte array wrapped by the DatabaseEntry.public void setData(byte[] data, int offset, int size)
data
- Byte array wrapped by the DatabaseEntry.offset
- Offset in the first byte in the byte array to be included.size
- Number of bytes in the byte array to be included.public void setPartial(int doff, int dlen, boolean partial)
Do partial retrieval or storage of an item. If the calling application is doing a retrieval, length bytes specified by dlen, starting at the offset set by doff bytes from the beginning of the retrieved data record are returned as if they comprised the entire record. If any or all of the specified bytes do not exist in the record, the get is successful, and any existing bytes are returned.
For example, if the data portion of a retrieved record was 100 bytes, and a partial retrieval was done using a DatabaseEntry having a partial length of 20 and a partial offset of 85, the retrieval would succeed and the retrieved data would be the last 15 bytes of the record.
If the calling application is storing an item, length bytes specified by dlen, starting at the offset set by doff bytes from the beginning of the specified key's data item are replaced by the data specified by the DatabaseEntry. If the partial length is smaller than the data, the record will grow; if the partial length is larger than the data, the record will shrink. If the specified bytes do not exist, the record will be extended using nul bytes as necessary, and the store will succeed.
It is an error to specify a partial key when performing a put operation of any kind.
It is an error to attempt a partial store using the Database.put
method in a database that supports duplicate records. Partial
stores in databases supporting duplicate records must be done using a
cursor method.
Note that the Partial properties are set only by the caller. They will never be set by a Database or Cursor method.
doff
- The offset of the partial record being read or written by the
application, in bytes.
dlen
- The byte length of the partial record being read or written by the
application, in bytes.
partial
- Whether this DatabaseEntry is configured to read or write partial
records.public int getPartialLength()
Note that the Partial properties are set only by the caller. They will never be set by a Database or Cursor method.
setPartial(int,int,boolean)
public void setPartialLength(int dlen)
Note that the Partial properties are set only by the caller. They will never be set by a Database or Cursor method.
dlen
- The byte length of the partial record being read or written by the
application, in bytes.
public int getPartialOffset()
Note that the Partial properties are set only by the caller. They will never be set by a Database or Cursor method.
setPartial(int,int,boolean)
public void setPartialOffset(int doff)
Note that the Partial properties are set only by the caller. They will never be set by a Database or Cursor method.
doff
- The offset of the partial record being read or written by the
application, in bytes.
setPartial(int,int,boolean)
public boolean getPartial()
Note that the Partial properties are set only by the caller. They will never be set by a Database or Cursor method.
setPartial(int,int,boolean)
public void setPartial(boolean partial)
Note that the Partial properties are set only by the caller. They will never be set by a Database or Cursor method.
partial
- Whether this DatabaseEntry is configured to read or write partial
records.
setPartial(int,int,boolean)
public int getOffset()
For a DatabaseEntry that is used as an output parameter, the offset will always be zero.
public void setOffset(int offset)
offset
- Offset in the first byte in the byte array to be included.public int getSize()
For a DatabaseEntry that is used as an output parameter, the size will always be the length of the data array.
public void setSize(int size)
size
- Number of bytes in the byte array to be included.public int getRecordNumber()
This method may be called at any time during the life of the application.
public void setRecordNumber(int recno)
recno
- the record number to be encodedpublic void setReuseBuffer(boolean reuse)
reuse
- whether to reuse the bufferpublic boolean getReuseBuffer()
This method may be called at any time during the life of the application.
public void setUserBuffer(int length, boolean usermem)
The data
field of the entry must refer to a buffer that is
at least length
bytes in length.
If the length of the requested item is less than or equal to that number
of bytes, the item is copied into the memory to which the
data
field refers. Otherwise, the size
field
is set to the length needed for the requested item, and a
MemoryException
is thrown.
Applications can determine the length of a record by setting
length
to 0 and calling DatabaseEntry.getSize
on the return value.
length
- the length of the buffer
usermem
- whether the buffer is owned by the applicationpublic boolean getUserBuffer()
This method may be called at any time during the life of the application.
public int getUserBufferLength()
This method may be called at any time during the life of the application.
|
Berkeley DB version 4.4.20 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |