[prev] [up] [next]



XML-RPC is a very lightweight, XML based protocol for remote procedure calls in a distributed environment.
Implementations are available for a wide range of programming languages and operating system configurations, which makes this protocol ideal for interprocess communication.


Information on XML-RPC itself is found on "http://www.xmlrpc.com/spec".

XML-RPC Client

To communicate with a remote XML-RPC service, first create a proxy object with:

    proxy := XMLRPC::XMLRPCProxy withUrl:<url>
where <url> is the services' http-url. Typically something like "http://bleu.west.spy.net/geo/RPC2" or "http://www.xmlrpc.com/RPC2".

Once created, a call is performed with:

    retVal := proxy invokeMethod:<nameOfMethod> withArgs:<arrayOfArgs>.
For calls without arguments you can also use "invokeMethod:<nameOfMethod>".

XML-RPC only supports a limited set of supported datatypes both as argument and as return value. These are:

If required, convert arguments or return values to an array or a dictionary.

Concrete Example: JIRA XML-RPC Client

As a concrete example, here is how to login to a local JIRA server and create an issue via XML.RPC:
    |jira issue sessionKey|

    jira := XMLRPC::XMLRPCProxy withUrl:'http://localhost:8081/rpc/xmlrpc'.
    sessionKey := jira invokeMethod:'jira1.login' with:userName with:password.

    issue := Dictionary new
		at:'project' put:'projectKey';
		at:'type' put:1;
		at:'summary' put:'Issue created via XMLRPC';
		at:'assignee' put:'responsibleUserName';
		at:'description' put:'Created with an ST/X client';

    jira invokeMethod:'jira1.createIssue' with:sessionKey with:issue.
    jira invokeMethod:'jira1.logout' with:sessionKey.

XML-RPC Server

To provide an XML-RPC service, an HTTPServer must first be configured and running; for example with:
    httpServer := HTTPServer serverOnPort:8080.
then, an XML-RPC service has to be instantiated for that server:
    xmlrpcService := XMLRPC::XMLRPCService new.
    xmlrpcService linkName:'/xmlrpc'.
    xmlrpcService registerServiceOn:httpServer.
To support the XML-RPC introspection interface (listMethods, methodHelp and methodSignature), use:
    xmlrpcService enableIntrospectionProtocol.
Finally, you must register the methods which can be called. For example, to arrange for the rpc-message "demo.foo" with a string argument to be attached to the "DemoClass foo:"-method, execute the following setup:
	registerMethod: 'demo.foo'
	help:'Invoke the foo method of the Demo class'
	signature:#('string' 'string')
	receiver: DemoClass
	selector: #foo:
Assuming, that the foo: methods code is:
    foo: params

	arg := params first.
	^ arg asUppercase
Of course, a common strategy would be to subclass XMLRPCService, and perform the above registration in its #initialize method.

Arguments to a called server method

The params argument responds to the at: and size messages and can therefore used like an argument-vector. However, it also provides a reference to the original HTTP-request (via the request method). This information might be used for authentication or statistics.

Using the Introspection Protocol to Query a Server's Interface

If the introspection interface is enabled, a client can explore an ST/X XML-RPC service's interface as in:
    server := XMLRPC::XMLRPCProxy withUrl:'http://localhost:8081/rpc/xmlrpc'.
    (server invokeMethod:'system.listMethods') do:[:eachMethodName |
	Transcript showCR:eachMethodName.
	Transcript showCR:((server invokeMethod:'system.methodHelp' with:eachMethodName).

No Warranty

This goody is provided AS-IS without any warranty whatsoever.

Copyright © 2010 eXept Software AG


Doc $Revision: 1.5 $