An XML-RPC server is a program that receives a request from a client, calls a method in response to that request, and returns the result. The server maintains a list of methods that it allows clients to call on; these are different Java classes called handlers. Apache XML-RPC handles all the XML and networking itself, enabling you to focus on the task you want a remote method to accomplish. There are several ways to serve methods remotely with the classes in the org.apache. xmlrpc package. The simplest is to use the WebServer class, which represents a simple HTTP web server that only responds to XML-RPC requests. This class has two constructors:
· WebServer(int)—Create a web server listening on the specified port number.
· WebServer(int, InetAddress)—Create a web server at the specified port and IP address. The second argument is an object of the java.net.InetAddress class.
Both constructors throw IOException exceptions if there’s an input/output problem creating and starting the server. The following statements create an XML-RPC web server on port 4413:
The web server does not contain the remote methods that clients call via XML-RPC. These reside in other Java classes, which are called handlers. To add a handler, call the server’s addHandler(String, Object) method with the specified handler name and handler object. The first argument to addHandler() is a name to give the handler, which can be anything— it’s comparable to naming a variable. Clients will use this name when calling remote methods. The SiteClient application created earlier today called the remote method dmoz.getRandomSite(). The first part of this call—the text preceding the period—refers to a handler named dmoz.
The second argument to addHandler() is an object of the class that has public methods, which can be called remotely. The following statements create a handler for a WebServer object named server:
The handler in this example is a DmozHandler object, which contains a getRandomSite() method that returns information about a random site in the Open Directory Project. You’ll be creating this class later. A class that handles remote method calls can be any Java class that contains public methods that return a value, as long as the methods take arguments that correspond with data types supported by Apache XML-RPC:
boolean, byte[], Date, double, Hashtable, int, String, and Vector.
You can easily put existing Java classes to use as XML-RPC handlers without modification as long as they do not contain public methods that should not be called and each public method returns a suitable value.
Using Apache XML-RPC, the web server allows any public method in the handler to be called, so you should use access control to keep prying clients out of methods that should remain off limits.
As the first step toward the creation of an XML-RPC service, the following code creates a simple web server that takes XML-RPC requests. Enter the text of Listing 20.4 and save the file as DmozServer.java.
