Package com.clickhouse.client.api.data_formats.internal

Class StringValue

java.lang.Object
com.clickhouse.client.api.data_formats.internal.StringValue
public class StringValue extends Object
Read-time holder for ClickHouse String or FixedString values that preserves raw bytes to avoid lossy decoding and unnecessary allocations.

This is an internal value holder, not a general-purpose type for user code. It is produced only by the read path when the binary-string feature is enabled (for example GenericRecord.getObject or BinaryStreamReader.readValue without a type hint), so that callers that need exact bytes can obtain them via toByteArray() and callers that need text can decode via asString(). Instances cannot be created by user code: the constructors are package-private and only the binary reader builds them. It is not a supported field type for POJO binding: declare POJO fields for String/FixedString columns as String or byte[] instead. Normal application code should generally consume String or byte[] rather than holding onto a StringValue.

This is a mutable structure and must be used with care. To avoid copying, it does not duplicate the bytes it is given: the constructor wraps the supplied array instead of copying it, and toByteArray() returns a direct reference to the backing array when the value spans the whole array. Consequently, mutating the source array, the array returned by toByteArray(), or reading the same value concurrently while it is being modified will change the observed value. Callers that need an independent snapshot must copy the bytes themselves.

Backed by a ByteBuffer for a richer API and future off-heap memory support. The decoded String produced by asString() is cached.

  • Field Details

  • Method Details

    • asByteBuffer

      public ByteBuffer asByteBuffer()
      Returns a read-only view over the raw bytes of this value. The returned buffer is independent (its own position/limit) and shares no mutable state with this value.
      Returns:
      read-only buffer positioned at the first byte of the value

    • toByteArray

      public byte[] toByteArray()
      Returns the raw bytes of this value, honoring the backing buffer's offset and position.

      As a zero-copy shortcut, when the value spans the entire backing array the live backing storage is returned directly (mutating it mutates this value); otherwise an exact-size copy of the value's bytes is returned. Callers that need a guaranteed independent snapshot should copy the result themselves.

      Returns:
      the value bytes (the live backing array when it spans the whole value, otherwise a copy)

    • size

      public int size()
      Returns:
      number of bytes in this value

    • isEmpty

      public boolean isEmpty()
      Returns:
      true if the value has no bytes

    • asString

      public String asString()
      Decodes the value using the default charset (UTF-8 unless another was provided at construction). The result is cached so repeated calls do not allocate a new string.
      Returns:
      decoded string

    • asString

      public String asString(Charset charset)
      Decodes the value using the given charset. The result is cached only when the charset matches the default charset of this value.
      Parameters:
      charset - charset to decode with (not null)
      Returns:
      decoded string

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object