In XML-RPC, method call and response [Figure 17.1:] are described as HTTP messages having body written in XML. The specification defines three types of messages [Figure 17.3:]: request message, response message and fault message.
XML-RPC request messages are a kind of HTTP request messages, whereas XML-RPC responses and fault messages are HTTP response messages. The following section describes the format of these messages briefly. Understanding message formats helps programmers to write their own implementation of XML-RPC specification as well as to debug and to establish connections between systems in different environments.
1. Request Message
An XML-RPC request message is basically an HTTP POST request message whose body is an XML document. This XML message body encodes the method call syntax. The message has the root element <methodCaii> that contains method name and its arguments. The name of the method is represented by the <methodName> element and argument list is provided using <params> element. The <params> element contains a list of <param> elements one for each argument. The value of the argument is specified by the <vaiue> element. For example, to invoke a method called fact, which takes an integer argument, the body of XML-RPC request message looks like this:
<?xml version=”1.0”?>
<methodCall>
<methodName>fact</methodName>
<params>
<param>
<value><int>5</int></value>
</param>
</params>
</methodCall>
And the HTTP request line and header look something like this:
POST /xmlrpc/RPC HTTP/1.0
User-Agent: Apache XML-RPC
Host: client.host.name
Content-Type: text/xml
Content-Length: length of XML body in bytes
XML-RPC specification does not provide the format of the URL (Uniform Resource Locator) in the request line and can be empty. In the above example, the /xmlrpc/RPC is the URL of the processor who will process this request message. The next two lines of the header specify the User-Agent and Host. The User-Agent is the name of the software making the request. The Host is the URL of the client. Note that, these two headers are not mandatory for most of XML-RPC servers.
The last two lines specify mandatory headers Content-Type and Content-Length. The value of Content-Type header is always text/xml as the content is an XML document. The value of Content- Length is the size of XML message body in number of bytes.
So, the XML-RPC request message (which is an HTTP POST request message) finally looks as shown in Figure 17.4:
Note that the content of <methodName> element is a sequence of alphanumeric characters, underscore, dot, colon, and back slash. The interpretation of this string depends entirely on the server. The string may be the exact name of the method (as shown in the previous example) or method name with object name as a prefix, or may be a name of a file containing a script to be executed etc. The server of the Apache XML-RPC Java library (that we shall use to demonstrate XML-RPC) expects this string as the following format:
objectName.methodName
Here objectName is the name of the object assigned by the server during its creation and methodName is the actual name of the method to be invoked.
Note that <params> tag may be absent if a method does not take any parameter. So the following is an example of method call without any parameter.
<?xml version=”1.0”?>
<methodCall>
<methodName>sayHello</methodName>
</methodCall>
The <vaiue> tag under <param> contains any of the six basic types or two compound types.
2. Response Message
An XML-RPC response message is basically an HTTP response message whose body is an XML document. This message is sent by the XML-RPC server as a result of method call. In the response line, the server should always return ‘200 OK’ unless an HTTP error occurs. A fault is represented by a separate message and is described in the next section. The header section should contain two headers Content-Type and Content-Length. The value of Content-Type header should be text/ xml and the value of Content-Length is the correct number of bytes in the XML message body.
The body of the message is an XML document whose root element is <methodResponse>. This tag contains a single <params> tag, which contains a single <param> tag. Since a method can only return one value, there exists only one <param> tag. An example of a response message body is shown below:
<?xml version=”1.0”>
<methodResponse>
<params>
<param>
<value><i4>120</i4></value>
</param>
</params>
</methodResponse>
The HTTP response line and header look something like this:
HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 142
So, the XML-RPC response message (which is an HTTP response message) finally looks as shown in Figure 17.5:
3. Fault Message
If XML-RPC server faces some problem processing the request, it notifies the client with a special message called fault message. Note that a fault message is also a response message except that it has a different format. In this case, the <methodResponse> tag contains <fauit> tag, which designates the message as a fault message. The <fauit> contains a <vaiue>, which is a <struct> containing two members. The name of the first member is fauitCode, whose value is an <int>, which indicates the error code. The name of the second member is faultstring, whose value is a <string> which gives an explanation about the error occurred. The following is an example fault message:
HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 365
<?xml version=”1.0”?>
<methodResponse>
<fault>
<value>
<struct>
<member>
<name>faultCode</name>
<value><int>0</int></value>
</member>
<member>
<name>faultString</name>
<value>No such handler: fact1</value>
</member>
</struct>
</value>
</fault>
</methodResponse>
This tells us that a fault occurred as an invalid method ‘fact1’ was mentioned in the request by the client.
Source: Uttam Kumar Roy (2015), Advanced Java programming, Oxford University Press.