DWR 是一個相當省事的框架,一句話概括它的價值:讓你能在 JavaScript 中直接呼叫 Java 方法,不必手寫一大堆 Ajax 與序列化程式碼。它的底層仍然是 Ajax,因此天然具備無重新整理的效果。
網路上 DWR 的範例不少,但大多只示範單一種方法的呼叫。本文刻意只談「使用層面」,不深入技術與設計細節,目標是讓初學者快速看懂:不同簽名的 Java 方法,在 JavaScript 端到底該怎麼寫。
<servlet> <servlet-name>dwr-invoker</servlet-name> <servlet-class>uk.ltd.getahead.dwr.DWRServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>dwr-invoker</servlet-name> <url-pattern>/dwr/*</url-pattern> </servlet-mapping>
想在開發階段看到 DWR 自動生成的除錯/測試頁面,可以在 servlet 中加上:
<init-param> <param-name>debug</param-name> <param-value>true</param-value> </init-param>
這個參數預設是 false。設為 true 之後,拜訪 https://localhost:port/app/dwr 就能看到部署的每一個 DWR class,並且可以直接測試 Java 方法的執行結果。不過為了安全性,正式環境務必把它改回 false。
實務上會遇到兩種情況:一個 servlet 對應多個 dwr.xml,或多個 servlet 各自對應一個以上的 dwr.xml。
3.1 一個 servlet、多個 dwr.xml
<servlet>
<servlet-name>dwr-invoker</servlet-name>
<servlet-class>uk.ltd.getahead.dwr.DWRServlet</servlet-class>
<init-param>
<param-name>config-1</param-name>
<param-value>WEB-INF/dwr1.xml</param-value>
</init-param>
<init-param>
<param-name>config-2</param-name>
<param-value>WEB-INF/dwr2.xml</param-value>
</init-param>
</servlet>
這種寫法有個規則:param-name 的值必須以 config 開頭,數量可以為 0 個以上。若完全沒有 param-name,DWR 會去讀 WEB-INF/dwr.xml;一旦出現任何一個 param-name,WEB-INF/dwr.xml 就不會被載入。
3.2 多個 servlet、各自對應 dwr.xml
<servlet>
<servlet-name>dwr-invoker</servlet-name>
<servlet-class>uk.ltd.getahead.dwr.DWRServlet</servlet-class>
</servlet>
<servlet>
<servlet-name>dwr-invoker1</servlet-name>
<servlet-class>uk.ltd.getahead.dwr.DWRServlet</servlet-class>
<init-param>
<param-name>config-admin</param-name>
<param-value>WEB-INF/dwr1.xml</param-value>
</init-param>
<init-param>
<param-name>debug</param-name>
<param-value>true</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>dwr-invoker</servlet-name>
<url-pattern>/dwr/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>dwr-invoker1</servlet-name>
<url-pattern>/dwr1/*</url-pattern>
</servlet-mapping>
這種切法的附加好處是:可以搭配 J2EE security,针对不同 URL 指派不同角色,權限控管更直覺。
dwr.xml 配置:
<dwr> <allow> <create creator="new" javascript="testClass" > <param name="class" value="com.dwr.TestClass" /> <include method="testMethod1"/> </create> </allow> </dwr>
幾個標籤的含義如下:<allow> 包住所有要暴露給 JavaScript 的東西;<create> 指定可遠端存取的 Java 類別,以及 DWR 取得該類別實例的方式——creator="new" 代表呼叫無參數建構子,其他還有走 Spring IOC 容器取得實例的做法;javascript 屬性決定 JavaScript 端要用什麼名稱來存取這個物件;<param> 指定真正要暴露的類別全名;<include> 指定要公開的方法(不寫就等於全部公開);<exclude> 則相反,用來排除特定方法。
JavaScript 端要先引入三個腳本:
<script src='dwr/interface/testClass.js'></script> <script src='dwr/engine.js'></script> <script src='dwr/util.js'></script>
其中 testClass.js 是 DWR 依配置自動產生的,engine.js 與 util.js 則是 DWR 自帶的。接著就能直接呼叫:
function callTestMethod1(){
testClass.testMethod1();
}
dwr.xml 的寫法與上一節完全相同,只差在 JavaScript 端多傳一個回呼函式:
function callTestMethod2(){
testClass.testMethod2(callBackFortestMethod2);
}
function callBackFortestMethod2(data){
// data 就是方法的返回值
alert("the return value is " + data);
}
參數直接當作呼叫時的第一個引數傳入即可:
function callTestMethod3(){
var data = "test String";
testClass.testMethod3(data);
}
簡單型別 DWR 會自動處理,但 JavaBean 基於安全考量必須顯式配置 <convert>:
<dwr> <allow> <create creator="new" javascript="testClass" > <param name="class" value="com.dwr.TestClass" /> <include method="testMethod4"/> </create> <convert match="com.dwr.TestBean"> <param name="include" value="username,password" /> </convert> </allow> </dwr>
<convert> 的作用就是告訴 DWR:伺服器端的 Java 物件與序列化後的 JavaScript 之間要如何互轉。原生型別、包裝類別、String、Date、陣列與集合這些 DWR 會自動搞定;JavaBean 則一定要靠這個標籤明確宣告。其中 match 指向要轉換的 bean 名稱,內層的 <param name="include"> 則列出要暴露的屬性。
JavaScript 端一樣是傳回呼函式接收,寫法與第 2 點相同,這裡不再重複。
JavaScript 端只要傳一個物件字面量進去,屬性名稱對應 bean 的欄位即可:
function callTestMethod5(){
var data = {
username: "user",
password: "password"
};
testClass.testMethod5(data);
}
如果方法簽名裡出現泛型集合,DWR 無法自動推斷型別,必須在 dwr.xml 補上 <signatures> 段落:
<signatures> <![CDATA[ import java.util.List; import com.dwr.TestClass; import com.dwr.TestBean; TestClass.testMethod7(Map<String,TestBean>); ]]> </signatures>
歸納幾個結論:
一、Java 方法回傳 List 或 Set 時,DWR 會轉成 JavaScript 的 Object 陣列;回傳 Map 時則轉成一個 Object,其屬性名稱就是原本 Map 的 key,屬性值就是對應的 value。
二、反過來說,當 Java 方法的參數是 List、Set 或 Map 時,JavaScript 端也要依上述規則自行組出對應的資料結構再傳過去。
以上就是在使用層面上,DWR 各種類型方法呼叫的完整整理。