[BUG] The JavaDoc comments for variable in the REST API are inconsistent with the implementation

[ndw]

In RESTServerParameters.java, which I had to go trolling through because of #5843 , we find:

 /**
     * XML description can be used inside Variables
     * in either the Query String of a GET request or
     * in the body of a POST request to specify the name
     * and value of an external XQuery variable.
     * 
     * Contexts: GET, POST
     * 
     * The value of this parameter, is an XML element with the format:
     * 
     *  <exist:variable>
     *      (exist:qname,
     *      sx:sequence)
     *  </exist:variable>
     * 
     *  <exist:qname>
     *      (exist:prefix?,
     *       exist:localname,
     *       exist:namespace?)
     *  </exist:qname>
     * 
     *  <sx:sequence>
     *      (sx:value+)
     *  </sx:sequence>
     * 
     *  <sx:value type? = string>
     *      (text() | element())
     *  </sx:value>
     */
    Variable,

Note, in particular, that the type attribute on sx:value is optional. But in the implementation (deep in Marshaller.java, afaict), we find:

                case XMLStreamConstants.START_ELEMENT :
                    if (NAMESPACE.equals(parser.getNamespaceURI()) && VALUE_ELEMENT.equals(parser.getLocalName())) {
                        String typeName = null;
                        // scan through attributes instead of direct lookup to work around issue in xerces
                        for (int i = 0; i < parser.getAttributeCount(); i++) {
                            if (ATTR_TYPE.equals(parser.getAttributeLocalName(i))) {
                                typeName = parser.getAttributeValue(i);
                                break;
                            }
                        }
                        if (typeName != null) {
                            final int type = Type.getType(typeName);
                            Item item;
                            if (Type.subTypeOf(type, Type.NODE))
                                {item = streamToDOM(type, parser, null);}
                            else
                                {item = new StringValue(null, parser.getElementText()).convertTo(type);}
                            result.add(item);
                        }
                    }
                    break;

Where the item is only added to the sequence if typeName is not null.

It seems to me that either passing in the value without a type should raise an error or the default type should be untyped.

[ndw]

It's also unclear how XML or map or array values should be passed. Using the types document-node(), map(*) and array(*) don't work. The appear to trigger some jakarata servelet exception related to casting TextImpl to something else...

[line-o]

Thanks for sharing your findings here. Especially, since you already dug so deep into the codebase.