Berkeley DB
version 4.8.30

com.sleepycat.bind.tuple
Class TupleOutput

java.lang.Object
  extended by java.io.OutputStream
      extended by com.sleepycat.util.FastOutputStream
          extended by com.sleepycat.bind.tuple.TupleOutput
All Implemented Interfaces:
Closeable, Flushable

public class TupleOutput
extends FastOutputStream

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 DataOutput interface. The reason this class does not implement 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.

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:


Field Summary
 
Fields inherited from class com.sleepycat.util.FastOutputStream
DEFAULT_BUMP_SIZE, DEFAULT_INIT_SIZE
 
Constructor Summary
TupleOutput()
          Creates a tuple output object for writing a byte array of tuple data.
TupleOutput(byte[] buffer)
          Creates a tuple output object for writing a byte array of tuple data, using a given buffer.
 
Method Summary
static int getBigIntegerByteLength(BigInteger val)
          Returns the byte length of a given BigInteger value.
 TupleOutput writeBigInteger(BigInteger val)
          Writes a BigInteger.
 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.
 TupleOutput writeByte(int val)
          Writes an signed byte (one byte) value to the buffer.
 TupleOutput writeBytes(char[] chars)
          Writes the specified bytes to the buffer, converting each character to an unsigned byte value.
 TupleOutput writeBytes(String val)
          Writes the specified bytes to the buffer, converting each character to an unsigned byte value.
 TupleOutput writeChar(int val)
          Writes a char (two byte) unsigned value to the buffer.
 TupleOutput writeChars(char[] chars)
          Writes the specified characters to the buffer, converting each character to a two byte unsigned value.
 TupleOutput writeChars(String val)
          Writes the specified characters to the buffer, converting each character to a two byte unsigned value.
 TupleOutput writeDouble(double val)
          Writes an signed double (eight byte) value to the buffer.
 TupleOutput writeFloat(float val)
          Writes an signed float (four byte) value to the buffer.
 TupleOutput writeInt(int val)
          Writes an signed int (four byte) value to the buffer.
 TupleOutput writeLong(long val)
          Writes an signed long (eight byte) value to the buffer.
 void writePackedInt(int val)
          Writes a packed integer.
 void writePackedLong(long val)
          Writes a packed long integer.
 TupleOutput writeShort(int val)
          Writes an signed short (two byte) value to the buffer.
 TupleOutput writeSortedDouble(double val)
          Writes a signed double (eight byte) value to the buffer, with support for correct default sorting of all values.
 TupleOutput writeSortedFloat(float val)
          Writes a signed float (four byte) value to the buffer, with support for correct default sorting of all values.
 TupleOutput writeString(char[] chars)
          Writes the specified characters to the buffer, converting each character to UTF format.
 TupleOutput writeString(String val)
          Writes the specified characters to the buffer, converting each character to UTF format, and adding a null terminator byte.
 TupleOutput writeUnsignedByte(int val)
          Writes an unsigned byte (one byte) value to the buffer.
 TupleOutput writeUnsignedInt(long val)
          Writes an unsigned int (four byte) value to the buffer.
 TupleOutput writeUnsignedShort(int val)
          Writes an unsigned short (two byte) value to the buffer.
 
Methods inherited from class com.sleepycat.util.FastOutputStream
addSize, getBufferBytes, getBufferLength, getBufferOffset, makeSpace, reset, size, toByteArray, toString, toString, write, write, write, writeFast, writeFast, writeFast, writeTo
 
Methods inherited from class java.io.OutputStream
close, flush
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

TupleOutput

public TupleOutput()
Creates a tuple output object for writing a byte array of tuple data.


TupleOutput

public TupleOutput(byte[] buffer)
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.
Method Detail

writeBytes

public final 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(int). 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.
Returns:
this tuple output object.
Throws:
NullPointerException - if the val parameter is null.

writeChars

public final 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(int).

Parameters:
val - is the string containing the characters to be written.
Returns:
this tuple output object.
Throws:
NullPointerException - if the val parameter is null.

writeString

public final 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.
Returns:
this tuple output object.

writeChar

public final 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.
Returns:
this tuple output object.

writeBoolean

public final 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.
Returns:
this tuple output object.

writeByte

public final 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.
Returns:
this tuple output object.

writeShort

public final 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.
Returns:
this tuple output object.

writeInt

public final 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.
Returns:
this tuple output object.

writeLong

public final 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.
Returns:
this tuple output object.

writeFloat

public final 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. Only non-negative values are sorted correctly by default. To sort all values correctly by default, use writeSortedFloat(float).

Parameters:
val - is the value to write to the buffer.
Returns:
this tuple output object.

writeDouble

public final 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. Only non-negative values are sorted correctly by default. To sort all values correctly by default, use writeSortedDouble(double).

Parameters:
val - is the value to write to the buffer.
Returns:
this tuple output object.

writeSortedFloat

public final 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.
Returns:
this tuple output object.

writeSortedDouble

public final 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.
Returns:
this tuple output object.

writeBytes

public final 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(int). 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.
Returns:
this tuple output object.
Throws:
NullPointerException - if the chars parameter is null.

writeChars

public final 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(int).

Parameters:
chars - is the array of characters to be written.
Returns:
this tuple output object.
Throws:
NullPointerException - if the chars parameter is null.

writeString

public final 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.
Returns:
this tuple output object.
Throws:
NullPointerException - if the chars parameter is null.

writeUnsignedByte

public final 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.
Returns:
this tuple output object.

writeUnsignedShort

public final 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.
Returns:
this tuple output object.

writeUnsignedInt

public final 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.
Returns:
this tuple output object.

writePackedInt

public final void writePackedInt(int val)
Writes a packed integer. Note that packed integers are not appropriate for sorted values (keys) unless a custom comparator is used.

See Also:
PackedInteger

writePackedLong

public final void writePackedLong(long val)
Writes a packed long integer. Note that packed integers are not appropriate for sorted values (keys) unless a custom comparator is used.

See Also:
PackedInteger

writeBigInteger

public final TupleOutput writeBigInteger(BigInteger val)
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.
IllegalArgumentException - if the byte array representation of val is larger than 0x7fff bytes.

getBigIntegerByteLength

public static int getBigIntegerByteLength(BigInteger val)
Returns the byte length of a given BigInteger value.

See Also:
writeBigInteger(java.math.BigInteger)

Berkeley DB
version 4.8.30

Copyright (c) 1996-2009 Oracle. All rights reserved.