深入了解功能強大的 Geronimo 應用服務器的內部工作，學習如何使用它來開 發數據庫應用程序。Java 開發人員 Neal Sanche 用文章“將數據庫連接到 Geronimo 應用服務器的三種方法”（developerWorks，2005 年 6 月）開始了這 趟旅行，這篇文章指導您創建簡單的電話簿數據庫應用程序。在本文中，您將學 習如何擴展初始數據庫應用程序，並為之提供一個使用 Apache Struts 和 Enterprise JavaBeans (EJB) 後端構建的功能用戶接口。您還將學習如何使用 Apache Maven 構建系統來構建、打包和部署電話簿數據庫應用程序。通過本文學 習如何簡化您的企業 Web 應用程序開發過程。
技術概覽
在學習示例應用程序之前，首先要詳細了解一下將用於創建和部署該應用程序 的三種技術。（要閱讀有關其中每一種技術的詳細信息，請參閱 參考資料。）
Maven 是用於構建 Java 應用程序的應用程序，它從源代碼一直構建到打包至 Web 站點。Geronimo 應用服務器是使用 Maven 應用程序的構建系統構建的。在 它的核心內，Maven 的可擴展框架允許創建模塊以執行構建軟件組件時需要的一 些動作。談到 Apache Ant（Java 構建工具），Maven 的動作已經與使用 UNIX 命令 make 生成的結果進行了比較。Maven 腳本還允許將應用程序自動部署到正 在運行的 Geronimo 服務器中。本文展示了如何使用 Maven 來將源代碼打包到完 整的 Java 2 Platform, Enterprise Edition (J2EE) 企業應用程序中。
Struts 是基於 Model 2 架構的 Web 應用程序框架（參閱 參考資料 獲得 JSP Model 2 的完整描述）。該混合架構最大程度地將業務邏輯和顯示邏輯隔離 。Struts 通過將業務邏輯隔離到純 Java 類中來實現這一目標，純 Java 類操作 數據，並提供了豐富的標記庫，該庫可用於在編寫 JavaServer Pages (JSP) 時 顯示數據。（在無數可用的 Web 開發框架中，許多框架都有很高的人氣，比如 Tapestry 和 JavaServer Faces，而 Struts 一直是我偏愛的一個。）
XDoclet 起源於存在已久的 Java 文檔工具 Javadoc。XDoclet 開發人員最初 以一種新穎的方法使用 Javadoc，即使用專門的注釋來生成可以被編譯成源代碼 的模型。他們從 Javadoc 的實際使用抽身而出，生產出他們自己的變種，叫做 Xjavadoc。但是在 XDoclet 早期，仍然需要在源代碼的 Javadoc 注釋中使用標 記來自動生產自動生成的代碼。編寫 J2EE 應用程序中的源代碼和部署描述符文 件可能十分冗長乏味。對於每一百行左右的 Java 代碼，預計可以生成至少三倍 多的支持 J2EE 描述符代碼來完成工作。為了大大減少開發多層企業應用程序的 痛苦，XDoclet 伸出援手，提供了代碼標記和代碼生成以使大部分部署描述符自 動生成。這樣就隱藏了 J2EE 的大量復雜性，但您要清楚代碼生成器在構建什麼 ，因為當事情沒有如期進行時，您必須檢查它。
部署計劃
正如在簡介中提到的，Maven 被 Geronimo 團隊用來構建整個應用服務器。您 可以利用 Maven 構建工具的強大功能來編譯應用程序源代碼，執行代碼生成（需 要 XDoclet 的幫助），綁定企業應用程序模塊，並最終將其部署到正在運行的 Geronimo 服務器中。
該過程以三個文件開始。第一個文件 project.xml 定義什麼是所謂的項目對 象模型（Project Object Model，POM）。它列出應用程序的相關信息，包括應用 程序名稱、編寫者、版本號、對構建應用程序非常重要的依賴關系，以及對如何 構建應用程序的概述。出於本文目的，我們將主要研究 POM 的依賴關系部分。（ 參考資料 中有到整個 POM 文件的鏈接。）
Maven 使用 project.xml 的依賴關系部分從 Internet 上的指定資源庫中下 載構建應用程序所需的工件。iBiblio（參閱 參考資料）就是這樣一個資源庫， 它包含數百個開放源代碼 Java 庫和支持文件，以及這些庫的 POM 信息。它收集 了大量信息，目的只有一個，即簡化應用程序構建過程中 Java 開發人員的生活 。電話簿應用程序 project.xml 文件的依賴關系部分由 23 個依賴關系組成，其 中一半是 .jar 文件，用於支持 Struts 和 DisplayTag 標記庫。其余的依賴關 系主要是 XDoclet 要求。不使用 Maven，每個依賴關系都需要與示例應用程序綁 定在一起。
Maven 只在第一次編譯應用程序時下載所有依賴的工件。以後的編譯運行利用 Maven 的本地資源庫（已下載工件的本地高速緩存，通常位於 $HOME 目錄的 .maven 目錄下）來獲得工件。
安裝 Maven 1.0.2
我們的示例應用程序需要對 Maven 進行一些初始設置以使一切正確工作。首 先，需要安裝 Maven 1.0.2（參閱 參考資料 中的 Maven Web 站點鏈接）。安裝 完成後，在命令行輸入 maven，將看到類似如下的信息：
E:\Documents and Settings\Neal\My Documents\eclipse\workspace\Phonebook> maven
__ __
| \/ |__ _Apache__ ___
| |\/| / _` \ V / -_) ' \ ~ intelligent projects ~
|_| |_\__,_|\_/\___|_||_| v. 1.0.2
編譯 Geronimo
然後，按照 Wiki（參閱 參考資料）上的指令從源代碼編譯 Geronimo。成功 構建之後，Geronimo 工件將位於本地資源庫。它們是構建示例應用程序所必需的 。編譯完 Geronimo 之後，查找 geronimo-deployment-plugin-1.0- SNAPSHOT.jar 文件，並將其安裝到 $MAVEN_HOME/plugins 目錄中，否則可能會 看到如下消息：
Tag library requested that is not present: 'geronimo:deploy' in plugin: 'null'
安裝 XDoclet 1.2.3
最後，需要將 XDoclet 1.2.3 安裝到 Maven 資源庫中。如果試圖構建示例應 用程序，會顯示一條 Maven 消息，指明它無法找到一些其他的 XDoclet 1.2.3 工件，這時您可能需要下載 XDoclet 1.2.3（lib 包），並將 .jar 文件解壓到 位於 .maven/repository/xdoclet/jars 的本地 Maven 資源庫中（參閱 參考資 料 以訪問 XDoclet Web 站點）。如果您是 Windows 用戶，應該在C:\Documents and Settings\username目錄下查找該 Maven 目錄。如果您是 UNIX 用戶，應該 在主目錄下查找該目錄。還應該通過將 maven-xdoclet-plugin-1.2.3.jar 添加 到 $MAVEN_HOME/plugins 目錄來安裝 XDoclet Maven 插件。
成功構建
具備這些先決條件之後，構建過程應該能夠順利進行。當然，可以在進行上述 工作之前嘗試構建，查看 Maven 找不到哪些文件，然後只安裝這些文件。可以嘗 試在示例應用程序的頂層目錄中運行 Maven。首先，許多工件將被下載，最後， 您將看到 BUILD SUCCESSFUL 消息。
要更多了解 Maven 做什麼，研究一下 maven.xml 和 project.properties 文 件。Maven 是面向目標的。它讀取 maven.xml 並嘗試滿足頂層項目元素的默認屬 性中指定的所有目標。在本例中，它嘗試滿足部署目標指明為先決條件的所有事 項；也就是說，它將嘗試構建 .ear 文件，然後嘗試停止和啟動應用程序。應用 程序的部署是通過上述的 Geronimo Deployment Maven 插件執行的。當然， Geronimo 服務器應該運行 —— 否則構建將失敗，並顯示如下消息：
Failed to retrieve RMIServer stub: javax.naming.ServiceUnavailableException
[Root exception is java.rmi.ConnectException: Connection refused to
host: 10.0.0.7; nested exception is:
java.net.ConnectException: Connection refused: connect]
如果收到該消息，使用如下命令啟動 Geronimo 服務器：
E:\geronimo-snapshot>java -jar bin\server.jar org/apache/geronimo/
DebugConsole org/apache/geronimo/RuntimeDeployer
該命令告訴 Geronimo 啟動其服務器、DebugConsole 應用程序配置和 RuntimeDeployer 配置。
調試控制台
DebugConsole（參見 圖 1）是可選組件，允許通過一個小 Web 應用程序（參 閱 http://localhost:8080/debug-tool）查看 Geronimo 服務器中在運行什麼。
圖 1. Geronimo DebugConsole
示例頂層頁面
構建完示例應用程序之後，可以訪問它的頂層頁面，您將看到如 圖 2 所示的 內容。
圖 2. 使用 Struts 1.2.7 構建的 Geronimo Phonebook 示例應用程序
完成應用程序構建之後：底層內容
既然已經成功構建了應用程序，而且看到了使用 Maven 的強大功能和簡單性 ，現在該學習使它完全運行所必需的文件布局和部分代碼。首先介紹 Web 應用程 序層，然後介紹 EJB 層。最後將查看結締組織 —— 連接所有組件並讓它完全工 作的部署計劃和配置文件。參考 圖 3 所示的文件目錄樹，以便找到這些文件。
圖 3. 示例應用程序文件的目錄布局
Web 應用程序層
Web 應用程序是用 JSP 和 Struts 1.2.7 框架編寫的。在 src/webapp 目錄 中將會找到組成示例應用程序 Web 接口的文件。
該應用程序由兩個主要視圖組成：電話號碼列表和電話號碼編輯屏幕。從數據 庫中編輯簡單記錄必需的所有特性（添加、刪除、編輯、更新和列表）都存在。 src/java/org/acme/phonebook/struts 目錄包含大量 Struts 動作來執行這些必 需功能，比如創建新條目，刪除條目，列出所有條目，編輯現有條目。
Struts Tiles 模板系統用於確保花費在讓 Web 應用程序外觀正常上的工作最 少。webapp/pages 目錄中的 site-template.jsp 文件定義應用程序的外觀。
接下來介紹的兩個主要 JSP 是 EditPhoneNumberPage.jsp 和 ListPhoneNumbersPage.jsp。其中每個頁面及其在應用程序中的功能在 清單 1 中說明。
清單 1. EditPhoneNumberPage.jsp
<%@ page language="java"%>
<%@ taglib uri="/tags/struts-bean" prefix="bean"%>
<%@ taglib uri="/tags/struts-html" prefix="html"%>
<%@ taglib uri="/tags/struts-tiles" prefix="tiles"%>
<tiles:insert page="/pages/site-template.jsp" flush="true">
<tiles:put name="content" type="string">
<hr>
<h1><bean:message key="h1.EditPhoneNumberPage" /></h1>
<hr>
<h2><bean:write name="phoneBookEntryForm" property="action"/>
</h2>
<html:form action="/pages/SaveEntry.do">
<table>
<tr>
<td>
<bean:message key="prompt.EditPhoneNumberPage.name" />
</td>
<td>
<html:text property="name" size="40" />
</td>
</tr>
<tr>
<td>
<bean:message key="prompt.EditPhoneNumberPage.phoneNumber" />
</td>
<td>
<html:text property="phoneNumber" size="40" /></td>
</tr>
<html:hidden property="action" />
<html:hidden property="pk" />
<tr>
<td></td>
<td>
<html:submit>
<bean:message key="button.submit" />
</html:submit> <html:reset>
<bean:message key="button.reset" />
</html:reset>
</td>
</tr>
</table>
</html:form>
</tiles:put>
</tiles:insert>
在 清單 1 中，前幾行設置將在頁面中處於活動狀態的標記庫。它們還將站點 模板的內容區域設置為內容將顯示的位置。本例展示了一個簡單的基於 Struts 的輸入屏幕，它用一些 <bean:message> 標記來顯示資源庫文件（位於 webapp/WEB-INF/classes/resources/application.properties）中的字符串。屏 幕將名稱和電話號碼提交給名為 SaveEntry.do 的 Struts 動作。
如果查看 清單 2 中 SaveEntry.java 源文件中的類 Javadoc 標記，將會看 到該應用程序中 XDoclet 標記的第一個示例。這些標記定義生成 Struts 部署描 述符 struts-config.xml 必需的所有屬性。
清單 2. SaveEntry.java Javadoc 類標記
/**
* Save an Entry
*
* @struts.action
* name = "phoneBookEntryForm"
* path = "/pages/SaveEntry"
* scope = "request"
* input = "/pages/EditPhoneNumberPage.jsp"
* unknown = "false"
* validate = "false"
* @struts.action-forward
* name = "success"
* path = "/pages/ListNumbers.do"
* redirect = "true"
*/
該示例代碼位於一個 nutshell 中，展示了 /pages/SaveEntry 動作從 EditPhoneNumberPage.jsp 中獲取輸入，並使用 phoneBookEntryForm 將來自頁 面的用戶輸入打包到 Java 代碼中。該動作完成之後，它重定向到 /pages/ListNumbers 動作以顯示號碼列表。
ListNumbers 動作位於 ListNumbers.java 文件中，它使用 清單 3 中的代碼 調用名為 PhoneBookSession 的 Session EJB。
清單 3. ListNumbers 動作的 execute() 方法的代碼段
PhoneBookSessionLocal session =
PhoneBookSessionUtil.getLocalHome().create();
// Call the method
Collection c = session.listEntries();
// Put the retrieved information into the request attributes
// so the page can render them.
request.setAttribute("numbers", c);
在 清單 3 中，可以看到 PhoneBookSessionUtil 類的使用。它是一個 XDoclet 生成的類，用於幫助獲得 PhoneBookSession 對象的主接口。創建了一 個會話，調用了它的 listEntries() 方法，該方法返回所有電話簿條目的集合。 然後請求對象中的 numbers 屬性被設置為該集合。這樣做的效果是將電話號碼放 到指定位置，以便用於顯示條目的 JSP 可以檢索並寫出列表，如 清單 4 所示。
清單 4. ListPhoneNumbersPage.jsp 中的 DisplayTag
<display:table name="numbers" requestURI="ListNumbers.do"
scope="request" pagesize="5" id="row_obj">
<display:column property="name" title="Name"/>
<display:column property="phoneNumber" title="Phone"/>
<display:column title="Actions">
<logic:present name="row_obj">
<html:link action="/pages/EditEntry"
paramId="id" paramName="row_obj"
paramProperty="name">Edit</html:link>
<html:link action="/pages/DeleteEntry"
paramId="id" paramName="row_obj"
paramProperty="name"
onclick="return confirmDelete('Number')">
Delete
</html:link>
</logic:present>
</display:column>
...
</display:table>
EJB 層
該應用程序中有兩個 EJB 類。第一個類使用容器管理持久性（Container- Managed Persistence，CMP）來提供對簡單數據庫表 PhoneBookEntryBean 的基 於對象的訪問。第二個類是一個 Stateless Session bean，它提供業務邏輯。通 常需要通過無狀態會話 bean 來操作 CMP bean，因為會話 bean 可被設置來提供 對數據庫的事務處理，從而在發生錯誤時可以回滾更新。此外，在 Session bean 中執行所有 CMP 操作使得 Web 應用程序無需知道數據庫訪問層的任何實現細節 。所以如果用另一種技術替換該層（比如使用 Hibernate 持久層），將無需更改 Web 應用程序中的代碼。
XDoclet 主要用在 EJB 層中以提供部署描述符生成。這對於減少構建此類應 用程序所需的維護工作是十分重要的。下載源代碼並查看 PhoneBookEntryBean.java 和 PhoneBookSessionBean.java 的類 Javadoc 注釋 ，以了解用於定義 EJB 類的大量 XDoclet 標記。
要生成無狀態會話 bean 的方法，添加名為 @ejb.interface-method 的 XDoclet 標記，其視圖類型屬性可以為 local、remote 或 both。該屬性告訴 XDoclet 在會話 bean 的本地接口、遠程接口或兩種接口中生成相應方法。您還 可以控制事務處理類型。參見 清單 5，它是其中一個接口方法的示例，列出電話 簿條目並返回它們的值對象表示。
清單 5. PhoneBookSessionBean.java 類的 listEntries() 方法
/**
* List all of the phone book entries.
* @return a collection of PhoneBookEntryValue objects.
*
* @ejb.interface-method view-type="both"
* @ejb.transaction type="Required"
*/
public java.util.Collection listEntries() {
ArrayList values = new ArrayList();
try {
Collection entries = PhoneBookEntryUtil.getLocalHome ().findAll();
Iterator i = entries.iterator();
while(i.hasNext()) {
PhoneBookEntryLocal entry = (PhoneBookEntryLocal)i.next ();
values.add(entry.getPhoneBookEntryValue());
}
} catch (Throwable ex) {
ex.printStackTrace();
}
return values;
}
結締組織
在我的文章“將數據庫連接到 Geronimo 應用服務器的三種方法” （developerWorks，2005 年 6 月）中詳細介紹了 Geronimo 的各種部署計劃的 重要性。讓這麼小的應用程序到達功能狀態是非常有挑戰性的，需要在部署計劃 中提供許多小選項，還有 XDoclet 標記之間的交互、標記生成的代碼，以及部署 計劃。但是詳細介紹這些內容超出了本文的范圍。示例程序有許多配置文件和部 署計劃，幾乎所有的這些東西都能在項目的 src/resources 子樹中找到。下文簡 要介紹了這些文件的相關細節，以說明需要進行哪些修改才能讓將來的應用程序 工作。
ear 子目錄包含企業應用程序部署描述符、application.xml 文件和 geronimo-application.xml 文件。在該應用程序中，這些文件被配置以提供應用 程序范圍的 Java 數據庫連接 (Java Database Connectivity, JDBC) 連接器。 閱讀“將數據庫連接到 Geronimo 應用服務器的三種方法”（developerWorks， 2005 年 6 月）以獲得該配置的詳細信息。mysql-plan.xml 和 tranql- connector-1.0-SNAPSHOT.rar 文件以及 application.xml 和 geronimo- application.xml 文件中的模塊定義是該配置的一部分，用於使運行時部署器正 確設置 JDBC 連接器。
geronimo-application.xml 文件包含 <application> 元素，它具有名 為 configId 的屬性。該元素對於 Maven 構建腳本的自動部署特性的正確運行是 十分關鍵的。所設置的值可用於 maven.xml 文件中任何 <deploy:*> 的 id 屬性中，如 清單 6 所示。
清單 6. maven.xml 啟動目標
<goal name="start">
<deploy:distribute
uri="deployer:geronimo:jmx:rmi://localhost/jndi/rmi:/JMXConnector"
username="system"
password="manager"
home="${basedir}"
module="target/${pom.artifactId}.ear"
/>
<deploy:start
uri="deployer:geronimo:jmx:rmi://localhost/jndi/rmi:/JMXConnector"
username="system"
password="manager"
id="org/acme/PhoneBook"/>
</goal>
在 清單 6 中，因為 geronimo-application.xml 文件中的 configId 屬性被 設置為 org/acme/PhoneBook，所以它還必須是自動部署語句中 id 屬性的值。 Geronimo 團隊為此設置了一個非常好的自動部署工具。但是，如果您經常自動部 署，請確保檢查您的臨時目錄，因為它們可能裝滿了舊的部署文件。
資源目錄中子目錄列表中的下一個目錄是 ejb 目錄。openejb-jar.xml 部署 描述符在 META-INF 子目錄中。該文件對於數據庫和實體 (CMP) bean 之間的所 有連接是必不可少的。還必須對該文件進行小修改，以確保對於您的企業 bean 存在相應的 Java 命名和目錄接口 (Java Naming and Directory Interface, JNDI) 名稱。該文件如 清單 7 所示。
清單 7. openejb-jar.xml
<?xml version="1.0"?>
<openejb-jar
xmlns="http://www.openejb.org/xml/ns/openejb-jar"
configId="org/acme/PhonebookEJB"
parentId="MysqlDatabase">
<cmp-connection-factory>
<resource-link>MysqlDataSource</resource-link>
</cmp-connection-factory>
<enterprise-beans>
<entity>
<ejb-name>PhoneBookEntry</ejb-name>
<local-jndi-name>
java:comp/env/ejb/PhoneBookEntryLocal
</local-jndi-name>
<table-name>phone</table-name>
<cmp-field-mapping>
<cmp-field-name>name</cmp-field-name>
<table-column>name</table-column>
</cmp-field-mapping>
<cmp-field-mapping>
<cmp-field-name>phoneNumber</cmp-field-name>
<table-column>phone</table-column>
</cmp-field-mapping>
</entity>
<session>
<ejb-name>PhoneBookSession</ejb-name>
<local-jndi-name>
java:comp/env/ejb/PhoneBookSessionLocal
</local-jndi-name>
</session>
</enterprise-beans>
</openejb-jar>
清單 7 最重要的元素是 <cmp-connection-factory> 及其 <resource-link> 子元素。<resource-link> 元素內的名稱必須與 JDBC 連接器配置的名稱相匹配，如下列代碼段所示：
...
<connectiondefinition-instance>
<name>MysqlDataSource</name>
...
openejb-jar.xml 中的 <local-jndi-name> 元素也是正常工作所必需 的。如果收到找不到 JNDI 名稱的錯誤消息，則可能錯誤設置了其中一個元素。
在 清單 7 中還需注意實體 bean 的 <table-name> 和 <table- column> 元素，在此必須配置哪些數據庫表和列映射到實體 bean 字段。參見 清單 7 中的 <cmp-field-mapping> 元素，其中有兩個該配置的示例。
最後一個目錄是名為 merge 的 src/resources 目錄。該目錄的內容與 XDoclet 代碼生成的執行方式直接相關。XDoclet 從 Javadoc 標記中提取信息， 但它還將信息合並到 merge 目錄內專門命名的文件中。這些合並文件包含 Web 應用程序層的一些配置信息。在項目的 src/resources/merge 目錄中， taglibs.xml 文件允許定義應用程序中的所有標記庫。當 XDoclet 生成 web.xml 和 struts-config.xml 時，有許多文件合並到其中。
另一個部署計劃存在於 src/webapp/WEB-INF/geronimo-jetty.xml 文件中， 如 清單 8 所示。
清單 8. geronimo-jetty.xml
<?xml version="1.0"?>
<web-app
xmlns="http://geronimo.apache.org/xml/ns/web/jetty"
xmlns:naming="http://geronimo.apache.org/xml/ns/naming"
configId="org/acme/PhoneBookWeb"
>
<context-priority-classloader>true</context-priority- classloader>
</web-app>
Geronimo 的 M4 版本將 geronimo-jetty.xml 部署計劃重命名為 geronimo- web.xml。因此，如果正在使用 M4 版本，則需要刪除 清單 8 中的 "/jetty"。 其他所有代碼將如 Geronimo M4 文章所述運行。
清單 8 所示的這個部署計劃有一個重要的行。如果不將 <context- priority-classloader> 元素設置為 true，則因為 Geronimo 庫中可用類的 沖突，Struts 應用程序將無法運行。將該值設置為 true 會告訴 Geronimo 在查 找類時使用標准 Web 應用程序范圍。這意味著，該應用程序隔離於服務器中運行 的其他任何應用程序。但同時還意味著，該應用程序需要的任何類都必須與該應 用程序綁定。
應用程序依賴的所有 .jar 組件綁定在 project.xml 依賴關系部分中指定， 並由 Maven 自動處理。
最後一個配置文件是 project.properties，它驅動大多數構建處理，位於項 目的根目錄。該文件是一個倉庫，存儲 XDoclet 相關信息、有關在 .war 文件中 包含哪些內容的信息，甚至還存儲控制 Java 編譯器輸出格式的屬性。
將所有這些元素放在一起要花費大量時間，但希望您能夠使用該示例應用程序 作為您前行的墊腳石。
結束語
本文為更大的應用程序提供了非常基本的起始模板。為業務邏輯添加更多 CMP bean 和會話 bean，可以創建一個更有趣的 Web 應用程序。我已經展示了 Maven 構建系統的主要優點，即降低編譯和生成最終 .ear 文件的嵌套文件結構的復雜 性。XDoclet 代碼生成系統還用於簡化生成 EJB 工件、Struts 工件和 Web 應用 程序工件的過程，這些工件是編譯最終電話簿應用程序所必需的。使用該示例應 用程序，您現在應該能夠利用 Maven 和 XDoclet 來簡化您的企業應用程序開發 過程。
Geronimo 開發人員已經按照 Sun J2EE 規范認真構建了服務器本身，並生產 出一種將部署和配置問題與細節嚴格分離的產品，而這是用容器托管應用程序所 必需的。
本文配套源碼
