Client Classes

Apache XML-RPC provides two client classes.

If you need full HTTP support (e.g. Proxies, Redirect etc), you should use XmlRpcClient. If you don't need full HTTP support and are concerned about performance, you should experiment with both XmlRpcClient and XmlRpcClientLite. On some platforms XmlRpcClient may be faster, while on others XmlRpcClientLite may be faster. Both client classes provide the same interface, which includes methods for synchronous and asynchronous calls.

Synchronous XML-RPC Calls

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

  XmlRpcClient xmlrpc = new XmlRpcClient ("http://localhost:8080/RPC2");
  Vector params = new Vector ();
  params.addElement ("some parameter");
  // this method returns a string
  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.

To quickly test your installation you can issue the following commands:

  java org.apache.xmlrpc.WebServer
  java org.apache.xmlrpc.XmlRpcClient http://localhost:8080 echo test 123

This should write [test, 123], which is the parameter array you sent to the echo handler of the XML-RPC server.

Asynchronous XML-RPC Calls

Apache XML-RPC supports asynchronous XML-RPC calls through the executeAsync() method in the XML-RPC client classes. This means that the call will return immediately without a result and the actual XML-RPC call will be executed in a separate thread.

If the caller is interested in the result of the remote call, or wants to be notified of exceptions, it can pass an object implementing the org.apache.xmlrpc.AsyncCallback interface to the XML-RPC client class. This interface defines two methods:

  public void handleResult (Object result, URL url, String method);
  public void handleError (Exception exception, URL url, String method);

Depending on the outcome of the call, one of these methods will be called.