com.sleepycat.bind.tuple

Class TupleInput

public class TupleInput extends FastInputStream

An InputStream with DataInput-like methods for reading tuple fields. It is used by TupleBinding.

This class has many methods that have the same signatures as methods in the java.io.DataInput interface. The reason this class does not implement java.io.DataInput is because it would break the interface contract for those methods because of data format differences.

Signed numbers are stored in the buffer in MSB (most significant byte first) order with their sign bit (high-order bit) inverted to cause negative numbers to be sorted first when comparing values as unsigned byte arrays, as done in a database. Unsigned numbers, including characters, are stored in MSB order with no change to their sign bit.

Strings and character arrays are stored either as a fixed length array of unicode characters, where the length must be known by the application, or as a null-terminated UTF byte array.

Floats and doubles are stored using two different representations: sorted representation and integer-bit (IEEE 754) representation. If you use negative floating point numbers in a key, you should use sorted representation; alternatively you may use integer-bit representation but you will need to implement and configure a custom comparator to get correct numeric ordering for negative numbers.

To use sorted representation use this set of methods:

To use integer-bit representation use this set of methods:

Constructor Summary
TupleInput(byte[] buffer)
Creates a tuple input object for reading a byte array of tuple data.
TupleInput(byte[] buffer, int offset, int length)
Creates a tuple input object for reading a byte array of tuple data at a given offset for a given length.
TupleInput(TupleOutput output)
Creates a tuple input object from the data contained in a tuple output object.
Method Summary
intgetPackedIntByteLength()
Returns the byte length of a packed integer.
intgetStringByteLength()
Returns the byte length of a null-terminated UTF string in the data buffer, including the terminator.
booleanreadBoolean()
Reads a boolean (one byte) unsigned value from the buffer and returns true if it is non-zero and false if it is zero.
bytereadByte()
Reads a signed byte (one byte) value from the buffer.
StringreadBytes(int length)
Reads the specified number of bytes from the buffer, converting each unsigned byte value to a character of the resulting string.
voidreadBytes(char[] chars)
Reads the specified number of bytes from the buffer, converting each unsigned byte value to a character of the resulting array.
charreadChar()
Reads a char (two byte) unsigned value from the buffer.
StringreadChars(int length)
Reads the specified number of characters from the buffer, converting each two byte unsigned value to a character of the resulting string.
voidreadChars(char[] chars)
Reads the specified number of characters from the buffer, converting each two byte unsigned value to a character of the resulting array.
doublereadDouble()
Reads a signed double (eight byte) value from the buffer.
floatreadFloat()
Reads a signed float (four byte) value from the buffer.
intreadInt()
Reads a signed int (four byte) value from the buffer.
longreadLong()
Reads a signed long (eight byte) value from the buffer.
intreadPackedInt()
Reads a packed integer.
shortreadShort()
Reads a signed short (two byte) value from the buffer.
doublereadSortedDouble()
Reads a signed double (eight byte) value from the buffer, with support for correct default sorting of all values.
floatreadSortedFloat()
Reads a signed float (four byte) value from the buffer, with support for correct default sorting of all values.
StringreadString()
Reads a null-terminated UTF string from the data buffer and converts the data from UTF to Unicode.
StringreadString(int length)
Reads the specified number of UTF characters string from the data buffer and converts the data from UTF to Unicode.
voidreadString(char[] chars)
Reads the specified number of UTF characters string from the data buffer and converts the data from UTF to Unicode.
intreadUnsignedByte()
Reads an unsigned byte (one byte) value from the buffer.
longreadUnsignedInt()
Reads an unsigned int (four byte) value from the buffer.
intreadUnsignedShort()
Reads an unsigned short (two byte) value from the buffer.

Constructor Detail

TupleInput

public TupleInput(byte[] buffer)
Creates a tuple input object for reading a byte array of tuple data. A reference to the byte array will be kept by this object (it will not be copied) and therefore the byte array should not be modified while this object is in use.

Parameters: buffer is the byte array to be read and should contain data in tuple format.

TupleInput

public TupleInput(byte[] buffer, int offset, int length)
Creates a tuple input object for reading a byte array of tuple data at a given offset for a given length. A reference to the byte array will be kept by this object (it will not be copied) and therefore the byte array should not be modified while this object is in use.

Parameters: buffer is the byte array to be read and should contain data in tuple format. offset is the byte offset at which to begin reading. length is the number of bytes to be read.

TupleInput

public TupleInput(TupleOutput output)
Creates a tuple input object from the data contained in a tuple output object. A reference to the tuple output's byte array will be kept by this object (it will not be copied) and therefore the tuple output object should not be modified while this object is in use.

Parameters: output is the tuple output object containing the data to be read.

Method Detail

getPackedIntByteLength

public int getPackedIntByteLength()
Returns the byte length of a packed integer.

See Also: PackedInteger

getStringByteLength

public final int getStringByteLength()
Returns the byte length of a null-terminated UTF string in the data buffer, including the terminator. Used with string values that were written using writeString.

Throws: IndexOutOfBoundsException if no null terminating byte is found in the buffer. IllegalArgumentException malformed UTF data is encountered.

readBoolean

public final boolean readBoolean()
Reads a boolean (one byte) unsigned value from the buffer and returns true if it is non-zero and false if it is zero. Reads values that were written using TupleOutput.

Returns: the value read from the buffer.

Throws: IndexOutOfBoundsException if not enough bytes are available in the buffer.

readByte

public final byte readByte()
Reads a signed byte (one byte) value from the buffer. Reads values that were written using TupleOutput.

Returns: the value read from the buffer.

Throws: IndexOutOfBoundsException if not enough bytes are available in the buffer.

readBytes

public final String readBytes(int length)
Reads the specified number of bytes from the buffer, converting each unsigned byte value to a character of the resulting string. Reads values that were written using TupleOutput. Only characters with values below 0x100 may be read using this method.

Parameters: length is the number of bytes to be read.

Returns: the value read from the buffer.

Throws: IndexOutOfBoundsException if not enough bytes are available in the buffer.

readBytes

public final void readBytes(char[] chars)
Reads the specified number of bytes from the buffer, converting each unsigned byte value to a character of the resulting array. Reads values that were written using TupleOutput. Only characters with values below 0x100 may be read using this method.

Parameters: chars is the array to receive the data and whose length is used to determine the number of bytes to be read.

Throws: IndexOutOfBoundsException if not enough bytes are available in the buffer.

readChar

public final char readChar()
Reads a char (two byte) unsigned value from the buffer. Reads values that were written using TupleOutput.

Returns: the value read from the buffer.

Throws: IndexOutOfBoundsException if not enough bytes are available in the buffer.

readChars

public final String readChars(int length)
Reads the specified number of characters from the buffer, converting each two byte unsigned value to a character of the resulting string. Reads values that were written using TupleOutput.

Parameters: length is the number of characters to be read.

Returns: the value read from the buffer.

Throws: IndexOutOfBoundsException if not enough bytes are available in the buffer.

readChars

public final void readChars(char[] chars)
Reads the specified number of characters from the buffer, converting each two byte unsigned value to a character of the resulting array. Reads values that were written using TupleOutput.

Parameters: chars is the array to receive the data and whose length is used to determine the number of characters to be read.

Throws: IndexOutOfBoundsException if not enough bytes are available in the buffer.

readDouble

public final double readDouble()
Reads a signed double (eight byte) value from the buffer. Reads values that were written using TupleOutput. Double.longBitsToDouble is used to convert the signed long value.

Note: This method operations on byte array values that by default (without a custom comparator) do not sort correctly for negative values. Only non-negative values are sorted correctly by default. To sort all values correctly by default, use TupleInput.

Returns: the value read from the buffer.

Throws: IndexOutOfBoundsException if not enough bytes are available in the buffer.

readFloat

public final float readFloat()
Reads a signed float (four byte) value from the buffer. Reads values that were written using TupleOutput. Float.intBitsToFloat is used to convert the signed int value.

Note: This method operations on byte array values that by default (without a custom comparator) do not sort correctly for negative values. Only non-negative values are sorted correctly by default. To sort all values correctly by default, use TupleInput.

Returns: the value read from the buffer.

Throws: IndexOutOfBoundsException if not enough bytes are available in the buffer.

readInt

public final int readInt()
Reads a signed int (four byte) value from the buffer. Reads values that were written using TupleOutput.

Returns: the value read from the buffer.

Throws: IndexOutOfBoundsException if not enough bytes are available in the buffer.

readLong

public final long readLong()
Reads a signed long (eight byte) value from the buffer. Reads values that were written using TupleOutput.

Returns: the value read from the buffer.

Throws: IndexOutOfBoundsException if not enough bytes are available in the buffer.

readPackedInt

public int readPackedInt()
Reads a packed integer. Note that packed integers are not appropriate for sorted values (keys) unless a custom comparator is used.

See Also: PackedInteger

readShort

public final short readShort()
Reads a signed short (two byte) value from the buffer. Reads values that were written using TupleOutput.

Returns: the value read from the buffer.

Throws: IndexOutOfBoundsException if not enough bytes are available in the buffer.

readSortedDouble

public final double readSortedDouble()
Reads a signed double (eight byte) value from the buffer, with support for correct default sorting of all values. Reads values that were written using TupleOutput.

Float.longBitsToDouble and the following bit manipulations are used to convert the stored representation to a signed double value.

  int val = ... // get stored bits
        val ^= (val < 0) ? 0x8000000000000000L : 0xffffffffffffffffL;
        return Double.longBitsToDouble(val);
 

Returns: the value read from the buffer.

Throws: IndexOutOfBoundsException if not enough bytes are available in the buffer.

readSortedFloat

public final float readSortedFloat()
Reads a signed float (four byte) value from the buffer, with support for correct default sorting of all values. Reads values that were written using TupleOutput.

Float.intBitsToFloat and the following bit manipulations are used to convert the stored representation to a signed float value.

  int val = ... // get stored bits
  val ^= (val < 0) ? 0x80000000 : 0xffffffff;
  return Float.intBitsToFloat(val);
 

Returns: the value read from the buffer.

Throws: IndexOutOfBoundsException if not enough bytes are available in the buffer.

readString

public final String readString()
Reads a null-terminated UTF string from the data buffer and converts the data from UTF to Unicode. Reads values that were written using writeString.

Returns: the converted string.

Throws: IndexOutOfBoundsException if no null terminating byte is found in the buffer. IllegalArgumentException malformed UTF data is encountered.

readString

public final String readString(int length)
Reads the specified number of UTF characters string from the data buffer and converts the data from UTF to Unicode. Reads values that were written using (char[]).

Parameters: length is the number of characters to be read.

Returns: the converted string.

Throws: IndexOutOfBoundsException if no null terminating byte is found in the buffer. IllegalArgumentException malformed UTF data is encountered.

readString

public final void readString(char[] chars)
Reads the specified number of UTF characters string from the data buffer and converts the data from UTF to Unicode. Reads values that were written using (char[]).

Parameters: chars is the array to receive the data and whose length is used to determine the number of characters to be read.

Throws: IndexOutOfBoundsException if no null terminating byte is found in the buffer. IllegalArgumentException malformed UTF data is encountered.

readUnsignedByte

public final int readUnsignedByte()
Reads an unsigned byte (one byte) value from the buffer. Reads values that were written using TupleOutput.

Returns: the value read from the buffer.

Throws: IndexOutOfBoundsException if not enough bytes are available in the buffer.

readUnsignedInt

public final long readUnsignedInt()
Reads an unsigned int (four byte) value from the buffer. Reads values that were written using TupleOutput.

Returns: the value read from the buffer.

Throws: IndexOutOfBoundsException if not enough bytes are available in the buffer.

readUnsignedShort

public final int readUnsignedShort()
Reads an unsigned short (two byte) value from the buffer. Reads values that were written using TupleOutput.

Returns: the value read from the buffer.

Throws: IndexOutOfBoundsException if not enough bytes are available in the buffer.