| com.sleepycat.util.FastOutputStream
 com.sleepycat.bind.tuple.TupleOutput
All known Subclasses: com.sleepycat.persist.impl.RecordOutput,
| TupleOutput | | public class TupleOutput extends FastOutputStream (Code) | | An OutputStream with DataOutput-like methods for
writing tuple fields. It is used by TupleBinding.
This class has many methods that have the same signatures as methods in
the
java.io.DataOutput interface. The reason this class does not
implement
java.io.DataOutput 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. BigInteger values are stored
with a preceding length having the same sign as the value.
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 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:
author:
Mark Hayes |
| Field Summary | |
| final static int | NULL_STRING_UTF_VALUE
We represent a null string as a single FF UTF character, which cannot
occur in a UTF encoded string. |
| Constructor Summary | |
| public | TupleOutput()
Creates a tuple output object for writing a byte array of tuple data. | | public | TupleOutput(byte[] buffer)
Creates a tuple output object for writing a byte array of tuple data,
using a given buffer. |
| Method Summary | |
| public static int | getBigIntegerByteLength(BigInteger val)
Returns the byte length of a given
BigInteger value. | | final public TupleOutput | writeBigInteger(BigInteger val)
Writes a
BigInteger . | | final public TupleOutput | writeBoolean(boolean val)
Writes a boolean (one byte) unsigned value to the buffer, writing one
if the value is true and zero if it is false.
Writes values that can be read using
TupleInput.readBoolean .
Parameters:
val - is the value to write to the buffer. | | final public TupleOutput | writeByte(int val)
Writes an signed byte (one byte) value to the buffer.
Writes values that can be read using
TupleInput.readByte .
Parameters:
val - is the value to write to the buffer. | | final public TupleOutput | writeBytes(String val)
Writes the specified bytes to the buffer, converting each character to
an unsigned byte value.
Writes values that can be read using
TupleInput.readBytes .
Only characters with values below 0x100 may be written using this
method, since the high-order 8 bits of all characters are discarded.
Parameters:
val - is the string containing the values to be written. | | final public TupleOutput | writeBytes(char[] chars)
Writes the specified bytes to the buffer, converting each character to
an unsigned byte value.
Writes values that can be read using
TupleInput.readBytes .
Only characters with values below 0x100 may be written using this
method, since the high-order 8 bits of all characters are discarded.
Parameters:
chars - is the array of values to be written. | | final public TupleOutput | writeChar(int val)
Writes a char (two byte) unsigned value to the buffer.
Writes values that can be read using
TupleInput.readChar .
Parameters:
val - is the value to write to the buffer. | | final public TupleOutput | writeChars(String val)
Writes the specified characters to the buffer, converting each character
to a two byte unsigned value.
Writes values that can be read using
TupleInput.readChars .
Parameters:
val - is the string containing the characters to be written. | | final public TupleOutput | writeChars(char[] chars)
Writes the specified characters to the buffer, converting each character
to a two byte unsigned value.
Writes values that can be read using
TupleInput.readChars .
Parameters:
chars - is the array of characters to be written. | | final public TupleOutput | writeDouble(double val)
Writes an signed double (eight byte) value to the buffer.
Writes values that can be read using
TupleInput.readDouble .
Double.doubleToLongBits is used to convert the signed
double value.
Note: This method produces byte array values that by default
(without a custom comparator) do not sort correctly for
negative values. | | final public TupleOutput | writeFloat(float val)
Writes an signed float (four byte) value to the buffer.
Writes values that can be read using
TupleInput.readFloat .
Float.floatToIntBits is used to convert the signed float
value.
Note: This method produces byte array values that by default
(without a custom comparator) do not sort correctly for
negative values. | | final public TupleOutput | writeInt(int val)
Writes an signed int (four byte) value to the buffer.
Writes values that can be read using
TupleInput.readInt .
Parameters:
val - is the value to write to the buffer. | | final public TupleOutput | writeLong(long val)
Writes an signed long (eight byte) value to the buffer.
Writes values that can be read using
TupleInput.readLong .
Parameters:
val - is the value to write to the buffer. | | final public void | writePackedInt(int val)
Writes a packed integer. | | final public TupleOutput | writeShort(int val)
Writes an signed short (two byte) value to the buffer.
Writes values that can be read using
TupleInput.readShort .
Parameters:
val - is the value to write to the buffer. | | final public TupleOutput | writeSortedDouble(double val)
Writes a signed double (eight byte) value to the buffer, with support
for correct default sorting of all values.
Writes values that can be read using
TupleInput.readSortedDouble .
Float.doubleToLongBits and the following bit
manipulations are used to convert the signed double value to a
representation that is sorted correctly by default.
long longVal = Double.doubleToLongBits(val);
longVal ^= (longVal < 0) ? 0xffffffffffffffffL : 0x8000000000000000L;
Parameters:
val - is the value to write to the buffer. | | final public TupleOutput | writeSortedFloat(float val)
Writes a signed float (four byte) value to the buffer, with support for
correct default sorting of all values.
Writes values that can be read using
TupleInput.readSortedFloat .
Float.floatToIntBits and the following bit manipulations
are used to convert the signed float value to a representation that is
sorted correctly by default.
int intVal = Float.floatToIntBits(val);
intVal ^= (intVal < 0) ? 0xffffffff : 0x80000000;
Parameters:
val - is the value to write to the buffer. | | final public TupleOutput | writeString(String val)
Writes the specified characters to the buffer, converting each character
to UTF format, and adding a null terminator byte.
Note that zero (0x0000) character values are encoded as non-zero values
and a null String parameter is encoded as 0xFF.
Writes values that can be read using
TupleInput.readString .
Parameters:
val - is the string containing the characters to be written. | | final public TupleOutput | writeString(char[] chars)
Writes the specified characters to the buffer, converting each character
to UTF format.
Note that zero (0x0000) character values are encoded as non-zero values.
Writes values that can be read using
TupleInput.readString(int) or
TupleInput.readString(char[]) .
Parameters:
chars - is the array of characters to be written. | | final public TupleOutput | writeUnsignedByte(int val)
Writes an unsigned byte (one byte) value to the buffer.
Writes values that can be read using
TupleInput.readUnsignedByte .
Parameters:
val - is the value to write to the buffer. | | final public TupleOutput | writeUnsignedInt(long val)
Writes an unsigned int (four byte) value to the buffer.
Writes values that can be read using
TupleInput.readUnsignedInt .
Parameters:
val - is the value to write to the buffer. | | final public TupleOutput | writeUnsignedShort(int val)
Writes an unsigned short (two byte) value to the buffer.
Writes values that can be read using
TupleInput.readUnsignedShort .
Parameters:
val - is the value to write to the buffer. |
| NULL_STRING_UTF_VALUE | | final static int NULL_STRING_UTF_VALUE(Code) | | We represent a null string as a single FF UTF character, which cannot
occur in a UTF encoded string.
|
| TupleOutput | | public TupleOutput()(Code) | | Creates a tuple output object for writing a byte array of tuple data.
|
| TupleOutput | | public TupleOutput(byte[] buffer)(Code) | | Creates a tuple output object for writing a byte array of tuple data,
using a given buffer. A new buffer will be allocated only if the number
of bytes needed is greater than the length of this buffer. A reference
to the byte array will be kept by this object and therefore the byte
array should not be modified while this object is in use.
Parameters:
buffer - is the byte array to use as the buffer. |
| writeBigInteger | | final public TupleOutput writeBigInteger(BigInteger val)(Code) | | Writes a
BigInteger . Supported
BigInteger values are
limited to those with a byte array (
BigInteger.toByteArray )
representation with a size of 0x7fff bytes or less. The maximum
BigInteger value is (20x3fff7 - 1) and the minimum value is
(-20x3fff7).
The byte format for a
BigInteger value is:
This format provides correct default sorting when the default
byte-by-byte comparison is used.
throws:
NullPointerException - if val is null.
throws:
IllegalArgumentException - if the byte array representation of valis larger than 0x7fff bytes. |
| writeBoolean | | final public TupleOutput writeBoolean(boolean val)(Code) | | Writes a boolean (one byte) unsigned value to the buffer, writing one
if the value is true and zero if it is false.
Writes values that can be read using
TupleInput.readBoolean .
Parameters:
val - is the value to write to the buffer. this tuple output object. |
| writeByte | | final public TupleOutput writeByte(int val)(Code) | | Writes an signed byte (one byte) value to the buffer.
Writes values that can be read using
TupleInput.readByte .
Parameters:
val - is the value to write to the buffer. this tuple output object. |
| writeBytes | | final public TupleOutput writeBytes(String val)(Code) | | Writes the specified bytes to the buffer, converting each character to
an unsigned byte value.
Writes values that can be read using
TupleInput.readBytes .
Only characters with values below 0x100 may be written using this
method, since the high-order 8 bits of all characters are discarded.
Parameters:
val - is the string containing the values to be written. this tuple output object.
throws:
NullPointerException - if the val parameter is null. |
| writeBytes | | final public TupleOutput writeBytes(char[] chars)(Code) | | Writes the specified bytes to the buffer, converting each character to
an unsigned byte value.
Writes values that can be read using
TupleInput.readBytes .
Only characters with values below 0x100 may be written using this
method, since the high-order 8 bits of all characters are discarded.
Parameters:
chars - is the array of values to be written. this tuple output object.
throws:
NullPointerException - if the chars parameter is null. |
| writeChar | | final public TupleOutput writeChar(int val)(Code) | | Writes a char (two byte) unsigned value to the buffer.
Writes values that can be read using
TupleInput.readChar .
Parameters:
val - is the value to write to the buffer. this tuple output object. |
| writeChars | | final public TupleOutput writeChars(String val)(Code) | | Writes the specified characters to the buffer, converting each character
to a two byte unsigned value.
Writes values that can be read using
TupleInput.readChars .
Parameters:
val - is the string containing the characters to be written. this tuple output object.
throws:
NullPointerException - if the val parameter is null. |
| writeChars | | final public TupleOutput writeChars(char[] chars)(Code) | | Writes the specified characters to the buffer, converting each character
to a two byte unsigned value.
Writes values that can be read using
TupleInput.readChars .
Parameters:
chars - is the array of characters to be written. this tuple output object.
throws:
NullPointerException - if the chars parameter is null. |
| writeDouble | | final public TupleOutput writeDouble(double val)(Code) | | Writes an signed double (eight byte) value to the buffer.
Writes values that can be read using
TupleInput.readDouble .
Double.doubleToLongBits is used to convert the signed
double value.
Note: This method produces 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
TupleOutput.writeSortedDouble .
Parameters:
val - is the value to write to the buffer. this tuple output object. |
| writeFloat | | final public TupleOutput writeFloat(float val)(Code) | | Writes an signed float (four byte) value to the buffer.
Writes values that can be read using
TupleInput.readFloat .
Float.floatToIntBits is used to convert the signed float
value.
Note: This method produces 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
TupleOutput.writeSortedFloat .
Parameters:
val - is the value to write to the buffer. this tuple output object. |
| writeInt | | final public TupleOutput writeInt(int val)(Code) | | Writes an signed int (four byte) value to the buffer.
Writes values that can be read using
TupleInput.readInt .
Parameters:
val - is the value to write to the buffer. this tuple output object. |
| writeLong | | final public TupleOutput writeLong(long val)(Code) | | Writes an signed long (eight byte) value to the buffer.
Writes values that can be read using
TupleInput.readLong .
Parameters:
val - is the value to write to the buffer. this tuple output object. |
| writePackedInt | | final public void writePackedInt(int val)(Code) | | Writes a packed integer. Note that packed integers are not appropriate
for sorted values (keys) unless a custom comparator is used.
See Also: PackedInteger |
| writeShort | | final public TupleOutput writeShort(int val)(Code) | | Writes an signed short (two byte) value to the buffer.
Writes values that can be read using
TupleInput.readShort .
Parameters:
val - is the value to write to the buffer. this tuple output object. |
| writeSortedDouble | | final public TupleOutput writeSortedDouble(double val)(Code) | | Writes a signed double (eight byte) value to the buffer, with support
for correct default sorting of all values.
Writes values that can be read using
TupleInput.readSortedDouble .
Float.doubleToLongBits and the following bit
manipulations are used to convert the signed double value to a
representation that is sorted correctly by default.
long longVal = Double.doubleToLongBits(val);
longVal ^= (longVal < 0) ? 0xffffffffffffffffL : 0x8000000000000000L;
Parameters:
val - is the value to write to the buffer. this tuple output object. |
| writeSortedFloat | | final public TupleOutput writeSortedFloat(float val)(Code) | | Writes a signed float (four byte) value to the buffer, with support for
correct default sorting of all values.
Writes values that can be read using
TupleInput.readSortedFloat .
Float.floatToIntBits and the following bit manipulations
are used to convert the signed float value to a representation that is
sorted correctly by default.
int intVal = Float.floatToIntBits(val);
intVal ^= (intVal < 0) ? 0xffffffff : 0x80000000;
Parameters:
val - is the value to write to the buffer. this tuple output object. |
| writeString | | final public TupleOutput writeString(String val)(Code) | | Writes the specified characters to the buffer, converting each character
to UTF format, and adding a null terminator byte.
Note that zero (0x0000) character values are encoded as non-zero values
and a null String parameter is encoded as 0xFF.
Writes values that can be read using
TupleInput.readString .
Parameters:
val - is the string containing the characters to be written. this tuple output object. |
| writeString | | final public TupleOutput writeString(char[] chars)(Code) | | Writes the specified characters to the buffer, converting each character
to UTF format.
Note that zero (0x0000) character values are encoded as non-zero values.
Writes values that can be read using
TupleInput.readString(int) or
TupleInput.readString(char[]) .
Parameters:
chars - is the array of characters to be written. this tuple output object.
throws:
NullPointerException - if the chars parameter is null. |
| writeUnsignedByte | | final public TupleOutput writeUnsignedByte(int val)(Code) | | Writes an unsigned byte (one byte) value to the buffer.
Writes values that can be read using
TupleInput.readUnsignedByte .
Parameters:
val - is the value to write to the buffer. this tuple output object. |
| writeUnsignedInt | | final public TupleOutput writeUnsignedInt(long val)(Code) | | Writes an unsigned int (four byte) value to the buffer.
Writes values that can be read using
TupleInput.readUnsignedInt .
Parameters:
val - is the value to write to the buffer. this tuple output object. |
| writeUnsignedShort | | final public TupleOutput writeUnsignedShort(int val)(Code) | | Writes an unsigned short (two byte) value to the buffer.
Writes values that can be read using
TupleInput.readUnsignedShort .
Parameters:
val - is the value to write to the buffer. this tuple output object. |
| Fields inherited from com.sleepycat.util.FastOutputStream | final public static int DEFAULT_BUMP_SIZE(Code)(Java Doc)
final public static int DEFAULT_INIT_SIZE(Code)(Java Doc)
|
|
|