Module com.darkcollective.relix.json
Package com.darkcollective.relix.json

Class JsonWriter

java.lang.Object
com.darkcollective.relix.json.JsonWriter
public final class JsonWriter extends Object
A minimal, dependency-free streaming writer for JSON text.

The writer is a fluent builder. Callers open and close containers with beginObject()/endObject() and beginArray()/endArray(), label object members with name(String), and emit scalars with the value overloads. Output is compact (no insignificant whitespace) and every string — both names and string values — is escaped per the JSON specification.

Structural guarantees

The writer fails fast with an IllegalStateException on misuse, so a buggy serializer cannot silently produce malformed JSON:
  • name(String) is only valid inside an object, and must precede each member value (no two names in a row, no name without a value).
  • A value inside an object must be preceded by a name(String).
  • endObject()/endArray() must match the currently open container, and an object may not be closed with a dangling name.
  • At most one value may be written at the top level.

Example


 String json = new JsonWriter()
     .beginObject()
         .name("op").value("Projection")
         .name("schema").beginArray()
             .beginObject().name("name").value("id").name("type").value("N").endObject()
         .endArray()
         .name("children").beginArray().endArray()
     .endObject()
     .toJson();
 // {"op":"Projection","schema":[{"name":"id","type":"N"}],"children":[]}

Instances are not thread-safe and are intended for single-pass use.

  • Constructor Details

    • JsonWriter

      public JsonWriter()
      Creates an empty writer.

  • Method Details

    • beginObject

      public JsonWriter beginObject()
      Begins a JSON object ({}).
      Returns:
      this writer, for chaining
      Throws:
      IllegalStateException - if a value is not permitted at this position

    • endObject

      public JsonWriter endObject()
      Ends the current JSON object.
      Returns:
      this writer, for chaining
      Throws:
      IllegalStateException - if no object is open, or a name was written without a following value

    • beginArray

      public JsonWriter beginArray()
      Begins a JSON array ([]).
      Returns:
      this writer, for chaining
      Throws:
      IllegalStateException - if a value is not permitted at this position

    • endArray

      public JsonWriter endArray()
      Ends the current JSON array.
      Returns:
      this writer, for chaining
      Throws:
      IllegalStateException - if no array is open

    • name

      public JsonWriter name(String name)
      Writes an object member name. Must be followed by exactly one value.
      Parameters:
      name - the member name; must not be null
      Returns:
      this writer, for chaining
      Throws:
      IllegalStateException - if not currently inside an object, or a name was already written without a value

    • value

      public JsonWriter value(String value)
      Writes a string value, or JSON null if value is null.
      Parameters:
      value - the string, or null for JSON null
      Returns:
      this writer, for chaining

    • value

      public JsonWriter value(long value)
      Writes an integral number value.
      Parameters:
      value - the number
      Returns:
      this writer, for chaining

    • value

      public JsonWriter value(double value)
      Writes a floating-point number value.
      Parameters:
      value - the number; must be finite
      Returns:
      this writer, for chaining
      Throws:
      IllegalArgumentException - if value is NaN or infinite (JSON has no representation for these)

    • value

      public JsonWriter value(boolean value)
      Writes a boolean value.
      Parameters:
      value - the boolean
      Returns:
      this writer, for chaining

    • nullValue

      public JsonWriter nullValue()
      Writes an explicit JSON null value.
      Returns:
      this writer, for chaining

    • toJson

      public String toJson()
      Returns the completed JSON document.
      Returns:
      the JSON text
      Throws:
      IllegalStateException - if any object/array is still open, or no value has been written

    • toString

      public String toString()
      Returns the JSON written so far, without checking for completeness. Useful for diagnostics; prefer toJson() for finished output.
      Overrides:
      toString in class Object
      Returns:
      the current buffer contents