Module org.firebirdsql.jaybird
Package org.firebirdsql.gds.ng

# Interface DatatypeCoder

All Known Implementing Classes:
  `DefaultDatatypeCoder`, `EncodingSpecificDatatypeCoder`

public interface DatatypeCoder
Interface defining the encoding and decoding for Firebird (numerical) data types.

Since:
  3
Author:
  Mark Rotteveel

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `FRACTIONS_PER_HOUR`
  `static final int`
  `FRACTIONS_PER_MILLISECOND`
  `static final int`
  `FRACTIONS_PER_MINUTE`
  `static final int`
  `FRACTIONS_PER_SECOND`
  `static final int`
  `NANOSECONDS_PER_FRACTION`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Reader`
  `createReader(InputStream in)`
  Creates a reader wrapping an input stream.
  `Writer`
  `createWriter(OutputStream out)`
  Creates a writer wrapping an input stream.
  `boolean`
  `decodeBoolean(byte[] buf)`
  Decode a boolean from `buf` from the first byte.
  `Decimal128`
  `decodeDecimal128(byte[] buf)`
  Decodes a decimal128 from a byte array of 16 bytes.
  `Decimal64`
  `decodeDecimal64(byte[] buf)`
  Decodes a decimal64 from a byte array of 8 bytes.
  `double`
  `decodeDouble(byte[] buf)`
  Decode a double value from `buf` from the first 8 bytes.
  `float`
  `decodeFloat(byte[] buf)`
  Decode a float value from `buf` from the first 4 bytes.
  `int`
  `decodeInt(byte[] buf)`
  Decode an int value from `buf` from the first 4 bytes.
  `int`
  `decodeInt(byte[] buf, int off)`
  Decode an int value from `buf` starting at offset `off` for 4 bytes.
  `BigInteger`
  `decodeInt128(byte[] buf)`
  Decodes a BigInteger from a byte array of 16 bytes (int128 format).
  `LocalDate`
  `decodeLocalDate(byte[] buf)`
  Decode `java.time.LocalDate` from `buf` from the first 4 bytes.
  `LocalDate`
  `decodeLocalDate(byte[] buf, int off)`
  Decode `java.time.LocalDate` from `buf` from the 4 bytes starting at `off`.
  `LocalDateTime`
  `decodeLocalDateTime(byte[] buf)`
  Decode `java.time.LocalDateTime` from `buf` from the first 8 bytes.
  `LocalDateTime`
  `decodeLocalDateTime(byte[] buf, int off)`
  Decode `java.time.LocalDateTime` from `buf` from the 8 bytes starting at `off`.
  `LocalTime`
  `decodeLocalTime(byte[] buf)`
  Decode `java.time.LocalTime` from `buf` from the first 4 bytes.
  `LocalTime`
  `decodeLocalTime(byte[] buf, int off)`
  Decode `java.time.LocalTime` from `buf` from the 4 bytes starting at `off`.
  `long`
  `decodeLong(byte[] buf)`
  Decode a long value from `buf` from the first 8 bytes.
  `short`
  `decodeShort(byte[] buf)`
  Decode a short value from `buf` from the first `sizeOfShort()` bytes.
  `short`
  `decodeShort(byte[] buf, int off)`
  Decode a short value from `buf` starting at offset `off` for `sizeOfShort()` bytes.
  `String`
  `decodeString(byte[] buf)`
  Decode a `String` from `buf` using the encoding of this datatype coder.
  `byte[]`
  `encodeBoolean(boolean val)`
  Encodes boolean as a byte array of 1 byte.
  `byte[]`
  `encodeDecimal128(Decimal128 val)`
  Encodes a decimal128 as a byte array of 16 bytes.
  `byte[]`
  `encodeDecimal64(Decimal64 val)`
  Encodes a decimal64 as a byte array of 8 bytes.
  `byte[]`
  `encodeDouble(double val)`
  Encode a double value as a byte array of 8 bytes.
  `byte[]`
  `encodeFloat(float val)`
  Encode a float value as a byte array of 4 bytes.
  `byte[]`
  `encodeInt(int val)`
  Encode an int value as a byte array of 4 bytes.
  `void`
  `encodeInt(int val, byte[] buf, int off)`
  Encode an int value into `buf` starting at index `off` for 4 bytes.
  `byte[]`
  `encodeInt128(BigInteger val)`
  Encodes a BigInteger as a byte array of 16 bytes (int128 format).
  `byte[]`
  `encodeLocalDate(LocalDate val)`
  Encode a `java.time.LocalDate` as a byte array of 4 bytes.
  `void`
  `encodeLocalDate(LocalDate val, byte[] buf, int off)`
  Encode a `java.time.LocalDate` to a byte array, requiring 4 bytes.
  `byte[]`
  `encodeLocalDateTime(LocalDateTime val)`
  Encode a `java.time.LocalDateTime` as a byte array of 8 bytes.
  `void`
  `encodeLocalDateTime(LocalDateTime val, byte[] buf, int off)`
  Encode a `java.time.LocalDateTime` to a byte array, requiring 8 bytes.
  `byte[]`
  `encodeLocalTime(LocalTime val)`
  Encode a `java.time.LocalTime` as a byte array of 4 bytes.
  `void`
  `encodeLocalTime(LocalTime val, byte[] buf, int off)`
  Encode a `java.time.LocalTime` to a byte array, requiring 4 bytes.
  `byte[]`
  `encodeLong(long val)`
  Encode a long value as a byte array of 8 bytes.
  `byte[]`
  `encodeShort(int val)`
  Encode a short value as a byte array of length `sizeOfShort()`.
  `void`
  `encodeShort(int val, byte[] buf, int off)`
  Encode a short value into `buf` starting at offset `off` for `sizeOfShort()` bytes.
  `byte[]`
  `encodeShort(short val)`
  Encode a short value as a byte array of length `sizeOfShort()`.
  `byte[]`
  `encodeString(String val)`
  Encode a `String` value as a byte array using the encoding of this datatype coder.
  `boolean`
  `equals(Object other)`
  `DatatypeCoder`
  `forEncodingDefinition(EncodingDefinition encodingDefinition)`
  Return a derived datatype coder that applies the supplied encoding definition for string conversions.
  `Encoding`
  `getEncoding()`
  `EncodingDefinition`
  `getEncodingDefinition()`
  `IEncodingFactory`
  `getEncodingFactory()`
  `int`
  `hashCode()`
  `int`
  `sizeOfShort()`
  The size of an encoded short in this data type coder.
  `DatatypeCoder`
  `unwrap()`
  Unwrap this datatype coder to its parent (or itself).

- ## Field Details

  - ### NANOSECONDS_PER_FRACTION

    static final int NANOSECONDS_PER_FRACTION
    See Also:
      - Constant Field Values

  - ### FRACTIONS_PER_MILLISECOND

    static final int FRACTIONS_PER_MILLISECOND
    See Also:
      - Constant Field Values

  - ### FRACTIONS_PER_SECOND

    static final int FRACTIONS_PER_SECOND
    See Also:
      - Constant Field Values

  - ### FRACTIONS_PER_MINUTE

    static final int FRACTIONS_PER_MINUTE
    See Also:
      - Constant Field Values

  - ### FRACTIONS_PER_HOUR

    static final int FRACTIONS_PER_HOUR
    See Also:
      - Constant Field Values

- ## Method Details

  - ### sizeOfShort

    int sizeOfShort()
    The size of an encoded short in this data type coder.
    Returns:
      size of an encoded short (either `2` or `4` bytes)
    Since:
      4

  - ### encodeShort

    byte[] encodeShort(short val)
    Encode a short value as a byte array of length `sizeOfShort()`.
    Parameters:
      `val` - value to be encoded
    Returns:
      `val` encoded as a byte array

  - ### encodeShort

    byte[] encodeShort(int val)
    Encode a short value as a byte array of length `sizeOfShort()`.
    Parameters:
      `val` - value to be encoded
    Returns:
      `val` encoded as a byte array

  - ### encodeShort

    void encodeShort(int val, byte[] buf, int off)
    Encode a short value into `buf` starting at offset `off` for `sizeOfShort()` bytes.

    NOTE: Implementations using 4 bytes to encode a short may choose to encode `val` (an int) as-is (which means the most significant two bytes can have a value other than 0x0000 or 0xFFFF, and a value of 0xFFFF (65_535) may be encoded as 0x0000_FFFF, and not as 0xFFFF_FFFF (-1). This behaviour may change at any time. For consistent behaviour, explicitly cast to short when calling this method.

    Parameters:
      `val` - value to be encoded
      `buf` - byte array of sufficient size (warning: this is datatype coder specific, see `sizeOfShort()`), never `null`
      `off` - offset to start encoding
    Since:
      4

  - ### decodeShort

    short decodeShort(byte[] buf)
    Decode a short value from `buf` from the first `sizeOfShort()` bytes.
    Parameters:
      `buf` - byte array of sufficient size (warning: this is datatype coder specific, see `sizeOfShort()`)
    Returns:
      short value from `buf`, or `0` when `buf` is `null`

  - ### decodeShort

    short decodeShort(byte[] buf, int off)
    Decode a short value from `buf` starting at offset `off` for `sizeOfShort()` bytes.
    Parameters:
      `buf` - byte array of sufficient size (warning: this is datatype coder specific, see `sizeOfShort()`), never `null`
      `off` - offset to start decoding
    Returns:
      short value from `buf`
    Since:
      4

  - ### encodeInt

    byte[] encodeInt(int val)
    Encode an int value as a byte array of 4 bytes.
    Parameters:
      `val` - value to be encoded
    Returns:
      `val` encoded as a byte array, or `0` when `buf` is `null`

  - ### encodeInt

    void encodeInt(int val, byte[] buf, int off)
    Encode an int value into `buf` starting at index `off` for 4 bytes.
    Parameters:
      `val` - value to be encoded
      `buf` - byte array of sufficient size, never `null`
      `off` - offset to start encoding
    Since:
      4

  - ### decodeInt

    int decodeInt(byte[] buf)
    Decode an int value from `buf` from the first 4 bytes.
    Parameters:
      `buf` - byte array of sufficient size
    Returns:
      int value decoded from `buf`, or `0` when `buf` is `null`

  - ### decodeInt

    int decodeInt(byte[] buf, int off)
    Decode an int value from `buf` starting at offset `off` for 4 bytes.
    Parameters:
      `buf` - byte array of sufficient size, never `null`
      `off` - offset to start decoding
    Returns:
      int value decoded from `buf`
    Since:
      4

  - ### encodeLong

    byte[] encodeLong(long val)
    Encode a long value as a byte array of 8 bytes.
    Parameters:
      `val` - value to be encoded
    Returns:
      `val` encoded as a byte array

  - ### decodeLong

    long decodeLong(byte[] buf)
    Decode a long value from `buf` from the first 8 bytes.
    Parameters:
      `buf` - byte array of sufficient size, or `0` when `buf` is `null`
    Returns:
      long value decoded from `buf`

  - ### encodeFloat

    byte[] encodeFloat(float val)
    Encode a float value as a byte array of 4 bytes.
    Parameters:
      `val` - value to be encoded
    Returns:
      `val` encoded as a byte array

  - ### decodeFloat

    float decodeFloat(byte[] buf)
    Decode a float value from `buf` from the first 4 bytes.
    Parameters:
      `buf` - byte array of sufficient size, or `0` when `buf` is `null`
    Returns:
      float value decoded from `buf`

  - ### encodeDouble

    byte[] encodeDouble(double val)
    Encode a double value as a byte array of 8 bytes.
    Parameters:
      `val` - value to be encoded
    Returns:
      `val` encoded as a byte array

  - ### decodeDouble

    double decodeDouble(byte[] buf)
    Decode a double value from `buf` from the first 8 bytes.
    Parameters:
      `buf` - byte array of sufficient size, or `0` when `buf` is `null`
    Returns:
      double value decoded from `buf`

  - ### encodeString

    byte[] encodeString(String val)
    Encode a `String` value as a byte array using the encoding of this datatype coder.
    Parameters:
      `val` - value to be encoded
    Returns:
      `val` encoded as a byte array, or `null` if `val` is `null`
    Since:
      4

  - ### createWriter

    Writer createWriter(OutputStream out)
    Creates a writer wrapping an input stream.
    Parameters:
      `out` - output stream
    Returns:
      writer applying the encoding of this datatype when writing
    Since:
      4

  - ### decodeString

    String decodeString(byte[] buf)
    Decode a `String` from `buf` using the encoding of this datatype coder.
    Parameters:
      `buf` - byte array to be decoded
    Returns:
      `String` decoded from `buf`, or `null` if `buf` is `null`
    Since:
      4

  - ### createReader

    Reader createReader(InputStream in)
    Creates a reader wrapping an input stream.
    Parameters:
      `in` - input stream
    Returns:
      reader applying the encoding of this datatype coder when reading
    Since:
      4

  - ### decodeBoolean

    boolean decodeBoolean(byte[] buf)
    Decode a boolean from `buf` from the first byte.
    Parameters:
      `buf` - (expected) 1 bytes
    Returns:
      `false` when 0, `true` for all other values, or `false` if `buf` is `null`

  - ### encodeBoolean

    byte[] encodeBoolean(boolean val)
    Encodes boolean as a byte array of 1 byte.
    Parameters:
      `val` - value to encode
    Returns:
      `true` as 1, `false` as 0.

  - ### decodeLocalTime

    LocalTime decodeLocalTime(byte[] buf)
    Decode `java.time.LocalTime` from `buf` from the first 4 bytes.
    Parameters:
      `buf` - (expected) at least 4 bytes
    Returns:
      `LocalTime` decoded from `buf`, or `null` if `buf` is `null`
    Since:
      5

  - ### decodeLocalTime

    LocalTime decodeLocalTime(byte[] buf, int off)
    Decode `java.time.LocalTime` from `buf` from the 4 bytes starting at `off`.
    Parameters:
      `buf` - (expected) at least 4 bytes from `off`, never `null`
      `off` - offset of the time value in `buf`
    Returns:
      `LocalTime` decoded from `buf`
    Since:
      6

  - ### encodeLocalTime

    byte[] encodeLocalTime(LocalTime val)
    Encode a `java.time.LocalTime` as a byte array of 4 bytes.
    Parameters:
      `val` - value to encode
    Returns:
      `val` encoded as a byte array, or `null` if `val` is `null`
    Since:
      5

  - ### encodeLocalTime

    void encodeLocalTime(LocalTime val, byte[] buf, int off)
    Encode a `java.time.LocalTime` to a byte array, requiring 4 bytes.
    Parameters:
      `val` - value to encode
      `buf` - byte array with at least 4 bytes starting at `off`, never `null`
      `off` - offset of the time value in `buf`
    Since:
      6

  - ### decodeLocalDate

    LocalDate decodeLocalDate(byte[] buf)
    Decode `java.time.LocalDate` from `buf` from the first 4 bytes.
    Parameters:
      `buf` - (expected) at least 4 bytes
    Returns:
      `LocalDate` decoded from `buf`, or `null` if `buf` is `null`
    Since:
      5

  - ### decodeLocalDate

    LocalDate decodeLocalDate(byte[] buf, int off)
    Decode `java.time.LocalDate` from `buf` from the 4 bytes starting at `off`.
    Parameters:
      `buf` - (expected) at least 4 bytes from `off`, never `null`
      `off` - offset of the time value in `buf`
    Returns:
      `LocalDate` decoded from `buf`
    Since:
      6

  - ### encodeLocalDate

    byte[] encodeLocalDate(LocalDate val)
    Encode a `java.time.LocalDate` as a byte array of 4 bytes.
    Parameters:
      `val` - value to encode
    Returns:
      `val` encoded as a byte array, or `null` if `val` is `null`
    Since:
      5

  - ### encodeLocalDate

    void encodeLocalDate(LocalDate val, byte[] buf, int off)
    Encode a `java.time.LocalDate` to a byte array, requiring 4 bytes.
    Parameters:
      `val` - value to encode
      `buf` - byte array with at least 4 bytes starting at `off`, never `null`
      `off` - offset of the date value in `buf`
    Since:
      6

  - ### decodeLocalDateTime

    LocalDateTime decodeLocalDateTime(byte[] buf)
    Decode `java.time.LocalDateTime` from `buf` from the first 8 bytes.
    Parameters:
      `buf` - (expected) at least 8 bytes
    Returns:
      `LocalDateTime` decoded from `buf`, or `null` if `buf` is `null`
    Since:
      5

  - ### decodeLocalDateTime

    LocalDateTime decodeLocalDateTime(byte[] buf, int off)
    Decode `java.time.LocalDateTime` from `buf` from the 8 bytes starting at `off`.
    Parameters:
      `buf` - (expected) at least 8 bytes from `off`, never `null`
      `off` - offset of the datetime value in `buf`
    Returns:
      `LocalDateTime` decoded from `buf`
    Since:
      6

  - ### encodeLocalDateTime

    byte[] encodeLocalDateTime(LocalDateTime val)
    Encode a `java.time.LocalDateTime` as a byte array of 8 bytes.
    Parameters:
      `val` - value to encode
    Returns:
      `val` encoded as a byte array, or `null` if `val` is `null`
    Since:
      5

  - ### encodeLocalDateTime

    void encodeLocalDateTime(LocalDateTime val, byte[] buf, int off)
    Encode a `java.time.LocalDateTime` to a byte array, requiring 8 bytes.
    Parameters:
      `val` - value to encode
      `buf` - byte array with at least 8 bytes starting at `off`, never `null`
      `off` - offset of the datetime value in `buf`
    Since:
      6

  - ### decodeDecimal64

    Decimal64 decodeDecimal64(byte[] buf)
    Decodes a decimal64 from a byte array of 8 bytes.
    Parameters:
      `buf` - data to decode (expects exactly 8 bytes)
    Returns:
      Decimal64 decoded from `buf`, or `null` if `buf` is `null`

  - ### encodeDecimal64

    byte[] encodeDecimal64(Decimal64 val)
    Encodes a decimal64 as a byte array of 8 bytes.
    Parameters:
      `val` - value to be encoded
    Returns:
      `val` encoded as a byte array, or `null` if `val` is `null`

  - ### decodeDecimal128

    Decimal128 decodeDecimal128(byte[] buf)
    Decodes a decimal128 from a byte array of 16 bytes.
    Parameters:
      `buf` - data to decode (expects exactly 16 bytes)
    Returns:
      Decimal128 decoded from `buf`, or `null` if `buf` is `null`

  - ### encodeDecimal128

    byte[] encodeDecimal128(Decimal128 val)
    Encodes a decimal128 as a byte array of 16 bytes.
    Parameters:
      `val` - value to be encoded
    Returns:
      `val` encoded as a byte array, or `null` if `val` is `null`

  - ### decodeInt128

    BigInteger decodeInt128(byte[] buf)
    Decodes a BigInteger from a byte array of 16 bytes (int128 format).
    Parameters:
      `buf` - data to decode (expects exactly 16 bytes)
    Returns:
      BigInteger decoded from `buf`, or `null` if `val` is `null`

  - ### encodeInt128

    byte[] encodeInt128(BigInteger val)
    Encodes a BigInteger as a byte array of 16 bytes (int128 format).

    The implementation expects to be passed a value that fits in 16 bytes. If a larger value is passed, an `IllegalArgumentException` is thrown.

    Parameters:
      `val` - value to be encoded
    Returns:
      `val` encoded as a byte array, or `null` if `val` is `null`

  - ### getEncodingFactory

    IEncodingFactory getEncodingFactory()
    Returns:
      encoding factory.

  - ### getEncodingDefinition

    EncodingDefinition getEncodingDefinition()
    Returns:
      encoding definition used by this datatype coder for string conversions.

  - ### getEncoding

    Encoding getEncoding()
    Returns:
      encoding used by this datatype coder for string conversions.

  - ### forEncodingDefinition

    DatatypeCoder forEncodingDefinition(EncodingDefinition encodingDefinition)
    Return a derived datatype coder that applies the supplied encoding definition for string conversions.
    Parameters:
      `encodingDefinition` - encoding definition
    Returns:
      derived datatype coder (this instance, if encoding definition is the same)
    Since:
      4

  - ### unwrap

    DatatypeCoder unwrap()
    Unwrap this datatype coder to its parent (or itself).
    Returns:
      parent of this datatype code, or itself if it has no parent.
    Since:
      4.0

  - ### equals

    boolean equals(Object other)

    Equality: same basic type (i.e.: wire protocol/JNA type + endianness) and same encoding definition.

    This does not need to take into account the encoding factory, as usage should be limited to datatype coders derived from the same connection.

    Overrides:
      `equals` in class `Object`
    Parameters:
      `other` - object to compare to
    Returns:
      `true` if other is an equivalent datatype coder.

  - ### hashCode

    int hashCode()
    Overrides:
      `hashCode` in class `Object`