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.