2. XML-RPC

1
2. XML-RPC
2
What is XML-RPC?

• XML-RPC provides an XML- and HTTP-based mechanism
  for making method or function calls across a
  network
• Use XML for messaging (use only a small XML
  vocabulary set)
• Use HTTP to pass information from a client
  computer to a server computer
• No notion of objects
• No mechanism for including information that uses
  other XML vocabularies
• Emerged in early 1998

3
Why XML-RPC?

• As distributed systems become more common, there
  is a need to integrate the applications in
  different computers, even within a company
• XML-RPC provides a simple tool to connect
  disparate parts inside a private network

Windows
Linux
App A
App A
App B
App B
4

• XML-RPC can also provide a simple interface to a
  computer for other computers in the world to
  access
• Similar to the case that a Web page is a human
  readable interface of a computer

oreillynet.com
Headline
HTTP GET
Web Server
HTTP response with HTML page
XML-RPC Request
XML-RPC Client
Other App
XML-RPC Server
Headline information
XML-RPC Response
5
Three Main Parts of XML-RPC

• Data Model
• A set of type for passing parameters, return
  values and faults (error messages)
• Use by both request and response
• Request Structure
• An HTTP post request containing method name and
  parameter information
• Response Structure
• An HTTP response containing return values or
  fault information

6
XML-RPC Data Model

• Define only 6 basic data types and 2 compound
  data types
• Seems to be enough for most practical applications

Basic Type names Description
int or i4 32-bit integers
double 64-bit floating pt
boolean true(1) or false(0)
string ASCII text, usually support Unicode
dateTime.iso8601 Dates in ISO8601 format CCYYMMDDTHHMMSS
base64 Binary defined as in RFC2045
7

• Some examples
• ltintgt27lt/intgt
• ltdoublegt27.31415lt/doublegt
• ltbooleangt1lt/booleangt
• ltstringgtHellolt/stringgt
• ltdateTime.iso8601gt20020125T022004
• lt/dateTime.iso8601gt
• ltbase64gtSGVsbG8sIFdvcmxkIQlt/base64gt
• These basic types are always enclosed in value
  elements
• ltvaluegt
• ltdoublegt -12.45 lt/doublegt
• lt/valuegt

8

• These basic types can be combined into two more
  complex types Array and Struct

ltvaluegt ltarraygt ltdatagt
ltvaluegtltstringgtThis lt/stringgtlt/valuegt
ltvaluegtltstringgtis lt/stringgtlt/valuegt
ltvaluegtltstringgtan lt/stringgtlt/valuegt
ltvaluegtltstringgtarray.lt/stringgtlt/valuegt
lt/datagt lt/arraygt lt/valuegt
9

• Arrays can contain mixtures of different types

ltvaluegt ltarraygt ltdatagt
ltvaluegtltbooleangt1lt/booleangtlt/valuegt
ltvaluegtltstringgtChan Tai-Man lt/stringgtlt/valuegt
ltvaluegtltintgt -91 lt/intgtlt/valuegt
ltvaluegtltdoublegt0.1234lt/doublegtlt/valuegt
lt/datagt lt/arraygt lt/valuegt
10
ltvaluegt ltarraygt ltdatagt ltvaluegt
ltarraygt ltdatagt
ltvaluegtltintgt10lt/intgtlt/valuegt
ltvaluegtltintgt20lt/intgtlt/valuegt lt/datagt
lt/arraygt lt/valuegt ltvaluegt
ltarraygt ltdatagt
ltvaluegtltintgt30lt/intgtlt/valuegt
ltvaluegtltintgt40lt/intgtlt/valuegt lt/datagt
lt/arraygt lt/valuegt lt/datagt
lt/arraygt lt/valuegt

• Arrays can be multi-dimensional
• E.g.

First Row
Second Row
11

• Struct contains unordered content, identified by
  name
• Names are string, although it is not necessary to
  enclose them by string elements
• Each struct element contains a list of member
  elements
• Member elements each contain one name element and
  one value element
• The order of members is not important

12
ltvaluegt ltstructgt ltmembergt
ltnamegtgivenNamelt/namegt ltvaluegtltstringgtTai-Ma
n lt/stringgtlt/valuegt lt/membergt ltmembergt
ltnamegtfamilyNamelt/namegt
ltvaluegtltstringgtChan lt/stringgtlt/valuegt
lt/membergt ltmembergt ltnamegtagelt/namegt
ltvaluegtltintgt27lt/intgtlt/valuegt lt/membergt
lt/structgt lt/valuegt
First member of the struct
Second member of the struct
Third member of the struct
13
ltvaluegt ltstructgt ltmembergt
ltnamegtNamelt/namegt ltvaluegtltstringgtalt/stringgtlt
/valuegt lt/membergt ltmembergt
ltnamegtattributeslt/namegt ltvaluegtltstructgt
ltmembergtltnamegthreflt/namegt
ltvaluegtltstringgthttp//ex.comlt/stringgtlt/valuegt
lt/membergt ltmembergtltnamegttargetlt/namegt
ltvaluegtltstringgt_toplt/stringgtlt/valuegt
lt/membergt lt/structgtlt/valuegt lt/membergt
lt/structgt lt/valuegt
We can also nest an array inside a struct
Nest a struct inside a struct
14
XML-RPC Request Structure

• XML-RPC requests are a combination of XML content
  and HTTP headers
• HTTP header a wrapper for passing the request
  over the Web

POST /xmlrpc HTTP 1.0 User-Agent
myXMLRPCClient/1.0 Host 192.168.124.2 Content-Typ
e text/html Content-Length 169 XML
statements

• XML content pass parameters and identify the
  procedure to be called

For example
15
lt?xml version1.0?gt ltmethodCallgt
ltmethodNamegtcircleArealt/methodNamegt ltparamsgt
ltparamgt ltvaluegtltdoublegt2.42lt/doublegtlt/value
gt lt/paramgt ltparamgt ltvaluegt
ltarraygt ltdatagt
ltvaluegtltintgt10lt/intgtlt/valuegt
ltvaluegtltintgt20lt/intgtlt/valuegt lt/datagt
lt/arraygt lt/valuegt lt/paramgt
lt/paramsgt lt/methodCallgt
Method to be called
Input parameters a double and an array
The XML statements contain the method name and
passed parameters
16
XML-RPC Response Structure

• If a request is successful the procedure was
  found, executed correctly, the result will be
  returned thru the response to the client

• Similar to request, a response needs to be
  attached to a HTTP header for surfing on the Web

HTTP/1.1 200 OK Date Sat, 06 Oct 2004 232004
GMT Server Apache.1.3.12 (Unix) Connection
close Content-Type text/html Content-Length
124 XML statements
For example
17
Return a double number
lt?xml version1.0?gt ltmethodResponsegt
ltparamsgt ltparamgt ltvaluegtltdoublegt2.42lt/do
ublegtlt/valuegt lt/paramgt lt/paramsgt lt/methodRes
ponsegt
Return a fault, no standardized error code
lt?xml version1.0?gt ltmethodResponsegt ltfaultgt
ltvaluegtltstringgtNo such method!lt/stringgtlt/valuegt
lt/faultgt lt/methodResponsegt
18
lt?xml version"1.0"?gt ltmethodResponsegt ltfaultgt
ltvaluegt ltstructgt ltmembergt
ltnamegtcodelt/namegt
ltvaluegtltintgt26lt/intgtlt/valuegt lt/membergt
ltmembergt ltnamegtmessagelt/namegt
ltvaluegtltstringgtNo such method!lt/stringgt
lt/valuegt lt/membergt
lt/structgt lt/valuegt lt/faultgt lt/methodResponse
gt
Return a struct The error code is created by the
app. Can only be understood in this app.
19
Developing With XML-RPC

• In real applications, we do not need to directly
  program the XML statements
• Only need to add an XML-RPC library and making
  some function calls thru this library
• Hence can be done by using any programming
  languages, such as Java
• For example, the Apache XML Projects Apache
  XML-RPC has provided packages that make
  integrating XML-RPC with Java easier

20
Apache XML-RPC

• Provide an automated registration process for
  adding methods to the XML-RPC server
• Provide a built-in server that only speaks
  XML-RPC, reducing the need to create full-blown
  servlets
• A client package that makes calling remote
  methods fairly simple

21
Prepare for XML-RPC Services
Develop the function to be called by the client
Create the server
Register the function to the server
Start the server
22
Develop The Function
public class AreaHandler public double
circleArea(double radius) double value
(radiusradiusMath.PI) return value

• Just a normal function that returns the area
  (double) of a circle based on the input radius
• Function name circleArea
• Input parameter the radius (double)

23
Create Server and Register Function

• First, import the libraries

import java.io.IOException import
org.apache.xmlrpc.WebServer import
org.apache.xmlrpc.XmlRpc
24
Should input a port number
public class AreaServer public static void
main(String args) try startServer(args)
catch (IOException e) public
static void startServer(String args) throws
IOException WebServer server new
WebServer( Integer.parseInt(args0))
server.addHandler(area,new AreaHandler())
server.start()
Convert to an integer
Register the class under the name area
Start server
25

• To fire up the server, just execute the class
  from the command line need specifying a port
  no.
• Assume the class has been compiled and the file
  AreaServer.class has been generated

gtjava AreaServer 8899
port number for the server
26
Developing the Client Program

• To call the function registered in the server, a
  tailor-made client program is required
• Also need to use the XML-RPC libraries

import java.io.IOException import
java.util.Vector import org.apache.xmlrpc.XmlRpc
import org.apache.xmlrpc.XmlRpcClient import
org.apache.xmlrpc.XmlRpcException
27
public class AreaClient public static void
main(String args) AreaClient client new
AreaClient() double radius
Double.parseDouble(args0) try double
area client.areaCircle(radius)
System.out.println(The area of the circle
would be area) catch (IOException e)
catch (XmlRpcException e)
public double areaCircle (double radius)
throws IOException, XmlRpcException
Cast to double
Call areaCircle(), if OK, report the result
28
Create a client and connect to the server at port
8899
public double areaCircle (double radius)
throws IOException, XmlRpcException
XmlRpcClient client new
XmlRpcClient(http//localhost8899/)
Vector params new Vector()
params.addElement(new Double (radius)) Object
result client.execute(area.circleArea, params)
String resultStr
result.toString() double area
Double.parseDouble(resultStr) return area
Add a Double object to the Vector object
Call the server function. The registered name
area and function name need to be known
Just to play safe
29

• By executing this program, a HTTP request will be
  generated. An example is shown as follows

POST / HTTP/1.1 Content-Length 175
Content-Type text/xml User-Agent Java1.3.0
Host localhost8899 Accept text/html,
image/gif, image/jpeg Connection keep-alive
lt?xml version"1.0" encoding"ISO-8859-1"?gt
ltmethodCallgtltmethodNamegtarea.circleArealt/methodNa
megt ltparamsgt ltparamgtltvaluegtltdoublegt3.0lt/doublegtlt
/valuegtlt/paramgt lt/paramsgt lt/methodCallgt
HTTP header
XML messages
30

• If everything is fine, the server will send back
  the methodResponse and embedded inside the HTTP
  response
• Assume the client program is compiled and the
  AreaClient.class is generated
• The result looks pretty simple

gtjava AreaClient 3 The area of the circle would
be 28.274 gtjava AreaClient 4 The area of the
circle would be 50.265
31
Concluding Remarks

• Java is only a tool for us to generate the XML
  messages
• Other programming languages can be used to do the
  same. For example, Perl
• For XML-RPC, client needs to have some knowledge
  of servers registered functions
• No way for the server to publicize its functions
  or to allow the client to automatically obtain
  such info
• Hence does not perfectly fit the requirements of
  Web Services