11.2.1. XML-RPC Libraries

Table 11-1. The XML-RPC classes

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.

11.2.2. Writing the Handler

Table 11-2. Supported Java types in XML-RPC

This is as simple as it seems. The method signature takes in and returns legal XML-RPC parameters, so you can safely register it with your (soon to be created) XML-RPC server and know it will be callable via XML-RPC.

11.2.3. Writing the Server

package javaxml2;

import helma.xmlrpc.WebServer;
import helma.xmlrpc.XmlRpc;

public class HelloServer {

    public static void main(String[] args) {
        if (args.length < 1) {
            System.out.println(
                "Usage: java javaxml2.HelloServer [port]");
            System.exit(-1);
        }
    
        try {
            // Use the Apache Xerces SAX Driver
            XmlRpc.setDriver("org.apache.xerces.parsers.SAXParser");

            // Start the server
            
        } catch (ClassNotFoundException e) {
            System.out.println("Could not locate SAX Driver");
        }                    
    }
}

package javaxml2;

import java.io.IOException;

import helma.xmlrpc.WebServer;
import helma.xmlrpc.XmlRpc;

public class HelloServer {

    public static void main(String[] args) {
        if (args.length < 1) {
            System.out.println(
                "Usage: java javaxml2.HelloServer [port]");
            System.exit(-1);
        }
    
        try {
            // Use the Apache Xerces SAX Driver
            XmlRpc.setDriver("org.apache.xerces.parsers.SAXParser");

            // Start the server
            System.out.println("Starting XML-RPC Server...");
            WebServer server = new WebServer(Integer.parseInt(args[0]));            
            
        } catch (ClassNotFoundException e) {
            System.out.println("Could not locate SAX Driver");
        } catch (IOException e) {
            System.out.println("Could not start server: " + 
                e.getMessage( ));
        }                                
    }
}

Compile this class and give it a try; it is completely functional, and should print out the status line and then pause, waiting for requests. You now need to add the handler class to the server so that it can receive requests.

Thus, the method requested is never explicitly defined in the XML-RPC server, but rather in the request from the client. Only a class instance is registered with the XML-RPC server. You can add methods to that class, restart the XML-RPC server with no code changes (allowing it to register an updated class instance), and then immediately request the new methods within your client code. As long as you can determine and send the correct parameters to the server, the new methods are instantly accessible. This is one of the advantages of XML-RPC over RMI, in that it can more closely represent an API; there are no client stubs, skeletons, or interfaces that must be updated. If a method is added, the method signature can be published to the client community and used immediately.

        try {
            // Use the Apache Xerces SAX Driver
            XmlRpc.setDriver("org.apache.xerces.parsers.SAXParser");

            // Start the server
            System.out.println("Starting XML-RPC Server...");
            WebServer server = new WebServer(Integer.parseInt(args[0]));            
            
            // Register the handler class
            server.addHandler("hello", new HelloHandler( ));
            System.out.println(
                "Registered HelloHandler class to \"hello\"");     

            System.out.println("Now accepting requests...");
            
        } catch (ClassNotFoundException e) {
            System.out.println("Could not locate SAX Driver");
        } catch (IOException e) {
            System.out.println("Could not start server: " + 
                e.getMessage( ));
        }      

It's that simple! You can now write a client for the server, and test communications across a network using XML-RPC. This is another advantage of XML-RPC; the barrier for entry into coding servers and clients is low, compared to the complexity of using RMI. Read on, and see creating a client is just as straightforward.

11.2.4. Writing the Client

package javaxml2;

import java.net.MalformedURLException;

import helma.xmlrpc.XmlRpc;
import helma.xmlrpc.XmlRpcClient;

public class HelloClient {
 
    public static void main(String args[]) {
        if (args.length < 1) {
            System.out.println(
                "Usage: java HelloClient [your name]");
            System.exit(-1);
        }
        
        try {
            // Use the Apache Xerces SAX Driver
            XmlRpc.setDriver("org.apache.xerces.parsers.SAXParser");
            
            // Specify the server
            XmlRpcClient client = 
                new XmlRpcClient("http://localhost:8585/");  

            // Create request

            // Make a request and print the result          
          
        } catch (ClassNotFoundException e) {
            System.out.println("Could not locate SAX Driver");
        } catch (MalformedURLException e) {
            System.out.println(
                "Incorrect URL for XML-RPC server format: " + 
                e.getMessage( ));
        }        
    } 
}

Although no actual RPC calls are being made, you now have a fully functional client application. You can compile and run this application, although you won't see any activity, as no connection is made until a request is initiated.

WARNING: Make sure you use the port number in your source code that you plan to specify to the server when you start it up. Obviously, this is a poor way to implement connectivity between the client and server; changing the port the server listens to requires changing the source code of our client! In your own applications, make this a user-defined variable; I've kept it simple for example purposes.

The ease with which this client and our server come together is impressive. Still, this program is not of much use until it actually makes a request and receives a response. To encode the request, invoke the execute( ) method on your XmlRpcClient instance. This method takes in two parameters: the name of the class identifier and method to invoke, which is a single String parameter, and a Vector containing the method parameters to pass in to the specified method. The class identifier is the name you registered to the HelloHandler class on the XML-RPC server; this identifier can be the actual name of the class, but it is often something more readable and meaningful to the client, and in this case it was "hello". The name of the method to invoke is appended to this, separated from the class identifier with a period, in the form [class identifier].[method name]. The parameters must be in the form of a Java Vector, and should include any parameter objects that are needed by the specified method. In the simple sayHello( ) method, this is a String with the name of the user, which should have been specified on the command line.

Once the XML-RPC client encodes this request, it sends the request to the XML-RPC server. The server locates the class that matches the request's class identifier, and looks for a matching method name. If a matching method name is found, the parameter types for the method are compared with the parameters in the request. If a match occurs, the method is executed. If multiple methods are found with the same name, the parameters determine which method is invoked; this process allows normal Java overloading to occur in the handler classes. The result of the method invocation is encoded by the XML-RPC server, and sent back to the client as a Java Object (which in turn could be a Vector of Objects!). This result can be cast to the appropriate Java type, and used in the client normally. If a matching class identifier/method/parameter signature is not found, an XmlRpcException is thrown back to the client. This ensures the client is not trying to invoke a method or handler that does not exist, or sending incorrect parameters.

All this happens with a few additional lines of Java code. You must import the XmlRpcException class, as well as java.io.IOException; the latter is thrown when communication between the client and server causes error conditions. You can then add the Vector class and instantiate it, adding to it a single String parameter. This allows your code to invoke the execute( ) method with the name of the handler, the method to call, and its parameters; the result of this call is cast to a String, which is printed out to the screen. In this example, the local machine is running the XML-RPC server on port 8585:

package javaxml2;

import java.io.IOException;
import java.net.MalformedURLException;
import java.util.Vector;

import helma.xmlrpc.XmlRpc;
import helma.xmlrpc.XmlRpcClient;
import helma.xmlrpc.XmlRpcException;

public class HelloClient {
 
    public static void main(String args[]) {
        if (args.length < 1) {
            System.out.println(
                "Usage: java HelloClient [your name]");
            System.exit(-1);
        }
        
        try {
            // Use the Apache Xerces SAX Driver
            XmlRpc.setDriver("org.apache.xerces.parsers.SAXParser");
            
            // Specify the server
            XmlRpcClient client = 
                new XmlRpcClient("http://localhost:8585/");  
                
            // Create request  
            Vector params = new Vector( );            
            params.addElement(args[0]);
            
            // Make a request and print the result          
            String result = 
               (String)client.execute("hello.sayHello", params);
        
            System.out.println("Response from server: " + result);
          
        } catch (ClassNotFoundException e) {
            System.out.println("Could not locate SAX Driver");
        } catch (MalformedURLException e) {
            System.out.println(
                "Incorrect URL for XML-RPC server format: " + 
                e.getMessage( ));
        } catch (XmlRpcException e) {
            System.out.println("XML-RPC Exception: " + e.getMessage( ));
        } catch (IOException e) {
            System.out.println("IO Exception: " + e.getMessage( ));
        }        
    } 
}

That's all that is required to make this work. Now compile your source code and open a command shell for running the example.

11.2.5. Talk to Me

Make sure that you have the XML-RPC classes and your example classes in your environment's classpath. Also, confirm that Apache Xerces or your chosen SAX driver is in your classpath and accessible, as the examples must load these classes for parsing. Once that is set up, start the HelloServer class by giving it a port number. On Windows, use the start command to start the server in a separate process:

c:\javaxml2\build>start java javaxml2.HelloServer 8585
Starting XML-RPC Server...
Registered HelloHandler class to "hello"
Now accepting requests...

On Unix, use the background processing command (&) to make sure you can run your client as well (or open another terminal window and duplicate your environment settings):

$ java javaxml2.HelloServer &
Starting XML-RPC Server...
Registered HelloHandler class to "hello"
Now accepting requests...