應用程式開發人員指南

為了利用與Manager Web 應用程式互動的特殊 Ant 任務，您需要執行以下任務一次（無論您計畫開發多少個 Web 應用程式）。

• 設定 Ant 自訂任務。Ant 自訂任務的實作程式碼在一個名為 $CATALINA_HOME/lib/catalina-ant.jar 的 JAR 檔案中，必須將其複製到 Ant 安裝的 lib 目錄中。

• 定義一個或多個 Tomcat 使用者。Manager Web 應用程式在安全約束下執行，需要使用者登入，並將安全角色 manager-script 指派給他們。如何定義這些使用者取決於您在 Tomcat 的 conf/server.xml 檔案中設定哪個 Realm，如需更多資訊，請參閱 Realm 設定操作指南。您可以定義任意數量的使用者（使用您喜歡的任何使用者名稱和密碼）並具有 manager-script 角色。

第一步是建立新的專案原始碼目錄，並自訂您將使用的 build.xml 和 build.properties 檔案。目錄結構說明於 前一節，或者您可以使用 範例應用程式 作為起點。

建立專案原始碼目錄，並在原始碼控制系統中定義它。這可以使用一系列像這樣的指令來完成

cd {my home directory}
mkdir myapp <-- Assumed "project source directory"
cd myapp
mkdir docs
mkdir src
mkdir web
mkdir web/WEB-INF
cvs or svn or git ... <-- Add this structure to the appropriate repository

若要驗證專案是否已在原始碼控制儲存庫中正確建立，您可能希望將專案簽出到一個獨立目錄，並確認所有預期的內容都存在。

接下來，您需要建立並簽入 build.xml 腳本的初始版本，以用於開發。為了快速且輕鬆地開始，請將您的 build.xml 建立在 基本 build.xml 檔案 上，此檔案包含在本手冊中，或從頭開始編寫。

cd {my home directory}
cd myapp
emacs build.xml     <-- if you want a real editor :-)
cvs or svn or git ... <-- Add this file to the repository

下一步是自訂在 build.xml 腳本中命名的 Ant 屬性。這可以透過在專案的頂層目錄中建立一個名為 build.properties 的檔案來完成。支援的屬性列在範例 build.xml 腳本內的註解中。至少，您通常需要定義 catalina.home 屬性，定義 Tomcat 安裝位置，以及管理員應用程式使用者名稱和密碼。您可能會得到類似這樣的結果

# Context path to install this application on
app.path=/hello

# Tomcat installation directory
catalina.home=/usr/local/apache-tomcat-10.1

# Manager webapp username and password
manager.username=myusername
manager.password=mypassword

一般來說，您不會想要將 build.properties 檔案簽入原始碼控制儲存庫，因為它對每個開發人員的環境都是唯一的。

現在，建立 Web 應用程式部署描述符的初始版本。您可以將 web.xml 建立在 基本 web.xml 檔案 上，或從頭開始編寫。

cd {my home directory}
cd myapp/web/WEB-INF
emacs web.xml
cvs or svn or git ... <-- Add this file to the repository

編輯/建立/測試任務通常會是您在開發和維護期間最常見的活動。下列一般原則適用。如 原始碼組織 中所述，新建立的原始碼檔案應位於適當的子目錄中，在您的專案原始碼目錄下。

您應該定期更新您的開發目錄，以反映其他開發人員執行的工作。

若要建立新檔案，請前往適當的目錄並建立檔案。當您對其內容感到滿意時（在建立和測試成功後），將新檔案新增到儲存庫。例如，若要建立新的 JSP 頁面

cd {my home directory}
cd myapp/web        <-- Ultimate destination is document root
emacs mypage.jsp
... build and test the application ...
cvs or svn or git ... <-- Add this file to the repository

定義在套件中的 Java 原始碼必須組織在目錄階層中（在 src/ 子目錄下），以符合套件名稱。例如，名為 com.mycompany.mypackage.MyClass.java 的 Java 類別應儲存在檔案 src/com/mycompany/mypackage/MyClass.java 中。每當您建立新檔案時，別忘了將它新增到原始碼控制系統中。

若要編輯現有的原始碼檔案，您通常只需開始編輯和測試，然後在一切正常時提交已變更的檔案。

當您準備好要編譯應用程式時，請發出下列指令（通常，您會希望開啟一個設定為專案原始碼目錄的 shell 視窗，這樣就只需要最後一個指令）

cd {my home directory}
cd myapp        <-- Normally leave a window open here
ant

Ant 工具會在您的 build.xml 檔案中執行預設的「編譯」目標，它會編譯任何新的或已更新的 Java 程式碼。如果您在「清除建置」後第一次編譯，它會導致所有內容重新編譯。

若要強制重新編譯您的整個應用程式，請改用此方法

cd {my home directory}
cd myapp
ant all

在檢查變更之前，養成這個非常好的習慣，以確保您沒有引入 Javac 的條件檢查未偵測到的任何細微問題。

若要測試您的應用程式，您會希望在 Tomcat 下安裝它。最快的執行方式是使用範例 build.xml 程式碼中包含的自訂 Ant 任務。使用這些指令可能會遵循類似這樣的模式

• 在需要時啟動 Tomcat。如果 Tomcat 尚未執行，您需要以一般方式啟動它。

• 編譯您的應用程式。使用 ant compile 指令（或僅使用 ant，因為這是預設值）。請確認沒有編譯錯誤。

• 安裝應用程式。使用 ant install 指令。這會指示 Tomcat 立即開始在 app.path 建置屬性中定義的內容路徑上執行您的應用程式。Tomcat 不需要 重新啟動才能讓此變更生效。

• 測試應用程式。使用您的瀏覽器或其他測試工具，測試您應用程式的功能。

• 視需要修改和重新建置。當您發現需要變更時，請在原始 原始碼 檔案中進行這些變更，而不是在輸出建置目錄中，並重新發出 ant compile 指令。這可確保您的變更將可用於稍後儲存（透過您選擇的原始碼控制系統）-- 輸出建置目錄會在必要時刪除並重新建立。

• 重新載入應用程式。Tomcat 會自動辨識 JSP 頁面的變更，但它會持續使用任何 servlet 或 JavaBean 類別的舊版本，直到重新載入應用程式為止。您可以透過執行 ant reload 指令來觸發此動作。

• 完成後移除應用程式。當您完成此應用程式的作業時，您可以透過執行 ant remove 指令來將它從執行中移除。

完成測試後，別忘了將變更提交到原始碼儲存庫！

當您完成新增功能，且已測試所有內容（您有測試，對吧 :-），此時該建立可部署在生產伺服器的網路應用程式可發行版本。需要執行下列一般步驟

• 從專案原始碼目錄中，發出指令 ant all，最後一次從頭開始重新建置所有內容。

• 使用原始碼控制系統標記程式碼的目前狀態，為用於建立此版本的原始檔建立識別碼。這讓您可以稍後從（原始檔）可靠地重建版本。

• 發出指令 ant dist，建立可發行的網路應用程式封存 (WAR) 檔案，以及包含對應原始碼的 JAR 檔案。

• 根據組織使用的標準發行程序，使用 tar 或 zip 工具封裝 dist 目錄的內容。