TupleOutput (Oracle - Berkeley DB Java API)
Date: 2017-04-13

com.sleepycat.bind.tuple

## Class TupleOutput

- java.lang.Object
- - java.io.OutputStream
  - - com.sleepycat.util.FastOutputStream
    - - com.sleepycat.bind.tuple.TupleOutput

- All Implemented Interfaces:
    java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable

      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.

  See Also:
    Tuple Formats

- - ### Field Summary

    - ### Fields inherited from class com.sleepycat.util.FastOutputStream

      `DEFAULT_BUMP_SIZE, DEFAULT_INIT_SIZE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `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

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static int` | `getBigDecimalMaxByteLength(java.math.BigDecimal val)` Returns the maximum byte length that would be output for a given `BigDecimal` value if `writeBigDecimal(java.math.BigDecimal)` were called.
    `static int` | `getBigIntegerByteLength(java.math.BigInteger val)` Returns the exact byte length that would would be output for a given `BigInteger` value if `writeBigInteger(java.math.BigInteger)` were called.
    `static int` | `getSortedBigDecimalMaxByteLength(java.math.BigDecimal val)` Returns the maximum byte length that would be output for a given `BigDecimal` value if `writeSortedBigDecimal(java.math.BigDecimal)` were called.
    `TupleOutput` | `writeBigDecimal(java.math.BigDecimal val)` Writes an unsorted `BigDecimal`.
    `TupleOutput` | `writeBigInteger(java.math.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(java.lang.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(java.lang.String val)` Writes the specified characters to the buffer, converting each character to a two byte unsigned value.
    `TupleOutput` | `writeDouble(double val)` Writes an unsorted double (eight byte) value to the buffer.
    `TupleOutput` | `writeFloat(float val)` Writes an unsorted 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.
    `TupleOutput` | `writePackedInt(int val)` Writes an unsorted packed integer.
    `TupleOutput` | `writePackedLong(long val)` Writes an unsorted packed long integer.
    `TupleOutput` | `writeShort(int val)` Writes an signed short (two byte) value to the buffer.
    `TupleOutput` | `writeSortedBigDecimal(java.math.BigDecimal val)` Writes a sorted `BigDecimal`.
    `TupleOutput` | `writeSortedDouble(double val)` Writes a sorted double (eight byte) value to the buffer.
    `TupleOutput` | `writeSortedFloat(float val)` Writes a sorted float (four byte) value to the buffer.
    `TupleOutput` | `writeSortedPackedInt(int val)` Writes a sorted packed integer.
    `TupleOutput` | `writeSortedPackedLong(long val)` Writes a sorted packed long integer.
    `TupleOutput` | `writeString(char[] chars)` Writes the specified characters to the buffer, converting each character to UTF format.
    `TupleOutput` | `writeString(java.lang.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(java.lang.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)`.
      Parameters:
        `val` - is the string containing the values to be written. Only characters with values below 0x100 may be written using this method, since the high-order 8 bits of all characters are discarded.
      Returns:
        this tuple output object.
      Throws:
        `java.lang.NullPointerException` - if the val parameter is null.
      See Also:
        Integer Formats

    - #### writeChars

          public final TupleOutput writeChars(java.lang.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:
        `java.lang.NullPointerException` - if the val parameter is null.
      See Also:
        Integer Formats

    - #### writeString

          public final TupleOutput writeString(java.lang.String val)

      Writes the specified characters to the buffer, converting each character to UTF format, and adding a null terminator byte. 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.
      See Also:
        String Formats

    - #### 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.
      See Also:
        Integer Formats

    - #### 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.
      See Also:
        Integer Formats

    - #### 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.
      See Also:
        Integer Formats

    - #### 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.
      See Also:
        Integer Formats

    - #### 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.
      See Also:
        Integer Formats

    - #### 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.
      See Also:
        Integer Formats

    - #### writeFloat

          public final TupleOutput writeFloat(float val)

      Writes an unsorted float (four byte) value to the buffer. Writes values that can be read using `TupleInput.readFloat()`.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Floating Point Formats

    - #### writeDouble

          public final TupleOutput writeDouble(double val)

      Writes an unsorted double (eight byte) value to the buffer. Writes values that can be read using `TupleInput.readDouble()`.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Floating Point Formats

    - #### writeSortedFloat

          public final TupleOutput writeSortedFloat(float val)

      Writes a sorted float (four byte) value to the buffer. Writes values that can be read using `TupleInput.readSortedFloat()`.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Floating Point Formats

    - #### writeSortedDouble

          public final TupleOutput writeSortedDouble(double val)

      Writes a sorted double (eight byte) value to the buffer. Writes values that can be read using `TupleInput.readSortedDouble()`.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Floating Point Formats

    - #### 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)`.
      Parameters:
        `chars` - is the array of values to be written. Only characters with values below 0x100 may be written using this method, since the high-order 8 bits of all characters are discarded.
      Returns:
        this tuple output object.
      Throws:
        `java.lang.NullPointerException` - if the chars parameter is null.
      See Also:
        Integer Formats

    - #### 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:
        `java.lang.NullPointerException` - if the chars parameter is null.
      See Also:
        Integer Formats

    - #### writeString

          public final TupleOutput writeString(char[] chars)

      Writes the specified characters to the buffer, converting each character to UTF format. 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:
        `java.lang.NullPointerException` - if the chars parameter is null.
      See Also:
        String Formats

    - #### 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.
      See Also:
        Integer Formats

    - #### 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.
      See Also:
        Integer Formats

    - #### 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.
      See Also:
        Integer Formats

    - #### writePackedInt

          public final TupleOutput writePackedInt(int val)

      Writes an unsorted packed integer.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Integer Formats

    - #### writePackedLong

          public final TupleOutput writePackedLong(long val)

      Writes an unsorted packed long integer.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Integer Formats

    - #### writeSortedPackedInt

          public final TupleOutput writeSortedPackedInt(int val)

      Writes a sorted packed integer.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Integer Formats

    - #### writeSortedPackedLong

          public final TupleOutput writeSortedPackedLong(long val)

      Writes a sorted packed long integer.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        Integer Formats

    - #### writeBigInteger

          public final TupleOutput writeBigInteger(java.math.BigInteger val)

      Writes a `BigInteger`.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      Throws:
        `java.lang.NullPointerException` - if val is null.
        `java.lang.IllegalArgumentException` - if the byte array representation of val is larger than 0x7fff bytes.
      See Also:
        Integer Formats

    - #### getBigIntegerByteLength

          public static int getBigIntegerByteLength(java.math.BigInteger val)

      Returns the exact byte length that would would be output for a given `BigInteger` value if `writeBigInteger(java.math.BigInteger)` were called.
      Parameters:
        `val` - the BigInteger
      Returns:
        the byte length.
      See Also:
        Integer Formats

    - #### writeBigDecimal

          public final TupleOutput writeBigDecimal(java.math.BigDecimal val)

      Writes an unsorted `BigDecimal`.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      Throws:
        `java.lang.NullPointerException` - if val is null.
      See Also:
        BigDecimal Formats

    - #### getBigDecimalMaxByteLength

          public static int getBigDecimalMaxByteLength(java.math.BigDecimal val)

      Returns the maximum byte length that would be output for a given `BigDecimal` value if `writeBigDecimal(java.math.BigDecimal)` were called.
      Parameters:
        `val` - the BigDecimal.
      Returns:
        the byte length.
      See Also:
        BigDecimal Formats

    - #### writeSortedBigDecimal

          public final TupleOutput writeSortedBigDecimal(java.math.BigDecimal val)

      Writes a sorted `BigDecimal`.
      Parameters:
        `val` - is the value to write to the buffer.
      Returns:
        this tuple output object.
      See Also:
        BigDecimal Formats

    - #### getSortedBigDecimalMaxByteLength

          public static int getSortedBigDecimalMaxByteLength(java.math.BigDecimal val)

      Returns the maximum byte length that would be output for a given `BigDecimal` value if `writeSortedBigDecimal(java.math.BigDecimal)` were called.
      Parameters:
        `val` - the BigDecimal.
      Returns:
        the byte length.
      See Also:
        BigDecimal Formats

Copyright (c) 1996, 2017 Oracle and/or its affiliates. All rights reserved.