XQueryServlet

The request module (in the http://exist-db.org/xquery/request function namespace) contains functions for handling HTTP request parameters. The session module (in the http://exist-db.org/xquery/session function namespace) contains functions for handling HTTP session variables. Functions in these namespaces are only usable if the query is executed through the XQueryGenerator or the XQueryServlet.

Contains the name of a request attribute. Instead of writing query results to the response output stream, XQueryServlet will store them into the named attribute. The value of the attribute will be an XQuery Sequence. If no query results were returned, the attribute will contain an empty sequence.

If set, the value of this attribute must contain the XQuery code to execute. Normally, XQueryServlet reads the XQuery from the file given in the request path. Use of the xquery.source attribute allows you to overwrite this behaviour, e.g. if you want to evaluate an XQuery which was generated within the controller.

If the main XQuery was retrieved from the file system, the module load path points to that directory. This applies to queries executed through the XQueryServlet, XQueryGenerator or the Java admin client.

XQuery modules executed via the REST interface, the XQueryServlet or XQueryGenerator are automatically cached. The compiled expression will be added to an internal pool of prepared queries. The next time a query or module is loaded from the same location, the already compiled code is reused. The code will only be recompiled if eXist-db decides that the source was modified or when it wasn't used for a longer period of time.

eXist-db's XQueryServlet as well as the XSLTServlet expect a few predefined request attributes. The names of these attributes are listed below, and are reserved, that is to say that they should not be used for other purposes.

Contains the name of a request attribute. Instead of writing query results to the response output stream, XQueryServlet will store them into the named attribute. The value of the attribute will be an XQuery Sequence. If no query results were returned, the attribute will contain an empty sequence.

If set, the value of this attribute must contain the XQuery code to execute. Normally, XQueryServlet reads the XQuery from the file given in the request path. Use of the xquery.source attribute allows you to overwrite this behaviour, e.g. if you want to evaluate an XQuery which was generated within the controller.

This attribute is usually combined with the xquery.attribute attribute provided by XQueryServlet and allows passing data between the two without additional serialization or deserialization overhead.

This attribute is usually combined with the xquery.attribute attribute provided by XQueryServlet and allows passing data between the two without additional serialization or deserialization overhead.

The example also demonstrates how information can be passed between actions. XQueryServlet (which is called implicitly because the URL ends with .xq) can save the results of the called XQuery to a request attribute instead of writing them to the HTTP output stream. It does so if it finds a request attribute named xquery.attribute, which should in turn contain the name of the request attribute that the output should be saved to.

In the example above, xquery.attribute is set to model. This causes XQueryServlet to fill the request attribute model with the results of the XQuery it executes. The query result will not be written to the HTTP response as you might expect, instead at this point the HTTP response body remains empty as the data is inside the request attribute.

The benefit of exchanging data through request attributes is that we save one serialization step: XQueryServlet directly passes the node tree of its output as a valid XQuery value, so XSLTServlet does not need to parse it again.

Older versions of eXide's ancestor sandbox application used the util:eval() function to evaluate the query. However, this had side-effects because util:eval() executes the query within the context of the parent query. Some features like module imports could not work properly. To avoid util:eval(), the controller code below passes the user-supplied query to XQueryServlet first, then post-processes each returned result and stores it into a session for later use by the AJAX frontend:

The client passes the user-supplied query string in a request parameter, so the controller has to forward this to XQueryServlet somehow. XQueryServlet has an option to read the XQuery source from a request attribute, xquery.source. The query result will be saved to the attribute results. The second XQuery, session.xq, takes the result and stores it into an HTTP session, returning only the number of hits and the elapsed time.

For example, valid names within the eXist-db's standard setup would be XQueryServlet or XSLTServlet. You can see some examples of these in the article .

If the main XQuery was retrieved from the file system, the module load path points to that directory. This applies to queries executed through the XQueryServlet, XQueryGenerator or the Java admin client.

As this example shows, serialization parameters can be set within the query itself. However, the interpretation of serialization parameters depends on the context in which the query is called. For instance, the JSON media-type declaration in the example above in only relevant in the context of an HTTP response header. Most output parameters are applicable only if the query is executed using the XQueryGenerator/XQueryServlet servlet or the REST server.

For example, valid names within the eXist-db's standard setup would be XQueryServlet or XSLTServlet. You can see some examples of these in the article .