com.sleepycat.je

Class DatabaseEntry

java.lang.Object

com.sleepycat.je.DatabaseEntry

All Implemented Interfaces:

java.io.Serializable

public class DatabaseEntry
extends java.lang.Object
implements java.io.Serializable

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.

Input and Output Parameters

DatabaseEntry objects are used for both input values (for example, when writing to a database or specifying a search parameter) and output values (for example, when reading from a database). For every CRUD method (get, put, etc), each of the method's DatabaseEntry parameters (key, data, etc) may be input or output parameters, and this is specified by the method's documentation.

Input Parameters

An input parameter is required by the JE method. The parameter may not be null, and the caller is also responsible for initializing the data of the DatabaseEntry to a non-null byte array.

Input parameters normally may not be partial. However, this is allowed under certain circumstances, namely the Cursor.putCurrent(com.sleepycat.je.DatabaseEntry) method allows specifying a partial data parameter in order to update only part of the record's data value. Input parameters are NOT allowed to be partial unless this is explicitly stated in the method documentation.

Although an input parameter is always used for input, in some cases it may be also used for output. For example, the Cursor.getSearchKeyRange(com.sleepycat.je.DatabaseEntry, com.sleepycat.je.DatabaseEntry, com.sleepycat.je.LockMode) method is passed a key parameter that is used as input, but since a record with a different key (greater or equal to the key given) may be found, the key parameter is also used to return the key that was found. Such parameters are documented as "input/output" parameters.

Another example is when a custom key comparator is used and a key parameter is passed to a search method. The input parameter may match a record's key even if the bytes are not equal, and the key of the record found will be returned via the parameter. The same thing is true of data (or primary key) parameters when a custom duplicate comparator is used. Because of this, all input parameters of "get" methods can potentially be used for output, however, they are not explicitly documented to be input/output parameters.

Output Parameters

An output parameter is not required by the JE method. It is used to optionally return a value to the caller. Null may be passed for the parameter if no returned value is needed. Passing null is a common way to optimize read operations when only the record's key, and not the record's data, is required. By passing null for the data parameter, a read from disk can be avoided when the data is not already cached. In addition, all output parameters may be partial to allow only returning a part of the data byte array. See Using Null and Partial DatabaseEntry Parameters for more information.

For output parameters, the byte array specified by the caller will not be used and may be null. The JE method will will always allocate a new byte array. Therefore, after calling a method that returns output parameters, 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.

Historical note: Prior to JE 7.0, null could not be passed for output parameters. Instead, DatabaseEntry.setPartial(0, 0, true) was called for a data parameter to avoid reading the record's data. Now, null can be passed instead.

Offset and Size Properties

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 output parameters, the Size will always be set to the length of the byte array and the Offset will always be set to zero.

However, for 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.

WARNING: In callbacks that are passed DatabaseEntry parameters, the application should always honor the Size and Offset properties, rather than assuming they have default values.

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
DatabaseEntry() Constructs a DatabaseEntry with null data.
DatabaseEntry(byte[] data) Constructs 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

Modifier and Type	Method and Description
boolean	equals(java.lang.Object o) Compares the data of two entries for byte-by-byte equality.
byte[]	getData() Returns the byte array.
int	getOffset() Returns the byte offset into the data array.
boolean	getPartial() Returns whether this DatabaseEntry is configured to read or write partial records.
int	getPartialLength() Returns the byte length of the partial record being read or written by the application, in bytes.
int	getPartialOffset() Returns the offset of the partial record being read or written by the application, in bytes.
int	getSize() Returns the byte size of the data array.
int	hashCode() Returns a hash code based on the data value.
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) Sets the byte offset into the data array.
void	setPartial(boolean partial) Configures 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) Sets the byte length of the partial record being read or written by the application, in bytes.
void	setPartialOffset(int doff) Sets the offset of the partial record being read or written by the application, in bytes.
void	setSize(int size) Sets the byte size of the data array.
java.lang.String	toString() Returns all the attributes of the database entry in text form, including the underlying data.

Methods inherited from class java.lang.Object

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

Constructor Detail

DatabaseEntry

public DatabaseEntry()

Constructs a DatabaseEntry with null data. The offset and size are set to zero.

DatabaseEntry

public DatabaseEntry(byte[] data)

Constructs a DatabaseEntry with a given byte array. The offset is set to zero; the size is set to the length of the array, or to zero if null is passed.

Parameters:

data - Byte array wrapped by the DatabaseEntry.

DatabaseEntry

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

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

Parameters:

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

toString

public java.lang.String toString()

Returns all the attributes of the database entry in text form, including the underlying data. The maximum number of bytes that will be formatted is taken from the static variable DatabaseEntry.MAX_DUMP_BYTES, which defaults to 100. MAX_DUMP_BYTES may be changed by an application if it wishes to cause more bytes to be formatted.

Overrides:

toString in class java.lang.Object

getData

public byte[] getData()

Returns the byte array.

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.

Returns:

The byte array.

setData

public void setData(byte[] data)

Sets the byte array. The offset is set to zero; the size is set to the length of the array, or to zero if null is passed.

Parameters:

data - Byte array wrapped by the DatabaseEntry.

setData

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

Sets the byte array, offset and size.

Parameters:

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.

setPartial

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

Configures this DatabaseEntry to read or write partial records.

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.

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.

All {partial. However, this is allowed under certain circumstances, namely the Cursor.putCurrent(com.sleepycat.je.DatabaseEntry) method allows specifying a partial data parameter in order to update only part of the record's data value. Input parameters are NOT allowed to be partial unless this is explicitly stated in the method documentation.

For storing an item using a partial parameter, 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 partial offset is greater than the length of the data, the record will be extended using zero bytes as necessary, and the store will succeed.

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

getPartialLength

public int getPartialLength()

Returns 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 Database or Cursor method.

Returns:

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

See Also:

setPartial(int,int,boolean)

setPartialLength

public void setPartialLength(int dlen)

Sets 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 Database or Cursor method.

Parameters:

dlen - The byte length of the partial record being read or written by the

See Also:

setPartial(int,int,boolean)

getPartialOffset

public int getPartialOffset()

Returns 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 Database or Cursor method.

Returns:

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

See Also:

setPartial(int,int,boolean)

setPartialOffset

public void setPartialOffset(int doff)

Sets 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 Database or Cursor method.

Parameters:

doff - 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()

Returns whether this DatabaseEntry 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 Database or Cursor method.

Returns:

Whether this DatabaseEntry is configured to read or write partial records.

See Also:

setPartial(int,int,boolean)

setPartial

public void setPartial(boolean partial)

Configures this DatabaseEntry to read or write partial records.

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

Parameters:

partial - Whether this DatabaseEntry is configured to read or write partial records.

See Also:

setPartial(int,int,boolean)

getOffset

public int getOffset()

Returns the byte offset into the data array.

For a DatabaseEntry that is used as an output parameter, the offset will always be zero.

Returns:

Offset in the first byte in the byte array to be included.

setOffset

public void setOffset(int offset)

Sets the byte offset into the data array. ArrayIndexOutOfBoundsException if the data, offset, and size parameters refer to elements of the data array which do not exist. Note that this exception will not be thrown by setSize() or setOffset(), but will be thrown by varous JE methods if "this" is inconsistent and is used as an input parameter to those methods. It is the caller's responsibility to ensure that size, offset, and data.length are consistent.

Parameters:

offset - Offset in the first byte in the byte array to be included.

getSize

public int getSize()

Returns the byte size of the data array.

For a DatabaseEntry that is used as an output parameter, the size will always be the length of the data array.

Returns:

Number of bytes in the byte array to be included.

setSize

public void setSize(int size)

Sets the byte size of the data array. ArrayIndexOutOfBoundsException if the data, offset, and size parameters refer to elements of the data array which do not exist. Note that this exception will not be thrown by setSize() or setOffset(), but will be thrown by varous JE methods if "this" is inconsistent and is used as an input parameter to those methods. It is the caller's responsibility to ensure that size, offset, and data.length are consistent.

Parameters:

size - Number of bytes in the byte array to be included.

equals

public boolean equals(java.lang.Object o)

Compares the data of two entries for byte-by-byte equality.

In either entry, if the offset is non-zero or the size is not equal to the data array length, then only the data bounded by these values is compared. The data array length and offset need not be the same in both entries for them to be considered equal.

If the data array is null in one entry, then to be considered equal both entries must have a null data array.

If the partial property is set in either entry, then to be considered equal both entries must have the same partial properties: partial, partialOffset and partialLength.

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Returns a hash code based on the data value.

Overrides:

hashCode in class java.lang.Object