Apache XML-RPC 教學文章+ 示範程式

[主題]
Apache XML-RPC 示範教學 (一)

[目的]
嘗試創作, 分享學習經驗

[下載連結]


[簡介]
Apache XML-RPC 為一組使用 Java 所寫成的 XML-RPC 套件, Apache XML-RPC 的類別分為 Client 端以及 Server 端兩大部分, 它是透過兩套廣為使用的協定 XML 以及 HTTP 來實作遠端程式呼叫.

[使用教學 Client 篇]
在 Client 方面提供了兩個主要的類別, 分別簡述如下:

1. org.apache.xmlrpc.XmlRpcClient
此類別使用了 java.net.URLConnection 類別, 為標準的 HTTP Client.

2. org.apache.xmlrpc.XmlRpcClientLite
此類別實作了自訂的輕量級 HTTP Client .

Tip:
假如您需要完整的 HTTP 協議支援 (例如: 代理伺服器, 重新導向...等等功能), 請使用 XmlRpcClient 類別. 反過來說, 假如您的程式並不需要完整的 HTTP 協議支援, 而又需要考慮到效能問題時, 請您嘗試上述兩種 Client 類別: XmlRpcClient 及 XmlRpcClientLite. 因為在某些平台上 XmlRpcClient 可能會較快些, 而在某些平台上, XmlRpcClientLite 則表現的更為出色. 此兩類別提供了同樣的介面, 都包含了同步以及非同步的呼叫. 因此, 使用方法上大同小異, 請使用者不必擔憂.

同步的 XML 遠端程式呼叫:
Apache XML-RPC 在使用上非常的直觀及簡易. 以下唯一些示範的程式碼, 各位也可以依樣畫葫蘆.

  //宣告一個簡易的 XmlRpcClient (使用標準的 J2SDK 套件)
  XmlRpcClient client = new XmlRpcClient ("http://knight.fcu.edu.tw:8080/XML-RPC");
  //params 存放了您的方法中所使用到的參數
  Vector params = new Vector ();
  params.addElement ("您的參數");
  //execute 方法將回傳字傳型態
  String result = (String) client.execute ("方法名稱", params);

Tip:
請各位朋友特別注意的是在當執行 execute 方法時可能會丟出 XmlRpcException 以及 IOException, 您必須再程式碼中宣告當例外發生時候的處理模式.

非同步的 XML 遠端程式呼叫:
Apache XML-RPC 支援非同步的遠端程式呼叫. 它是經由 XML-RPC Client 類別中的 eexecuteAsync() 方法來達成. 使用該方法會啟動另外一個執行緒來執行該方法的呼叫, 而 executeAsync 會立即回傳, 而不像 execute 方法會等待處理結果. 假如您想要知道遠端的執行結果, 或是想要在例外發生時被通知, 您可以傳入一個實作 org.apache.xmlrpc.AsyncCallback 介面的物件類別. 此介面定義了兩個方法: 

public void handleResult (Object result, URL url, String method);
public void handleError (Exception exception, URL url, String method);

此兩方法會視遠端執行的狀況而個別被呼叫.

[使用教學 Server 篇]
在 Server 這端, 您可以選擇把函式庫綁入現有的 server 框架軟體, 或者使用此套件中內建的迷你 HTTP 伺服器. 就讓我們先來看看要如何使用 Server 端的相關類別, 並學習如何在 Server 上註冊相對應的處理物件.

XML-RPC Handler Objects
Apache XML-RPC 套件在 Server 端也同樣提供了兩個類別供各位朋友使用, 分別簡述如下:

1. org.apache.xmlrpc.XmlRpcServer
此類別為 Apache XML-RPC 中的標準 Server 類別, 可用于和現成的 Server 整合.
2. org.apache.xmlrpc.WebServer
此類別提供前面我提到的迷你 HTTP 伺服器.

上面的兩個 Server 端類別都提供下列方法以供您註冊或註銷當作 XML 遠端成呼叫處理類別的 Java 物件.

addHandler (String name, Object handler);
removeHandler (String name);

Tip:
視您提供給 Server 的處理類別, 將會出現下列的情形:
假如您傳給 XmlRpcServer 任何的 Java 物件, 它將會透過物件的自省機製 (object introspection) 嘗試著去解析所有進來的程式呼叫. 舉例來說: 透過尋找在處理類別之中的公用方法, 找出相對應于呼叫裡頭所要求的方法名稱以及參數型態. 特別注意的是在 XML 遠端程式呼叫的要求中的參數型態必須符合下列規定:

A.
XML-RPC 資料型態: or
XML Parser 所產生的資料型態: java.lang.Integer
Client 所預期的資料型態: int

B.
XML-RPC 資料型態:
XML Parser 所產生的資料型態: java.lang.Boolean
Client 所預期的資料型態: boolean

C.
XML-RPC 資料型態:
XML Parser 所產生的資料型態: java.lang.String
Client 所預期的資料型態: java.lang.String

D.
XML-RPC 資料型態:
XML Parser 所產生的資料型態: java.lang.Double
Client 所預期的資料型態: double

F.
XML-RPC 資料型態:
XML Parser 所產生的資料型態: java.util.Date
Client 所預期的資料型態: java.util.Date

G.
XML-RPC 資料型態:
XML Parser 所產生的資料型態: java.util.Hashtable
Client 所預期的資料型態: java.util.Hashtable

H.
XML-RPC 資料型態:
XML Parser 所產生的資料型態: java.util.Vector
Client 所預期的資料型態: java.util.Vector

G.
XML-RPC 資料型態:
XML Parser 所產生的資料型態: byte[ ]
Client 所預期的資料型態: byte[ ]

否則呼叫將會失敗. 同樣地, 所回傳的結果型態也必須被此 XML 遠端程式呼叫套件所支援. 而若您傳入實作 org.apache.xmlrpc.XmlRpcHandler 或 org.apache.xmlrpc.AuthenticatedXmlRpcHandler 介面的程式處理物件給 XmlRpcServer 時, execute() 方法將會在每次遠端程式呼叫時被呼叫. 因此您能夠完全的控制如何來處理 XML 遠端程式呼叫要求, 也讓您能夠對輸入和輸出的參數來作檢查以及轉換, 以及進行錯誤處理...等等.

未完, 請待續篇

Best regards,
tzutolin