5.5.4 SOAP Message Format

The design goal of XRPC is to create a distributed XQuery mechanism with which different XQuery processors at different sites can jointly execute queries. This implies that our XRPC extension also encompasses a network protocol.

Network communicating in XRPC uses the Simple Object Access Protocol (SOAP), i.e. XML messages over HTTP. The SOAP XRPC message format is defined in XRPC.xsd. According to the classification in the article "Discover SOAP encoding's impact on Web service performance", the SOAP XRPC protocol belongs to the family of "document/literal". Note that SOAP XRPC should not be confused with SOAP RPC, a sub-protocol defined by the SOAP 1.2 standard ¹.

XRPC Request Message. SOAP messages consist of an envelope, with an optional Header element and a Body element. Inside the body, we define a request element with several attributes:

• required attributes
  • module: namespace URI of the XQuery module (NB: do not use the user defined prefix for the module!)
  • method: name of the called function
  • arity: the number of parameters the called method has
  • location: the at-hint, i.e. the location where the module file is stored.
• optional attributes
  • iter-cnt: number of iterations included in this request
  • updCall: is the called function an updating function (as defined by XQUF) or not. Note that the pathfinder document management functions (e.g. pf:add-doc()) are also considered to be updating functions by XRPC.

The actual parameter values of a single function call are enclosed by a call element. Each individual parameter consists of a sequence element, that contains zero or more values.

Below we show the SOAP XRPC request message generated for the first example query (Q2) that looks for films played by Sean Connery:

<?xml version="1.0" encoding="utf-8"?>
<env:Envelope
    xmlns:xrpc="http://monetdb.cwi.nl/XQuery"
    xmlns:env="http://www.w3.org/2003/05/soap-envelope"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://monetdb.cwi.nl/XQuery http://monetdb.cwi.nl/XQuery/XRPC.xsd">
  <env:Body>
    <xrpc:request module="filmdb"
                  method="filmsByActor"
                  arity="1"
                  location="http://example.org/film.xq"
                  iter-cnt="1"
                  updCall="false">
      <xrpc:call>
        <xrpc:sequence>
          <xrpc:atomic-value xsi:type="xs:string">Sean Connery</xrpc:atomic-value>
        </xrpc:sequence>
      </xrpc:call>
    </xrpc:request>
  </env:Body>
</env:Envelope>

• Atomic values are represented with atomic-value, and are annotated with their (simple) XML Schema Type in the xsi:type attribute. Thus, the heterogeneously typed sequence consisting on a string "abc" and a double 3.1 would become:

       <xrpc:sequence>
         <xrpc:atomic-value xsi:type="xs:string">abc</xrpc:atomic-value>
         <xrpc:atomic-value xsi:type="xs:double">3.1</xrpc:atomic-value>
       </xrpc:sequence>
  

• XML nodes are passed by value, enclosed by an element element:

       <xrpc:sequence>
         <xrpc:element>
           <filmName>The Rock</filmName>
         </xrpc:element>
         <xrpc:element>
           <filmName>Goldfinger</filmName>
         </xrpc:element>
       </xrpc:sequence>
  

  Similarly, the XML Schema XRPC.xsd defines enclosing elements for document, attribute, text, processing instruction, and comment nodes. Document nodes are represented in the SOAP message as a document element that contains the serialized document root. Text, comment and processing instruction nodes are serialized textually inside the respective elements text, comment and processing-instruction. Attribute nodes are serialized inside the attribute element: <xrpc:attribute x="y">.

• User-defined types: XRPC fully supports the XQuery Data Model, a requirement for making it an orthogonal language feature. This implies XRPC also supports passing of values of user-defined XML Schema types, including the ability to validate SOAP messages. XQuery already allows importing XML Schema files that contain such definitions. Values of user-defined types are enclosed in SOAP messages by element elements, with a xsi:type attribute annotating their type. The XQuery system implementing XRPC should include a xmlns namespace definition as well as a xsi:schemaLocation declaration inside the Envelope element when values of such imported element types occur in the SOAP message.
• Multi-parameter functions: for functions with more than one parameters, the value of each parameter is enclosed in a separate sequence element. For example, to call the function

       declare function add ($v1 as xs:integer, $v2 as xs:integer) as xs:integer
  

  with the parameters 10 and 20, the values are serialized as the following:

       <xrpc:sequence>
         <xrpc:atomic-value xsi:type="xs:integer">10</xrpc:atomic-value>
       <xrpc:sequence>
       <xrpc:sequence>
         <xrpc:atomic-value xsi:type="xs:integer">20</xrpc:atomic-value>
       <xrpc:sequence>
  

• Loop-lifting: on of the main feature of the SOAP XRPC protocol is the support for loop-lifting, that is, all iterations in a for-loop that containing the applications of the same function (but usually with different parameter values) on the same remote peer, are serialized in one XRPC request message. The parameter values of each iteration is enclosed in a separate call element. The execution results of all those iterations will also be serialized into one XRPC response message. For example, the example query (Q2) above contains two iterations that call the same function on the same remote peer. For this query, the following request message (only the main part is shown) will be generated:

       <xrpc:request module="filmdb"
                     method="filmsByActor"
                     arity="1"
                     location="http://example.org/film.xq"
                     iter-cnt="2"
                     updCall="false">
         <xrpc:call>
           <xrpc:sequence>
             <xrpc:atomic-value xsi:type="xs:string">Julie Andrews</xrpc:atomic-value>
           </xrpc:sequence>
         </xrpc:call>
         <xrpc:call>
           <xrpc:sequence>
             <xrpc:atomic-value xsi:type="xs:string">Sean Connery</xrpc:atomic-value>
           </xrpc:sequence>
         </xrpc:call>
       </xrpc:request>
  

XRPC Response Messages follow the same principles, e.g.:

<?xml version="1.0" encoding="utf-8"?>
<env:Envelope
  xmlns:xrpc="http://monetdb.cwi.nl/XQuery"
  xmlns:env="http://www.w3.org/2003/05/soap-envelope"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://monetdb.cwi.nl/XQuery
                      http://monetdb.cwi.nl/XQuery/XRPC.xsd">
  <env:Body>
    <xrpc:response module="filmdb" method="filmsByActor">
      <xrpc:sequence>
        <xrpc:element><filmName>The Rock</filmName></xrpc:element>
        <xrpc:element><filmName>Goldfinger</filmName></xrpc:element>
      </xrpc:sequence>
    </xrpc:response>
  </env:Body>
</env:Envelope>

Inside the body is now a xrpc:response element that contains the result sequence of the remote function call.

XRPC Error Message. Whenever an XRPC server discovers an error during the processing of an XRPC request, it immediately stops execution and sends back an XRPC error message, using the format of the SOAP Fault message (see SOAP Version 1.2 Part 0: Primer and Part 1: Messaging Framework). For example, the following SOAP Fault message indicates that a required module could not be loaded:

<?xml version="1.0" encoding="utf-8"?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
              xmlns:xml="http://www.w3.org/XML/1998/namespace">
  <env:Body>
    <env:Fault>
      <env:Code>
        <env:Value>env:Receiver</env:Value>
      </env:Code>
      <env:Reason>
        <env:Text xml:lang="en">could not load module!</env:Text>
      </env:Reason>
    </env:Fault>
  </env:Body>
</env:Envelope>