Apache XML-RPC

specify fault codes.

ƒ What timezone should be assumed for the dateTime.iso8601 type? UTC? localtime?

Don't assume a timezone. It should be specified by the server in its documentation what assumptions it makes about timezones.

Using the XML-RPC library on the client side is quite straightforward. Here is some sample code:

// create new client, parametrer is the url of the server

XmlRpcClient xmlrpc = new XmlRpcClient ("http://localhost:8080/RPC2");

// build parameter for the request Vector params = new Vector ();

params.addElement ("some parameter");

// call the remote procedure

String result = (String) xmlrpc.execute ("method.name", params);

Note that execute can throw XmlRpcException and IOException, which must be caught or declared by your code.

3.3.2. Server Side XML-PRC

On the server side, you can either embed the XML-RPC library into an existing server frame-work, or use the built-in special purpose HTTP server. Let's first look at how to register handler objects to tell an XML-RPC server how to map incoming requests to actual methods.

XML-RPC Handler Objects

The org.apache.xmlrpc.XmlRpcServer and org.apache.xmlrpc.WebServer classes provide methods that let your register and unregister Java objects as XML-RPC handlers:

addHandler (String name, Object handler);

removeHandler (String name);

Parallel Programming in Java: MultithradedServer Prof. Dr. Alois Schütte 50/60

Depending on what kind of handler object you give to the server, it will do one of the follow-ing thfollow-ings:

1. If you pass the XmlRpcServer any Java object, the server will try to resolve incoming calls via object introspection, i.e. by looking for public methods in the handler object corresponding to the method name and the parameter types of incoming requests.

The input parameters of incoming XML-RPC requests must match the argument types of the Java method (see conversion table), or otherwise the method won't be found. The re-turn value of the Java method must be supported by XML-RPC.

(We will use that kind of handler object.)

2. If you pass the XmlRpcServer an object that implements interface

org.apache.xmlrpc.XmlRpcHandler or org.apache.xmlrpc.AuthenticatedXmlRpcHandler the execute() method will be called for every incoming request. You are then in full con-trol of how to process the XML-RPC request, enabling you to perform input and output parameter checks and conversion, special error handling etc.

In both cases, incoming requests will be interpreted as handlerName.methodName with han-dlerName being the String that the handler has been registered with, and methodName being the name of the method to be invoked. You can work around this scheme by registering a handler with the name "$default". In this case you can drop the handlerName. part from the method name.

Parallel Programming in Java: MultithradedServer Prof. Dr. Alois Schütte 51/60

Using the build-in HTTP-Server

The XML-RPC library comes with its own built-in HTTP server. This is not a general pur-pose web server, its only purpur-pose is to handle XML-RPC requests. The HTTP server can be embedded in any Java application with a few simple lines:

// create Web-Server

WebServer webserver = new WebServer (port);

// add handler for a request

webserver.addHandler ("examples", someHandler);

A special bonus when using the built in Web server is that you can set the IP addresses of cli-ents from which to accept or deny requests. This is done via the following methods:

webserver.setParanoid (true); // deny all clients webserver.acceptClient ("192.168.0.*"); // allow local access webserver.denyClient ("192.168.0.3"); // except for this one ...

webserver.setParanoid (false); // disable client filter

If the client filter is activated, entries to the deny list always override those in the accept list.

Thus, webserver.denyClient ("*.*.*.*") would completely disable the web server.

Using XML-RPC within a Servlet environment (we do not use it in our example)

The XML-RPC library can be embedded into any Web server framework that supports reading HTTP POSTs from an InputStream. The typical code for processing an incoming XML-RPC re-quest looks like this:

Parallel Programming in Java: MultithradedServer Prof. Dr. Alois Schütte 52/60

XmlRpcServer xmlrpc = new XmlRpcServer ();

xmlrpc.addHandler ("examples", new ExampleHandler ());

...

byte[] result = xmlrpc.execute (request.getInputStream ());

response.setContentType ("text/xml");

response.setContentLength (result.length);

OutputStream out = response.getOutputStream();

out.write (result);

out.flush ();

Note that the execute method does not throw any exception, since all errors are encoded into the XML result that will be sent back to the client.

A full example servlet is included in the package. There is a sample XML-RPC Servlet included in the library. You can use it as a starting point for your own needs.

3.3.3. Data types

The following table explains how data types are converted between their XML-RPC representa-tion and Java.

Note that the automatic invocation mechanism expects your classes to take the primitive data types as input parameters. If your class defines any other types as input parameters (in-cluding java.lang.Integer, long, float), that method won't be usable from XML-RPC unless you write your own handler.

For return values, both the primitive types and their wrapper classes work fine.

Parallel Programming in Java: MultithradedServer Prof. Dr. Alois Schütte 53/60

XML-RPC data type Java date type

<i4> or <int> int

<boolean> boolean

<string> java.lang.String

<double> double

<dateTime.iso8601> java.util.Date

<struct> java.util.Hashtable

<array> java.util.Vector

<base64> byte[]