JAVA—咖啡館

摘要：

XML-RPC是一種簡單的，輕量級的通過HTTP協(xié)議進行RPC通信的規(guī)范。本文以Apache XML-RPC 3.0為基礎(chǔ)，對XML-RPC的基本原理及Apache XML-RPC 3.0的主要特性進行了討論和分析。

正文：

一、概述

XML-RPC是一種簡單的，輕量級的通過HTTP協(xié)議進行RPC通信的規(guī)范。一個XML-RPC消息就是一個請求體為XML的HTTP-POST請求，被調(diào)用的方法在服務(wù)器端執(zhí)行并將執(zhí)行結(jié)果以XML格式編碼后返回。

以下是通過ethereal抓到的一個典型的XML-RPC調(diào)用包（為便于閱讀，進行了格式化）：

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

<?xml version="1.0" encoding="UTF-8"?>

<methodCall xmlns:ex="http://ws.apache.org/xmlrpc/namespaces/extensions">

      <methodName>Calculator.add</methodName>

      <params>

            <param>

                  <value>

                        <i4>2</i4>

                  </value>

            </param>

            <param>

                  <value>

                        <i4>3</i4>

                  </value>

            </param>

      </params>

</methodCall>

而對應(yīng)的返回數(shù)據(jù)包為：

HTTP/1.1 200 OK

Server: Apache XML-RPC 1.0

Connection: close

Content-Type: text/xml

Content-Length: 189

<?xml version="1.0" encoding="UTF-8"?>

<methodResponse xmlns:ex="http://ws.apache.org/xmlrpc/namespaces/extensions">

      <params>

            <param>

                  <value>

                        <i4>5</i4>

                  </value>

            </param>

      </params>

</methodResponse>

其格式很簡單，幾乎是不言自明的，分別用methodCall和methodResponse標簽標識發(fā)送給Server的調(diào)用請求和Server的返回結(jié)果，請求方法的名稱用methodName標識，參數(shù)用params和param標識，而參數(shù)的類型標簽則如下表所示：

Tag	Java Type	說明
<i4> or <int>	Integer/int	4字節(jié)帶符號整數(shù)值
<boolean>	Boolean	0 (false) or 1 (true)
<string>	String	字符串
<double>	Double	雙精度帶符號浮點值
<dateTime.iso8601>	java.util.Date	日期/時間
<base64>	byte[]	base64編碼的二進制數(shù)據(jù)
<struct>	java.util.Map	鍵值對，鍵為String類型，而值為任意有效類型
<array>	Object[] java.util.List	對象數(shù)組

二、舉例

下面舉一個實際運用XML-RPC進行RPC調(diào)用的例子，XML-RPC規(guī)范有多種針對不同語言的實現(xiàn)，這里我們使用的是Apache的XML-RPC3.0RC1。

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

commons-codec-1.3（通用編碼/解碼算法實現(xiàn)，可參考http://www.devx.com/Java/Article/29795/1954?pf=true或http://jakarta.apache.org/commons/codec/userguide.html來獲得該軟件包的詳細信息）

commons-httpclient-3.0.1（HTTP協(xié)議的客戶端編程工具包，詳細介紹見http://www-128.ibm.com/developerworks/cn/opensource/os-httpclient/）

將上述通用工具包解壓后，拷貝其中的jar文件到XML-RPC解壓目錄的dist目錄中。

并添加如下環(huán)境變量：

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

 

整個應(yīng)用很簡單，通過XML-RPC調(diào)用Server端提供的HelloHandler.sayHello方法回顯一個字符串信息。下面是HelloHandler接口及其實現(xiàn)類相關(guān)代碼：

// HelloHandler.java

package demo.xmlrpc;

 

public interface HelloHandler {

      public String sayHello(String str);

}

 

// HelloHandlerImpl.java

package demo.xmlrpc;

 

public class HelloHandlerImpl implements HelloHandler {

      public String sayHello(String str){

            return "Hello, " + str + "!";

      }

}

以下是對應(yīng)的Server端源代碼：

// Server1.java

package demo.xmlrpc;

 

import java.io.IOException;

import java.io.OutputStream;

import javax.servlet.ServletConfig;

import javax.servlet.ServletException;

import javax.servlet.http.HttpServlet;

import javax.servlet.http.HttpServletRequest;

import javax.servlet.http.HttpServletResponse;

 

import org.apache.xmlrpc.XmlRpcException;

import org.apache.xmlrpc.server.PropertyHandlerMapping;

import org.apache.xmlrpc.server.XmlRpcServerConfigImpl;

import org.apache.xmlrpc.webserver.XmlRpcServletServer;

 

public class Server1 extends HttpServlet {

      private XmlRpcServletServer server;

     

      public void init(ServletConfig pConfig) throws ServletException {

            super.init(pConfig);

            try {

                  // create a new XmlRpcServletServer object

                  server = new XmlRpcServletServer();

                  // set up handler mapping of XmlRpcServletServer object

                  PropertyHandlerMapping phm = new PropertyHandlerMapping();

                  phm.addHandler("HelloHandler", HelloHandlerImpl.class);                 

                  server.setHandlerMapping(phm);

                  // more config of XmlRpcServletServer object     

                  XmlRpcServerConfigImpl serverConfig = (XmlRpcServerConfigImpl)server.getConfig();

                  serverConfig.setEnabledForExtensions(true);

                  serverConfig.setContentLengthOptional(false);

            } catch (XmlRpcException e) {

                  try {

                        log("Failed to create XmlRpcServer: " + e.getMessage(), e);

                  } catch (Throwable ignore) {

                  }

                  throw new ServletException(e);

            }

      }

     

      public void doPost(HttpServletRequest pRequest, HttpServletResponse pResponse)

            throws IOException, ServletException {

            server.execute(pRequest, pResponse);

      }

}

以下是對應(yīng)的Client端源代碼：

// Client1.java

package demo.xmlrpc;

 

import java.io.IOException;

import java.net.MalformedURLException;

import java.util.Vector;

import java.net.URL;

 

import org.apache.xmlrpc.XmlRpcException;

import org.apache.xmlrpc.client.XmlRpcClient;

import org.apache.xmlrpc.client.XmlRpcClientConfigImpl;

 

public class Client1 {

      public static void main(String[] args) {

            try {

                  // config client

                  XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();

                  config.setServerURL(new URL("http://localhost:8080/jsp/XmlRpcServer"));      // should be modified according to your configuration of jsp container

                  // create a new XmlRpcClient object and bind above config object with it

                  XmlRpcClient client = new XmlRpcClient();

                  client.setConfig(config);

                  // create parameter list

                  Vector<String> params = new Vector<String>();

                  params.addElement("Tom");

                  // execute XML-RPC call

                  String result = (String) client.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();

            }

      }

}

程序源碼中已包含了詳細的注釋，這里就不作過多解釋了。但需注意XmlRpcDemo_Client中的ServerURL信息應(yīng)根據(jù)自己的的jsp容器的配置作相應(yīng)調(diào)整，并需設(shè)置相應(yīng)的servlet-mapping信息，在我的jsp目錄（Tomcat5.5的Context之一）下的WEB_INF/web.xml文件中存在如下的servlet-mapping信息：

<servlet>

      <servlet-name>XmlRpcServer</servlet-name>

      <servlet-class>demo.xmlrpc.Server1</servlet-class>

</servlet>

<servlet-mapping>

      <servlet-name>XmlRpcServer</servlet-name>

      <url-pattern>/XmlRpcServer</url-pattern>

</servlet-mapping>

并且，上述Server1.class及其他相關(guān)類文件已被拷貝到jsp/WEB-INF/classes/demo/xmlrpc目錄下。

在啟動Tomcat并執(zhí)行

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

前，你應(yīng)該將%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中應(yīng)該如何實現(xiàn)上述功能。

以下是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 {

      public void doPost(HttpServletRequest request, HttpServletResponse response)

                  throws ServletException, IOException {

            XmlRpcServer xmlrpc = new XmlRpcServer();

            xmlrpc.addHandler("HelloHandler", new HelloHandlerImpl());

            byte[] result = xmlrpc.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顯得更為復(fù)雜，已經(jīng)習(xí)慣了2.0單一模塊風(fēng)格的開發(fā)者可能需要一些時間適應(yīng)這種變化。

三、其它特性

除了上面的基本功能，XML-RPC3還支持動態(tài)代理/工廠和異步通信等特性。

通過運用動態(tài)代理特性，我們可以在Server端及Client端共享接口信息，從而在編譯期間進行必要的類型檢查，在XML-RPC內(nèi)部，所有的調(diào)用仍然是被動態(tài)轉(zhuǎn)發(fā)給XmlRpcClient對象來完成的。但要使用XML-RPC3的動態(tài)代理功能，相應(yīng)的服務(wù)器端的處理器類名稱必須是Client端接口類的全名（含包名，該名稱一般應(yīng)該與Server端接口類全名一致），否則將會導(dǎo)致調(diào)用失敗。以上面的HelloHandler接口為例，其對應(yīng)的處理器類名稱應(yīng)該為：demo.xmlrpc.HelloHandler。

Note: 動態(tài)代理（JDK1.3引入）是Proxy模式、依賴注入（Dependency Injection）及動態(tài)代碼生成等技術(shù)相結(jié)合的一種應(yīng)用，在各新型Web應(yīng)用框架及容器中被廣泛采用。

而要使用XML-RPC的異步通信功能，只需實現(xiàn)org.apache.xmlrpc.client.AsyncCallback接口，該接口包括兩個方法：

public void handleResult(XmlRpcRequest pRequest, Object pResult);

public void handleError(XmlRpcRequest pRequest, Throwable pError);

此外，為了便于在普通應(yīng)用中使用XML-RPC，XML-RPC還提供了一個WebServer類，以便在應(yīng)用中內(nèi)嵌一個HTTP服務(wù)器，為Client程序提供HTTP服務(wù)。

下面的范例演示了上面提到的幾種特性，以下是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協(xié)議，http://hedong.3322.org/archives/000470.html

3.    Dynamic Proxy Classes，http://java.sun.com/j2se/1.3/docs/guide/reflection/proxy.html

4.    透明，動態(tài)代理的前世今生，《程序員》2005年第1期。