SDatabaseEntry (Oracle - Berkeley DB Client-Server API)
Date: 2018-05-29

com.sleepycat.client

## Class SDatabaseEntry

- java.lang.Object
- - com.sleepycat.client.SDatabaseEntry

- All Implemented Interfaces:
    SDatabaseEntryBase

      public class SDatabaseEntry
      extends java.lang.Object
      implements SDatabaseEntryBase

  Encodes database key and data items as a byte array.

  Storage and retrieval for the `SDatabase` and `SCursor` methods are based on key/data pairs. Both key and data items are represented by SDatabaseEntry objects. Key and data byte arrays may refer to arrays of zero length up to arrays of essentially unlimited length. A key item may also refer to a record number, which is a 32-bit integer. In this case, the record number must be accessed through `setRecordNumber(int, java.nio.ByteOrder)` and `getRecordNumber(java.nio.ByteOrder)` instead of setData and getData.

  The SDatabaseEntry class provides simple access to an underlying object whose elements can be examined or changed. SDatabaseEntry objects can be subclassed, providing a way to associate with it additional data or references to other structures.

  Access to SDatabaseEntry objects is not re-entrant. In particular, if multiple threads simultaneously access the same SDatabaseEntry object using `SDatabase` or `SCursor` methods, the results are undefined.

  ### Input and Output Parameters

  SDatabaseEntry objects are used for both input data (when writing to a database or specifying a search parameter) and output data (when reading from a database). For certain methods, one parameter may be an input parameter and another may be an output parameter. For example, the `SDatabase.get(com.sleepycat.client.STransaction, com.sleepycat.client.SDatabaseEntry, com.sleepycat.client.SDatabaseEntryBase, com.sleepycat.client.SLockMode)` method has an input key parameter and an output data parameter. The documentation for each method describes whether its parameters are input or output parameters.

  For SDatabaseEntry input parameters, the caller is responsible for initializing the data array of the SDatabaseEntry. For SDatabaseEntry output parameters, the method called will initialize the data array.

  ### Partial Offset and Length Properties

  By default the specified data (byte array, offset and size) corresponds to the full stored key or data item. Optionally, the Partial property can be set to true, and the PartialOffset and PartialLength properties are used to specify the portion of the key or data item to be read or written. For details, see the `setPartial(int, int, boolean)` method.

  Note that the Partial properties are set only by the caller. They will never be set by a `SDatabase` or `SCursor` method. Therefore, the application can assume that the Partial properties are not set, unless the application itself sets them explicitly.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `SDatabaseEntry()` Construct a SDatabaseEntry with null data.
    `SDatabaseEntry(byte[] data)` Construct a SDatabaseEntry with a given byte array.
    `SDatabaseEntry(byte[] data, int offset, int size)` Construct a DatabaseEntry with a given byte array, offset and size.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(java.lang.Object obj)`
    `byte[]` | `getData()` Return the byte array.
    `boolean` | `getExternalFile()` Return whether this SDatabaseEntry is configured to be stored as an external file.
    `protected java.lang.Object` | `getField(F field)` Return the value set on a specified field.
    `int` | `getOffset()` Always return zero.
    `boolean` | `getPartial()` Return whether this SDatabaseEntry is configured to read or write partial records.
    `int` | `getPartialLength()` Return the byte length of the partial record being read or written by the application, in bytes.
    `int` | `getPartialOffset()` Return the offset of the partial record being read or written by the application, in bytes.
    `int` | `getRecordNumber(java.nio.ByteOrder byteOrder)` Return the record number encoded in this entry's buffer.
    `int` | `getSize()` Return the byte size of the data array.
    `protected T` | `getThriftObj()`
    `int` | `hashCode()`
    `SDatabaseEntry` | `setData(byte[] data)` Sets the data byte array.
    `SDatabaseEntry` | `setData(byte[] data, int offset, int size)` Sets the data byte array.
    `SDatabaseEntry` | `setExternalFile(boolean externalFile)` Configure this SDatabaseEntry to be stored as an external file.
    `SDatabaseEntry` | `setPartial(int doff, int dlen, boolean partial)` Configure this SDatabaseEntry to read or write partial records.
    `SDatabaseEntry` | `setRecordNumber(int recno, java.nio.ByteOrder byteOrder)` Initialize the entry from a logical record number.

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

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

- - ### Constructor Detail

    - #### SDatabaseEntry

          public SDatabaseEntry()

      Construct a SDatabaseEntry with null data.

    - #### SDatabaseEntry

          public SDatabaseEntry(byte[] data)

      Construct a SDatabaseEntry with a given byte array.
      Parameters:
        `data` - byte array wrapped by the SDatabaseEntry

    - #### SDatabaseEntry

          public SDatabaseEntry(byte[] data,
                                int offset,
                                int size)

      Construct a DatabaseEntry with a given byte array, offset and size.
      Parameters:
        `data` - byte array wrapped by the SDatabaseEntry.
        `offset` - offset in the first byte in the byte array to be included.
        `size` - number of bytes in the byte array to be included.

  - ### Method Detail

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### equals

          public boolean equals(java.lang.Object obj)

      Overrides:
        `equals` in class `java.lang.Object`

    - #### getExternalFile

          public boolean getExternalFile()

      Return whether this SDatabaseEntry is configured to be stored as an external file.
      Returns:
        whether this SDatabaseEntry is configured to be stored as an external file

    - #### setExternalFile

          public SDatabaseEntry setExternalFile(boolean externalFile)

      Configure this SDatabaseEntry to be stored as an external file.
      Parameters:
        `externalFile` - whether this SDatabaseEntry is configured to be stored as an external file
      Returns:
        this

    - #### getData

          public byte[] getData()

      Return the byte array.

      For a SDatabaseEntry that is used as an output parameter, the byte array will always be a newly allocated array. The byte array specified by the caller will not be used and may be null.

      Returns:
        the byte array

    - #### setData

          public SDatabaseEntry setData(byte[] data)

      Sets the data byte array. The array is copied into this entry.

      Parameters:
        `data` - byte array
      Returns:
        this

    - #### setData

          public SDatabaseEntry setData(byte[] data,
                                        int offset,
                                        int size)

      Sets the data byte array. The specified range of the specified array is copied into this entry.

      Parameters:
        `data` - byte array
        `offset` - the start of the range to be copied
        `size` - the length of the range to be copied
      Returns:
        this

    - #### getPartialLength

          public int getPartialLength()

      Return the byte length of the partial record being read or written by the application, in bytes.

      Note that the Partial properties are set only by the caller. They will never be set by a `SDatabase` or `SCursor` method.

      Returns:
        the byte length of the partial record being read or written by the application, in bytes
      See Also:
        `setPartial(int, int, boolean)`

    - #### getPartialOffset

          public int getPartialOffset()

      Return the offset of the partial record being read or written by the application, in bytes.

      Note that the Partial properties are set only by the caller. They will never be set by a `SDatabase` or `SCursor` method.

      Returns:
        the offset of the partial record being read or written by the application, in bytes
      See Also:
        `setPartial(int, int, boolean)`

    - #### getPartial

          public boolean getPartial()

      Return whether this SDatabaseEntry is configured to read or write partial records.

      Note that the Partial properties are set only by the caller. They will never be set by a `SDatabase` or `SCursor` method.

      Returns:
        whether this SDatabaseEntry is configured to read or write partial records.
      See Also:
        `setPartial(int, int, boolean)`

    - #### setPartial

          public SDatabaseEntry setPartial(int doff,
                                           int dlen,
                                           boolean partial)

      Configure this SDatabaseEntry to read or write partial records.

      Do partial retrieval or storage of an item. If the calling application is doing a retrieval, length bytes specified by `dlen`, starting at the offset set by `doff` bytes from the beginning of the retrieved data record are returned as if they comprised the entire record. If any or all of the specified bytes do not exist in the record, the get is successful, and any existing bytes are returned.

      For example, if the data portion of a retrieved record was 100 bytes, and a partial retrieval was done using a SDatabaseEntry having a partial length of 20 and a partial offset of 85, the retrieval would succeed and the retrieved data would be the last 15 bytes of the record.

      If the calling application is storing an item, length bytes specified by `dlen`, starting at the offset set by `doff` bytes from the beginning of the specified key's data item are replaced by the data specified by the SDatabaseEntry. If the partial length is smaller than the data, the record will grow; if the partial length is larger than the data, the record will shrink. If the specified bytes do not exist, the record will be extended using nul bytes as necessary, and the store will succeed.

      It is an error to specify a partial key when performing a put operation of any kind.

      It is an error to attempt a partial store using the `SDatabase.put(com.sleepycat.client.STransaction, com.sleepycat.client.SDatabaseEntry, com.sleepycat.client.SDatabaseEntry)` method in a database that supports duplicate records. Partial stores in databases supporting duplicate records must be done using a cursor method.

      Note that the Partial properties are set only by the caller. They will never be set by a `SDatabase` or `SCursor` method.

      Parameters:
        `doff` - the offset of the partial record being read or written by the application, in bytes
        `dlen` - the byte length of the partial record being read or written by the application, in bytes
        `partial` - whether this SDatabaseEntry is configured to read or write partial records
      Returns:
        this

    - #### getRecordNumber

          public int getRecordNumber(java.nio.ByteOrder byteOrder)

      Return the record number encoded in this entry's buffer.
      Parameters:
        `byteOrder` - the byte order used to decode the record number. If this entry is retrieved from or will be sent to a server, this must be the server's byte order. See `BdbServerConnection.getServerByteOrder()`.
      Returns:
        the record number encoded in this entry's buffer

    - #### setRecordNumber

          public SDatabaseEntry setRecordNumber(int recno,
                                                java.nio.ByteOrder byteOrder)

      Initialize the entry from a logical record number. Record numbers are integer keys starting at 1.
      Parameters:
        `recno` - the record number to be encoded
        `byteOrder` - the byte order used to decode the record number. If this entry is retrieved from or will be sent to a server, this must be the server's byte order. See `BdbServerConnection.getServerByteOrder()`.
      Returns:
        this

    - #### getOffset

          public int getOffset()

      Always return zero. For compatibility with DPL APIs.
      Returns:
        always zero

    - #### getSize

          public int getSize()

      Return the byte size of the data array.

      It is an error to call this method if this entry contains a record number.

      Returns:
        number of bytes in the data array

    - #### getThriftObj

          protected T getThriftObj()

    - #### getField

          protected java.lang.Object getField(F field)
                                       throws java.lang.IllegalStateException

      Return the value set on a specified field. Throw IllegalStateException if the field is not set.
      Parameters:
        `field` - the field
      Returns:
        the field's value
      Throws:
        `java.lang.IllegalStateException` - if the field is not set

Copyright (c) 2016, 2018 Oracle and/or its affiliates. All rights reserved.