应用程序开发人员指南

为了利用与 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 的安装位置）以及 manager 应用程序的用户名和密码。您最终可能会得到类似这样的内容

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

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

# 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 文件中的默认“compile”目标，这将编译任何新的或已更新的 Java 代码。如果这是您在“build clean”之后第一次编译，它将导致所有内容重新编译。

要强制重新编译整个应用程序，请执行此操作

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 命令将其从实时执行中移除。

完成测试后，不要忘记将您的更改提交到源代码仓库！

当您完成添加新功能并已测试所有内容（您确实测试了，对吧 :-) 时，是时候创建 Web 应用程序的可分发版本了，该版本可以部署到生产服务器上。需要以下通用步骤

• 从项目源代码目录执行命令 ant all，最后一次从头开始重建所有内容。

• 使用源代码控制系统标记代码的当前状态，为创建此发布版本所使用的所有源文件创建一个标识符。这使您能够在以后可靠地重建发布版本（从源代码）。

• 执行命令 ant dist，以创建可分发的 Web 应用程序存档 (WAR) 文件，以及一个包含相应源代码的 JAR 文件。

• 根据您组织使用的标准发布流程，使用 tar 或 zip 工具打包 dist 目录的内容。