Asynchronous XML-to-JSON Conversion

New Feature: Asynchronous XML-to-JSON Conversion

XML.toJSONObjectAsync(...)
A new asynchronous method toJSONObjectAsync has been introduced to improve performance when working with large XML files. This feature wraps the existing synchronous XML.toJSONObject(Reader) method with CompletableFuture to provide non-blocking execution.

Method Signature
public static void toJSONObjectAsync(
Reader reader,
Consumer onSuccess,
Consumer onError)

Parameters

1. Reader reader: Input reader containing XML data.
2. Consumer onSuccess: Callback function invoked with the resulting JSONObject if parsing is successful.
3. Consumer onError: Callback function invoked with the exception if parsing fails.

Implementation Highlights

• Internally uses CompletableFuture.supplyAsync(...) to offload XML parsing to a background thread.
• Preserves existing logic from the synchronous XML.toJSONObject(...) method.
• Uses CompletionException wrapping for proper exception propagation.

Example Usage
XML.toJSONObjectAsync(
new FileReader("largefile.xml"),
jsonObject -> System.out.println("Parsed JSON: " + jsonObject),
error -> System.err.println("Error: " + error.getMessage())
);

Use Case
This method is ideal for:

• Handling large XML files without blocking the main thread.
• UI applications where responsiveness is critical.
• Server-side environments where non-blocking IO is preferred.

Backward Compatibility
No breaking changes. The existing synchronous XML.toJSONObject(...) methods remain fully supported.

Additional Notes
The asynchronous execution is performed using the common ForkJoinPool. For more advanced use cases, future releases may provide overloads accepting a custom ExecutorService.

Streaming is On Mates

Feature Description

JSONObject.toStream(): New public method that returns a sequential Stream traversing every node (objects, arrays, and primitive leaves) in depth-first order. Enables fluent chaining of all Stream operations (forEach, map, filter, collect, etc.).
JSONNode utility class : Lightweight record delivered by the stream, exposing• getKey() & getValue()• getPath() (JSON-pointer-style, e.g. root/arr[0]/id)• getParent() reference• helpers isLeaf(), typed getters (getStringValue(), getIntValue() …) and updateValue() for in-place mutation of the underlying JSONObject.
JSONNodeSpliterator (internal) : Depth-first spliterator powering toStream(); protects against circular references, includes array indices in paths, and delivers nodes lazily (small memory footprint).
Extensive JUnit coverage : Three new test suites (> 100 assertions) proving full traversal, stream chaining (filter → map → collect), in-place updates, path correctness, and leaf detection—all existing JSON-java tests still pass.

No breaking changes. All additions are backward-compatible; existing codebases compile unchanged. Requires Java 8+ (Streams API).

---

🔧 Quick Example

JSONObject obj = XML.toJSONObject(
    "<Books>" +
      "<book><title>A</title><price>10</price></book>" +
      "<book><title>B</title><price>20</price></book>" +
    "</Books>");
// Collect all titles

List<String> titles = obj.toStream()

.filter(n -> "title".equals(n.getKey()))

.map(JSONNode::getStringValue)

.collect(Collectors.toList());
// Discount every numeric price by 25 %

obj.toStream()

.filter(n -> "price".equals(n.getKey()) && n.getValue() instanceof Number)

.forEach(n -> n.updateValue(((Number) n.getValue()).doubleValue() * 0.75));

---

XML Key Transformation & JSONNode Streaming Enhancements

New Features

XML Key Transformation Support

• Added overloaded method: XML.toJSONObject(Reader reader, KeyTransformer keyTransformer)
• Accepts a functional interface KeyTransformer to apply custom transformations to XML element names and attribute keys during parsing.
• Enables dynamic key transformation (e.g., prefixing, reversing, pattern-based changes) during XML to JSON conversion.
• Transformation is applied inline while parsing, eliminating post-processing passes.

KeyTransformer Functional Interface

• Introduced KeyTransformer interface under XML class.
• Simplifies providing custom key transformation logic via lambda expressions or method references.

Performance Considerations

• Key transformation is now applied during XML parsing (streaming approach).
• Reduces overhead of traversing and mutating the entire JSONObject after parsing.
• Improves time and space efficiency for large XML documents.

Enhancements

JSONNode Utility Class

• Represents a node in the JSON structure with path tracking.
• Supports getters for path, key, value, and parent.
• Provides utility methods: isLeaf(), isObject(), isArray(), and type-safe value accessors (getStringValue(), getIntValue(), etc.).

JSONNodeSpliterator Implementation

• Spliterator-based traversal of JSONObject with:
• Recursive streaming.
• Leaves-only streaming.
• Flat (top-level) streaming.
• Handles cycles to prevent infinite recursion in deeply nested or circular structures.

Streaming APIs in JSONObject

• Added methods to JSONObject:
• toStream() — streams all nodes (recursive).
• toLeafStream() — streams only leaf nodes.
• toFlatStream() — streams top-level nodes without descending into nested objects.
• Provides functional access to JSONObject nodes for querying and manipulation.

Unit Tests Added

Tests for:

• Simple and nested JSONObject streaming.
• JSONArray streaming with path validation.
• Leaf-only and flat-only stream correctness.
• XML parsing with identity key transformation.
• Complex XML documents with transformed keys and validation on extracted data.
• Validated correctness of city extraction and computed metrics (average age) using new streaming API.

Milestone2

Feature Enhancements:

1) Selective XML to JSON Conversion via JSONPointer

• Introduced an optimized toJSONObject(Reader reader, JSONPointer path) method to extract only a specific subtree of an XML document based on a JSONPointer.
• Uses a streaming XML parser to avoid full document parsing, improving performance for large XML files.
• Supports normalization of trailing slashes in path inputs.

2) XML Subtree Replacement Support

• Added overloaded method toJSONObject(Reader reader, JSONPointer path, JSONObject replacement) to allow replacing a subtree at a specified path with a provided JSON object.
• Handles both shallow (1–2 levels) and deep paths using efficient parsing strategies.
• Special handling added for trailing slashes: when present, the content inside the target is replaced, not the key itself.

3) Public API Exposure for JSON Pointer Token Processing

• Made unescapeToken(String token) publicly accessible for consistent token unescaping across modules.

Infrastructure Improvements:

• Added CountingReader, a custom reader wrapper that tracks the parsing progress in character count, helping