XML-RPC Library for Java

This is a Java implementation of the XML-RPC developed by UserLand. XML-RPC is a lightweight remote protocol that uses XML to encode procedure calls and responses. This library has been designed to be easy to use and as independent from other class libraries as possible.

Download xmlrpc-java.zip. The current version is 1.0 beta 3 and was released on April 18 2000. I'll watch bug reports for a few week and evantually drop the beta tag. Click here to see what has changed since the last release.

There is a mailing list for XML-RPC/Java. Please direct all questions to this list, you'll have better chances to get a quick reply than if you send mail directly to me.

API documentation is also available. The API docs also contain information about the new applet and FESI packages, which are not described in this document.

Server side XML-RPC
    Defining an XML-RPC handler
    Embedding XML-RPC into an existing web server framework
    Using the built-in dedicated web server
Client side XML-RPC
Choosing an XML parser
Type mapping between XML-RPC and Java
Release History
History and Credits

Server side XML-RPC

Client side XML-RPC
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 command:

  java helma.xmlrpc.XmlRpcClient 12

This should call examples.getStateName(12) at nirvana.userland.com:80.

Choosing an XML parser
Type mapping between XML-RPC and Java
The following table shows type conversions from XML-RPC to 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 (including 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.
 
XML-RPC data type Data Types generated 
by the Parser
Types expected by the 
Invoker as input parameters
of RPC handlers
<i4> or <int> java.lang.Integer int
<boolean> java.lang.Boolean boolean
<string> java.lang.String java.lang.String
<double> java.lang.Double double
<dateTime.iso8601> java.util.Date java.util.Date
<struct>  java.util.Hashtable java.util.Hashtable
<array> java.util.Vector java.util.Vector
<base64> byte[ ] byte[ ]
<nil/> null null
Release History
1.0 beta 3 April 17, 2000 1.0 beta 2 April 17, 2000 1.0 beta April 17, 2000 0.5.1 July 15, 1999 0.5 July 5, 1999 0.4.2 March 18, 1999 (based in part on feedback to 0.4) 0.4 March 17, 1999 0.3 January 29, 1999 0.2 January 24, 1999 initial release
History and Credits

The initial idea for implementing XML-RPC in Java came from Tom Fürstner at the time we were working together at the Austrian Broadcasting Corporation's online division. Tom is a big supporter of both Userland Frontier and XML and has helped me to see the value of XML-RPC.

Since the first release there have been a lots of improvements and bug fixes contributed by a lot of people. Although I' sure to forget some of them I'd like to thank Matthew Woodard, Colin Sampaleanu, Daniel Beaudry, Matthew Dornquast, John Jordano, Bernd-Christoph Schwede, Scott McLoughlin, Roger Wright, Oleg Moroz, John Snell, Josh Lucas and Skip Montanaro for their feedback and contributions. If I forgot to mention you let me know.