On the server side, you can either embed the XML-RPC library into an existing server framework, or use the built-in special purpose HTTP server. Let's first look at how to register handler objects to tell an XML-RPC server how to map incoming requests to actual methods.
addHandler (String name, Object handler); removeHandler (String name);
Depending on what kind of handler object you give to the server, it will do one of the following things:
The XML-RPC library can be embedded into any Web server framework that supports reading HTTP POSTs from an InputStream. The typical code for processing an incoming XML-RPC request looks like this:
XmlRpcServer xmlrpc = new XmlRpcServer (); xmlrpc.addHandler ("examples", new ExampleHandler ()); ... byte result = xmlrpc.execute (request.getInputStream ()); response.setContentType ("text/xml"); response.setContentLength (result.length()); OutputStream out = response.getOutputStream(); out.write (result); out.flush ();
Note that the execute method does not throw any exception, since all errors are encoded into the XML result that will be sent back to the client. A full example servlet is included in the package. There is a sample XML-RPC Servlet included in the library. You can use it as a starting point for your own needs.
The XML-RPC library comes with its own built-in HTTP server. This is not a general purpose web server, its only purpose is to handle XML-RPC requests. The HTTP server can be embedded in any Java application with a few simple lines:
WebServer webserver = new WebServer (port); webserver.addHandler ("examples", someHandler);
You can also start the web server from the command line by typing:
You can specify the server port, but there's no way to manipulate RPC handlers in command line mode, so you'll either have to modify WebServer.java for your purposes or embed it into your own application. A special bonus when using the built in Web server is that you can set the IP addresses of clients from which to accept or deny requests. This is done via the following methods:
webserver.setParanoid (true); // deny all clients webserver.acceptClient ("192.168.0.*"); // allow local access webserver.denyClient ("192.168.0.3"); // except for this one ... webserver.setParanoid (false); // disable client filter
If the client filter is activated, entries to the deny list always override those in the accept list. Thus, webserver.denyClient ("*.*.*.*") would completely disable the web server.
Note that the XML-RPC client in Frontier 5 has its requests hard-coded to URI /RPC2. To work with these clients, you have to configure your server environment to respond to /RPC2. This should be fixed in a newer version.