应用程序开发人员指南

• 背景
• 标准目录布局
• 共享库文件
• Web 应用程序部署描述符
• Tomcat 上下文描述符
• 使用 Tomcat 部署

在描述如何组织源代码目录之前，了解 Web 应用程序的运行时组织会很有帮助。在 Servlet API 规范 2.2 版之前，服务器平台之间的一致性很低。然而，符合 2.2（或更高）版本规范的服务器必须接受标准格式的 Web 应用程序归档文件，下文将对此进行进一步讨论。

Web 应用程序被定义为按标准布局组织的目录和文件的层级结构。这种层级结构可以以其“未打包”形式访问（其中每个目录和文件在文件系统中独立存在），也可以以“打包”形式（称为 Web 归档文件，或 WAR 文件）访问。前者格式在开发期间更有用，而后者则在分发您的应用程序以供安装时使用。

您的 Web 应用程序层级结构的顶级目录也是您应用程序的 文档根目录。在这里，您将放置构成应用程序用户界面的 HTML 文件和 JSP 页面。当系统管理员将您的应用程序部署到特定服务器时，他们会为您的应用程序分配一个 上下文路径（本手册的后续章节将描述在 Tomcat 上的部署）。因此，如果系统管理员将您的应用程序分配到上下文路径 /catalog，则引用 /catalog/index.html 的请求 URI 将从您的文档根目录中检索 index.html 文件。

为了方便创建所需格式的 Web 应用程序归档文件，将您的 Web 应用程序的“可执行”文件（即 Tomcat 在执行您的应用程序时实际使用的文件）按照 WAR 格式本身要求的相同组织结构进行排列会很方便。为此，您的应用程序的“文档根目录”将包含以下内容

• *.html、*.jsp 等。 - 您的应用程序的 HTML 和 JSP 页面，以及其他必须对客户端浏览器可见的文件（例如 JavaScript、样式表文件和图像）。在大型应用程序中，您可以选择将这些文件划分为子目录层级结构，但对于小型应用程序，通常只维护一个目录会简单得多。
  
  
• /WEB-INF/web.xml - 您的应用程序的 Web 应用程序部署描述符。这是一个 XML 文件，描述了组成您应用程序的 Servlet 和其他组件，以及您希望服务器为您强制执行的任何初始化参数和容器管理的安全性约束。此文件将在以下小节中更详细地讨论。
  
  
• /WEB-INF/classes/ - 此目录包含您的应用程序所需的任何 Java 类文件（和相关资源），包括 Servlet 和非 Servlet 类，这些文件未组合到 JAR 文件中。如果您的类组织成 Java 包，则必须在 /WEB-INF/classes/ 下的目录层级结构中反映这一点。例如，名为 com.mycompany.mypackage.MyServlet 的 Java 类需要存储在名为 /WEB-INF/classes/com/mycompany/mypackage/MyServlet.class 的文件中。
  
  
• /WEB-INF/lib/ - 此目录包含 JAR 文件，这些 JAR 文件中包含您的应用程序所需的 Java 类文件（和相关资源），例如第三方类库或 JDBC 驱动程序。

当您将应用程序安装到 Tomcat（或任何其他 2.2 或更高版本的 Servlet 容器）中时，WEB-INF/classes/ 目录中的类以及 WEB-INF/lib/ 目录中找到的 JAR 文件中的所有类都将对您的特定 Web 应用程序中的其他类可见。因此，如果您将所有所需的库类包含在这些位置之一（请务必检查您使用的任何第三方库的再分发权利许可），您将简化您的 Web 应用程序的安装——无需调整系统类路径（或在服务器中安装全局库文件）。

本信息大部分摘自 Servlet API 规范 2.3 版的第 9 章，您应查阅该章以获取更多详细信息。

与大多数 Servlet 容器一样，Tomcat 也支持一次性安装库 JAR 文件（或未打包的类），并使其对所有已安装的 Web 应用程序可见（而无需将其包含在 Web 应用程序本身内部）的机制。Tomcat 如何定位和共享此类类的详细信息在 类加载器操作指南 文档中进行了描述。Tomcat 安装中用于共享代码的常用位置是 $CATALINA_HOME/lib。放置在此处的 JAR 文件对 Web 应用程序和 Tomcat 内部代码都可见。这是放置您的应用程序或 Tomcat 内部使用（例如 DataSourceRealm）所需的 JDBC 驱动程序的好地方。

开箱即用，标准 Tomcat 安装包含各种预安装的共享库文件，包括

• Servlet 6.0 和 JSP 4.0 API，它们是编写 Servlet 和 JSP 的基础。
  
  

如上所述，/WEB-INF/web.xml 文件包含您应用程序的 Web 应用程序部署描述符。正如文件名扩展名所暗示的，该文件是一个 XML 文档，它定义了服务器需要了解的关于您应用程序的一切（除了 上下文路径，它在应用程序部署时由系统管理员分配）。

部署描述符的完整语法和语义在 Servlet API 规范 2.3 版的第 13 章中定义。随着时间的推移，预计将提供开发工具来为您创建和编辑部署描述符。同时，为了提供一个起点，这里提供了一个 基本的 web.xml 文件。此文件包含描述每个包含元素的用途的注释。

注意 - Servlet 规范包含 Web 应用程序部署描述符的文档类型描述符（DTD），Tomcat 在处理您的应用程序的 /WEB-INF/web.xml 文件时会强制执行此处定义的规则。特别是，您必须按照 DTD 定义的顺序（参见第 13.3 节）输入您的描述符元素（例如 <filter>、<servlet> 和 <servlet-mapping>）。

/META-INF/context.xml 文件可用于定义 Tomcat 特定的配置选项，例如访问日志、数据源、会话管理器配置等。此 XML 文件必须包含一个 Context 元素，该元素将被视为对应于 Web 应用程序所部署到的 Host 元素的子元素。Tomcat 配置文档 包含有关 Context 元素的信息。

下面的描述使用变量名 $CATALINA_BASE 来指代大多数相对路径解析所依据的基础目录。如果您尚未通过设置 CATALINA_BASE 目录为多个实例配置 Tomcat，则 $CATALINA_BASE 将被设置为 $CATALINA_HOME 的值，即您安装 Tomcat 的目录。

为了执行，Web 应用程序必须部署在 Servlet 容器上。即使在开发过程中也是如此。我们将描述如何使用 Tomcat 提供执行环境。Web 应用程序可以通过以下方法之一部署在 Tomcat 中

• 将未打包的目录层级结构复制到 $CATALINA_BASE/webapps/ 目录下的子目录中。Tomcat 将根据您选择的子目录名称为您的应用程序分配上下文路径。我们将在构建的 build.xml 文件中使用此技术，因为它是开发期间最快、最简单的方法。安装或更新应用程序后，请务必重启 Tomcat。
  
  
• 将 Web 应用程序归档文件复制到 $CATALINA_BASE/webapps/ 目录中。Tomcat 启动时，它会自动将 Web 应用程序归档文件展开成其未打包的形式，并以这种方式执行应用程序。这种方法通常用于将由第三方供应商或您的内部开发人员提供的额外应用程序安装到现有的 Tomcat 安装中。注意 - 如果您使用此方法，并且希望以后更新您的应用程序，您必须同时替换 Web 应用程序归档文件并删除 Tomcat 创建的已展开目录，然后重启 Tomcat，以反映您的更改。
  
  
• 使用 Tomcat “Manager” Web 应用程序来部署和取消部署 Web 应用程序。Tomcat 包含一个 Web 应用程序，默认部署在上下文路径 /manager 上，它允许您在运行中的 Tomcat 服务器上部署和取消部署应用程序而无需重启服务器。有关使用 Manager Web 应用程序的更多信息，请参见管理器应用程序操作指南。
  
  
• 在您的构建脚本中使用“Manager”Ant 任务。Tomcat 包含一套针对 Ant 构建工具的自定义任务定义，它们允许您自动化向“Manager”Web 应用程序执行命令。这些任务在 Tomcat 部署器中使用。
  
  
• 使用 Tomcat 部署器。Tomcat 包含一个捆绑了 Ant 任务的打包工具，可用于在部署到服务器之前自动预编译作为 Web 应用程序一部分的 JSP。
  
  

在其他 Servlet 容器上部署您的应用程序将因容器而异，但所有与 Servlet API 规范（2.2 版或更高版本）兼容的容器都必须接受 Web 应用程序归档文件。请注意，其他容器不要求接受未打包的目录结构（如 Tomcat 所做），也不要求提供共享库文件的机制，但这些功能通常是可用的。