com.sleepycat.db
Class Dbt

java.lang.Object
  |
  +--com.sleepycat.db.Dbt

Direct Known Subclasses:

DataThang

public class Dbt

extends Object

This information describes the specific details of the Dbt class, used to encode keys and data items in a database.

Key/Data Pairs

Storage and retrieval for the Db access methods are based on key/data pairs. Both key and data items are represented by Dbt objects. Key and data byte strings may refer to strings of zero length up to strings of essentially unlimited length. See Database limits for more information.

The Dbt class provides simple access to an underlying data structure, whose elements can be examined or changed using the usual set or get methods. Dbt can be subclassed, providing a way to associate with it additional data or references to other structures.

The constructors set all elements of the underlying structure to zero. The constructor with one parameter has the effect of setting all elements to zero except for the data and size elements. The constructor with three parameters has the effect of setting all elements to zero except for the data, size and offset elements.

In the case where the flags structure element is set to 0, when being provided a key or data item by the application, the Berkeley DB package expects the data object to be set to a byte array of size bytes. When returning a key/data item to the application, the Berkeley DB package will store into the data object a byte array of size bytes. During a get operation, if none of the Db.DB_DBT_MALLOC, Db.DB_DBT_REALLOC or Db.DB_DBT_USERMEM flags are specified, the operation occurs as if Db.DB_DBT_MALLOC was used.

Access to Dbt objects is not re-entrant. In particular, if multiple threads simultaneously access the same Dbt object using Db API calls, the results are undefined, and may result in a crash. One easy way to avoid problems is to use Dbt objects that are created as local variables and not shared among threads.

Constructor Summary

Dbt()
Construct an empty Dbt.

Dbt(byte[] data)
Construct a Dbt where the data is the contents of the array and the Dbt's length is set to the length of the array.

Dbt(byte[] data, int off, int len)
Construct a Dbt from len bytes from the array, starting at off.

Dbt(Object serialobj)
Construct a Dbt where the data is the serialized form of the Object.

Method Summary

byte[]	get_data() Deprecated. As of Berkeley DB 4.2, replaced by getData()
int	get_dlen() Deprecated. As of Berkeley DB 4.2, replaced by getPartialLength()
int	get_doff() Deprecated. As of Berkeley DB 4.2, replaced by getPartialOffset()
int	get_flags() Deprecated. As of Berkeley DB 4.2, replaced by getFlags()
Object	get_object() Deprecated. As of Berkeley DB 4.2, replaced by getObject()
int	get_offset() Deprecated. As of Berkeley DB 4.2, replaced by getOffset()
int	get_recno_key_data() Deprecated. As of Berkeley DB 4.2, replaced by getRecordNumber()
int	get_size() Deprecated. As of Berkeley DB 4.2, replaced by getSize()
int	get_ulen() Deprecated. As of Berkeley DB 4.2, replaced by getUserBufferLength()
byte[]	getData() Return the data array.
int	getFlags() Return the object flag value.
Object	getObject() Return an object from the data array, encoding the object using the Java serialization API.
int	getOffset() Return the byte offset into the data array.
int	getPartialLength() Return the length of the partial record, in bytes.
int	getPartialOffset() Return the offset of the partial record, in bytes.
int	getRecordNumber() Return an object from the data array, expecting that data to be a logical record number.
int	getSize() Return the data array size.
int	getUserBufferLength() Return the length in bytes of the user-specified buffer.
void	set_data(byte[] data) Deprecated. As of Berkeley DB 4.2, replaced by setData(byte[])
void	set_dlen(int dlen) Deprecated. As of Berkeley DB 4.2, replaced by setPartialLength(int)
void	set_doff(int doff) Deprecated. As of Berkeley DB 4.2, replaced by setPartialOffset(int)
void	set_flags(int flags) Deprecated. As of Berkeley DB 4.2, replaced by setFlags(int)
void	set_object(Object serialobj) Deprecated. As of Berkeley DB 4.2, replaced by setObject(Object)
void	set_offset(int offset) Deprecated. As of Berkeley DB 4.2, replaced by setOffset(int)
void	set_recno_key_data(int recno) Deprecated. As of Berkeley DB 4.2, replaced by setRecordNumber(int)
void	set_size(int size) Deprecated. As of Berkeley DB 4.2, replaced by setSize(int)
void	set_ulen(int ulen) Deprecated. As of Berkeley DB 4.2, replaced by setUserBufferLength(int)
void	setData(byte[] data) Set the data array.
void	setFlags(int flags) Set the object flag value.
void	setObject(Object serialobj) Initialize the data array from a serialized object, encoding the object using the Java serialization API.
void	setOffset(int offset) Set the byte offset into the data array.
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 data array from a logical record number.
void	setSize(int size) Set the byte size of the data array.
void	setUserBufferLength(int ulen) Set the byte size of the user-specified buffer.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Dbt

public Dbt()

Construct an empty Dbt.

Dbt

public Dbt(byte[] data)

Construct a Dbt where the data is the contents of the array and the Dbt's length is set to the length of the array.

Parameters:

data - the array to which the Dbt's data is set.

Dbt

public Dbt(byte[] data,
           int off,
           int len)

Construct a Dbt from len bytes from the array, starting at off.

Parameters:

data - the array from which the Dbt's data is set.

len - the length of the data in bytes.

off - starting byte offset of the data in the array.

Dbt

public Dbt(Object serialobj)
    throws IOException

Construct a Dbt where the data is the serialized form of the Object. The instanced passed must therefore implement the Serializable interface. The Dbt's length will be set to the length of the byte array required to store this serialized form.

Parameters:

serialobj - the serialized form to which the Dbt's data is set.

Throws:

IOException - If there is an error while serializing the object.

Method Detail

setData

public void setData(byte[] data)

Set the data array. Note that the array data is not copied immediately, but only when the Dbt is used.

Parameters:

data - an array of bytes to be used to set the content for the Dbt.

setFlags

public void setFlags(int flags)

Set the object flag value.

The flags parameter must be set by bitwise inclusively OR'ing together one or more of the following values: If Db.DB_DBT_MALLOC or Db.DB_DBT_REALLOC is specified, Berkeley DB allocates a properly sized byte array to contain the data. This can be convenient if you know little about the nature of the data, specifically the size of data in the database. However, if your application makes repeated calls to retrieve keys or data, you may notice increased garbage collection due to this allocation. If you know the maximum size of data you are retrieving, you might decrease the memory burden and speed your application by allocating your own byte array and using Db.DB_DBT_USERMEM. Even if you don't know the maximum size, you can use this option and reallocate your array whenever your retrieval API call throws a DbMemoryException.

Parameters:

flags - Dbt flag value.

setObject

public void setObject(Object serialobj)
               throws IOException

Initialize the data array from a serialized object, encoding the object using the Java serialization API. This method uses ObjectOutputStream internally to manipulate an array of bytes representing an object (and any connected objects). All of the rules of Java Serialization apply. In particular, the object(s) must implement either the Serializable or Externalizable interface. The serialized encoding trades efficiency for convenience.

Parameters:

serialobj - the object to be serialized.

Throws:

IOException - If there is an error while de-serializing the object.

setOffset

public void setOffset(int offset)

Set the byte offset into the data array.

The number of bytes offset into the data array determine the portion of the array actually used. This element is accessed using Dbt.getOffset and Dbt.setOffset. Although Java normally maintains proper alignment of byte arrays, the set_offset method can be used to specify unaligned addresses. Unaligned address accesses that are not supported by the underlying hardware may be reported as an exception, or may stop the running Java program.

Parameters:

offset - the byte offset into the data array.

setPartialLength

public void setPartialLength(int dlen)

Set the byte length of the partial record being read or written by the application, in bytes. See the Db.DB_DBT_PARTIAL flag for more information.

Parameters:

dlen - the length of the partial record in bytes.

setPartialOffset

public void setPartialOffset(int doff)

Set the offset of the partial record being read or written by the application, in bytes. See the Db.DB_DBT_PARTIAL flag for more information.

Parameters:

doff - the offset of the partial record.

setRecordNumber

public void setRecordNumber(int recno)

Initialize the data array from a logical record number. Recno database records are ordered by integer keys starting at 1. When the Dbt.setRecordNumber method is called, the data, size and offset fields in the Dbt are implicitly set to hold a byte array representation of the integer key.

Parameters:

recno - The recno parameter logical record number used to initialize the data array.

setSize

public void setSize(int size)

Set the byte size of the data array.

Parameters:

size - the size of the data array in bytes.

setUserBufferLength

public void setUserBufferLength(int ulen)

Set the byte size of the user-specified buffer.

Note that applications can determine the length of a record by setting the ulen to 0 and checking the return value found in size. See the Db.DB_DBT_USERMEM flag for more information.

Parameters:

ulen - The ulen parameter the size of the data array in bytes.

set_data

public void set_data(byte[] data)

Deprecated. As of Berkeley DB 4.2, replaced by setData(byte[])

set_dlen

public void set_dlen(int dlen)

Deprecated. As of Berkeley DB 4.2, replaced by setPartialLength(int)

set_doff

public void set_doff(int doff)

Deprecated. As of Berkeley DB 4.2, replaced by setPartialOffset(int)

set_flags

public void set_flags(int flags)

Deprecated. As of Berkeley DB 4.2, replaced by setFlags(int)

set_object

public void set_object(Object serialobj)
                throws IOException

Deprecated. As of Berkeley DB 4.2, replaced by setObject(Object)

Throws:

IOException

set_offset

public void set_offset(int offset)

Deprecated. As of Berkeley DB 4.2, replaced by setOffset(int)

set_recno_key_data

public void set_recno_key_data(int recno)

Deprecated. As of Berkeley DB 4.2, replaced by setRecordNumber(int)

set_size

public void set_size(int size)

Deprecated. As of Berkeley DB 4.2, replaced by setSize(int)

set_ulen

public void set_ulen(int ulen)

Deprecated. As of Berkeley DB 4.2, replaced by setUserBufferLength(int)

getData

public byte[] getData()

Return the data array.

Returns:

the data array.

getFlags

public int getFlags()

Return the object flag value.

Returns:

the object flag value.

getObject

public Object getObject()
                 throws IOException,
                        ClassNotFoundException

Return an object from the data array, encoding the object using the Java serialization API. This method uses ObjectInputStream internally to manipulate an array of bytes representing an object (and any connected objects). All of the rules of Java Serialization apply. In particular, the object(s) must implement either the Serializable or Externalizable interface. The serialized encoding trades efficiency for convenience.

Returns:

an object from the data array, expecting that data to be a serialized object.

Throws:

IOException - If there is an error while de-serializing the object.

ClassNotFoundException - If the stream contains a class not found by the runtime while de-serializing.

getOffset

public int getOffset()

Return the byte offset into the data array.

Returns:

the byte offset into the data array.

getPartialLength

public int getPartialLength()

Return the length of the partial record, in bytes.

Returns:

the length of the partial record, in bytes.

getPartialOffset

public int getPartialOffset()

Return the offset of the partial record, in bytes.

Returns:

the offset of the partial record, in bytes.

getRecordNumber

public int getRecordNumber()

Return an object from the data array, expecting that data to be a logical record number.

Returns:

an object from the data array, expecting that data to be a logical record number.

getSize

public int getSize()

Return the data array size.

Returns:

the data array size.

getUserBufferLength

public int getUserBufferLength()

Return the length in bytes of the user-specified buffer.

Returns:

the length in bytes of the user-specified buffer.

get_data

public byte[] get_data()

Deprecated. As of Berkeley DB 4.2, replaced by getData()

Returns:

Description of the Return Value

get_dlen

public int get_dlen()

Deprecated. As of Berkeley DB 4.2, replaced by getPartialLength()

Returns:

Description of the Return Value

get_doff

public int get_doff()

Deprecated. As of Berkeley DB 4.2, replaced by getPartialOffset()

Returns:

Description of the Return Value

get_flags

public int get_flags()

Deprecated. As of Berkeley DB 4.2, replaced by getFlags()

Returns:

Description of the Return Value

get_object

public Object get_object()
                  throws IOException,
                         ClassNotFoundException

Deprecated. As of Berkeley DB 4.2, replaced by getObject()

Returns:

Description of the Return Value

Throws:

IOException

ClassNotFoundException

get_offset

public int get_offset()

Deprecated. As of Berkeley DB 4.2, replaced by getOffset()

Returns:

Description of the Return Value

get_recno_key_data

public int get_recno_key_data()

Deprecated. As of Berkeley DB 4.2, replaced by getRecordNumber()

Returns:

Description of the Return Value

get_size

public int get_size()

Deprecated. As of Berkeley DB 4.2, replaced by getSize()

Returns:

Description of the Return Value

get_ulen

public int get_ulen()

Deprecated. As of Berkeley DB 4.2, replaced by getUserBufferLength()

Returns:

Description of the Return Value