Class DittoQueryResultItem

java.lang.Object
com.ditto.java.DittoQueryResultItem
All Implemented Interfaces:
Closeable, AutoCloseable
public final class DittoQueryResultItem extends Object implements Closeable

Represents a single match of a DQL query, similar to a "row" in SQL terms.

This is a reference type serving as a "cursor", allowing for efficient access of the underlying data in various formats (Dictionary, CBOR, or JSON).

The getValue() method lazily materializes the value and keeps it in memory until the item goes out of scope or dematerialize() is called. To reduce memory footprint, structure your code so items can be processed as a stream (one by one or in batches) and dematerialize them immediately after use.

This class implements Closeable for resource management. Use try-with-resources statements for automatic cleanup.

See Also:

  • Method Details

    • getValue

      public @NonNull DittoCborSerializable.Dictionary getValue()

      Returns the content as a materialized dictionary.

      The item's value is materialized on first access and subsequently on each access after calling dematerialize(). Once materialized, the value is kept in memory until explicitly dematerialized or the item goes out of scope.

      Returns:
      the item's content as a DittoCborSerializable.Dictionary.
      See Also:

    • isMaterialized

      public boolean isMaterialized()
      Returns whether the value is currently materialized in memory.
      Returns:
      true if the value is materialized, false otherwise.
      See Also:

    • materialize

      public @Nullable DittoCborSerializable.Dictionary materialize() throws DittoException

      Loads and materializes the item's content into memory.

      This method loads the CBOR representation of the item's content and decodes it into a dictionary that can be accessed via getValue(). The dictionary is kept in memory until dematerialize() is called. This is a no-op if the value is already materialized.

      Returns:
      a DittoCborSerializable.Dictionary containing the item's data, or null.
      Throws:
      DittoException - if there is a problem retrieving or decoding the data.
      See Also:

    • dematerialize

      public void dematerialize()

      Releases the materialized value from memory.

      Call this method to free memory after processing an item. This is a no-op if the item is not currently materialized.

      See Also:

    • getCborData

      public byte[] getCborData()

      Returns the content of the item as raw CBOR data.

      Important: The returned CBOR data is not cached. Call this method once and keep the result for as long as needed to avoid unnecessary recomputation.

      Returns:
      a byte array containing the CBOR-encoded data.

    • getJsonString

      public @NonNull String getJsonString()

      Returns the content of the item as a JSON string.

      Important: The returned JSON string is not cached. Call this method once and keep the result for as long as needed to avoid unnecessary recomputation.

      Returns:
      a JSON string representation of the item's content.

    • close

      public void close() throws IOException

      Closes this query result item and releases associated resources.

      This method should be called when the item is no longer needed to free resources. Use try-with-resources statements for automatic cleanup.

      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException - if an I/O error occurs during cleanup.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

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