XML-RPC

Overview

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.

Documentation

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:

Integers (in the 32bit range, -2147483648 .. 2147483647)
Booleans (true, false)
Floats (actually: C-doubles)
Strings
Arrays (of any of the supported types)
Dictionaries (with string-keys and values being any of the supported types)

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';
		yourself.

    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:

    xmlrpcService
	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|

	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.

<info@exept.de>

Doc $Revision: 1.5 $