XQueryWebService Framework Overview

XQueryWebService is a framework that allows you to expose an XQuery as a Web service. Implemented as a library for Java classes, XQueryWebService is designed to simplify the design and implementation of Web Servlet Applications. The jar file for this library, xquerywebservice.jar, is located in the \lib directory where you install DataDirect XQuery.

The XQueryWebService framework provides a Servlet implementation to expose as a Web service XQuery stored in a specific directory. Each XQuery exposes one operation; this operation is expressed in the query body through a function that takes the name of the XQuery file without the extension. For example, the file emp.xquery provides the emp operation. Parameters (external variables) expressed in the XQuery, if any, are reflected in the operation’s prototype.

XQuery modules cannot be published as Web services. A module can be parsed only indirectly when imported by another query.

An XQuery is compiled using lazy evaulation on the first request; after that it is compiled only if the XQuery source on the disk changes.

Third Party Dependencies

The XQueryWebService framework does not require any additional Java library; it relies only on built-in classes, like JAXP to manipulate XML, which are available from Java 1.4.2 and later.

Web Service Interfaces

The Web Service Description Language (WSDL) specification allows a Web service to be exposed through several types of bindings: HTTP GET, HTTP POST and SOAP over HTTP. This section describes these bindings in greater detail.

HTTP GET

The simplest binding is HTTP GET, often described as REST (Representational State Transfer), in which the Web service call is represented by a URL with all its parameters inline. Consider the following URI: 

       http://examples.xquery.com/employee-lookup/emp.xquery?id=A-C71970F

Here, employee-lookup is the service name, emp is the operation name, and what follows after the question mark is a name/value pair of parameters (id=A-C71970F).

HTTP GET is very simple to invoke – it is equivalent to accessing an HTML page on a Web server; any internet browser can invoke an XQuery Web service this way. However, only simple types such as strings or numbers can be passed through HTTP GET, limiting this approach to Remote Procedure Calling (RPC) style Web services. Web service responses from a REST binding are always XML fragments.

HTTP POST

HTTP POST allows you to design Web services with sophisticated request messages in the form of XML fragments. The drawback to HTTP POST is that the XQuery language does not provide a standard function to perform this type of binding.

SOAP

SOAP over HTTP is layered on HTTP POST, with the addition of an XML-based wire protocol that describes what the request/response looks like and provides a tighter integration with XML Schema. The SOAP protocol defines an optional element called Header to carry information like user/password or session id.

For more information on Web service interfaces, see XQueryWebService Framework Architecture.