Concepts

Let’s go a little deeper into the details of XML-RPC. The following figure shows the call side flow of an XML-RPC remote procedure call:

Your client application calls some functions in an XML-RPC library in order to make the RPC. These functions have arguments that use the native data types of the programming language you’re using—in this case, Java. The job of the XML-RPC library is to take those Java data values and convert them to elements in an XML document. That XML document can then be passed to an HTTP library, which is used to POST that XML data to the server machine’s HTTP port. On the server side, the server’s HTTP library receives the POSTed XML data and passes it to an XML-RPC library on the server. This library takes the XML data and converts it into data in the appropriate programming language—again, Java in this case—and then calls the server method by passing it the converted data as arguments. The entire process then reverses itself to get the return value of the server procedure from the server back over to the client.

Note that the word object doesn’t appear in the last paragraph. XML-RPC is about invoking procedures. There’s no notion of invoking methods on objects, polymorphic/virtual method dispatch, or any of those sorts of concepts. You can use XML-RPC in an object-oriented language, but you can also use it with languages that don’t support objects. This is in keeping with XML-RPC’s target usage as a way of integrating functionality.

XML Encoding RPCs

What does an XML-RPC document look like? It depends on whether you’re calling the procedure or returning a result from the procedure. Calling a procedure looks like this:

  1: <?xml version="1.0" encoding="UTF-8"?>   2: <methodCall>

The root element of an XML-RPC procedure call document is called <methodCall>. It has one immediate child, <methodName>, which specifies the procedure to be called:

  3:  <methodName>createBook</methodName>

The next child of <methodCall> is <params>, which is a container element containing enough <param> elements to supply all the arguments needed by the procedure:

  4:  <params>   5:   <param>   6:    <value>   7:     <string>Professional XML Development with Apache Tools/string>   8:    </value>   9:   </param>

A <param> element contains a <value> element, which in turn contains an element that describes the type of the parameter value. The content of the type element is the value of the parameter. We’ll discuss the type elements in more detail later. In this document, most of the values are Strings, so you see <string> as the type element. The one exception is in line 27, where you see <i4>, a 4-byte integer:

 10:   <param>  11:    <value>  12:     <string>Theodore W. Leung</string>  13:    </value>  14:   </param>  15:   <param>  16:    <value>  17:     <string>0-7645-4355-5</string>  18:    </value>  19:   </param>  20:   <param>  21:    <value>  22:     <string>December</string>  23:    </value>  24:   </param>  25:   <param>  26:    <value>  27:     <i4>2003</i4>  28:    </value>  29:   </param>  30:   <param>  31:    <value>  32:     <string>Wrox </string>  33:    </value>  34:   </param>  35:   <param>  36:    <value>  37:     <string>Indianapolis, Indiana</string>  38:    </value>  39:   </param>  40:  </params>  41: </methodCall>

There are two forms for an RPC response document—one for successful RPCs and one for unsuccessful RPCs. The XML document for a successful RPC looks like this:

  1: <?xml version="1.0" encoding="UTF-8"?>   2: <methodResponse>   3:  <params>   4:   <param>   5:    <value>   6:     <i4>1</i4>   7:    </value>   8:   </param>   9:  </params>  10: </methodResponse>

In this case, the root <methodResponse> element contains a <params> element with a single <param> element. This corresponds to a single-valued function return value. As you’ll see, XML-RPC lets you encode structs, so it’s possible to return composite results from XML-RPC calls.

The second case, for a faulty procedure call, looks like this:

  1: <?xml version="1.0" encoding="UTF-8"?>   2: <methodResponse>   3:  <fault>   4:   <value>   5:    <struct>   6:     <member>   7:      <name>faultCode</name>   8:      <value><int>1</int></value>   9:     </member>  10:     <member>  11:      <name>faultString</name>  12:      <value><string>Illegal argument</string></value>  13:     </member>  14:    </struct>  15:   </value>  16:  </fault>  17: </methodResponse>

Instead of <methodResponse> containing a <params> element, it contains a <fault> element. The <fault> element contains a <struct> that has two values: an integer faultCode and a faultString describing a human-readable description of the error that occurred.

Here are descriptions of all the type elements available in XML-RPC:

• <i4> /<int>—The value is a 4-byte signed integer.

• <string>—The value is a string, which may contain NULL bytes. There has been some confusion over whether XML-RPC strings are ASCII strings or Unicode strings. At the time of this writing, the specification has been updated to allow Unicode strings, based on the use of Unicode in XML. Be aware that not all XML-RPC implementations may support Unicode strings.

• <boolean>—The value is a boolean, with allowable values of 0 (false) and 1 (true).

• <double>—The value is a double-precision signed floating-point number.

• <dateTime.iso8601>—The value is a time and date according to the ISO 8601 standard for time and date formats. The problem is that the value of the time zone is dependent on the server you’re contacting. This makes it difficult to use <dateTime.iso8601> in a portable fashion.

• <base64>—The value is a base64-encoded binary value.

• <array>—The value is a heterogeneous array (not all the values must be of the same type). An <array> element contains a <data> element that’s a container for an unlimited number of <value> elements. A sample array might be as follows:

  <array>  <data>   <value><string>John Doe</string></value>   <value><i4>26</i4></value>   <value><double>492.36</double></value>  </data> </array> 

  The value of a <value> element may itself be an <array> or <struct>.

• <struct>—The value is a struct, a set of <member> elements. A <member> element has <name> and <value> as children. The named value aspect of <struct>s is what differentiates them from <array>s. The <name> element is a string, whereas the <value>element can contain any XML-RPC value, including <array> or <struct>. Here’s a sample struct:

  <struct>  <member>   <name></name>   <value></value>  </member> <member>   <name></name>   <value></value>  </member> <member>   <name></name>   <value></value>  </member> <member>   <name></name>   <value></value>  </member> </struct>

The XML-RPC specification doesn’t say how the server should interpret the <methodName> element. The server can use this as a procedure name, or it can use it as the name of a shell script to execute. It doesn’t matter, as long as the server can take the request document and produce a response document. If you’d like more details about XML-RPC, you can find the specification at www.xmlrpc.com/spec.

Using HTTP as an RPC Transport

XML-RPC uses HTTP to perform the task of getting the procedure call document from one machine to another. XML-RPC calls use the HTTP POST method to move the data to the remote machine. The return value of the procedure call is the HTTP response to the POST method. Here’s a wire dump of the POST for a procedure call:

  1: POST /RPC2 HTTP/1.0   2: User-Agent: Apache XML-RPC 1.0   3: Host: 127.0.0.1   4: Content-Type: text/xml   5: Content-Length: 665

All the HTTP headers you would expect to find are present. Line 1 shows the HTTP method (POST), the URI on the server being POSTed to (/RPC2), and the version of HTTP (1.0). Line 2 shows the user agent, in this case the Apache XML-RPC client. Line 3 says which host made the request. The HTTP Content-Type and Content-Length headers appear in lines 4 and 5 just like any other HTTP POST request. The remainder of the POST is the XML document that represents the procedure call:

  6:    7: <?xml version="1.0" encoding="UTF-8"?>   8: <methodCall>   9:  <methodName>createBook</methodName>  10:  <params>  11:   <param>  12:    <value>  13:     <string>Professional XML Development with Apache Tools</string>  14:    </value>  15:   </param>  16:   <param>  17:    <value>  18:     <string>Theodore W. Leung</string>  19:    </value>  20:   </param>  21:   <param>  22:    <value>  23:     <string>0-7645-4355-5</string>  24:    </value>  25:   </param>  26:   <param>  27:    <value>  28:     <string>December</string>  29:    </value>  30:   </param>  31:   <param>  32:    <value>  33:     <i4>2003</i4>  34:    </value>  35:   </param>  36:   <param>  37:    <value>  38:     <string>Wrox</string>  39:    </value>  40:   </param>  41:   <param>  42:    <value>  43:     <string>Indianapolis, Indiana</string>  44:    </value>  45:   </param>  46:  </params>  47: </methodCall>

As you might expect, the response from an XML-RPC server looks like a normal HTTP response:

  1: HTTP/1.0 200 OK   2: Server: Apache XML-RPC 1.0   3: Connection: close   4: Content-Type: text/xml   5: Content-Length: 154

Line 1 shows the version of HTTP (1.0), the HTTP return code (200), and the explanation (OK) for that return code. Line 2 identifies the server you’re interacting with, Apache XML-RPC 1.0. The HTTP 1.1 keep-alive header, Connection, appears in line 3 and says the client can close its connection. The response must also provide a Content-Type and Content-Length, as shown in lines 4 and 5. After that, the server returns the actual response data in the form of an XML-RPC response document:

  6:    7: <?xml version="1.0" encoding="UTF-8"?>   8: <methodResponse>   9:  <params>  10:   <param>  11:    <value>  12:     <i4>1</i4>  13:    </value>  14:   </param>  15:  </params>  16: </methodResponse>

Support for using HTTP is available via libraries written in many languages. This makes it easy to implement XML-RPC, assuming you have access to such a library. This is a key design goal of XML-RPC: to make it easy to implement and to leverage as much existing infrastructure as possible. By using HTTP as the transport mechanism, XML-RPC gains the benefit of all the work that has been done to make HTTP secure. All the tricks you know for Web security translate to XML-RPC. So, your knowledge of SSL, proxy servers, and firewalls all transfers over to using XML-RPC, because you’re using the same transport protocol, HTTP.