XML-RPC a lightweight data communication protocol

1. XML-RPCa lightweight data communication protocol Jing Deng Computer Science Department University of Colorado at Boulder 26 September 2001

2. Overview • Introduction • XML-RPC protocol • How it works • Data format • How to use XML-RPC (Java example) • References

3. Introduction • What is XML-RPC • Remote process calling protocol with XML format • What can it do • allow software running on disparate operating systems, running in different environments to make procedure calls over the Internet. • History • Created by UserLand Software in April 1998, for its Frontier software communication

4. Fundamentals • XML • A very powerful meta-language for description data. XML-RPC just uses a little bit of XML • RPC • A mechanism which allows a program running on one computer to execute a function that is actually running on another computer • HTTP • Most data on Internet are transferred under HTTP protocol • Not very efficient, but easy to use • Make XML-RPC more convenient to be used in web applications

5. Definition • XML-RPC is a remote procedure calling protocol that works over the Internet. • XML-RPC is composed by an HTTP-POST request and a HTTP reply. • The body of the request and the value returned from server is formatted by XML.

6. XML-RPC Overview • XML-RPC call is conducted between two parties: • A client to send RPC request • A server to process RPC request and send back the return value to the client • Server’s address is in a standard URL • http://example.org:8080/rpcserver/ • The data is composed by a HTTP header and a XML body

7. XML-RPC Overview (Cont.) • A XML-RPC request and a XML-RPC response • Both of them are composed by a HTTP header and a XML body • Request should indicate a method name and its parameters • Response should contain a function return value and indicates if it is a successful return or a error message • There is a data type set for parameters and return value

8. HTTP POST (XML) call HTTP REPLY (XML) return XML XML call return How does XML-RPC work client Web server Client program procedure XML-RPC listener

9. POST /RPC2 HTTP/1.0 User-Agent: Frontier/5.1.2 Host: xml.colorado.edu Content-Type: text/xml Content-length: 181 <?xml version=“1.0”?> <methodCall> <methodName>examples.getStateName</methodName> <params> <param> <value><i4>41</i4></value> </param></params> </methodCall> Request Example

10. Request Format • A single <methodCall> structure, which contains • A single <methodName>. It contains the calling method’s name • A single <params>, which can contain any number of • <param>s. Each <param> has a • <value>

11. Data Type – Scalar <value>s <i4> or <int> four-byte signed integer -12 <boolean> 0 (false) or 1 (true) 1 <string> ASCII string Hi! <double> double-precision 3.1415 <dateTime.iso8601> date/time 19980717T14:08:55 <base64> base64-encoded binary eW91IGNhbid (default type is string)

12. Data Type (Cont.) - <struct> <struct> contains <member>s, each <member> contains a <name> and a <value> <struct> <member> <name>lowerBound</name> <value><i4>18</i4></value> </member> <member> <name>upperBound</name> <value><i4>122</i4></value> </member> </struct>

13. Data Type (Cont.) - <array> An <array> contains a single <data> element, which can contain any number of <value>s <array> <data> <value><i4>12</i4></value> <value><string>Egypt</<string></value> <value><boolean>0</boolean></value> <value><i4>-31</i4></value> </data> </array>

14. Response Example HTTP/1.1 200 OK Connection: close Content-Length: 158 Content-Type: text/xml Date: Wed, 26 Sep 2001 10:10:28 GMT Server: UserLand Frontier/5.1.2-WinNT <?xml version=“1.0”?> <methodResponse> <params> <param> <value><string>South Dakota</string></value> </param></params> </methodResponse>

15. Response Format • One <methodResponse>, it may contains either • A single <params> -- a successful procedure return It contains a single <param> which contains a single <value> • A <fault> -- a failure procedure return It contains a <value> which is a <struct> that contains two members: <faultCode> and <int>, <faultString> and <string>

16. Example - XML-RPC in Java • Many XML-RPC applications encapsulate the details of XML-RPC protocol • They provides an interface for users to send remote procedure call, and retrieve return value • A XML-RPC Java library: helma.xmlrpc

17. Helma.xmlprc • A free XML-RPC library • http://xmlrpc.helma.org/ • Contains source code, documentations, and examples • Has a jar file as a library: xmlrpc.jar, which contains a OpenXML parser as well • Easy to install

18. XML-RPC Client • Send XML-RPC to server, and get the return value • Interface (encapsulate most protocol details: HTTP, XML) • XmlRpcClient class • XmlRpcClient(String URL); • public Object execute(String procedure_name, Vector params);

19. XML-RPC Server • Process XML-RPC request, call the procedure that request wants to call, and send back the return value • Two kinds of server • A mini web server, only process XML-RPC WebServer class • (See its interface later…) • XML-RPC listener which cooperates with a web server XmlRpcServer class • Input is a XML stream, and output is a XML stream also • execute() method to process RPC

20. XML-RPC Handler • Contains the procedures client wants to call • We need to register handler to server • Automatic registration • Explicit registration • Implement XmlRpcHanlder interface • Use Xml.RpcHandler.execute() to process input parameter • Interface • WebServer.addHandler(String handler_name, Object handler);

21. Example - Handler public class AreaHandler { public Double rectArea(double length, double width) { return new Double(length * width); } public Double circleArea(double radious) { double value = (radious * radious * Math.PI); return new Double (value); } }

22. Example - Server import java.io.IOException; import helma.xmlrpc.WebServer; import helma.xmlrpc.XmlRpc; public class AreaServer { public static void main(String[] args) { try { WebServer server = new WebServer(Integer.parseInt(args[0])); server.addHandler("area", new AreaHandler()); } catch (IOException e) { System.out.println("Could not start server: " + e.getMessage()); } }}

23. Example - Client import java.io.IOException; import java.util.Vector; import helma.xmlrpc.XmlRpc; import helma.xmlrpc.XmlRpcClient; import helma.xmlrpc.XmlRpcException; public class AreaClient { public static void main(String args[]) { try { XmlRpcClient client = new XmlRpcClient("http://localhost:8899"); // continue….

24. Example – Client (Cont.) // continue from last slide….. Vector params = new Vector(); params.addElement(new Double(args[0])); Object result = client.execute("area.circleArea", params); System.out.println(result.toString()); } catch (IOException e) { System.out.println("IO Exception: " + e.getMessage()); } catch (XmlRpcException e) { System.out.println("Exception within XML-RPC: " + e.getMessage()); } } }

25. Discussions • Characters of XML-RPC • Platform independent because it is a protocol • Very simple, very easy to implement, very ease to use • Too simple for some applications • Implemented with many languages: Java, C/C++, Perl, Python, etc… • Other important issues I didn’t mention… • Security • Apply XML-RPC in web applications

26. Discussions (Cont.) • Comparisons • Differences between XML-RPC and web page • Differences between XML-RPC and RMI, Corba • Differences between XML-RPC and SOAP • Beyond XML-RPC • SOAP, UDDI, WSDL, BXXP

27. References • XML-RPC documents http://www.xmlrpc.com http://www.xmlrpc.com/spec http://xmlrpc-c.sourceforge.net/xmlrpc-howto/xmlrpc-howto.html • XML-RPC in Java http://xmlrpc.helma.org • XML-RPC in C and C++ http://xmlrpc-c.sourceforge.net/sample-code.php

28. References (Cont.) • Book Simon St.Laurent, Joe Johnston, Edd Dumbill, programming web services with XML-RPC, O’Reilly, 2001 • Others http://www.w3.org/2000/xp/ http://www.google.com

29. Thanks!