应用开发人员指南

部署

在描述怎样组织你的源代码目录(source code directories)之前，有必要考察一下一个网络应用程序的运行时间(runtime)的组织结构。在Servlet API规范2.2版之前，各个服务器平台不是很(统一)一致。然而，遵守2.2(以及其后版)规范的服务器都被要求接受标准格式的网络应用档案(Web Application Archive),我们在下面会再讨论到这点。

一个网络应用程序可以说是由标准规划布局的一些文件和目录组成的一个阶层(hierarchy)。这样一个阶层以“未包装”的形式存取，这种形式就是指每个目录和文件在文件系统里分离存在；或者以“包装过”的形式存取，这种形式就是所谓的网络档案，或WAR文件。前面一种格式在程序开发时比较有用，而后者在你需要把可被安装使用的程序进行分配(distribute)时适用。

网络应用程序阶层的最顶层目录也就是应用程序的文件根(document root)。你将要把组成应用程序的用户接口的HTML和JSP页面放在这里。当系统管理员(system administrator)把你的应用程序调度到一个特定的服务器时，他(她)会给你的应用程序指派一个context path(这个手册的后半部会描述Tomcat的调度)。这样，如果系统管理员把你的应用程序指派给context path /catalog,那么一个有关/catalog/index.html 的URI请求(request)就会从你的文件根那里检索出index.html 文件。 /catalog/index.html

标准目录格局

为了便于按要求格式产生网络应用程序档案,合适的办法就是按照WAR的格式(format)把你的应用程序里的“可执行”文件(就是Tomcat用来执行你的程序的文件)放在同样一个组织结构里。按照这种做法，下面的有关内容应该放置在你的应用程序的“文件根”目录里。

*.html, *.jsp, etc. - HTML和JSP页面，还有其他相关文件(比如象JavaScript,stylesheet文件以及图象)应该被客户浏览器看到。对于较大的应用程序，你可以选择把这些文件分配到分支目录(subdirectory)中去，但对于小的应用程序，通常把这些文件放在一个目录里比较简单。

/WEB-INF/web.xml - 网络应用程序调度描述符。这是一个可扩充标记语言(XML)文件，它描述了构成你的程序的servlets和其他部件，同时也描述了初始化参数(initialization parameters)，以及你想要服务器执行的有关容器管理安全性的限制。以后的章节里对这个文件会有详细的讨论。 Web Application Deployment Descriptor

/WEB-INF/classes/ - 这个目录包含应用程序里必需的Java类文件(以及相关的资源)，包括没有被组合到JAR文件里的servlet和non-servlet类。如果把你的类文件组织成Java包(package)，你必须把这点也反映在/WEB-INF/classes/ .下的目录里。例如，一个叫做com.mycompany.mypackage.MyServlet 的Java class,应该被放在文件/ WEB-INF/classes/com.mycompany.mypackage.MyServlet.class里面。 /WEB-INF/classes/com/mycompany/mypackage/MyServlet.class

/WEB-INF/lib/ - 这个目录包括由Java类文件(以及相关资源)组成的JAR文件，比如象其他第三类class libraries或JDBC驱动程式(drivers)。

当你把程序安装在Tomcat里(或其他2.2/2.3相兼容的服务器上)，那些在WEB-INF/classes/目录里的classes,以及其所有的WEB-INF/lib/目录里JAR文件里的classes,对于你的程序里的其他类来说都是可视的。这样，如果你把所必须的library classes放在上面所提到的地址之一（要检查一下你是否具有重新分配third party libraries的权限），你就可以把你的程序安装简单化-- 不需要调整你的系统class path(或者在你的服务器上安装全局库文件(global library files))。

这里的许多信息摘录自第九章Servlet应用编程界面规范，2.3版，详细内容请到那里参考。

共享文件库

和许多servlet容器一样，Tomcat支持这样一种机制，那就是安装library JAR文件(或未被包装的classes),使它们可被已安装的程序使用。关于Tomcat是怎样定位和共享这些类的详细内容在Class Loader HOW-TO 文件里有描述。我们这里仅讨论在Tomcat里安装共享编码时二个通用的地址。

$CATALINA_HOME/common/lib - 放在这里的JAR文件既可被网络应用程序看见，又可被Tomcat内部编码看见(visible). 最好是把JDBC驱动程式放在这里，JDBC驱动程式是你的程序和Tomcat内部使用所必需的东西(如JDBCRealm)。

$CATALINA_HOME/shared/lib - 放在这里的JAR文件可被所有的网络应用程序看见，但不能被Tomcat内部编码看见。这个地方放置你的程序特有的共享文件库。

除此之外，标准的Tomcat5安装包括了一些先已安装好的共享文件库，它们包括：

The Servlet 2.4和JSP 2.0 APIs，它们是写servlets和JavaServer Pages的基础。

和JAXP(1.2版)应用编程接口相兼容的可扩充标记语言语法分析程式(XML Parser)，这样你的程序可执行DOM-based 或者SAX-based XML文件。

网络应用程序部署描述符

在下面的描述中使用变量名$CATALINA_HOME来代指Tomcat5所安装的目录地址,这是一个基础目录(base directory),其他的相关路径由它而派生。不过，如果你已经把Tomcat设置成多个体实例(multiple instances),并且设立了一个$CATALINA_BASE目录，那么你就应使用$CATALINA_BASE而不是$CATALINA_HOME作为参照。

如上面所提到的，/WEB-INF/web.xml 文件包括了你的程序所使用的网络应用调度描述符。从文件的附注档名(filename extension)就可以知道这是个XML文件，它描述了服务器所需要知道的关于你的程序的所有情况(context path 除外，它是由系统管理员在调度你的程序时指派的)。

完整的关于调度描述符的语法及语义在第13章the Servlet应用编程接口规范，2.3版有定义。希望在将来能够有开发工具来帮你制作和编辑调度描述符。一个basic web.xml 文件给你提供了一个起点。这个文件包含了用来解说每一个元素用途的注释。 basic web.xml file

注意— The Servlet规范为网络应用程序调度描述符提供了一个文档类型描述符(DTD)，同时Tomcat5在运行你的应用程序/WEB-INF/web.xml 文件时，强制执行这里定义的有关规责。特别地，你必须按DTD规定的顺序输入你的描述符元素(如 <filter> , <servlet> , and <servlet-mapping>)(参看13.3章节)。 <filter>

Tomcat语境描述符

在下面的描述中使用变量名$CATALINA_HOME来代指Tomcat5所安装的目录地址,这是一个基础目录(base directory),其他的相关路径由它而派生。不过，如果你已经把Tomcat设置成多个体实例(multiple instances),并且设立了一个$CATALINA_BASE目录，那么你就应使用$CATALINA_BASE而不是$CATALINA_HOME作为参照。

一个/META-INF/context.xml 文件可用来定义Tomcat特有的配置选项,如loggers, data sources, session manager 的配置及其他。这个XML文件必须包括一个上下文元素(Context element)，这个元素是Host元素的子元素，Tomcat配置文档中Host元素的注释里有Context元素的详细信息。

用Tomcat 5部署

为了能被执行，一个网络应用程序必须要被调度到servlet容器上。在开发程序时也是这样。我们将要描述应用Tomcat来提供一个可执行环境。可以用下面的几种方法在Tomcat里调度你的程序。

把未包装的目录层次复制在$CATALINA_HOME/webapps/目录下面的分目录里。基于你选择的分目录名称，Tomcat会给你的程序指派一个上下文路径(context path)。因为这是开发程序时最快最简易的方法，我们把这个技术用在我们自己构造的build.xml 文件里。确保在安装和更新你的程序后重新启动Tomcat。

把网络应用程序档案文件复制在$CATALINA_HOME/webapps/目录里。当Tomcat启动时，它会自动把网络应用程序档案文件扩展成为未包装形式，同时执行它。这种处理办法通常用来把第三类卖主或者内部开发人员提供的额外的程序加入到已经存在的Tomcat安装里。注意—如果你用这种办法，又希望在以后更新你的程序，你必须更新网络应用程序档案文件,和同时删除Tomcat产生的扩展目录，然后重新启动Tomcat，这样才能反映出更改。

利用Tomcat5"管理员"网络应用程序来部署(deploy)和反部署(undeploy)网络应用程序。Tomcat5里面包含一个被部署在context path /manager 上的程序，允许你在运行中的Tomcat服务器上进行部署和反部署，而不需要重新启动它。关于使用管理员网络程序(the Manager web application)的更多信息，请参看 administrator 文档资料(TODO: hyperlink)。 /manager

使用“管理员”Ant Tasks来制作Script。Tomcat5包括一系列定义Ant build工具的用户化作业(task)，允许你对“管理员”网络程序自动执行命令。这些作业(tasks)被用在Tomcat调度员里。

使用Tomcat调度员。Tomcat5包含一个全包装的工具来绑定(bundling)Ant作业，也可以用于自动预编译JSPs——这些JSP在被调度到服务器之前是网络应用程序的一部分。

把程序调度到其他servlet容器上的方式对每个容器都是特定的，不过所有和Servlet API Specification(2.2以及其后版本)相适宜的容器，都被要求接受网络应用程序档案文件。注意，其他容器没有被要求(象Tomcat那样)接受未包装的目录结构，或者提供共享文件库的机制，不过它们通常都有这些特性。 NOT