com.sleepycat.bind.tuple
Class TupleInput

java.lang.Object
  |
  +--java.io.InputStream
        |
        +--com.sleepycat.util.FastInputStream
              |
              +--com.sleepycat.bind.tuple.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 DataInput interface. The reason this class does not implement 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.

• Null strings are UTF encoded as { 0xFF }, which is not allowed in a standard UTF encoding. This allows null strings, as distinct from empty or zero length strings, to be represented in a tuple. Using the default comparator, null strings will be ordered last.
• Zero (0x0000) character values are UTF encoded as non-zero values, and therefore embedded zeros in the string are supported. The sequence { 0xC0, 0x80 } is used to encode a zero character. This UTF encoding is the same one used by native Java UTF libraries. However, this encoding of zero does impact the lexicographical ordering, and zeros will not be sorted first (the natural order) or last. For all character values other than zero, the default UTF byte ordering is the same as the Unicode lexicographical character ordering.

Floats and doubles are stored in standard Java integer-bit representation (IEEE 754). Non-negative numbers are correctly ordered by numeric value. However, negative numbers are not correctly ordered; therefore, if you use negative floating point numbers in a key, you'll need to implement and configure a custom comparator to get correct numeric ordering.

Author:

Mark Hayes

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

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.
byte	readByte() Reads a signed byte (one byte) value from the buffer.
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.
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.
char	readChar() Reads a char (two byte) unsigned value from the buffer.
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.
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.
double	readDouble() Reads a signed double (eight byte) value from the buffer.
float	readFloat() Reads a signed float (four byte) value from the buffer.
int	readInt() Reads a signed int (four byte) value from the buffer.
long	readLong() Reads a signed long (eight byte) value from the buffer.
short	readShort() Reads a signed short (two byte) value from the buffer.
String	readString() Reads a null-terminated UTF string from the data buffer and converts the data from UTF to Unicode.
void	readString(char[] chars) Reads the specified number of UTF characters string from the data buffer and converts the data from UTF to Unicode.
String	readString(int length) Reads the specified number of UTF characters string from the data buffer and converts the data from UTF to Unicode.
int	readUnsignedByte() Reads an unsigned byte (one byte) value from the buffer.
long	readUnsignedInt() Reads an unsigned int (four byte) value from the buffer.
int	readUnsignedShort() Reads an unsigned short (two byte) value from the buffer.

Methods inherited from class com.sleepycat.util.FastInputStream

available, getBufferBytes, getBufferLength, getBufferOffset, mark, markSupported, read, read, read, readFast, readFast, readFast, reset, skip

Methods inherited from class java.io.InputStream

close

Methods inherited from class java.lang.Object

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

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

readString

public final String readString()
                        throws IndexOutOfBoundsException,
                               IllegalArgumentException

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

Returns:

the converted string.

Throws:

IndexOutOfBoundsException - if no null terminating byte is found in the buffer.

IllegalArgumentException - malformed UTF data is encountered.

readChar

public final char readChar()
                    throws IndexOutOfBoundsException

Reads a char (two byte) unsigned value from the buffer. Reads values that were written using TupleOutput.writeChar(int).

Returns:

the value read from the buffer.

Throws:

IndexOutOfBoundsException - if not enough bytes are available in the buffer.

readBoolean

public final boolean readBoolean()
                          throws IndexOutOfBoundsException

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.writeBoolean(boolean).

Returns:

the value read from the buffer.

Throws:

IndexOutOfBoundsException - if not enough bytes are available in the buffer.

readByte

public final byte readByte()
                    throws IndexOutOfBoundsException

Reads a signed byte (one byte) value from the buffer. Reads values that were written using TupleOutput.writeByte(int).

Returns:

the value read from the buffer.

Throws:

IndexOutOfBoundsException - if not enough bytes are available in the buffer.

readShort

public final short readShort()
                      throws IndexOutOfBoundsException

Reads a signed short (two byte) value from the buffer. Reads values that were written using TupleOutput.writeShort(int).

Returns:

the value read from the buffer.

Throws:

IndexOutOfBoundsException - if not enough bytes are available in the buffer.

readInt

public final int readInt()
                  throws IndexOutOfBoundsException

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

Returns:

the value read from the buffer.

Throws:

IndexOutOfBoundsException - if not enough bytes are available in the buffer.

readLong

public final long readLong()
                    throws IndexOutOfBoundsException

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

Returns:

the value read from the buffer.

Throws:

IndexOutOfBoundsException - if not enough bytes are available in the buffer.

readFloat

public final float readFloat()
                      throws IndexOutOfBoundsException

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

Returns:

the value read from the buffer.

Throws:

IndexOutOfBoundsException - if not enough bytes are available in the buffer.

readDouble

public final double readDouble()
                        throws IndexOutOfBoundsException

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

Returns:

the value read from the buffer.

Throws:

IndexOutOfBoundsException - if not enough bytes are available in the buffer.

readUnsignedByte

public final int readUnsignedByte()
                           throws IndexOutOfBoundsException

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

Returns:

the value read from the buffer.

Throws:

IndexOutOfBoundsException - if not enough bytes are available in the buffer.

readUnsignedShort

public final int readUnsignedShort()
                            throws IndexOutOfBoundsException

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

Returns:

the value read from the buffer.

Throws:

IndexOutOfBoundsException - if not enough bytes are available in the buffer.

readUnsignedInt

public final long readUnsignedInt()
                           throws IndexOutOfBoundsException

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

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)
                       throws IndexOutOfBoundsException

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.writeBytes(java.lang.String). 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.

readChars

public final String readChars(int length)
                       throws IndexOutOfBoundsException

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.writeChars(java.lang.String).

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.

readBytes

public final void readBytes(char[] chars)
                     throws IndexOutOfBoundsException

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.writeBytes(java.lang.String). 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.

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)
                     throws IndexOutOfBoundsException

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.writeChars(java.lang.String).

Parameters:

chars - is the array to receive the data and whose length is used to determine 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.

readString

public final String readString(int length)
                        throws IndexOutOfBoundsException,
                               IllegalArgumentException

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 TupleOutput.writeString(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)
                      throws IndexOutOfBoundsException,
                             IllegalArgumentException

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 TupleOutput.writeString(char[]).

Parameters:

chars - is the array to receive the data and whose length is used to determine 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.