应用开发者指南_source

应用开发者指南

源代码组织

目录

·   目录结构 1.  外部依赖 ·   源代码控制 ·   BUILD.XML 配置文件

 

目录结构

下面的描述使用$CATALINA_BASE作为相对路径的基础。如果您没有使用CATALINA_BASE使Tomcat配置成多实例，$CATALINA_BASE会被设置成$CATALINA_HOME，也就是Tomcat6的安装目录。 本手册推荐您将源代码目录结构（本章描述的）和应用部署的目录结构（前面章节描述的）分开。保持这种分离有下面几点好处： ·   如果可执行的web应用不混乱，源代码目录的内容就更容易管理、移动和备份。 ·   源代码控制工具更容易管理仅有源代码文件的目录。 ·   当部署的目录结构分开时，构成您应用的可安装的发布版本文件更容易选择。 正如我们将会看到的那样，ant部署工具使创建和处理这些目录结构几乎是毫无痛苦可言的。 一个应用实际用来放置源代码的目录和文件结构可以放任何您喜欢的东西。尽管如此，接下来讨论的组织形式会更加可用，并且是下面讨论的样例配置文件build.xml所期望的。所有这些组成部分放在项目源代码目录的最上层： ·   docs/ - 您的应用的文档，不管什么格式，请放在该目录下。 ·   src/ - 您的应用要生成servlets，beans和其它class的Java源代码文件。如果您的应用是用包结构组织的（非常推荐），包层次结构应该反映该目录下的目录层次结构。 ·   web/ - 应用的客户端要访问的web站点的静态内容（例如HTML页面，JSP页面，JavaScript文件，Css样式文件以及图片文件）。该目录是您的web应用的文档根目录，并且这里能找到的任何子目录结构将会反映在用于请求资源的请求URI上。 ·   web/WEB-INF/ - 您的应用所需要的特殊配置文件，包括web应用描述符文件(web.xml,在Servlet Specification 中定义)， 您所创建的自定义标签库的描述符文件， 以及web应用所您想包含的其它资源文件。尽管该目录是文档根目录的子目录，Servlet 规范 禁止直接使用该目录的内容（或任何它所包含的文件）向客户端请求提供服务。因此，这是放置配置文件的很好的地方，这些配置文件含有敏感信息（例如数据库连接的用户名和密码）但对您的应用又是必须的操作的。 在开发过程中，将会创建2个临时目录： ·   build/ - 当执行一次缺省的构建（ant），该目录会放入web应用包WAR的完整的文件列表的image。Tomcat 6 运行您部署这种解包目录的应用，可以把它们拷贝到$CATALINA_BASE/webapps目录，或者通过“Manager”web应用来安装。后一种方法在开发阶段非常有用，下面将描述。 ·   dist/ - 当您执行ant的dist目标，该目录就会被创建。他将创建web应用发布文件的完整映像,包括许可信息，文档以及您准备的README文件。 请注意，这两个目录在您的源代码控制系统中不应被打包，因为它们在开发过程中会按需从头创建和删除。如果您想永久性的保留所做的修改，您不应在这些目录里编辑源代码文件，因为这些修改在下次构建时会丢失。 外部依赖 如果您的应用需要用到外部项目或package的jar包（或其它资源），该怎么做呢？一个常见的例子就是在您的应用中包含JDBC的驱动，以便操作数据库。 不同的开发者对这个问题会采取不同的方法。对于应用依赖的JAR文件，有些人支持在每个应用的源代码控制系统中都checking一份JAR文件的拷贝。可在很多应用使用相同的JAR文件时，将导致很大管理问题——特别是需要将JAR升级到不同的版本是。 因此，本手册不推荐您把一份依赖的JAR包保存到源代码控制系统中。相反，外部依赖应该集成到构建您的应用的步骤中。那样，无论您的开发系统装在什么地方，您就总能获得JAR包的正确的版本，不用担心每次更新您的应用时，所依赖的JAR包也变化了。 在样例Ant build.xml文件中, 我们会演示如何定义构建属性，以便让您配置要拷贝文件的位置，当这些要拷贝的文件变化了，也不用修改build.xml。对于某个特定的开发者使用的构建属性, 它可以被定制成应用生成前的基础，或者作为开发者home目录下的标准构建属性。 在很多情况下，您的开发系统管理员可能已经在Tomcat的lib目录下安装了需要的JAR包。如果这步已经完成，您就不需做任何操作了——样例build.xml自动构造了一个编译用的classpath,它包含了这些JAR包。

 

源代码控制

正如前面所提到的，我们非常推荐您把应用的源代码放入放入源代码控制系统来管理，例如CVS。如果您决定这么做，所有源代码结构中的目录和文件将会被登记并保存——但动态生成的文件不会。如果您也登记了二进制的文件（例如图片和JAR文件），请确保在源代码控制系统中体现。 我们推荐您（在前一章中）不要在部署过程中把build目录和dist目录中的内容保存到源代码控制系统中。一个简单的方法来告诉CVS忽略这些目录的方法就是在源代码目录的顶层创建一个.cvsignore的文件，里面包含下面的内容： build dist build.properties 这里提到的build.properties也要忽略，原因将在处理 章节中解释。 源代码控制环境的详细资料不在本手册的讨论范围之内。然后当使用命令行的CVS客户端时，应该遵从下面的步骤： ·   要刷新您的源代码状态，进入项目的源代码目录，然后执行cvs update -dP。 ·   当您在源代码层次中创建了一个新的子目录，要把该目录登记到CVS中，请使用命令cvs add {文件名}。 ·   当您第一次创建一个新的源代码文件，导航到含有该文件的目录，然后把使用命令cvs add {文件名}来登记这个新文件。 ·   如果您不再需要某个特定的源代码文件，就导航到含有该文件的目录并删除它。然后撤销在该文件在CVS中的登记，使用命令cvs remove {文件名}来实现。 ·   当您创建、修改和删除源代码时，修改不会在源代码仓库的服务器中反映。为了保存当前的修改，进入项目源代码目录然后执行cvs commit命令。您会被要求写一段简单的描述，它将和更新的源代码一起保存在新版本中。 CVS, 像其它的源代码控制系统一样, 有很多额外的特性 (例如对某个发布版本打标签，支持多分支开发，然后合并)。参考前言 中的链接和参考资料来获取更多的信息。

 

BUILD.XML配置文件

我们将使用ant 工具来管理源代码文件的编译，同时也用它来创建部署的目录层次结构。Ant在编译文件的控制下运行，通常叫做build.xml,它定义了需要的处理步骤。该文件保存在源代码目录结构的顶层，应该被checkin到您的源代码控制系统中。 就像一个Makefile, build.xml 文件 提供了一些目标来支撑可选的开发活动，例如创建相关的JavaDoc文档，删除部署的home目录从而可以从头开始构建项目，或者创建web应用的打包的文件从而您可以发布您的应用。一个构造良好的build.xml将包含内部的文档，该文档会描述开发者设计的要用的目标，也包含内部使用的目标。为了让Ant显示项目的文档，进入到包含build.xml的目录中然后键入： ant -projecthelp 为了使您快速开始, 提供了一个basic build.xml file，您可以在您的应用中将它定制并安装在您的源代码目录中。 该文件包含了很多注释，它们描述了多种可以被执行的目标。简单来说，下面的目标通常都会提供： ·   clean – 该目标删除任何存在的build和dist目录，因此它们可以从头重新构建。因为没有重新编译所有影响的class,所以能保证您没有对运行时会导致问题的源代码进行修改。 ·   compile – 这个目标用来编译任何从上次编译开始后的源代码修改。结果 class 文件 are 被创建在WEB-INF/classes目录下，这正是web应用所期望的class文件所在的地方。有用该命令在开发过程中经常执行，通常他会被当做缺省目标，所以一个简单的ant命令就会执行它。 ·   all – 这个目标是个快捷方式，它包括了运行clean目标，然后是编译目标。因此它能确保您编译了整个应用，从而确保您没有引入任何未知的不兼容修改。 ·   javadoc – 该目标创建web应用的JavaDoc API 文档。 样例 build.xml 假定您需要在发布的时候包含API文档，因此它会在dist目录下生成docs子目录。有用您无需再每次编译时都生成javadoc，太目标通常作为dist目标的依赖，但不作为要编译的目标的依赖。 ·   dist – 该目标会为您的应用创建一个发布目录，包括了任何需要的文档，您的java class的javadoc，以及一个web应用的war包文件，这个war包文件会被发送到想安装该应用的系统管理员处。由于该目标也依赖于deploy目标，web应用的war包也会把部署时包括的任何外部的依赖也打到包里 。 为了交互式的开发和使用Tomcat6测试您的应用，定义了下面额外的目标: ·   install – 告诉当前正在运行的Tomcat6，让您当前正在开发立即可运行和可测试。该动作不需要让Tomcat6重启，但也不会在Tomcat下次重启后记得执行该目标。 ·   reload – 一旦应用被安装了，您仍然可以继续修改并使用compile目标重新编译。Tomcat6会自动识别JSP页面的修改，但不会对Servlet或JavaBean修改识别-这个命令将告诉Tomcat重启当前已安装的应用从而使修改能被识别到。 ·   remove – 当您完成了开发和测试活动，您可以告诉Tomcat6从服务中移除该应用。 使用开发和测试目标需要一些额外的一次性安装，这些内容在下一页中描述。