Add `ArrayNode JsonNode.asArray()` helper method

[cowtowncoder]

(note: part of https://github.com/FasterXML/jackson-future-ideas/wiki/JSTEP-3 changes)

(inspired by FasterXML/jackson-dataformat-xml#695)

With some JSON structures (as well as other formats, most notably XML), there is sometimes need to process/express things such that single-values that are not express as (JSON) Arrays would be handled same as 1-element arrays. Example shown with XML is that following documents:

    <list>
        <element>
            <a>value 1a</a>
            <b>value 1b</b>
        </element>
        <element>
            <a>value 2a</a>
            <b>value 2b</b>
        </element>
    </list>

    <list>
        <element>
            <a>value a</a>
            <b>value b</b>
        </element>
    </list>

become different JsonNodes structurally: basically equivalent of JSON like so:

{ "list":
    "element": [
        { ... },
       { .... }
   ]
}

{ "list":
     "element": {
          "a": "value a",
          "b": "value b"
     }
}

So to help handling with such case -- or, possibly, modifying such content, we could add new method:

ArrayNode asArray();

which will return:

• this for ArrayNode
• new ArrayNode() (empty ArrayNode) for MissingNode ("missing" node)
• new ArrayNode().add(this) for all other JsonNode implementations

to allow unifying processing of otherwise structurally mismatching JsonNode trees.

[yawkat]

I don't think we should encourage this kind of code by adding API to it. Wrapping all node types except for arrays in a single-element array is a bit weird.

[JooHyukKim]

@yawkat Because I think suggestion from xml-module kinda makes sense, makes me more curious why this would be weird or a bad idea? 👀

[cowtowncoder]

It seems weird from plain JSON perspective, but as @JooHyukKim pointed it makes more sense for XML handling; or more generally for "single Object as-is, two or more as Array" usage patterns which are pretty common (esp. with scripting languages).

While I personally also dislike such polymorphism (if something allows multiple values I feel it ought to be Array even if it contains just 1 element) I think there's something to be said for supporting actual use cases.

[cowtowncoder]

Realized something: JsonNode does not necessarily know how to create ArrayNode (only ArrayNode and ObjectNode know) -- there should always be a JsonNodeFactory to construct, to allow custom implementations.
Because of this, addition cannot really go in JsonNode.

And it may be odd addition in general so will close for now.

[ofrias]

I don't know about the internal implementation (JsonNodeFactory, etc.) but I think adding asArray() makes sense.

With the current implementation, JsonNode.get("element") returns an ArrayNode for the first XML

    <list>
        <element>
            <a>value 1a</a>
            <b>value 1b</b>
        </element>
        <element>
            <a>value 2a</a>
            <b>value 2b</b>
        </element>
    </list>

but an ObjectNode for the second XML:

    <list>
        <element>
            <a>value a</a>
            <b>value b</b>
        </element>
    </list>

But both XML are have in fact the exact same structure, the only difference is the number of elements in the list. This is odd for me and it is happening now.

This why having a helper method like JsonNode.asArray(String element) returning an ArrayNode makes sense for me.

It would be similar to the helper methods like for example JsonNode.asDouble(String element) that return a double even if the element is a string. Of course you could call Double.parse() from the string but it is useful to have this helper method.

[JooHyukKim]

What @ofrias ur suggesting sounds like it could be created as a new issue (probably a feature request) at XML module repo?

[cowtowncoder]

I will not be adding this method in general JsonNode since there is no way to construct nodes properly.

XML module could perhaps have helper methods -- but another thing to note is that JsonNode itself is translation from XML input: but lossy and not exact representation because it cannot be (due to XML information model being different from JSON one).

[cowtowncoder]

What @ofrias ur suggesting sounds like it could be created as a new issue (probably a feature request) at XML module repo?

That's where this started. I re-opened original issue.

[ofrias]

I will not be adding this method in general JsonNode since there is no way to construct nodes properly.

But the same happens with method public ArrayNode withArray(String exprOrProperty) and it is in JsonNode. It has an empty implementation throwing an UnsupportedOperationException and then it is overridden in ObjectNode that has the factory. The same could be done as I propose here.

XML module could perhaps have helper methods

A helper method can be easily implemented in user code, the purpose of having it directly in JsonNode is ease of use. In the same way as asDouble() is a helper method and could be also implemented in client code.

-- but another thing to note is that JsonNode itself is translation from XML input: but lossy and not exact representation because it cannot be (due to XML information model being different from JSON one).

It is true that at the time of building the tree Jackson doesn't have information about whether a node (<element> in the example) is in fact an individual node or part of a list. But the point is that at the time of using tree the user of JsonNode API has this knowledge and can call get("element") if he/she knows it is an individual node, or asArray("element") if he/she knows it is an array that could happen to have just one element.
It is the same that happens with asDouble() for "quoted doubles". The tree is constructed with strings but since the user knows it is in fact a quoted double, he/she calls asDouble().

[cowtowncoder]

I concur with other points on caller knowing what they are doing, regardless of whether Jackson itself can know what translations were done.

But the factory method problem is not solvable by OOP: only ArrayNode and ObjectNode instances know how to construct other things. Calling this on "unwrapped" TextNode, f.ex can not be solved by sub-classing, unfortunately.

So that's a no-go. ObjectMapper has JsonNodeFactory, as do things like DeserializationContext but not scalar (non-structured) JsonNodes.

[ofrias]

But the factory method problem is not solvable by OOP: only ArrayNode and ObjectNode instances know how to construct other things. Calling this on "unwrapped" TextNode, f.ex can not be solved by sub-classing, unfortunately.

But what I propose it very similar to what is already implemented for public ArrayNode withArray(String exprOrProperty). This method has empty implementation in JsonNode that just throws an UnsupportedOperationException. Then it is overriden/implemented in ObjectNode and ArrayNode that are the classes that have the factory to construct ArrayNode's which is also needed to implement withArray method. What I propose is having an empty public ArrayNode asArray(String element) method throwing the UnsupportedOperationException in JsonNode class and the implementation in ObjectNode class (and maybe in other classes too if it is found to be applicable). The implementation in ObjectNode could something like this:

    public ArrayNode asArray(String element) {
        JsonNode node = get(element);
        if (node == null) {
            return this._nodeFactory.arrayNode();
        }
        if (node.isArray()) {
            return node;
        } else {
            return this._nodeFactory.arrayNode().add(node);
        }
    }

[ofrias]

As for the TextNode, it will not have overriden the asArray method, so if it is ever called by mistake it will throw the UnsupportedOperationException. The same that happens when you call withArray on a TextNode.