Add newline-delimited WireType.JSONL (JSON Lines) alongside comma-separated WireType.JSON_ONLY

[peter-lawrey]

This PR introduces newline-separated JSON Lines support via WireType.JSONL, while keeping the existing comma-separated stream behaviour available via WireType.JSON_ONLY.

WireType.JSONL is intended for streaming/log-style use cases where each message is a complete JSON object on its own line ({...}\n{...}\n). It also adds a JSON-specific reader that can safely consume both JSONL and legacy comma-separated JSON streams.

Motivation

WireType.JSON_ONLY currently emits a comma-separated JSON stream, which is awkward for line-oriented tooling and streaming pipelines. JSONL is a widely used convention that makes record boundaries explicit, supports incremental processing, and plays nicely with “tail -f”, log shippers, and batch ingestion.

What changed

• New WireType.JSONL

  • Text wire that outputs one JSON document per line (newline terminated).
  • Defaults to no type metadata (useTypes(false)), and uses JSONL-friendly conventions.

• JSONWire JSONL mode (useJsonlDocuments)

  • Adds a jsonlMode flag to preserve JSONL contexts.

  • Configures JSONL defaults:

    • useTypes(false)
    • useLowerCaseEnums(true) (configurable)
    • JSONL-specific read/write contexts

  • Overrides methodWriter() in JSONL mode to avoid the parent useTextDocuments() call overwriting the JSONL contexts.

• JSONLReadDocumentContext

  • JSON-specific read context that finds document boundaries by tracking brace/array depth (and respecting JSON strings/escapes), rather than YAML markers.

  • Accepts both:

    • newline-delimited JSONL ({...}\n{...}\n)
    • comma-separated JSON streams ({...},{...},{...})

  • Strips outer braces when presenting the document body to the reader (matching the existing “document wrapper” behaviour).

• JSONLWriteDocumentContext

  • Ensures each document is a complete JSON object:

    • Wraps output in { ... }
    • Appends \n after each document

  • Produces valid JSONL output for method writer streaming:

    • {"event":[...]}
    • {"event":[...]}

• Lowercase enum serialisation

  • Adds useLowerCaseEnums(boolean) and implements lowercase output for enums (including untyped enum values) without allocating new strings.

Output format examples

• Method writer (JSONL)

  {"event":["first",1 ]}
  {"event":["second",2 ]}
  {"event":["third",3 ]}
  

• Object write note

  • Double braces are expected in some paths because the document context adds outer braces and the reader strips them when exposing content.

Test plan

• Added/expanded JSONLTest with streaming coverage:

  • testMethodReaderStreamingJsonl – reads multiple newline-delimited events

  • testMethodReaderCommaSeparatedJson – reads comma-separated JSON streams

  • testWriteJsonReadJsonl – verifies WireType.JSON_ONLY output is readable by the JSONL reader

  • testWriteJsonlReadJson – verifies JSONL round-trip

  • Existing JSONL suite: 33 tests pass (1 skipped)

    • mvn -Dtest=JSONLTest test

Compatibility

• WireType.JSON_ONLY behaviour remains unchanged.
• WireType.JSONL provides a line-oriented alternative and a reader tolerant of both newline and comma delimiters, easing migration and mixed-stream handling.

[sonarqubecloud]

Quality Gate passed

Issues
70 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[tgd]

Well-implemented JSONL support with excellent test coverage. Approving with minor suggestions.

[tgd]

Suggestion: This empty close() override just calls super.close() and can be removed - it adds no behavior.

[tgd]

Suggestion: Consider localizing the @SuppressWarnings("deprecation") to the specific method(s) that use deprecated APIs rather than suppressing it class-wide. This makes it clearer which code paths touch deprecated APIs.

[tgd]

Suggestion: Consider adding a thread-safety note to the Javadoc, e.g.:

 * <p>Thread safety: The returned wire instance is not thread-safe.

This matches the documentation style in the test class.