XML-RPC Libraries

A lot of work has already gone into RPC, and more recently XML-RPC. Like using SAX, DOM, and JDOM for XML handling, there is no reason to reinvent the wheel when there are good, even exceptional, Java packages in existence for your desired purpose. The center for information about XML-RPC and links to libraries for Java as well as many other languages can be found at http://www.xmlrpc.com.

On Hannes's site is a description of the classes in his XML-RPC package and instructions. Download the archive file and expand the files into your development area or IDE. You should then be able to compile these classes; there is example servlets  that requires the servlet classes (servlet.jar for Servlet API 2.2). You can obtain these classes with the Tomcat servlet engine by pointing your web browser to http://jakarta.apache.org. If you do not wish to play with the servlet example, the servlet classes are not required for the programs in this chapter.

The core distribution (which does not include the applet or regular expression examples in the downloaded archive) is made up of thirteen classes, all in the helma.xmlrpc package. These are in a ready-to-use format in the lib/xmlrpc.jar file of the distribution. The classes within that distribution are detailed briefly in Table 11-1.

Table 11-1. The XML-RPC classes

Class	Purpose
XmlRpc	Core class allowing method calls on handlers by an XML-RPC server.
XmlRpcClient	Class for client to use for RPC communication over HTTP, including proxy and cookie support.
XmlRpcClientLite	Class for client to use when a less-featured HTTP client is needed (no cookies, proxy support).
XmlRpcServer	Class for servers to use to receive RPC calls.
XmlRpcServlet	Provides the functionality of XmlRpcServer in a servlet format.
XmlRpcProxyServlet	Acts as an XML-RPC servlet proxy.
XmlRpcHandler	Base interface for controlling XML-RPC interactions by handlers.
AuthenticatedXmlRpcHandler	Same as XmlRpcHandler, but allows for authentication.
Base64	Encodes and decodes between bytes and base 64 encoding characters.
Benchmark	Times roundtrip XML-RPC interactions for a specific SAX driver.
WebServer	A lightweight HTTP server for use by XML-RPC servers.

The SAX classes (from earlier examples) and a SAX driver are not included in the distribution, but they are required for operation. In other words, you need a complete XML parser implementation that supports SAX. I continue to use Apache Xerces in these examples, although the libraries support any SAX 1.0-compatible driver.
Once you have all the source files compiled, ensure that the XML-RPC classes, SAX classes, and your XML parser classes are all in your environment's classpath. This should have you ready to write your own custom code and start the process of "saying hello." Keep the XML-RPC source files handy, as looking at what is going on under the hood can aid in your understanding of the examples.

Saying Hello

You are probably interested in seeing if XML-RPC might be the right solution for some of your development problems. To elaborate on XML-RPC, we'll now look at building some actual working Java code using XML-RPC. In the great tradition of programming, I'll start with a simple "Hello World" type program. I'll show you how to define an XML-RPC server, and have that server register a handler. This handler takes in a Java String parameter and the user's name, and returns "Hello" and the user's name; for example, the method might return "Hello Shirley" when invoked. Then you'll need to make this handler available for XML-RPC clients. Finally, I'll demonstrate building a simple client to connect to the server and request the method invocation.

In a practical case, the XML-RPC server and handler would be on one machine, probably a heavy-duty server, and the client on another machine, invoking the procedure calls remotely. However, if you don't have multiple machines available, you can still use the examples locally. Although this will be much faster than an actual client and server, you can still see how the pieces fit together and get a taste of XML-RPC.

What Is RPC?

 RPC is remote procedure calls. Where RMI lets you interoperate directly with a Java object, RPC is built in more of a dispatch fashion. Instead of dealing with objects, RPC lets you use standalone methods across a network. Although this limits interactivity, it does make for a slightly simpler interface to the client. You can think of RPC as a way to use "services" on remote machines, while RMI allows you to use "servers" on remote machines. The subtle difference is that RMI typically is driven entirely by the client, with events occurring when methods are invoked remotely. RPC is often built more as a class or set of classes that works to perform tasks with or without client intervention; however, at times these classes service requests from clients, and execute "mini" tasks for the clients. I will show you some examples shortly to clarify these definitions.

RPC, while not as interactive an environment as RMI, does offer some significant advantages. RPC allows disparate systems to work together. While RMI allows the use of IIOP for connecting Java to CORBA servers and clients, RPC allows literally any type of application intercommunication, because the transport protocol can be HTTP. Since virtually every language in use today has some means of communicating via HTTP, RPC is very attractive for programs that must connect to legacy systems. RPC is also typically more lightweight than RMI (particularly when using XML as the encoding, which I'll cover next); while RMI often has to load entire Java classes over the network (such as code for applets and custom helper classes for EJB), RPC only has to pass across the request parameters and the resulting response, generally encoded as textual data. RPC also fits very nicely into the API model, allowing systems that are not part of your specific application to still access information from your application. This means that changes to your server do not have to result in changes to other clients' application code; with pure textual data transfer and requests, additional methods can be added without client recompilation, and minor changes are sufficient to use these new methods.

The problem with RPC has traditionally been the encoding of data in transfer; imagine trying to represent a Java Hashtable or Vector in a very lightweight way through textual formats. When you consider that these structures can, in turn, hold other Java object types, the data representation quickly becomes tricky to write; it also has to remain a format that is usable by all the disparate programming languages, or the advantages of RPC are lessened. Until recently, an inverse relationship had been developing between the quality and usability of the encoding and its simplicity; in other words, the easier it became to represent complex objects, the more difficult it became to use the encoding in multiple programming languages without proprietary extensions and code. Elaborate textual representations of data were not standardized and required completely new implementations in every language to be usable. You can see where this discussion is leading.
See XML-RPC
Learn about What is RMI?

XML-RPC

XML-RPC is actually a specific flavor of RPC, which stands for remote procedure calls. If you are new to programming, or have worked with the Java language only a short time, remote procedure calls may be new for you; if you've been around the block in the development world, you may be a bit rusty, as RPC has fallen out of vogue in recent years. In this chapter I look at why those three little letters in front of RPC are revolutionizing what was becoming a computing dinosaur, and how to use XML-RPC from the world of Java. I also spend some time at the end of this chapter looking at real-world applications of XML-RPC, trying to shed some light not only on how to use this technology, but when to use it.

If you are part of the tidal wave of object-oriented development that has come along in the past three to five years, even hearing the word "procedure" may send shivers down your back. Procedural languages such as PL/SQL and ANSI C are not popular for a long list of very good reasons. You have probably been scolded for calling a Java method a function or procedure before, and almost certainly know better than to write "spaghetti code," code that has method after method chained together in a long line. RPC has fallen by the wayside much as these languages and techniques have. There are new, object-oriented ways of achieving the same results, often with better design and performance. Surprisingly, though, the rise of XML has brought with it the rise and prominence of APIs specifically built for XML-RPC, and a gradual trend toward using XML-RPC in specific situations despite the connotations it carries.

Before trying to use these APIs, it is worth spending some time looking at what RPC is and how it compares to similar Java technologies, most notably remote method invocation (RMI). If you do choose to use XML-RPC in your applications (and you almost surely will want to at some point), be assured that you will probably have to justify your choice to other developers, particularly those who may have just read books on EJB or RMI. Certainly there are places for all these technologies. Understanding the proper application of each is critical to your success not only as a developer, but as a team member and mentor. Keeping in mind these reasons for understanding the concepts behind these remote methodologies, let's take a look at the two most popular ways to operate upon objects across a network: RPC and RMI.

The greatest obstacle to using RPC has traditionally been its encoding. But then XML came along with a solution. XML provided not only a very simple, textual representation of data, but a standard for the structure of that data. Concerns about proprietary solutions became moot when the W3C released the XML 1.0 specification, reassuring RPC coders that XML was not going anywhere. In addition, SAX provided a lightweight, standard way to access XML, making it much easier to implement RPC libraries. This left only transmission over HTTP (something people have been doing for many years) and the specific encoding and decoding APIs for XML-RPC implementers to write. After a few beta implementations of XML-RPC libraries, it became clear that XML was also a very fast and lightweight encoding, resulting in better performance for XML-RPC libraries than expected. XML-RPC is now a viable and stable solution for remote procedure calls.

For you, the Java developer, XML-RPC provides a way to handle simple creation of "hooks" into your application and its services, for your own use as well as for other application clients in different divisions or even different companies. It also uncouples these APIs from Java if clients are unable to use the Java language directly. Finally, XML-RPC removes RMI from the technologies that have to be learned to use distributed services (at least initially). I'll spend this chapter looking at how to implement an XML-RPC server and client; I'll show an example of how a server can operate independently of clients, yet still provide XML-RPC accessible interfaces to interoperate with and query its data. Although I'm not going to look at RMI in depth in this chapter, I continually compare the XML-RPC solution to RMI, pointing out why XML-RPC is a better solution for some specific types of tasks.