Apache XML-RPC provides two client classes.

• org.apache.xmlrpc.XmlRpcClient uses java.net.URLConnection, the HTTP client that comes with the standard Java API
• org.apache.xmlrpc.XmlRpcClientLite provides its own lightweight HTTP client implementation.

XmlRpcClientLite is usually faster, but if you need full HTTP support (e.g. Proxies, Redirect etc), you should use XmlRpcClient.Both client classes provide the same interface, which includes methods for synchronous and asynchronous 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.

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.