Dbt (Sleepycat Software, Inc. - Berkeley DB Java API)
Keywords: com.sleepycat.db.Dbt,Dbt class

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DB version 4.2.52
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DB version 4.2.52
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 1996-2003 Sleepycat Software, Inc. - All rights reserved.