安装
为了使用Tomcat 5开发web应用程序,你首先要安装它。下面各小节简要的说明了必要的安装步骤。
JDK
Tomcat 5.5被设计运行在J2SE 5.0之上,但它也可以运行在JDK1.4之上,只是要求使用兼容包。
对各种平台的兼容JDKs参见http://java.sun.com/j2se/。
Tomcat
二进制Tomcat服务器安装包从http://java.sun.com/j2se/ 下载。手册假定你是使用最新的Tomcat 5发布版本。
在手册的以后内容中,例子shell脚本假定你已经设置环境变量CATALINA_HOME,该变量指定Tomcat 5的安装路径和目录。
Ant
Ant build工具的二进制安装包从http://ant.apache.org/bindownload.cgi 下载。手册假定你使用的是Ant1.4或更高版本。操作说明应该也同样适应于更高版本,但没有经过测试。
从上面提供的网址下载并安装Ant,然后把Ant的bin 目录增加到PATH 环境变量中。这样做了之后,你就可以执行ant shell命令了。
CVS
除了上面说明的工具之外,强烈建议你下载安装source code control(源代码控制、版本管理)工具来维护构建应用程序的源代码文件,如CVS(Concurrent Version System)。除了服务器程序外,你也需要合适的客户端工具,以用于check out源代码文件,和check in修改版本。
部署
在说明如何组织你的源代码目录之前,需要先检查一下web应用程序的运行时组织结构。和Servlet API规范的之前版本相比,规范2.2在服务器平台一致性方面仅有很小的改动。但是,2.2规范要求的遵循该规范的服务器必须接受Web Application Archive作为标准格式,这将在下面进行讨论。
web应用程序的标准规划被定义为层次结构的目录和文件。该层次结构有两种组织形式。一种是"unpacked"方式,这种情况下每个目录和文件分散的保存在文件系统中;另一种是"packed"方式,如Web ARchive或称WAR文件。第一种方式在开发期间比较有用,而后一种方式主要用于应用程序的发布安装。
web应用程序层次结构的顶级目录也即应用程序的document root(根文档),通常在该位置放置包含应用程序用户界面的HTML文件和JSP页面。当系统管理员将应用程序部署到一个特定的服务器上时,他将分配一个context path(上下文路径)给应用程序。因此,如果系统管理员给应用程序分配的上下文路径为 /catalog,则指向 /catalog/index.html 的URI请求将从根文档下获取index.html文件。
标准的目录结构
为了更方便按要求的格式创建Web应用程序档案文件(WAR),在放置"可执行"文件时(这里的可执行文件指Tomcat在执行你的app时实际使用到的所有文件),保持与WAR格式本身要求的组织结构相一致是最好的。因此,你需要在应用程序的"根文档"目录下放置以下内容:
● *.html, *.jsp, etc. : 应用程序中的HTML文件、JSP页面文件及其他必须对客户端浏览器可见的文件(如JavaScript,stylesheet文件,images文件)。对于大型应用程序,你需要考虑把这些文件分别放置在不同的子目录结构中,但对于一个小应用程序,通常简单地把这些文件保存在同一个目录下。
●/WEB-INF/web.xml : Web应用程序的部署描述器(Web Application Deployment Descriptor)。一个XML文件,描述servlets和其他组件,同时包括一些初始化参数、及需要服务器执行的容器管理的安全限制等。这个文件将在后面章节有更详细的描述。
●/WEB-INF/classes/ : 这个目录下保存所有的应用程序需要的、没有被打包到JAR文件中的Java类文件(及相关资源),包括servlet和non-servlet类。如果类被组织成Java的包,则必须在 /WEB-INFO/classes/ 下以目录层次结构的方式保存。例如,一个名为 com.mycompany.mypackage.MyServlet 的类,就应该保存为 /WEB-INFO/classes/com/mycompany/mypackage/MyServlet.class。
●/WEB-INF/lib/ : 这个目录下保存打包了Java类文件(及相关的资源)的JAR文件,如第三方的类库或JDBC驱动程序等。
当在Tomcat(或任何其他2.2/2.3 兼容的服务器)上安装应用程序时,WEB-INFO/classes/ 目录下的类和WEB-INFO/lib/ 目录下JAR文件中打包的所有类,对特定的web应用程序的其他类都是可见的。因此,如果在这些位置的某个地方包含了所有必须的库类(确保已经获得了使用到的任何第三方库重新发布权力的许可),就可以简化web应用程序的安装---无须对系统类路径,或服务器中全局库文件的安装环境,做任何调整。
以上说明的大部分内容摘自Servlet API规范,version 2.3,的第9章,在那里你可以看到更详细的说明。
共享库文件
如大多servlet容器一样,Tomcat 5 也支持这样的机制:库JAR文件(或unpacked 类)一次安装,即可对所有已安装的web应用程序可见(除了要包含他的web应用程序本身之外)。Tomcat如何定位并共享这些类的细节在Class Loader HOW-TO文档中有详细说明。为了实现以上机制,Tomcat 5 安装环境中有两个位置用于共享代码:
●$CATALINA_HOME/common/lib : 放置这里的JAR文件对web应用程序和内部Tomcat代码(internal Tomcat code)都可见。这是放置JDBC驱动程序的好地方,因为JDBC对你的应用程序及内部Tomcat使用(如JDBCRealm)都需要。
●$CATALINA_HOME/shared/lib : 放置这里的JAR文件对所有web应用程序可见,但对内部Tomcat代码不可见。这是放置只用于应用程序的共享库的好地方。
除此之外,标准Tomcat 5安装环境包含了各种预安装的共享库文件,如:
●Servlet 2.4 和JSP 2.0 APIs,这是写servlets和JavaServer 页面的基础;
●兼容JAXP(version 1.2)APIs的XML 解析器(XML Parser),因此你的应用程序可以执行基于DOM或基于SAX的XML文档处理。
Web Application Deployment Descriptor
以下描述中使用$CATALINA_HOME 变量名指Tomcat 5的安装目录,同时也是大部分相对路径解析的基目录。但是,如果你的Tomcat 5配置成多实例模式、并设置了CATALINA_BASE 目录时,你应该使用$CATALINA_BASE 代替$CATALINA_HOME 引用。
如上面提到的,/WEB-INFO/web.xml 文件包含应用程序的部署描述信息。如文件扩展名暗示的,此文件为XML文档,其中定义了服务器需要知道的有关应用程序的所有信息(除了context path,context path是应用程序部署时系统管理员指定的)。
部署描述器的完整语法和语义定义在Servlet API规范(version 2.3)的第13章。随着时间的推移,你的最终期望是应该提供部署工具来进行部署描述器的创建和编辑。期间,为了提供一个起点,一个基础web.xml文件(basic web.xml file)首先被提供。这个文件包含了每个元素用途的描述。
NOTE:Servlet规范为web应用程序部署描述器包含了DTD(Document Type Descriptor),Tomcat 5在处理web应用程序的 /WEB-INFO/web.xml 文件时遵循了这个规则。特别地,你必须按DTD定义的顺序输入描述符元素(如<filter>, <servlet>, 及<servlet-mapping>)。
Tomcat Context Descriptor
/META-INF/context.xml 文件用于定义Tomcat的特殊配置选项,如loggers,data sources,session manager configuration,等。此XML文件必须包含一个Context元素,Context元素看起来像是Host元素的子元素,和Host一样,Tomcat配置文档在Context元素下包含了Context的配置信息。
Deployment with Tomcat 5
为了执行,一个web应用程序必须首先被部署到一个servlet容器中。在开发期间这是必须的。这里将描述使用Tomcat 5提供一个执行环境。web应用程序可以用下面几种方法之一部署到Tomcat上:
●Copy unpacked directory hierarchy into subdirectory in directory $CATALINA_HOME/webapps/
拷贝unpacked目录层次结构到$CATALINA_HOME/webapps/ 目录下的子目录中
Tomcat 将基于你选择的子目录名分配一个context path给你的web应用程序。我们将在我们构造的build.xml文件使用这个技术,因为这是开发期间最快和最容易的方法。要确保在安装或更新应用程序后重启Tomcat。
●Copy the web application archive file into directory $CATALINA_HOME/webapps/
拷贝web应用程序档案文件到目录$CATALINA_HOME/webapps/ 下
当Tomcat启动时,它将自动展开web应用程序档案文件到其unpacked的格式,并以那种方式执行应用程序。这个方法是用于安装附加应用程序到Tomcat安装环境的典型方法,如由第三方厂家或内部开发机构提供的应用程序。
NOTE : 如果使用这个方法,并希望稍后更新应用程序,必须替换web应用程序档案文件并同时删除Tomcat创建的展开目录,然后重启tomcat以反应你的更新。
●Use the Tomcat 5 "Manager" web application to deploy and undeploy web applications
使用Tomcat 5 "Manager" web应用程序部署和去部署web应用程序
Tomcat 5包含了一个web应用程序,用于在不要重启Tomcat服务器的情况下、在运行的Tomcat服务器上完成部署和去部署web应用程序的工作。该web应用程序缺省部署在context path /manager 下。
●Use "Manager" Ant Tasks In Your Build Script
在Build脚本中用 "Manager" Ant 任务
Tomcat 5包含了一组对Ant build工具的客户化任务定义,这些任务定义允许你自动执行web应用程序管理的操作。这些任务也被用在Tomcat 的部署器中。
●Use the Tomcat Deployer
使用Tomcat 5部署器
Tomcat 5包含了一个绑定Ant任务的打包工具,这个工具可以用于在JSPs部署到服务器之前的自动预编译。
部署应用程序到其他servlet容器需要遵循其他容器的规范,但所有兼容Servlet API规范的容器都必须能够接收一个web应用程序档案文件(WAR)。注意,其他容器没有被要求一定接收unpacked目录结构(如Tomcat支持的一样),或提供共享库文件的支持,而这些特性通常都是很有用的。
源代码管理
以下描述中使用$CATALINA_HOME 变量名指Tomcat 5的安装目录,同时也是大部分相对路径解析的基目录。但是,如果你的Tomcat 5配置成多实例模式、并设置了CATALINA_BASE 目录时,你应该使用$CATALINA_BASE 代替$CATALINA_HOME 引用。
首先,一个重要建议是:将源代码目录结构与可部署的应用程序的目录结构分离。这样做有以下好处:
●如果没有"可执行的"应用程序版本在内,源代码文件可以更容易管理、删除及备份。
●源代码版本控制更容易管理源代码目录;
●部署目录结构分离可以使得构建应用程序的安装发布包时更容易选择;
如将要看到的,ant部署工具将使得这样的目录结构在创建和处理时几乎没有任何痛苦。
应用程序源代码的目录和文件结构可以由你随意设置,不过,下面的目录结构已被证明是非常适用的,这也是例子build.xml配置文件希望的结构。所有这些内容都保存在应用程序的项目源代码目录的顶级目录下:
●docs/ - 应用程序文档目标,可以保存开发小组采用的任何格式文档。
●src/ - 用于产生应用程序中唯一的servlets、beans、及其他Java类的Java源代码文件的目录。如果源代码被组织成packages(高度推荐),package结构应该和此目录下的子目录结构一致。
●web/ - 应用程序客户端可以访问的站点上的所有静态内容目录(HTML页面,JSP页面,JavaScript文件,CSS样式单文件,及图片等)。这个目录将是web应用程序的根文档,下面的任何子目录结构都被反应在访问这些文件的请求URIs。
●web/WEB-INF/ - 应用程序需要的特殊配置文件,包括web应用程序部署描述器(web.xml)、自定义标签库的标签库描述器、及其他可能包含的资源文件。虽然这个目录显示为根文档的一个子目录,但是Servlet规范禁止客户请求直接处理此目录下的内容(或其包含的任何文件)。因此,这是保存敏感的、但却是应用程序成功执行所必须的配置信息的好地方(如数据库链接用户和口令)。
在部署过程中,两个额外的目录将被临时创建:
●build/ - 当执行缺省build(ant)时,此目录包含应用程序的web应用程序档案(WAR)中的文件的一致映像。Tomcat 5 允许以这样的unpacked 目录方式部署应用程序:或者拷贝到$CATALINA_HOME/webapps 目录,或者通过"Manager"web应用程序安装。第二种方法在开发过程中非常有用。
●dist/ - 在执行ant dist时此目录被创建。它将创建web应用程序的二进制发布版本的一个一致映像,包括许可信息、文档、README文件等。
注意,这两个目录应该不被归档在版本控制中,因为他们是在部署过程中视需删除和重建的。如果想要维护一个永久的改变,你不要编辑这些目录下的任何源代码文件,这些改变将在下一次build时丢失。
外部依赖
如果应用程序需要来自外部项目或包的JAR文件(或其他资源)时该怎么办呢?常见的例子是应用程序需要包含JDBC驱动程序。
对于这个问题,不同的开发人员会采用不同的方法。我们鼓励的方法是checking依赖的JAR文件的一份拷贝到需要这些JAR文件的任何一个应用程序的版本控制系统中。可是,当在多个应用程序中使用相同JAR文件时,这样做可能导致严重的管理问题,特别是当面临对JAR文件的不同版本的升级需要时。
因此,我们建议,不要把包的拷贝保存在应用程序的版本控制系统中,而是把外部依赖集成为应用程序building的一部分。这样,就可以在部署安装时拣取合适的JAR文件版本,而无须担心每次JAR文件更新时要更新应用程序。
在例子Ant build.xml文件中,我们讲解了如何定义build属性以配置预拷贝的文件位置,而不是在这些文件改变时必须修改build.xm。
特定的开发人员使用的build属性,可以在per-application基线或缺省的"标准"build属性上进行定制,并保存在开发人员的home目录下。
在多数情况下,开发环境中已经把必须的JAR文件安装到Tomcat 5的 common/lib 或 shared/lib 目录下。如果是这样,你就不需要做任何事情,例子build.xml文件自动创建包含这些文件的编译类路径(classpath)。