com.sleepycat.client

Class SDatabaseEntry

java.lang.Object

com.sleepycat.client.SDatabaseEntry

All Implemented Interfaces:

SDatabaseEntryBase

public class SDatabaseEntry
extends java.lang.Object
implements SDatabaseEntryBase

Encodes database key and data items as a byte array.

Storage and retrieval for the SDatabase and SCursor methods are based on key/data pairs. Both key and data items are represented by SDatabaseEntry objects. Key and data byte arrays may refer to arrays of zero length up to arrays of essentially unlimited length. A key item may also refer to a record number, which is a 32-bit integer. In this case, the record number must be accessed through setRecordNumber(int, java.nio.ByteOrder) and getRecordNumber(java.nio.ByteOrder) instead of setData and getData.

The SDatabaseEntry class provides simple access to an underlying object whose elements can be examined or changed. SDatabaseEntry objects can be subclassed, providing a way to associate with it additional data or references to other structures.

Access to SDatabaseEntry objects is not re-entrant. In particular, if multiple threads simultaneously access the same SDatabaseEntry object using SDatabase or SCursor methods, the results are undefined.

Input and Output Parameters

SDatabaseEntry 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 SDatabase.get(com.sleepycat.client.STransaction, com.sleepycat.client.SDatabaseEntry, com.sleepycat.client.SDatabaseEntryBase, com.sleepycat.client.SLockMode) 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 SDatabaseEntry input parameters, the caller is responsible for initializing the data array of the SDatabaseEntry. For SDatabaseEntry output parameters, the method called will initialize the data array.

Partial Offset and Length Properties

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 SDatabase or SCursor method. Therefore, the application can assume that the Partial properties are not set, unless the application itself sets them explicitly.

Constructor Summary

Constructors

Constructor and Description
SDatabaseEntry() Construct a SDatabaseEntry with null data.
SDatabaseEntry(byte[] data) Construct a SDatabaseEntry with a given byte array.
SDatabaseEntry(byte[] data, int offset, int size) Construct a DatabaseEntry with a given byte array, offset and size.

Method Summary

Modifier and Type	Method and Description
boolean	equals(java.lang.Object obj)
byte[]	getData() Return the byte array.
boolean	getExternalFile() Return whether this SDatabaseEntry is configured to be stored as an external file.
protected java.lang.Object	getField(F field) Return the value set on a specified field.
int	getOffset() Always return zero.
boolean	getPartial() Return whether this SDatabaseEntry 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(java.nio.ByteOrder byteOrder) Return the record number encoded in this entry's buffer.
int	getSize() Return the byte size of the data array.
protected T	getThriftObj()
int	hashCode()
SDatabaseEntry	setData(byte[] data) Sets the data byte array.
SDatabaseEntry	setData(byte[] data, int offset, int size) Sets the data byte array.
SDatabaseEntry	setExternalFile(boolean externalFile) Configure this SDatabaseEntry to be stored as an external file.
SDatabaseEntry	setPartial(int doff, int dlen, boolean partial) Configure this SDatabaseEntry to read or write partial records.
SDatabaseEntry	setRecordNumber(int recno, java.nio.ByteOrder byteOrder) Initialize the entry from a logical record number.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SDatabaseEntry

public SDatabaseEntry()

Construct a SDatabaseEntry with null data.

SDatabaseEntry

public SDatabaseEntry(byte[] data)

Construct a SDatabaseEntry with a given byte array.

Parameters:

data - byte array wrapped by the SDatabaseEntry

SDatabaseEntry

public SDatabaseEntry(byte[] data,
                      int offset,
                      int size)

Construct a DatabaseEntry with a given byte array, offset and size.

Parameters:

data - byte array wrapped by the SDatabaseEntry.

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

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

getExternalFile

public boolean getExternalFile()

Return whether this SDatabaseEntry is configured to be stored as an external file.

Returns:

whether this SDatabaseEntry is configured to be stored as an external file

setExternalFile

public SDatabaseEntry setExternalFile(boolean externalFile)

Configure this SDatabaseEntry to be stored as an external file.

Parameters:

externalFile - whether this SDatabaseEntry is configured to be stored as an external file

Returns:

this

getData

public byte[] getData()

Return the byte array.

For a SDatabaseEntry 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.

Returns:

the byte array

setData

public SDatabaseEntry setData(byte[] data)

Sets the data byte array. The array is copied into this entry.

Parameters:

data - byte array

Returns:

this

setData

public SDatabaseEntry setData(byte[] data,
                              int offset,
                              int size)

Sets the data byte array. The specified range of the specified array is copied into this entry.

Parameters:

data - byte array

offset - the start of the range to be copied

size - the length of the range to be copied

Returns:

this

getPartialLength

public int getPartialLength()

Return the byte length of the partial record being read or written by the application, in bytes.

Note that the Partial properties are set only by the caller. They will never be set by a SDatabase or SCursor method.

Returns:

the byte length of the partial record being read or written by the application, in bytes

See Also:

setPartial(int, int, boolean)

getPartialOffset

public int getPartialOffset()

Return the offset of the partial record being read or written by the application, in bytes.

Note that the Partial properties are set only by the caller. They will never be set by a SDatabase or SCursor method.

Returns:

the offset of the partial record being read or written by the application, in bytes

See Also:

setPartial(int, int, boolean)

getPartial

public boolean getPartial()

Return whether this SDatabaseEntry is configured to read or write partial records.

Note that the Partial properties are set only by the caller. They will never be set by a SDatabase or SCursor method.

Returns:

whether this SDatabaseEntry is configured to read or write partial records.

See Also:

setPartial(int, int, boolean)

setPartial

public SDatabaseEntry setPartial(int doff,
                                 int dlen,
                                 boolean partial)

Configure this SDatabaseEntry to read or write partial records.

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 SDatabaseEntry 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 SDatabaseEntry. 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 SDatabase.put(com.sleepycat.client.STransaction, com.sleepycat.client.SDatabaseEntry, com.sleepycat.client.SDatabaseEntry) 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 SDatabase or SCursor method.

Parameters:

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 SDatabaseEntry is configured to read or write partial records

Returns:

this

getRecordNumber

public int getRecordNumber(java.nio.ByteOrder byteOrder)

Return the record number encoded in this entry's buffer.

Parameters:

byteOrder - the byte order used to decode the record number. If this entry is retrieved from or will be sent to a server, this must be the server's byte order. See BdbServerConnection.getServerByteOrder().

Returns:

the record number encoded in this entry's buffer

setRecordNumber

public SDatabaseEntry setRecordNumber(int recno,
                                      java.nio.ByteOrder byteOrder)

Initialize the entry from a logical record number. Record numbers are integer keys starting at 1.

Parameters:

recno - the record number to be encoded

byteOrder - the byte order used to decode the record number. If this entry is retrieved from or will be sent to a server, this must be the server's byte order. See BdbServerConnection.getServerByteOrder().

Returns:

this

getOffset

public int getOffset()

Always return zero. For compatibility with DPL APIs.

Returns:

always zero

getSize

public int getSize()

Return the byte size of the data array.

It is an error to call this method if this entry contains a record number.

Returns:

number of bytes in the data array

getThriftObj

protected T getThriftObj()

getField

protected java.lang.Object getField(F field)
                             throws java.lang.IllegalStateException

Return the value set on a specified field. Throw IllegalStateException if the field is not set.

Parameters:

field - the field

Returns:

the field's value

Throws:

java.lang.IllegalStateException - if the field is not set