Package io.codemine.java.postgresql.codecs

Interface Codec<A>

Type Parameters:
A - the type of the value
All Known Implementing Classes:
CompositeCodec, EnumCodec
public interface Codec<A>
A codec for a single scalar value.

Each codec supports two wire formats:

  • Field Details

  • Method Details

    • bit

      static Codec<Bit> bit(int n)
      Returns a codec for PostgreSQL bit(n) — a fixed-length bit string of exactly n bits.

      If n <= 0, this returns the unparameterized BIT codec.

    • varbit

      static Codec<Bit> varbit(int n)
      Returns a codec for PostgreSQL varbit(n) — a variable-length bit string of at most n bits.

      If n <= 0, this returns the unparameterized VARBIT codec.

    • varchar

      static Codec<String> varchar(int n)
      Returns a codec for PostgreSQL varchar(n) — a variable-length character string of at most n characters.

      If n <= 0, this returns the unparameterized VARCHAR codec.

    • money

      static Codec<BigDecimal> money(int decimals)
      Returns a codec for PostgreSQL money — a monetary amount stored as a scaled integer.

      The decimals parameter specifies the number of fractional decimal digits, which is determined by the database's lc_monetary locale setting. The most common value is 2 (cents), but locales without a fractional unit (e.g. Japanese yen) use 0.

      Parameters:
      decimals - the number of fractional digits (must be ≥ 0)

    • bpchar

      static Codec<String> bpchar(int n)
      Returns a codec for PostgreSQL bpchar(n) — a fixed-length blank-padded character string of exactly n characters.

    • schema

      default String schema()
      Returns the PostgreSQL schema name for this type, or empty string or null if the type is in the default search path.

    • name

      String name()
      Returns the PostgreSQL type name (e.g. "int4", "text").

    • dimensions

      default int dimensions()
      Returns the number of array dimensions for this codec. 0 for scalar codecs; n for n-dimensional array codecs.

    • typeSig

      default String typeSig()
      Returns the full PostgreSQL type signature, including schema if applicable.

    • inDim

      default Codec<List<A>> inDim()
      Returns an array codec whose element type is this codec. The returned codec uses PostgreSQL's array literal syntax ({elem1,elem2,...} or {elem1;elem2;...}) for text format and the standard binary array header for binary format.

    • scalarOid

      default int scalarOid()
      Returns the PostgreSQL base-type OID, or 0 if not statically known (e.g. user-defined composite types).

      The OID is used inside binary-format array and composite headers to tag each element with its type.

    • arrayOid

      default int arrayOid()
      Returns the PostgreSQL array-type OID for this element type, or 0 if not known.

    • oid

      default int oid()
      Returns the OID for this type: array OID when dimensions() > 0, else scalar OID.

    • jdbcType

      default int jdbcType()
      Returns the JDBC Types constant that best represents this PostgreSQL type.

    • encodeInText

      void encodeInText(StringBuilder sb, A value)
      Writes the given value to the string builder in PostgreSQL textual literal form.

      This is primarily used for encoding fields inside composite and array literals. The written form must be the canonical text representation accepted by PostgreSQL for the type.

    • encodeInTextToString

      default String encodeInTextToString(A value)
      Encodes the given non-null value as a PostgreSQL text literal and returns it as a String. Convenience wrapper around encodeInText(StringBuilder, Object).

    • decodeInText

      Codec.ParsingResult<A> decodeInText(CharSequence input, int offset) throws Codec.DecodingException
      Parses a PostgreSQL text-format literal of type A from input starting at offset.

      The input must be a non-null CharSequence holding the raw text as returned by the PostgreSQL server (e.g. the string value of a column obtained via ResultSet.getString(int)). Passing the String directly avoids an extra copy compared to converting to a char[] first. NULL column values must be handled by the caller before invoking this method.

      Returns the parsed value together with the offset of the first character that was not consumed, allowing callers to continue parsing subsequent fields without copying the input. Throws Codec.DecodingException if the input cannot be interpreted as a valid literal of type A.

      Throws:
      Codec.DecodingException

    • decodeInTextFromString

      default A decodeInTextFromString(String input) throws Codec.DecodingException
      Decodes a PostgreSQL text-format literal of type A from the given string. Convenience wrapper around decodeInText(CharSequence, int) that passes the full string starting at offset 0.
      Throws:
      Codec.DecodingException - if the input cannot be interpreted as a valid literal of type A

    • encodeInBinary

      void encodeInBinary(A value, ByteArrayOutputStream out)
      Encodes the given non-null value into the PostgreSQL binary wire format, appending the bytes directly to out.

      Appends exactly the binary payload for the value — no length prefix. The caller (e.g. CompositeCodec) is responsible for prepending the 4-byte int32 length header required by the PostgreSQL composite and array binary protocols.

      The byte order is always big-endian, as required by the PostgreSQL wire protocol.

      Throws:
      UnsupportedOperationException - if binary encoding is not implemented for this type

    • encodeInBinaryToBytes

      default byte[] encodeInBinaryToBytes(A value)
      Convenience overload that encodes the value into a freshly-allocated byte array and returns it. Delegates to encodeInBinary(Object, ByteArrayOutputStream).

    • encodeInBinaryToByteBuffer

      default ByteBuffer encodeInBinaryToByteBuffer(A value)
      Convenience overload that encodes the value into a ByteBuffer. Delegates to encodeInBinaryToBytes(Object).

    • decodeInBinary

      A decodeInBinary(ByteBuffer buf, int length) throws Codec.DecodingException
      Decodes a value from the PostgreSQL binary wire format.

      buf must be a big-endian ByteBuffer positioned at the first byte of the value's payload. length is the number of bytes that make up the payload (as read from the preceding int32 length header). The method advances the buffer position by exactly length bytes.

      NULL handling (length == -1) must be performed by the caller before invoking this method.

      Throws:
      Codec.DecodingException - if the binary data is malformed
      UnsupportedOperationException - if binary decoding is not implemented for this type

    • decodeInBinaryFromBytes

      default A decodeInBinaryFromBytes(byte[] bytes) throws Codec.DecodingException
      Decodes a value from a byte array in the PostgreSQL binary wire format. Convenience wrapper around decodeInBinary(ByteBuffer, int).
      Throws:
      Codec.DecodingException - if the binary data is malformed
      UnsupportedOperationException - if binary decoding is not implemented for this type

    • random

      A random(Random r, int size)
      Generates a random value of type A, for testing purposes. The provided Random instance should be used as the source of randomness, and the generated values should cover a wide range of possible inputs, including edge cases.

      The size parameter follows the QuickCheck convention: it is a non-negative integer that controls the "size" of the generated value — for scalars it bounds the magnitude, for collections it bounds the number of elements, and for multidimensional arrays it is propagated uniformly to all sub-arrays so that the resulting array has a rectangular shape.

    • map

      default <B> Codec<B> map(Function<A,B> to, Function<B,A> from)
      Returns a new codec that maps values of type A to type B using the provided pair of mapping functions. The returned codec encodes and decodes values of type B by delegating to this codec for the underlying A values.
      Type Parameters:
      B - the target value type
      Parameters:
      to - function mapping from A to B
      from - function mapping from B back to A
      Returns:
      a new codec for values of type B

    • withType

      default Codec<A> withType(String schema, String name)
      Returns a new codec for a PostgreSQL domain type based on this codec. The returned codec uses the provided schema and name as its type identity but delegates all encoding and decoding to this codec. The OIDs default to 0 (unknown), which is appropriate when the domain's OID is not statically known.

      Example — defining a domain CREATE DOMAIN positive_amount AS numeric CHECK (VALUE > 0): 

      
 Codec<BigDecimal> positiveAmount = Codec.NUMERIC.withType("", "positive_amount");
      Parameters:
      schema - the PostgreSQL schema, or empty/null for the default search path
      name - the PostgreSQL domain type name
      Returns:
      a new codec for the domain type

    • withType

      default Codec<A> withType(String schema, String name, int scalarOid, int arrayOid)
      Returns a new codec for a PostgreSQL domain type based on this codec, with explicit OIDs. Use this overload when the domain's OIDs are known ahead of time (e.g. looked up from pg_type).
      Parameters:
      schema - the PostgreSQL schema, or empty/null for the default search path
      name - the PostgreSQL domain type name
      scalarOid - the PostgreSQL scalar OID for this domain type
      arrayOid - the PostgreSQL array OID for this domain type
      Returns:
      a new codec for the domain type