ava RPC通信机制之XML-RPC：Apache XML-RPC 3.0开发简介

luinstein

摘要：

XML-RPC是一种简单的，轻量级的通过HTTP协议进行RPC通信的规范。本文以Apache XML-RPC 3.0为基础，对XML-RPC的基本原理及Apache XML-RPC 3.0的主要特性进行了讨论和分析。

正文：一、概述

XML-RPC是一种简单的，轻量级的通过HTTP协议进行RPC通信的规范。一个XML-RPC消息就是一个请求体为XML的HTTP-POST请求，被调用的方法在服务器端执行并将执行结果以XML格式编码后返回。

以下是通过ethereal抓到的一个典型的XML-RPC调用包（为便于阅读，进行了格式化）：

POST /xmlrpc HTTP/1.1

Content-Type: text/xml

User-Agent: Apache XML RPC 3.0 (Jakarta Commons httpclient Transport)

Host: 135.252.156.147:8080

Content-Length: 260

1. <?xml version="1.0" encoding="UTF-8"?>
   
2. <methodCall xmlns:ex="http://ws.apache.org/xmlrpc/namespaces/extensions">
   
3.       <methodName>Calculator.add</methodName>
   
4.       <params>
   
5.             <param>
   
6.                   <value>
   
7.                         <i4>2</i4>
   
8.                   </value>
   
9.             </param>
   
10.             <param>
    
11.                   <value>
    
12.                         <i4>3</i4>
    
13.                   </value>
    
14.             </param>
    
15.       </params>
    
16. </methodCall>

复制代码

而对应的返回数据包为：

HTTP/1.1 200 OK

Server: Apache XML-RPC 1.0

Connection: close

Content-Type: text/xml

Content-Length: 189

1. <?xml version="1.0" encoding="UTF-8"?>
   
2. <methodResponse xmlns:ex="http://ws.apache.org/xmlrpc/namespaces/extensions">
   
3.       <params>
   
4.             <param>
   
5.                   <value>
   
6.                         <i4>5</i4>
   
7.                   </value>
   
8.             </param>
   
9.       </params>
   
10. </methodResponse>

复制代码

其格式很简单，几乎是不言自明的，分别用methodCall和methodResponse标签标识发送给Server的调用请求和Server的返回结果，请求方法的名称用methodName标识，参数用params和param标识，而参数的类型标签则如下表所示：

Tag	Java Type	说明
<i4> or <int>	Integer/int	4字节带符号整数值
<boolean>	Boolean	0 (false) or 1 (true)
<string>	String	字符串
<double>	Double	双精度带符号浮点值
<dateTime.iso8601>	java.util.Date	日期/时间
<base64>	byte[]	base64编码的二进制数据
<struct>	java.util.Map	键值对，键为String类型，而值为任意有效类型
<array>	Object[]              java.util.List	对象数组

二、举例

下面举一个实际运用XML-RPC进行RPC调用的例子，XML-RPC规范有多种针对不同语言的实现，这里我们使用的是Apache的XML-RPC3.0RC1。

在开始之前，需到http://jakarta.apache.org/commons/index.html下载如下程序包：

commons-codec-1.3（通用编码/解码算法实现，可参考http://www.devx.com/Java/Article/29795/1954?pf=true或http://jakarta.apache.org/commons/codec/userguide.html来获得该软件包的详细信息）

commons-httpclient-3.0.1（HTTP协议的客户端编程工具包，详细介绍见http://www-128.ibm.com/developerworks/cn/opensource/os-httpclient/）

将上述通用工具包解压后，拷贝其中的jar文件到XML-RPC解压目录的dist目录中。

并添加如下环境变量：

XMLRPC_HOME      XML-RPC的解压目录

XMLRPC_LIB        %XMLRPC_HOME%/dist

XMLRPCCLASSPATH      %XMLRPC_LIB%/xmlrpc-common-3.0rc1.jar;%XMLRPC_LIB%/xmlrpc-server-3.0rc1.jar;%XMLRPC_LIB%/xmlrpc-client-3.0rc1.jar;%XMLRPC_LIB%/commons-httpclient-3.0.1.jar;%XMLRPC_LIB%/commons-codec-1.3.jar

整个应用很简单，通过XML-RPC调用Server端提供的HelloHandler.sayHello方法回显一个字符串信息。下面是HelloHandler接口及其实现类相关代码：

1. // HelloHandler.java
   
2. package demo.xmlrpc;
   
3. 
   
4. public interface HelloHandler {
   
5.       public String sayHello(String str);
   
6. }
   
7. 
   
8. // HelloHandlerImpl.java
   
9. package demo.xmlrpc;
   
10. 
    
11. public class HelloHandlerImpl implements HelloHandler {
    
12.       public String sayHello(String str){
    
13.             return "Hello, " + str + "!";
    
14.       }
    
15. }

复制代码

以下是对应的Server端源代码：

1. // Server1.java
   
2. package demo.xmlrpc;
   
3. 
   
4. import java.io.IOException;
   
5. import java.io.OutputStream;
   
6. import javax.servlet.ServletConfig;
   
7. import javax.servlet.ServletException;
   
8. import javax.servlet.http.HttpServlet;
   
9. import javax.servlet.http.HttpServletRequest;
   
10. import javax.servlet.http.HttpServletResponse;
    
11. 
    
12. import org.apache.xmlrpc.XmlRpcException;
    
13. import org.apache.xmlrpc.server.PropertyHandlerMapping;
    
14. import org.apache.xmlrpc.server.XmlRpcServerConfigImpl;
    
15. import org.apache.xmlrpc.webserver.XmlRpcServletServer;
    
16. 
    
17. public class Server1 extends HttpServlet {
    
18.       private XmlRpcServletServer server;
    
19.       
    
20.       public void init(ServletConfig pConfig) throws ServletException {
    
21.             super.init(pConfig);
    
22.             try {
    
23.                   // create a new XmlRpcServletServer object
    
24.                   server = new XmlRpcServletServer();
    
25.                   // set up handler mapping of XmlRpcServletServer object
    
26.                   PropertyHandlerMapping phm = new PropertyHandlerMapping();
    
27.                   phm.addHandler("HelloHandler", HelloHandlerImpl.class);                  
    
28.                   server.setHandlerMapping(phm);
    
29.                   // more config of XmlRpcServletServer object      
    
30.                   XmlRpcServerConfigImpl serverConfig = (XmlRpcServerConfigImpl)server.getConfig();
    
31.                   serverConfig.setEnabledForExtensions(true);
    
32.                   serverConfig.setContentLengthOptional(false);
    
33.             } catch (XmlRpcException e) {
    
34.                   try {
    
35.                         log("Failed to create XmlRpcServer: " + e.getMessage(), e);
    
36.                   } catch (Throwable ignore) {
    
37.                   }
    
38.                   throw new ServletException(e);
    
39.             }
    
40.       }
    
41.       
    
42.       public void doPost(HttpServletRequest pRequest, HttpServletResponse pResponse)
    
43.             throws IOException, ServletException {
    
44.             server.execute(pRequest, pResponse);
    
45.       }
    
46. }

复制代码

以下是对应的Client端源代码：

1. // Client1.java
   
2. package demo.xmlrpc;
   
3. 
   
4. import java.io.IOException;
   
5. import java.net.MalformedURLException;
   
6. import java.util.Vector;
   
7. import java.net.URL;
   
8. 
   
9. import org.apache.xmlrpc.XmlRpcException;
   
10. import org.apache.xmlrpc.client.XmlRpcClient;
    
11. import org.apache.xmlrpc.client.XmlRpcClientConfigImpl;
    
12. 
    
13. public class Client1 {
    
14.       public static void main(String[] args) {
    
15.             try {
    
16.                   // config client
    
17.                   XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
    
18.                   config.setServerURL(new URL("http://localhost:8080/jsp/XmlRpcServer"));      // should be modified according to your configuration of jsp container
    
19.                   // create a new XmlRpcClient object and bind above config object with it
    
20.                   XmlRpcClient client = new XmlRpcClient();
    
21.                   client.setConfig(config);
    
22.                   // create parameter list
    
23.                   Vector<String> params = new Vector<String>();
    
24.                   params.addElement("Tom");
    
25.                   // execute XML-RPC call
    
26.                   String result = (String) client.execute("HelloHandler.sayHello", params);                  
    
27.                   System.out.println(result);
    
28.             } catch (MalformedURLException e) {
    
29.                   System.out.println(e.toString());
    
30.             } catch (XmlRpcException e) {
    
31.                   System.out.println(e.toString());
    
32.             } catch (IOException e) {
    
33.                   e.printStackTrace();
    
34.             }
    
35.       }
    
36. }

复制代码

程序源码中已包含了详细的注释，这里就不作过多解释了。但需注意XmlRpcDemo_Client中的ServerURL信息应根据自己的的jsp容器的配置作相应调整，并需设置相应的servlet-mapping信息，在我的jsp目录（Tomcat5.5的Context之一）下的WEB_INF/web.xml文件中存在如下的servlet-mapping信息：

1. <servlet>
   
2.       <servlet-name>XmlRpcServer</servlet-name>
   
3.       <servlet-class>demo.xmlrpc.Server1</servlet-class>
   
4. </servlet>
   
5. <servlet-mapping>
   
6.       <servlet-name>XmlRpcServer</servlet-name>
   
7.       <url-pattern>/XmlRpcServer</url-pattern>
   
8. </servlet-mapping>

复制代码

并且，上述Server1.class及其他相关类文件已被拷贝到jsp/WEB-INF/classes/demo/xmlrpc目录下。

在启动Tomcat并执行

java -classpath %CLASSPATH%;%XMLRPCCLASSPATH% demo.xmlrpc.Client1.java

前，你应该将%XMLRPC_HOME%/dist、%XMLRPC_HOME%/lib下的几个jar文件（source就不用拷了）及前面下载的commons-codec-1.3.jar拷贝到%TOMCAT_HOME%/common/lib或jsp/WEB-INF/lib下。

Note：除了上面这种方式，你可以无需编写任何Server端代码，仅通过简单配置完成上述功能，具体可参考：http://ws.apache.org/xmlrpc/server.html

接下来，作为比较，我们来看看XML-RPC2.0中应该如何实现上述功能。

以下是2.0版的Server程序：

1. // Server2.java
   
2. package demo.xmlrpc;
   
3. 
   
4. import java.io.IOException;
   
5. import java.io.OutputStream;
   
6. 
   
7. import javax.servlet.ServletException;
   
8. import javax.servlet.http.HttpServlet;
   
9. import javax.servlet.http.HttpServletRequest;
   
10. import javax.servlet.http.HttpServletResponse;
    
11. 
    
12. import org.apache.xmlrpc.XmlRpcServer;
    
13. 
    
14. public class Server2 extends HttpServlet {
    
15.       public void doPost(HttpServletRequest request, HttpServletResponse response)
    
16.                   throws ServletException, IOException {
    
17.             XmlRpcServer xmlrpc = new XmlRpcServer();
    
18.             xmlrpc.addHandler("HelloHandler", new HelloHandlerImpl());
    
19.             byte[] result = xmlrpc.execute(request.getInputStream());
    
20.             response.setContentType("text/xml");
    
21.             response.setContentLength(result.length);
    
22.             OutputStream out = response.getOutputStream();
    
23.             out.write(result);
    
24.             out.flush();
    
25.       }
    
26. }

复制代码

以下是2.0版的Client程序：

1. // Client2.java
   
2. package demo.xmlrpc;
   
3. 
   
4. import java.io.IOException;
   
5. import java.net.MalformedURLException;
   
6. import java.util.Vector;
   
7. 
   
8. import org.apache.xmlrpc.XmlRpcClient;
   
9. import org.apache.xmlrpc.XmlRpcException;
   
10. 
    
11. public class Client2 {
    
12.       public static void main(String[] args) {
    
13.             try {
    
14.                   XmlRpcClient xmlrpc = new XmlRpcClient("http://localhost:8080/jsp/XmlRpcServer");
    
15.                   Vector<String> params = new Vector<String>();
    
16.                   params.addElement("Tom");
    
17.                   String result = (String) xmlrpc.execute("HelloHandler.sayHello", params);
    
18.                   System.out.println(result);
    
19.             } catch (MalformedURLException e) {
    
20.                   System.out.println(e.toString());
    
21.             } catch (XmlRpcException e) {
    
22.                   System.out.println(e.toString());
    
23.             } catch (IOException e) {
    
24.                   e.printStackTrace();
    
25.            }
    
26.       }
    
27. }

复制代码

总体上看，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端代码：

1. // Server3.java
   
2. package demo.xmlrpc;
   
3. 
   
4. import org.apache.xmlrpc.server.PropertyHandlerMapping;
   
5. import org.apache.xmlrpc.server.XmlRpcServer;
   
6. import org.apache.xmlrpc.server.XmlRpcServerConfigImpl;
   
7. import org.apache.xmlrpc.webserver.WebServer;
   
8. 
   
9. public class Server3 {
   
10.       private static final int port = 8080;
    
11. 
    
12.       public static void main(String [] args) throws Exception {
    
13.             WebServer webServer = new WebServer(port);
    
14. 
    
15.             XmlRpcServer xmlRpcServer = webServer.getXmlRpcServer();
    
16. 
    
17.             PropertyHandlerMapping phm = new PropertyHandlerMapping();
    
18.             phm.addHandler("demo.xmlrpc.HelloHandler", HelloHandlerImpl.class);
    
19.             
    
20.             xmlRpcServer.setHandlerMapping(phm);
    
21. 
    
22.             XmlRpcServerConfigImpl serverConfig = (XmlRpcServerConfigImpl)xmlRpcServer.getConfig();
    
23.             serverConfig.setEnabledForExtensions(true);
    
24.             serverConfig.setContentLengthOptional(false);
    
25. 
    
26.             webServer.start();
    
27.       }
    
28. }

复制代码

下面是Client端代码：

1. // Client3.java
   
2. package demo.xmlrpc;
   
3. 
   
4. import java.net.URL;
   
5. import java.util.List;
   
6. import java.util.Vector;
   
7. 
   
8. import org.apache.xmlrpc.XmlRpcRequest;
   
9. import org.apache.xmlrpc.XmlRpcException;
   
10. import org.apache.xmlrpc.client.XmlRpcClient;
    
11. import org.apache.xmlrpc.client.XmlRpcClientConfigImpl;
    
12. import org.apache.xmlrpc.client.AsyncCallback;
    
13. import org.apache.xmlrpc.client.util.ClientFactory;
    
14. 
    
15. class EchoCallback implements AsyncCallback {
    
16.       public void handleResult(XmlRpcRequest pRequest, Object pResult) {
    
17.             System.out.println("Server returns: " + (String)pResult);
    
18.       }
    
19.       
    
20.       public void handleError(XmlRpcRequest pRequest, Throwable pError) {
    
21.             System.out.println("Error occurs: " + pError.getMessage());
    
22.       }
    
23. }

复制代码

1. public class Client3 {
   
2.       public static void main(String [] args) throws Exception {
   
3.             // create configuration
   
4.             XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
   
5.             config.setServerURL(new URL("http://localhost:8080/xmlrpc"));
   
6.             config.setEnabledForExtensions(true);
   
7.             config.setConnectionTimeout(60 * 1000);
   
8.             config.setReplyTimeout(60 * 1000);
   
9. 
   
10.             XmlRpcClient client = new XmlRpcClient();
    
11.             // set configuration
    
12.             client.setConfig(config);
    
13.             
    
14.             // make a call using dynamic proxy
    
15.             ClientFactory factory = new ClientFactory(client);
    
16.             HelloHandler handler = (HelloHandler)factory.newInstance(HelloHandler.class);
    
17.             String str = handler.sayHello("Bill David");
    
18.             System.out.println(str);
    
19.             
    
20.             // make an asynchronous call
    
21.             List<String> params = new Vector<String>(); // for JDK before 1.5, use 'List params = new Vector();'
    
22.             params.add("Tom");
    
23.             client.executeAsync("demo.xmlrpc.HelloHandler.sayHello", params, new EchoCallback());
    
24.       }
    
25. }

复制代码

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期。

from:http://go.cxweb.com.cn/psc5u