public class Server implements AsynchronousRequestHandler, UnmarshallerAid,
          RMIServerInterface {
        private static final String NAME_PATTERN = "^example\\.(.*)";
        private XmlRpcMethodProxy proxy;
        
        public Server() {
          this.proxy = new XmlRpcMethodProxy(NAME_PATTERN, this);
        }
        
        public void handleRequest(RpcCall call, RpcCallContext context, ResponseChannel rspChannel)
            throws Exception {
          // A deferred method call can be handed off to an application thread ...
          DeferredMethodCall defCall = new DeferredMethodCall(this.proxy, call, rspChannel);
      
          // ... and executed like this.
          defCall.invoke();
        }
      
        public Class getType(String methodName, int index) {
          return this.proxy.getType(methodName, index);
        }
      
        public FieldNameCodec getFieldNameCodec(String methodName ) {
          // The default codec is almost always fine.
          return null;
        }
      }


      XmlRpcServer server = new XmlRpcServer(InetAddress.getByName(host), port);
      Server handler = new Server();
      server.registerHandler(null, Server.NAME_PATTERN, handler, handler);
      server.start();

XML-RPC over HTTPS - Using SSL

With Java 1.4 Sun introduced native support for SSL in the form of JSSE. RoX can take advantage of this if you want to secure your RPC communications. Configuration is as per Sun's instructions regarding configuring JSSE. Beyond that, using SSL with RoX is very simple. If you're using RoX as a client just make sure the protocol in your URL is set to https instead of http. If you're using RoX as a server then you simply use a constructor with an additional boolean parameter and pass in true. There are a few other slightly more fiddly bits if you want more control but that's it. Assuming JSSE has been configured correctly, or if you're happy with an anonymous SSL session, you're done.

It's a kind of magic

One last piece of magic before we're done.

This little party trick is proprietary (i.e. I made it up) and so it's not enabled by default since that would make Rox a non-compliant XML-RPC server implementation out of the box, and we wouldn't want that, would we?

The basic idea is pretty simple. Rox can, if you ask nicely, unpack HTTP GET requests that use the CGI parameter passing notation, and map these onto your XML-RPC method call handlers. Why would you want to do this? Well, often your XML-RPC method calls are actually pretty simple and XML can be pretty verbose. For example, adding two integers might logically look like this:

add(1, 2)

<?xml version="1.0"?>
<methodCall?>
   <methodName?>add</methodName?>
   <params?>
      <param?>
         <value?><int?>1</int?></value?>
      </param?>
      <param?>
         <value?><int?>2</int?></value?>
      </param?>
   </params?>
</methodCall?>

Sure, you rarely have to deal with this directly, that's why libraries like Rox exist. But you may not always have the luxury of an XML-RPC library. Perhaps none exists for the language you're using (unlikely but possible), or the environment you're working in is too contrained (perhaps you have limited resources) to support an XML-RPC library. Or maybe you're just lazy and simply shelling out to cURL or Wget appeals. Whatever the reasons, the functionality I'm describing means clients can invoke exactly the same XML-RPC server handler the above XML fragment would invoke using the following GET request:

GET http://localhost/add?1&2

curl http://localhost/add?1&2
wget http://localhost/add?1&2

Enabling this functionality is a one-liner. The sample snippet below is exactly the same as that used in the section on handling methods on the server side, with a one line addtion (four actually, but two are empty lines and one is a comment to call out the change).

      public class Server implements SynchronousRequestHandler {
        public RpcResponse handleRequest(RpcCall call, RpcCallContext context)
            throws Exception {
            // Handle the request
        }
      }


      XmlRpcServer server = new XmlRpcServer(InetAddress.getByName(host), port);
      
      // Vive Le Difference!
      server.registerRequestUnmarshaller(HttpConstants.Methods.GET, new CgiRequestUnmarshaller());
      
      server.registerHandler(null, "^example\\.", new Server());
      server.start();

A few points are worth calling out explicitly:

• This is not an either-or proposition. You can have your cake and eat it too. Registering the CGI request unmarshaller doesn't mean you can't handle vanilla XML-RPC methods at the same time. It is possible to disable the default XML-RPC unmarshaller by registering a null handler for the HTTP POST method. Why you'd want to do that, I'm not sure, but you can.
• It's possible to roll your own handlers, take a look at the com.flat502.rox.server.CgiRequestUnmarshaller class as a starting point. And there's nothing preventing you from registering handlers for custom HTTP verbs.
• You get pretty much all of Rox's unmarshalling and method dispatch magic for free. If you're using the server side dynamic proxy based API then Rox will look the method up by name and use it's signature to convert values to their appropriate type. So if you've defined an add method with a signature like this

  public int add(int a, int b)
  

  then Rox will look up the method, discover it takes two integer arguments, and convert the two values in our original GET request:

  GET http://localhost/add?1&2
  

  into integers before calling the add method.

Thanks for flying

That's it. There's not much more to say except enjoy.

List of examples

• AsyncClientDemo.java
• AsyncServerDemo.java
• RMIAsyncServerDemo.java
• RMIClientDemo.java
• RMISyncServerDemo.java
• SyncClientDemo.java
• SyncServerDemo.java
• SSLClientDemo.java
• SSLServerDemo.java
• CgiServerDemo.java
• ValidationSuiteServer.java

Supplemental source files

• RMIServerInterface.java
• TimeInfo.java