how to implement XML-RPC

[Ruilin Yang]

Can anybody give me some description on how to implement XML-RPC to couple two separate applications ? What kind of classes in each side respectively ? What this classes should do (methods) ?
Thanks
Ruilin

[Valentin Crettaz]

Check out the http://www.xmlrpc.com website.
Anothe rgood site with examples is: http://classic.helma.at/hannes/xmlrpc
HIH

[Scott Bain]

One application is the "handler", which is the application being called. It does not have to implement any special interface, nor extend any special class, but it has to "register" itself with an XML-RPC Server.
The other application, which is calling across the web for the service involved, uses an instance of an XML-RPC client. Here is some code to illustrate this.
This handler is "any old class" that has at least one public method. All public methods of this class will be available to the calling programs.
public class HelloHandler {
public String sayHello(String name) {
return "Hello " + name;
}
}
Next, you need to set up a server, and register this handler class with it.
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 HelloServer [port]");
System.exit(-1);
}

try {
XmlRpc.setDriver("org.apache.xerces.parsers.SAXParser");
System.out.println("Starting XML-RPC Server...");
WebServer server = new WebServer(Integer.parseInt(args[0]));
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());
}
}

}
That's all you do on the server side.
On the client side, you do something like this:
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 {
XmlRpc.setDriver("org.apache.xerces.parsers.SAXParser");

XmlRpcClient client =
new XmlRpcClient("http://localhost:8585/");

Vector params = new Vector();
params.addElement(args[0]);

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());
}
}
Note that the package I am using here comes from Hannes Walnofer. See http://classic.helma.at/hannes/xmlrpc/
This example, btw, is very much like the one in "Java and XML" by Brett McLaughlin.
HTH

[Ruilin Yang]

Scott,
Thanks, and also Valentin.
This means I do not need to use a servlet to send this XML-RPC request over http. I believe the xml-rpc request (a xml file) needs to be constructed and passed to the clientHelloHandler class. This xml file will goes in the client program (?):
Vector params = new Vector();
params.addElement(args[0]);
String result =
String)client.execute("hello.sayHello", params);
Here I am assume the handler system is a completelly separate system, but can be connected through http. In this case how do we register the handler in the xml-rpc servern ?
Is XML-RPC server the XML-RPC library own built-in HTTP server ? As in your code:
WebServer server = new WebServer(Integer.parseInt(args[0]));
server.addHandler("hello", new HelloHandler());
If I want to build an interface package to couple two application I would need 3 classes (maybe):
one class generate the XML-RPC request (XML)file, the second one setup the XML-RPC server, register the called application/system, the 3rd one will be client program calling the called system. This 3rd class may also used to parse the response XML file/stream into a java objects and send the object back to the calling application. Or do I better use 4 classes instead of 3 ?
Please correct me.

Thanks
Ruilin

[Scott Bain]

You don't need a servlet, no, unless you want to send the request over port 80. In that case, Hannes' package has a servlet version of the server: helma.xmlrpc.XmlRpcServlet
My example used the non-servlet version, over port 8080, but the basics are the same either way.
HTH

[Scott Bain]

>I believe the xml-rpc request (a xml file) needs
>to be constructed and passed to the
>clientHelloHandler class. This xml file will
>goes in the client program (?):
Actually, the XMLRPC implementation handles all the creation and parsing of XML for you, you don't have to bother with it.
As far as registering the handler goes, the instantiation ("new") of the handler object, in:
server.addHandler("hello", new HelloHandler());
Causes the server to hold a reference to the handler instance. That's all there is to it!

[Ruilin Yang]

Scott,
Thanks, that is great information.
I am also concerned with design an xml-rpc interface as a modular. This means when either side of the applications changes I do not need to change my xml-rpc interface modular. Previously I thought I need 3 or 4 classes.
Now I like to get some comments from you about my design of the interface modular. You can correct me or even throw away what I am thinking:
If I want to build an interface package to couple two application I would need 3 classes (maybe):
one class generate the XML-RPC request (XML) file from the calling application, the second one setup the XML-RPC server, register the called application/system, the 3rd one will be client program calling the called system. This 3rd class may also used to parse the response XML file/stream received from the called application into a java objects and send the objects back to the calling application ?
Thanks again
Ruilin

[Scott Bain]

If I understand your question correctly, I think you're missing one concept here. The XMLRPC implementation handles all the XML encoding and parsing for you... you do not need to write a class that reads the XML stream; the XMLRPC client marshalls the method call into XML, the XMLRPC server unmarshalls this structure back into a standard set of parameters for the method call on the handler.
The only issue with versioning you need concern yourself with, then is the public interface of the handler class. If that changes, you'll need to change the client in terms of sending the proper parameters and casting the result back to the proper type. So long as you don't change the public interface of the handler, you don't even need to worry about these issues.
Am I answering your question here?

[Ruilin Yang]

Scott,
Thanks a lots. I am still not very clear about the implementation. For example, here is an example XML-RPC request:
<?xml version="1.0"?>
<methodCall>
<methodName>someMethod</methodName>
<params>
<param>
<value><string>someValue</string></value>
</param>
</params>
</methodCall>
Do we need to use a java class to generate this XML file dynamically.
where does this file goes ? I know this file will goes to the client program. Maybe some where in the following lines:
XmlRpcClient client =
new XmlRpcClient("http://localhost:8585/");
Vector params = new Vector();
params.addElement(args[0]);
String result =
(String)client.execute("hello.sayHello", params);
System.out.println("Response from server: " + result);
The result we get will be a xml file or java object.
Please execuse my ignorance and give me some low level instructions.
Thanks,
Ruilin

[Scott Bain]

Sorry I've not made this terribly clear...
When you invoke the XMLRPC client, it generates the XML for you, sends it to the server, where it is decomposed back into the method call. You never have to create any XML, you never store it or manipulate it in any way. Unless someone told you, you would never ever know that XML was involved.
When the server returns the value from the method, here again the XML is invisible to you... you simply cast the return value back into the type you were expecting (yes, error checking is a bit thin here), and your method call is complete.
To more specifically answer your last question, the value returned in an object, not an XML file or stream. It's upcast to Object, so you have to cast it back to whatever you know it to be (String, in this case).
Make sense?
[ January 16, 2002: Message edited by: Scott Bain ]