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

com.sleepycat.bind.tuple

## Class TupleBase<E>

- java.lang.Object
- - com.sleepycat.bind.tuple.TupleBase<E>

- Direct Known Subclasses:
    TupleBinding, TupleSerialBinding, TupleSerialKeyCreator, TupleTupleBinding, TupleTupleKeyCreator

      public class TupleBase<E>
      extends java.lang.Object

  A base class for tuple bindings and tuple key creators that provides control over the allocation of the output buffer.

  Tuple bindings and key creators append data to a `TupleOutput` instance, which is also a `FastOutputStream` instance. This object has a byte array buffer that is resized when it is full. The reallocation of this buffer can be a performance factor for some applications using large objects. To manage this issue, the `setTupleBufferSize(int)` method may be used to control the initial size of the buffer, and the `getTupleOutput(E)` method may be overridden by subclasses to take over creation of the TupleOutput object.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `TupleBase()` Initializes the initial output buffer size to zero.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static TupleInput` | `entryToInput(DatabaseEntry entry)` Utility method to create a new tuple input object for reading the data from a given buffer.
    `int` | `getTupleBufferSize()` Returns the initial byte size of the output buffer.
    `protected TupleOutput` | `getTupleOutput(E object)` Returns an empty TupleOutput instance that will be used by the tuple binding or key creator.
    `static void` | `inputToEntry(TupleInput input, DatabaseEntry entry)` Utility method to set the data in a entry buffer to the data in a tuple input object.
    `static TupleOutput` | `newOutput()` Deprecated. replaced by `getTupleOutput(E)`
    `static TupleOutput` | `newOutput(byte[] buffer)` Deprecated. replaced by `getTupleOutput(E)`
    `static void` | `outputToEntry(TupleOutput output, DatabaseEntry entry)` Utility method to set the data in a entry buffer to the data in a tuple output object.
    `void` | `setTupleBufferSize(int byteSize)` Sets the initial byte size of the output buffer that is allocated by the default implementation of `getTupleOutput(E)`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### TupleBase

          public TupleBase()

      Initializes the initial output buffer size to zero.

      Unless `setTupleBufferSize(int)` is called, the default `FastOutputStream.DEFAULT_INIT_SIZE` size will be used.

  - ### Method Detail

    - #### setTupleBufferSize

          public void setTupleBufferSize(int byteSize)

      Sets the initial byte size of the output buffer that is allocated by the default implementation of `getTupleOutput(E)`.

      If this property is zero (the default), the default `FastOutputStream.DEFAULT_INIT_SIZE` size is used.

      Parameters:
        `byteSize` - the initial byte size of the output buffer, or zero to use the default size.

    - #### getTupleBufferSize

          public int getTupleBufferSize()

      Returns the initial byte size of the output buffer.
      Returns:
        the initial byte size of the output buffer.
      See Also:
        `setTupleBufferSize(int)`

    - #### getTupleOutput

          protected TupleOutput getTupleOutput(E object)

      Returns an empty TupleOutput instance that will be used by the tuple binding or key creator.

      The default implementation of this method creates a new TupleOutput with an initial buffer size that can be changed using the `setTupleBufferSize(int)` method.

      This method may be overridden to return a TupleOutput instance. For example, an instance per thread could be created and returned by this method. If a TupleOutput instance is reused, be sure to call its `FastOutputStream.reset()` method before each use.

      Parameters:
        `object` - is the object to be written to the tuple output, and may be used by subclasses to determine the size of the output buffer.
      Returns:
        an empty TupleOutput instance.
      See Also:
        `setTupleBufferSize(int)`

    - #### outputToEntry

          public static void outputToEntry(TupleOutput output,
                                           DatabaseEntry entry)

      Utility method to set the data in a entry buffer to the data in a tuple output object.
      Parameters:
        `output` - is the source tuple output object.
        `entry` - is the destination entry buffer.

    - #### inputToEntry

          public static void inputToEntry(TupleInput input,
                                          DatabaseEntry entry)

      Utility method to set the data in a entry buffer to the data in a tuple input object.
      Parameters:
        `input` - is the source tuple input object.
        `entry` - is the destination entry buffer.

    - #### entryToInput

          public static TupleInput entryToInput(DatabaseEntry entry)

      Utility method to create a new tuple input object for reading the data from a given buffer. If an existing input is reused, it is reset before returning it.
      Parameters:
        `entry` - is the source entry buffer.
      Returns:
        the new tuple input object.

    - #### newOutput

          public static TupleOutput newOutput()

      Deprecated. replaced by `getTupleOutput(E)`
      Utility method for use by bindings to create a tuple output object.
      Returns:
        a new tuple output object.

    - #### newOutput

          public static TupleOutput newOutput(byte[] buffer)

      Deprecated. replaced by `getTupleOutput(E)`
      Utility method for use by bindings to create a tuple output object with a specific starting size.
      Parameters:
        `buffer` - is the byte array to use as the buffer.
      Returns:
        a new tuple output object.

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