Apache XML-RPC (2.0/3.0)入门：使用java搭建服务端和客户端

1、简介
　　XML-RPC的全称是XML Remote Procedure Call，即XML远程方法调用。它是一套允许运行在不同操作系统、不同环境的程序实现基于Internet过程调用的规范和一系列的实现。这种远程过程调用使用http作为传输协议，XML作为传送信息的编码格式。Xml-Rpc的定义尽可能的保持了简单，但同时能够传送、处理、返回复杂的数据结构。
　　XML-RPC是工作在Internet上的远程过程调用协议。一个XML-RPC消息就是一个请求体为xml的http-post请求，被调用的方法在服务器端执行并将执行结果以xml格式编码后返回。

请求实例

下面是一个XML-RPC的请求实例 http://ws.apache.org/xmlrpc/server.html
[html] view plaincopyprint?

POST /RPC2 HTTP/1.0User-Agent: Frontier/5.1.2 (WinNT)Host: betty.userland.comContent-Type: text/xmlContent-length: 181

　　<?xml version="1.0"?>

　　<methodCall>

　　<methodName>examples.getStateName</methodName>

　　<params>

　　<param>

　　<value><i4>41</i4></value>

　　</param>

　　</params>

　　</methodCall>

响应实例
下面是一个XML-RPC的响应实例

　　

[html] view plaincopyprint?

HTTP/1.1 200 OKConnection: closeContent-Length: 158Content-Type: text/xmlDate: Fri, 17 Jul 1998 19:55:08 GMTServer: UserLand Frontier/5.1.2-WinNT

　　<?xml version="1.0"?>

　　<methodResponse>

　　<params>

　　<param>

　　<value><string>some string params</string></value>

　　</param>

　　</params>

　　</methodResponse>

下面将简要介绍如何快速适用Apache搭建服务端和客户端
2、搭建服务端
首先通过http://labs.renren.com/apache-mirror//ws/xmlrpc/apache-xmlrpc-current-bin.zip下载最新版本，当前最新版本是3.1.3，解压后将lib目录下得所有jar包都拷贝到项目WEB-INF/lib目录下。
然后将下面这段XML加入到项目的web.xml文件中：

[html] view plaincopyprint?

<servlet>
<servlet-name>XmlRpcServlet</servlet-name>
<servlet-class>org.apache.xmlrpc.webserver.XmlRpcServlet</servlet-class>
<init-param>
<param-name>enabledForExtensions</param-name>
<param-value>true</param-value>
<description>
Sets, whether the servlet supports vendor extensions for XML-RPC.
</description>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>XmlRpcServlet</servlet-name>
<url-pattern>/xmlrpc</url-pattern>
</servlet-mapping>

先建一个java类：

[java] view plaincopyprint?

package org.apache.xmlrpc.demo;
public class Calculator {
public int add(int i1, int i2) {
return i1 + i2;
}
public int subtract(int i1, int i2) {
return i1 - i2;
}
}

在包org.apache.xmlrpc.webserver下面新建一个 XmlRpcServlet.properties文件，注意：包名和文件名都不能变。在里面添加上对刚才新建的Calculator类的声明，以便外部调用。
Calculator=org.apache.xmlrpc.demo.Calculator
=左侧是Calculator是外部调用时使用的名称，=右侧是类的全名（包括包名）
至此，服务端就简单搭建完成了。
3、搭建客户端
由于XML-RPC是支持跨平台调用的，各个平台有与之相对应的实现，这里介绍java平台下客户端的调用实现方式。
新建一个java类，贴入下面代码

[java] view plaincopyprint?

import java.net.URL;

import org.apache.xmlrpc.client.XmlRpcClient;
import org.apache.xmlrpc.client.XmlRpcClientConfigImpl;

public class RPCTest {
public static void main(String[] args)throws Exception {
XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
config.setServerURL(new URL("http://127.0.0.1:8080/ProjectName/xmlrpc"));
XmlRpcClient client = new XmlRpcClient();
client.setConfig(config);
Object[] params = new Object[]{new Integer(31), new Integer(9)};
Integer result = (Integer) client.execute("Calculator.add", params);
System.out.println(result);
}
}

将上面代码中的ProjectName换成自己的项目名称，点击运行，完成调用。
f

接下来，作为比较，我们来看看XML-RPC2.0中应该如何实现上述功能。
以下是2.0版的Server程序：
// Server2.java
package demo.xmlrpc;

import java.io.IOException;
import java.io.OutputStream;

import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.apache.xmlrpc.XmlRpcServer;

public class Server2 extends HttpServlet {
private XmlRpcServer xmlrpcServer;

public void init() throws ServletException {

// 配置XmlRpcServer

xmlrpcServer = new XmlRpcServer();

XmlRpc.setMaxThreads(2000);

XmlRpc.setKeepAlive(true);

XmlRpc.setEncoding("UTF-8");

xmlrpcServer.addHandler("fuzeAppMid", new XmlRpcServiceFacade(););

}
public void doPost(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
byte[] result = xmlrpcServer.execute(request.getInputStream());
response.setContentType("text/xml");
response.setContentLength(result.length);
OutputStream out = response.getOutputStream();
out.write(result);
out.flush();
}
}
以下是2.0版的Client程序：
// Client2.java
package demo.xmlrpc;

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

import org.apache.xmlrpc.XmlRpcClient;
import org.apache.xmlrpc.XmlRpcException;

public class Client2 {
public static void main(String[] args) {
try {
XmlRpcClient xmlrpc = new XmlRpcClient("http://localhost:8080/jsp/XmlRpcServer");
Vector<String> params = new Vector<String>();
params.addElement("Tom");
String result = (String) xmlrpc.execute("HelloHandler.sayHello", params);
System.out.println(result);
} catch (MalformedURLException e) {
System.out.println(e.toString());
} catch (XmlRpcException e) {
System.out.println(e.toString());
} catch (IOException e) {
e.printStackTrace();
}
}
}
总体上看，3.0比2.0在可配置性方面有了一些改进，其它方面则没有太大变化，但由于功能模块的分离，使得3.0较2.0显得更为复杂，已经习惯了2.0单一模块风格的开发者可能需要一些时间适应这种变化。

三、其它特性

除了上面的基本功能，XML-RPC3还支持动态代理/工厂和异步通信等特性。
通过运用动态代理特性，我们可以在Server端及Client端共享接口信息，从而在编译期间进行必要的类型检查，在XML-RPC内部，所有的调用仍然是被动态转发给XmlRpcClient对象来完成的。但要使用XML-RPC3的动态代理功能，相应的服务器端的处理器类名称必须是Client端接口类的全名（含包名，该名称一般应该与Server端接口类全名一致），否则将会导致调用失败。以上面的HelloHandler接口为例，其对应的处理器类名称应该为：demo.xmlrpc.HelloHandler。
Note: 动态代理（JDK1.3引入）是Proxy模式、依赖注入（Dependency Injection）及动态代码生成等技术相结合的一种应用，在各新型Web应用框架及容器中被广泛采用。
而要使用XML-RPC的异步通信功能，只需实现org.apache.xmlrpc.client.AsyncCallback接口，该接口包括两个方法：
public void handleResult(XmlRpcRequest pRequest, Object pResult);
public void handleError(XmlRpcRequest pRequest, Throwable pError);
此外，为了便于在普通应用中使用XML-RPC，XML-RPC还提供了一个WebServer类，以便在应用中内嵌一个HTTP服务器，为Client程序提供HTTP服务。
下面的范例演示了上面提到的几种特性，以下是Server端代码：
// Server3.java
package demo.xmlrpc;

import org.apache.xmlrpc.server.PropertyHandlerMapping;
import org.apache.xmlrpc.server.XmlRpcServer;
import org.apache.xmlrpc.server.XmlRpcServerConfigImpl;
import org.apache.xmlrpc.webserver.WebServer;

public class Server3 {
private static final int port = 8080;

public static void main(String [] args) throws Exception {
WebServer webServer = new WebServer(port);

XmlRpcServer xmlRpcServer = webServer.getXmlRpcServer();

PropertyHandlerMapping phm = new PropertyHandlerMapping();
phm.addHandler("demo.xmlrpc.HelloHandler", HelloHandlerImpl.class);

xmlRpcServer.setHandlerMapping(phm);

XmlRpcServerConfigImpl serverConfig = (XmlRpcServerConfigImpl)xmlRpcServer.getConfig();
serverConfig.setEnabledForExtensions(true);
serverConfig.setContentLengthOptional(false);

webServer.start();
}
}
下面是Client端代码：
// Client3.java
package demo.xmlrpc;

import java.net.URL;
import java.util.List;
import java.util.Vector;

import org.apache.xmlrpc.XmlRpcRequest;
import org.apache.xmlrpc.XmlRpcException;
import org.apache.xmlrpc.client.XmlRpcClient;
import org.apache.xmlrpc.client.XmlRpcClientConfigImpl;
import org.apache.xmlrpc.client.AsyncCallback;
import org.apache.xmlrpc.client.util.ClientFactory;

class EchoCallback implements AsyncCallback {
public void handleResult(XmlRpcRequest pRequest, Object pResult) {
System.out.println("Server returns: " + (String)pResult);
}

public void handleError(XmlRpcRequest pRequest, Throwable pError) {
System.out.println("Error occurs: " + pError.getMessage());
}
}

public class Client3 {
public static void main(String [] args) throws Exception {
// create configuration
XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
config.setServerURL(new URL("http://localhost:8080/xmlrpc"));
config.setEnabledForExtensions(true);
config.setConnectionTimeout(60 * 1000);
config.setReplyTimeout(60 * 1000);

XmlRpcClient client = new XmlRpcClient();
// set configuration
client.setConfig(config);

// make a call using dynamic proxy
ClientFactory factory = new ClientFactory(client);
HelloHandler handler = (HelloHandler)factory.newInstance(HelloHandler.class);
String str = handler.sayHello("Bill David");
System.out.println(str);

// make an asynchronous call
List<String> params = new Vector<String>(); // for JDK before 1.5, use 'List params = new Vector();'
params.add("Tom");
client.executeAsync("demo.xmlrpc.HelloHandler.sayHello", params, new EchoCallback());
}
}
Note:由于Server3使用了8080端口，注意不要在Tomcat运行时启动Server3（除非你的Tomcat运行在其他端口）。

参考：

1. XML-RPC，http://ws.apache.org/xmlrpc/
2. XML-RPC协议，http://hedong.3322.org/archives/000470.html
3. Dynamic Proxy Classes，http://java.sun.com/j2se/1.3/docs/guide/reflection/proxy.html
4. 透明，动态代理的前世今生，《程序员》2005年第1期。