1. XML-RPC OPERATIONAL PRINCIPLE
The method call and response in XML-RPC happens broadly in the following way [Figure 17.2:]:
- A client encodes the name of a function to be called and its arguments in an XML message as described by XML-RPC specification.
- The client then creates an HTTP post request message with the XML message as body and sends it to the server over the network using HTTP.
- Upon receiving this request message, the server forwards it to an XML-RPC processor.
- The XML-RPC processor parses the message to obtain the name of the function to be called and its argument list.
- The server then calls the function with the specified arguments.
- The return value of the function (if any) is again encoded in an XML message as described by XML-RPC specification.
- The server then creates an HTTP response message with this and the XML message as body and sends it back to the client using HTTP.
- Finally, the client, upon receiving the response message, extracts the information and performs further processing.
Before developing XML-RPC-based applications, let us now have an overview of supported data types.
2. DATA TYPES
A method is usually invoked with some data in the form of parameters. The response from that method may also contain data as a return value. However, unlike method call, which may contain multiple parameters, the response contains at most one return value. A data item in an XML-RPC request or response is embedded within a <vaiue>…</vaiue> element. To represent these values, XML-RPC specification defines six basic data types and two compound data types. Only values of these types may be passed to or returned from the remote method. Note that all the data is written in XML as string values. The specific data type tags are used to indicate how a server/client should interpret the data.
2.1. Basic Data Types
XML-RPC specification defines six types for integer, floating point number, Boolean, string, date-time and binary data. These types (except string) are always embedded in <vaiue> elements. Only strings may be embedded in a <vaiue> element directly omitting the <string> element.
Integer
For integers, XML-RPC specification has defined only one type. This type represents a 32-bit (four-byte) signed integer ranging from -2,147,483,648 (-231) to 2,147,483,647 (231-1). It is represented by the tag <int> or <i4>, where i4 stands for 4-byte integer. The following shows some of the examples of integer types:
<i4>23</i4>
<i4>-7</i4>
<i4>+3</i4>
<int>3</int>
<int>-2</int>
<int>+4</int>
Note that an implementation of XML-RPC specification must recognize this type for input parameters.
Floating point numbers
For floating point numbers, XML-RPC specification provides a type that refers to 64-bit double precision signed floating point numbers ranging from —4.94 x 10-324 to —1.79 x 10308. The type is indicated by the tag <doubie>. The following shows some of the examples of floating point types:
<double>3.42</double>
<double>-2.13</double>
<double>-0.13</double>
<double>+1.22</double>
Boolean values
A type is also incorporated to express Boolean values. This type represents only values 1 or 0 which corresponds to Boolean true and false respectively. It is represented by the tag <booiean>. Here are all the possible representations of Boolean values in XML-RPC:
<boolean>1</boolean>
<boolean>0</boolean>
Strings
XMP-RPC string type refers to the sequence of ASCII characters. A string value is represented using <string> tag. The following is an example representation of a string value in XML-RPC:
<string>RPC->Remote Procedure Call</string>
However, strings may be embedded in a <value> element directly omitting the <string> element. Note that <value> tag is used as the container of all other types. An XML-RPC implementation must understand both representations. So, the following representation is also valid and is usually used.
<value>RPC->Remote Procedure Call</value>
XML characters in the form of entity reference are permissible in a string. For example, if we want to use special XML characters, such as ‘&’ and ‘<’, in a string value, we must use the corresponding entity references (e.g., & for & and > for > etc.). The following are some valid string representations that use special characters:
<string>XML & RPC</string>
<string>4 > 3</string>
The parsers of this XML document should interpret the first string as XML & RPC and the second as 4 > 3 as they use the XML entities for the special characters & and >.
Date and Time
Dates and times are represented in XML-RPC using a single type and is indicated using dateTime. iso8 601 element. This type conforms to the ISO 8601 standard and hence has this name. It allows us to specify both date and time simultaneously in the ccyymmddthh:mm:ss format. Here is one example:
<dateTime.iso8601>20130902T06:49:21</dateTime.iso8601>
This indicates the date “2nd September, 2013” and time “06:49:21” (using the 24-hour clock format). The following is another example:
<dateTime.iso8601>20141015T15:45:00</dateTime.iso8601>
The above element represents the date “15th October, 2014” and time “15:45:00” (when this manuscript is being developed).
Binary
We know that control characters (having ASCII code lower than that of space character (32)) are not allowed in XML. So, arbitrary binary data cannot be transported using a sequence of integer values as they may contain these control characters. For this reason, XML-RPC specification introduced a type for raw binary data. This is indicated using <base64> tag. A value of this type is a base64 encoded value from binary data. The encoding technique is described in RFC 2045. The following is an example encoding of the string “Hi!”:
<base64>SGkh</base64>
Similarly, the following example shows the encoding of the string “Hello World!”
<base64>SGVsbG8gV29ybGQh</base64>
2.2. Compound Data Types
The basic types represent simple values and are sufficient for simple and less complex applications. However, complex applications may require more complex types to represent compound structure such as array, struct etc. Fortunately, XML-RPC provides two types array and struct for these compound values.
Array
In XML-RPC, an array is a sequence of data items. However, unlike traditional array where array elements are of same type, XML-RPC allows array elements to be of different types. Also there is no provision for numbering array elements. In general, an array is represented as follows:
<array>
<data>
<value>An XML-RPC value</value>
<value>An XML-RPC value</value>
…
<value>An XML-RPC value</value>
</data>
</array>
The sequence of values are written between <array><data> and </data></array>. Values are specified using <value> tag. For example, the following shows an array of 3 integers:
<array>
<data>
<value><int>2</int></value>
<value><int>3</int></value>
<value><int>4</int></value>
</data>
</array>
As mentioned earlier, array elements need not be of the same type. So, the following XML-RPC array is valid.
<array>
<data>
<value><string>B. S. Roy</string></value>
<value><int>35</int></value>
<value><double>48.34</double></value>
</data>
</array>
In the above example, the array elements represent the name, age and weight of a person respectively.
The array elements need not always be basic type. They may be any valid compound types as well. This enables us to create a multidimensional array by embedding arrays within an array. The following shows a two-dimensional array of 2 rows and 3 columns:
<array>
<data>
<value>
<array>
<data>
<value><int>1</int></value>
<value><int>2</int></value>
<value><int>3</int></value>
</data>
</array>
</value>
<value>
<array>
<data>
<value><int>4</int></value>
<value><int>5</int></value>
<value><int>6</int></value>
</data>
</array>
</value>
</data>
</array>
Struct
A struct in XML-RPC is a sequence of name-value pair. Each pair is said to be a member of struct and is represented by <member> element. The name of a member is an ASCII string and the value is any valid XML-RPC value including array or struct. A struct has the following general form:
<struct>
<member>
<name>name1</name>
<value>value1</value>
</member>
<member>
<name>name2</name>
<value>value2</value>
</member>
<member>
<name>nameN</name>
<value>valueN</value>
</member>
</struct>
The following is an example of struct that stores information of a person:
<struct>
<member>
<name>firstName</name>
<value><string>Banhishikha</string></value>
</member>
<member>
<name>lastName</name>
<value><string>Roy</string></value>
</member>
<member>
<name>age</name>
<value><int>35</int></value>
</member>
</struct>
Similarly, the following example contains information of a method call:
<struct>
<member>
<name>methodName</name>
<value><string>sqrt</string></value>
</member>
<member>
<name>y</name>
<value><int>4</int></value>
</member>
</struct>
This represents a call of a method sqrt with parameter 4. A struct may contain arrays or arrays may also contain struct. This enables XML-RPC programmers to describe even an extremely complex structure in a very easy way. A summary of XML-RPC data types is shown in Table 17.1:
Source: Uttam Kumar Roy (2015), Advanced Java programming, Oxford University Press.