Package com.apicatalog.tree.io

Interface TreeGenerator

All Known Implementing Classes:
NativeMaterializer
public interface TreeGenerator
Provides a uniform, event-based abstraction for constructing tree-like data structures. This interface decouples the process of describing a tree from its final representation.

It is the conceptual counterpart to TreeAdapter, which reads tree structures.

While this interface can be implemented and driven manually, it is often used as a target for a TreeTraversal. The visitor traverses a source tree (read via a TreeAdapter) and calls the appropriate methods on this generator, effectively enabling powerful tree transformation and conversion workflows.

Implementations can use this sequence of construction events for two main purposes:

  1. Serialization: Writing the structure directly to an output stream in a specific format (e.g., text-based JSON, XML, YAML, or binary formats like CBOR).
  2. Materialization: Building a concrete, in-memory object model or document tree.

This approach is analogous to streaming parsers like SAX or StAX, but for generation rather than parsing. The generator is stateful and forward-only, expecting methods to be called in a valid sequence.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    beginList()
    Begins a new list (or array) structure.
    void
    beginMap()
    Begins a new map (or object) structure.
    void
    beginSet()
    Begins a new set structure.
    void
    binaryValue(byte[] value)
    Adds a binary data value to the current context.
    void
    booleanValue(boolean value)
    Adds a boolean value to the current context.
    void
    end()
    Ends the current map or collection structure.
    Features
    features()
     
    void
    nullValue()
    Adds a null value to the current context.
    void
    numericValue(double value)
    Adds a double-precision floating-point value to the current context.
    void
    numericValue(long value)
    Adds a long integer value.
    void
    numericValue(BigDecimal value)
    Adds an arbitrary-precision decimal value to the current context.
    void
    numericValue(BigInteger value)
    Adds an arbitrary-precision integer value.
    void
    stringValue(String value)
    Adds a string value.

  • Method Details

    • features

      Features features()

    • nullValue

      void nullValue() throws TreeIOException
      Adds a null value to the current context.
      Throws:
      TreeIOException - if an I/O error occurs during construction.

    • booleanValue

      void booleanValue(boolean value) throws TreeIOException
      Adds a boolean value to the current context.
      Parameters:
      value - the boolean value to add.
      Throws:
      TreeIOException - if an I/O error occurs during construction.

    • stringValue

      void stringValue(String value) throws TreeIOException
      Adds a string value. Depending on the context, this could represent a map key, a value associated with a key, or an element in a collection.
      Parameters:
      value - the non-null string value to add.
      Throws:
      TreeIOException - if an I/O error occurs during construction.

    • numericValue

      void numericValue(long value) throws TreeIOException
      Adds a long integer value. Depending on the context, this could represent a map key (in formats like CBOR), a value, or a collection element.
      Parameters:
      value - the long value to add.
      Throws:
      TreeIOException - if an I/O error occurs during construction.

    • numericValue

      void numericValue(BigInteger value) throws TreeIOException
      Adds an arbitrary-precision integer value. Depending on the context, this could represent a map key, a value, or a collection element.
      Parameters:
      value - the non-null BigInteger value to add.
      Throws:
      TreeIOException - if an I/O error occurs during construction.

    • numericValue

      void numericValue(double value) throws TreeIOException
      Adds a double-precision floating-point value to the current context.
      Parameters:
      value - the double value to add.
      Throws:
      TreeIOException - if an I/O error occurs during construction.

    • numericValue

      void numericValue(BigDecimal value) throws TreeIOException
      Adds an arbitrary-precision decimal value to the current context.
      Parameters:
      value - the non-null BigDecimal value to add.
      Throws:
      TreeIOException - if an I/O error occurs during construction.

    • binaryValue

      void binaryValue(byte[] value) throws TreeIOException
      Adds a binary data value to the current context. The specific encoding (e.g., Base64 for JSON, or direct bytes for CBOR) is determined by the underlying implementation.
      Parameters:
      value - the non-null byte array to add.
      Throws:
      TreeIOException - if an I/O error occurs during construction.

    • beginMap

      void beginMap() throws TreeIOException
      Begins a new map (or object) structure. After this call, the generator expects a sequence of key-value pairs.

      The type of a key is determined by the target format. For formats like JSON, keys are strings added via stringValue(String). For others, like CBOR, keys can also be other types.

      Every call to this method must be matched by a corresponding call to end().
      Throws:
      TreeIOException - if an I/O error occurs during construction.

    • beginList

      void beginList() throws TreeIOException
      Begins a new list (or array) structure. An ordered collection that allows duplicates. After this call, subsequent calls are expected to be the elements of the list. Every call to this method must be matched by a corresponding call to end().
      Throws:
      TreeIOException - if an I/O error occurs during construction.

    • beginSet

      void beginSet() throws TreeIOException
      Begins a new set structure. An unordered collection of unique elements. After this call, subsequent calls are expected to be the elements of the set. Every call to this method must be matched by a corresponding call to end().
      Throws:
      TreeIOException - if an I/O error occurs during construction.

    • end

      void end() throws TreeIOException
      Ends the current map or collection structure. This call must match a preceding beginMap() or beginList().
      Throws:
      TreeIOException - if an I/O error occurs during construction.