概述

注意： 这是本文的第二版。为了与 Cloudscape Version 10 和 Derby 相一致，此版本对之前提供的资料和技术作了增强。如果您使用的是 Cloudscape Version 5，还请参考 Cloudscape 与 Tomcat 的集成。

Tomcat 是一个开放源码的 Java 2 Enterprise Edition™（J2EE）servlet 容器，可以将它用作 Java Servlet 和 JavaServer Pages 技术的参考实现。该实现准确、快速，而且易于使用，并且在有 Apache 软件许可证的情况下是免费提供的。

Cloudscape 是一种占用资源少的、基于标准的、完全用 Java 实现的数据库管理器。可以将之完全嵌入到任何 Java 应用程序中，允许静默安装和使用单一管理作用域。与在单独的进程中运行的其他数据库管理器不同，嵌入式 Cloudscape 与应用程序在同一 Java 虚拟机中运行。这极大地减少了数据库的开销。而且它还支持复杂 SQL、事务和 JDBC，不会破坏数据一致性，因此，当它增长到需要企业范围的容量时，您就能够将应用程序迁移到 IBM® DB2® Universal Database™。

在 2004 年 8 月，IBM 将 Cloudscape 代码捐献给了 Apache Software Foundation (ASF)。在 Apache 中这个项目叫做 Derby，它是一个孵化器项目。开发人员可以在 Apache 的许可下为 Derby 代码作出贡献，或者下载 Derby 代码。从 Cloudscape Version 10 开始，IBM 的 Cloudscape 解决方案都以 Derby 代码为基础。也可以从 IBM 下载 Cloudscape。下载 Cloudscape 不需要任何许可费用，但是可以从 IBM 购买对它的支持。

除了由于使用 Derby 而必须修改的一些示例脚本外，无论使用哪种实现，本文提供的资料和技术都是同样适用的。

假设

本文讨论的资料和技术基于以下软件平台。

• Windows XP Professional®，带有 2005 年 6 月 1 日之后的所有服务包和更新（请参阅 http://www.microsoft.com/windows）
• Java Version 1.4.2 ( IBM Windows 32 build cn1420-20040626) （请参阅 http://www.ibm.com/java，并搜索 "IBM developer kits"）
• Tomcat Version 5.0.28 （请参阅 http://jakarta.apache.org/tomcat/）
• Cloudscape Version 10.0.2.0 （请参阅 http://www.ibm.com/software/data/cloudscape）
• Derby snapshot Version 10.0.2.1 （请参阅 http://incubator.apache.org/derby）

您可以将本文中的信息应用到其他操作系统和后续版本中，但是平台的改变和产品的增强总是有可能使得这些信息变得不正确或过时。在将该信息应用到您的环境中时，请记住这一点。

可供选择的集成场景

有不止一种集成 Cloudscape 和 Tomcat 的方法。为了说明最有用的选择方案，我将它们收集为三种示例场景：

原型（prototype）集成

如果您正为一个原型或概念验证（proof-of-concept）练习开发 Web 应用程序，那么该场景可能就足够了。不需要修改 Tomcat 的配置，所有一切都可以包含在 Web 应用程序的归档文件（WAR）中。

临时（casual）集成

如果需要数据库管理器来实现一个用于 Tomcat 用户身份验证的域，或者如果需要数据库管理器支持多个 Web 应用程序，那么该场景更合适。在这个场景中，Tomcat 配置中添加了一些 Cloudscape JAR 文件，一起添加的还有一个实现 Tomcat LifecyleEvent 接口的类。当初始化和终止 Tomcat 服务器时，该类将初始化和关闭 Cloudscape。

企业集成

如果需要高效的连接池来同时支持多个用户，并且希望 Web 应用程序独立于 JDBC™ URL 规范和数据库名，那么您需要该场景。在这个场景中，Tomcat 引用，并因此访问 Cloudscape 安装目录中的整个 Cloudscape 库。JNDI Data Source 定义提供了高效的连接池。此外，需要启动 Cloudscape Network Service，以便在 Web 应用程序使用该数据库时，远程应用程序和管理工具可以访问它。

您通常会选择与您的情况最匹配的场景，并使用该场景中描述的备选方案。如果出于某种原因，该场景中只包含一个备选方案，但该方案被证明并不适合您，那么您可以检查其他场景，以获得更好的备选方案。

HelloCloudscape.jsp

HelloCloudscape.jsp 是一个极其简单的 JavaServer Page（JSP），用于验证 Cloudscape 是否与 Tomcat 正确集成。它是从 hello.jsp 扩展而来的，包含 Tomcat 示例程序。

为了匹配集成，在每个场景中，JSP 的实现都稍有不同。场景细节中解释了这些差异，但在所有情况下，HelloCloudscape.jsp 都提供了一个 HTML 表单，用来获取创建连接以及执行 SQL 命令所需的信息。

• 在原型（Prototype）场景和临时（Casual）场景中，表单中的第一个字段用来获得 Cloudscape 数据库连接的统一资源定位符（Universal Resource Locator，URL），而第二个字段用来输入要执行的 SQL 命令。
  
  
• 在企业场景中，表单中的第一个字段用来获得 JDBC 数据源的 JNDI 资源名，而第二个字段用来输入要执行的 SQL 命令。

提交表单时，会将请求送回 HelloCloudscape.jsp， HelloCloudscape.jsp 将

1. 重新显示输入表单。
2. 回显表单上提交的信息。
3. 获取数据库连接。
4. 执行提供的 SQL 命令。
5. 显示 SQL 命令的结果。

如果该过程中抛出异常（Exception），HelloCloudscape.jsp 将尽力显示该异常消息和 Java 堆栈跟踪。

注意： 不要在生产 Web 站点上安装 HelloCloudscape.jsp。在将 Web 应用程序部署到生产 Web 站点之前，要确信已经从中删除了 HelloCloudscape.jsp。HelloCloudscape.jsp 将暴露敏感数据，因为攻击者可以用它来检查和修改您站点上的任何 Cloudscape 数据库。

cloudscape 数据库连接 URL 示例

Java 数据库连接（JDBC）URL 提供了用来指定和建立特定数据库连接的信息。

对于嵌入式 Cloudscape 系统，Cloudscape JDBC 驱动程序的名称是 org.apache.derby.jdbc.EmbeddedDriver，而且 URL 具有以下形式。

jdbc:derby:database[;attributes]

其中

jdbc

是所有 JDBC URL 的标准前缀。

derby

是由 Cloudscape 或 Derby JDBC 驱动程序解释的 URL 的子协议标识符。

database

将替换为引用 Cloudscape 数据库的标识符，通常表示为到包含该数据库的目录的限定路径。

attributes

是应用于连接的可选属性，由分号进行分隔。

这里有一些有用的示例。

• jdbc:derby:C:\Program Files\IBM\Cloudscape_10.0\demo\databases\toursDB 将建立到 Cloudscape 提供的 Tours 示例数据库的连接，假定 Cloudscape 已经安装在名为 C:\Program Files\IBM\Cloudscape_10.0 的目录中，这是 Windows 平台上的默认安装目录。请注意，不要将 Cloudscape 与 Windows 驱动器符号或反斜杠分隔符混淆。
  
  
• jdbc:derby:C:\Temp\Demo\NewDatabase;create=true 将在目录 C:\Temp\Demo\NewDatabase 中新建名为 'NewDatabase' 的数据库，并建立连接。如果有必要，还需要创建目录 Temp 和 Demo。如果无法创建数据库，就会抛出 SQLException，表示无法找到该数据库。如果该数据库已经存在，就会建立连接并发出 SQLWarning。
  
  
• jdbc:derby:C:\Temp\Demo\Data;user=Mary;password=contrary 将使用 Mary作为用户标识符，使用 contrary作为密码，建立到名为 'Data' 的数据库的连接，该数据库位于目录 C:\Temp\Demo\Data 中。
  
  
• jdbc:derby:C:\Temp\Demo\Data;shutdown=true 将使 Cloudscape 关闭 C:\Temp\Demo\Data 目录中名为 'Data' 的数据库。该形式将通过执行最后的检查点来关闭单个数据库。Cloudscape 系统和任何其他活动数据库都将保持活动状态。
  
  
• jdbc:derby:;shutdown=true 将使 Cloudscape 关闭整个系统。在所有的活动数据库上执行最后的检查点，从驱动程序注册表中删除 Cloudscape JDBC 驱动程序，抛出 SQLException 以表示关闭成功，并且不返回任何连接。
  
  

对于连接 Cloudscape 网络服务器的客户机应用程序，Cloudscape JDBC 驱动程序的名称是 com.ibm.db2.jcc.DB2Driver，而且 URL 具有以下形式。

jdbc:derby:net://host:port/database[;cAttributes][:dAttributes;]

其中

jdbc

是所有 JDBC URL 的标准前缀。

derby

是由 DB2 universal JDBC 驱动程序解释的 URL 的子协议标识符。

net

是引用远程网络服务器的 URL 的子协议标识符。

host

将替换为目标 Cloudscape 网络服务器所驻留的主机名或 IP 地址。

port

将替换为目标 Cloudscape 网络服务器监听请求的端口号（默认为 1527）。

database

将替换为引用 Cloudscape 数据库的标识符，通常表示为到包含该数据库的目录的限定路径。 注意，如果包含路径信息，则该名称必须用双引号（"）括起来，以防路径的斜杠（/）被错误解释。

cAttributes

是应用于连接的可选 Cloudscape 属性，由分号（;）进行分隔。Cloudscape 属性将由网络服务器上的 Cloudscape 解释，必要时，它们与驱动程序属性之间以冒号（:）隔开。

dAttributes

是应用于连接的可选的 DB2 universal 驱动程序属性，之间以分号隔开，并且以分号结束。和 Cloudscape 属性不同，驱动程序属性会影响 DB2 universal 驱动程序的行为，并且不会被发送到网络服务器。注意，当在 URL 中指定此类属性时，它们与 URL 的其他部分由冒号（:）隔开。

这里有一些有用的示例。

• jdbc:derby:net://localhost:1527/"C:\Temp\Demo \Data";create=true:user=Mary;password=contrary; 将在本地主机上建立到 Cloudscape 网络服务器的远程连接，监听端口 1527。它将在 C:\Temp\Demo\NewDatabase 目录中创建新的数据库，并建立连接。如果有必要，还需要创建目录 Temp 和 Demo。如果无法创建数据库，就会抛出 SQLException，表示无法找到该数据库。如果该数据库已经存在，就会建立连接并发出 SQLWarning。DB2 universal 要求有用户名和密码，对于该连接，用户标识符和密码分别是 Mary 和 contrary。注意，用户标识符和密码是驱动程序属性，所以最前面是一个冒号，各属性之间以分号隔开，最终以分号结束。
  
  
• jdbc:derby:net://localhost:1527/"C:\Temp\Demo \Data";shutdown=true:user=Mary;password=contrary; 将使本地主机上监听端口 1527 的 Cloudscape 网络服务器关闭位于 C:\Temp\Demo\Data 目录中的数据库。该形式将通过执行最后的检查点来关闭单个数据库。Cloudscape 系统和任何其他活动数据库都将保持活动状态。
  
  

非法关闭和随后的重启恢复

注意： 如果关闭了 Tomcat，但是没有发出合适的 Cloudscape 关闭命令，Cloudscape 就会按照系统失败的情况来处理。虽然不会丢失任何信息，但是重启 Cloudscape 之后，第一次建立数据库连接时，Cloudscape 将使用其日志文件来恢复已提交的事务，并回滚未提交的事务。这会将数据库置于一致的有效状态。进行恢复的代价很高，因此，使用合适的关闭命令将提高启动性能。

回页首

原型场景

这是最简单的场景。它通过牺牲运行时效率来获得简单性。对于原型和概念验证开发练习，该场景通常已经足够。该场景具有以下特性。

• 您所需的一切都包含在 Web 应用程序的归档文件中。安装已完成的 Web 应用程序之后，不需要额外执行安装任务来修改 Tomcat 配置。
  
  
• Cloudscape 库只能被开发中的 Web 应用程序访问。
  
  
• 每次向 HelloCloudscape.jsp 提交表单，它都会动态加载 Cloudscape JDBC 驱动程序。第一次加载驱动程序时将初始化 Cloudscape 系统。随后的加载产生的开销很少，但在其他方面没有什么影响。
  
  
• 每次向 HelloCloudscape.jsp 提交表单，它都会创建一个新的连接。
  
  
• 对于给定的数据库，在首次建立连接时，Cloudscape 将激活该数据库。
  
  
• 如果 Tomcat 关闭，而 Cloudscape 数据库处于活动状态，这等同于发生了系统故障。虽然不会丢失任何数据库修改，但是 Cloudscape 必须在下次激活数据库时执行恢复操作。
  
  
• 一旦激活数据库，直到关闭该数据库后，其他的 Cloudscape 系统才能使用它。

如果您未安装开发中的 Web 应用程序，那么请遵循以下指示。

1. 停止 Tomcat 服务器。
   
   
2. 下载 CloudscapeDemo.zip 文件。
   
   
3. 将 CloudscapeDemo.zip 解压到 Tomcat webapps 目录（通常是 InstallDir\webapps，其中 InstallDir 应替换为 Tomcat 的安装目录名）。
   
   
4. 将 derby.jar 从 Cloudscape 库复制到用来演示 Web 应用程序的库中（通常是 InstallDir\webapps\CloudscapeDemo\WEB-INF\lib，其中 InstallDir 替换成 Tomcat 的安装目录名）。
   
   
5. 启动 Tomcat 服务器。
   
   
6. 启动浏览器，并导航至 HelloCloudscape.jsp （通常是 http://localhost:8080/CloudscapeDemo/HelloCloudscape.jsp）。
   
   
7. 通过在 HelloCloudscape.jsp 提供的表单中提交适当的 JDBC URL 和 SQL 命令来测试集成。
   
   
8. 开发 Web 应用程序。将 HelloCloudscape.jsp 中的数据库逻辑用作 Web 应用程序中数据库逻辑的示例代码。
   
   
9. 一旦可用，就从 Web 应用程序中删除 HelloCloudscape.jsp。
   
   

如果已经安装了开发中的 Web 应用程序，那么请遵循以下指示。

1. 下载 HelloCloudscape.jsp 文件。
   
   
2. 将 HelloCloudscape.jsp 复制到放置应用程序的公用 JSP 文件的目录中（通常是 InstallDir\webapps\appl，其中 InstallDir 替换成 Tomcat 的安装目录名，appl 替换成 Web 应用程序的目录名）。
   
   
3. 将 derby.jar 从 Cloudscape 库复制到 Web 应用程序的库中（通常是 InstallDir\webapps\appl\WEB-INF\lib，其中 InstallDir 替换成 Tomcat 的安装目录名，appl 替换成 Web 应用程序的目录名）。
   
   
4. 启动 Tomcat 服务器。
   
   
5. 启动浏览器，并导航至 HelloCloudscape.jsp（通常是 http://localhost:8080/appl/HelloCloudscape.jsp ，其中 appl 替换成应用程序的目录名）。
   
   
6. 通过在提供的表单中提交适当的 JDBC URL 和 SQL 命令来测试集成。
   
   
7. 继续 Web 应用程序的开发。将 HelloCloudscape.jsp 中的数据库逻辑用作 Web 应用程序中数据库逻辑的示例代码。
   
   
8. 一旦可用，就从 Web 应用程序中删除 HelloCloudscape.jsp。
   
   

回页首

临时场景

该场景允许多个 Web 应用程序（甚至 Tomcat JDBC 域）同时使用 Cloudscape。此外，可以使用 Tomcat 服务器的生命周期事件来触发 Cloudscape 的初始化和关闭。该场景具有以下特性。

• 只需要对 Tomcat 的配置进行细微修改。
  
  
• 将 Cloudscape 库放置在 Tomcat 的公共库中。
  
  
• 将实现 Tomcat 的 LifecycleEvent 接口的类 ServerLifecycleListener 添加到公共库中。
  
  
• 修改 Tomcat 服务器配置（server.xml），以注册 ServerLifecycleListener 类。
  
  
• 当 Tomcat 启动时，ServerLifecycleListener 将加载 Cloudscape JDBC 驱动程序，从而初始化 Cloudscape。
  
  
• 当 Tomcat 终止时，ServerLifecycleListener 将关闭 Cloudscape 系统，从而强制每个活动的数据库都实施最后的检查点，并消除重新激活数据库时进行恢复处理的需要。
  
  
• 每次向 HelloCloudscape.jsp 提交表单，都会创建一个新的连接。
  
  
• 对于给定的数据库，在首次建立连接时，Cloudscape 将激活该数据库。
  
  
• 一旦激活数据库，直到关闭该数据库时，其他的 Cloudscape 系统才能使用它。

对于本场景，请按照以下指示执行。

1. 停止 Tomcat 服务器。
   
   
2. 下载 CloudscapeCasual.zip 和 ServerListener.zip 文件。
   
   
3. 将 CloudscapeCasual.zip 解压缩至 Tomcat webapps 目录（通常是 InstallDir\webapps ，其中 InstallDir 替换成 Tomcat 的安装目录名）。
   
   
4. 将 ServerListener.zip 解压缩至一个合适的目录中，并查看 ServerListener\org\apache\derby\tomcat\ServerLifecycleListener.java。
   
   
5. 将 ServerListener\classes 目录复制到 Tomcat 的服务器目录中（通常是 InstallDir\server ，其中 InstallDir 替换成 Tomcat 的安装目录名）。
   
   
6. 将 derby.jar 从 Cloudscape 库复制到 Tomcat 的公共库中（通常是 InstallDir\common\lib ，其中 InstallDir 替换成 Tomcat 的安装目录名）。
   
   
7. 备份并编辑 Tomcat 服务器配置（InstallDir\conf\server.xml ，其中 InstallDir 替换成 Tomcat 的安装目录名），并在 <Server> 元素的开头添加下列元素。
   

   <Listener className="org.apache.derby.tomcat.ServerLifecycleListener" debug="0" />

   
   
   
8. 启动 Tomcat 服务器。
   
   
9. 启动浏览器，并导航至 HelloCloudscape.jsp（通常是 http://localhost:8080/CloudscapeCasual/HelloCloudscape.jsp）。
   
   
10. 通过在提供的表单中提交适当的 JDBC URL 和 SQL 命令来测试集成。
    
    
11. 继续 Web 应用程序的开发。将 HelloCloudscape.jsp 中的数据库逻辑用作 Web 应用程序中数据库逻辑的示例代码。
    
    
12. 一旦可用，就从 Tomcat Web 应用程序中删除 CloudscapeCasual 目录。
    
    

回页首

企业场景

与临时场景相同，该场景也允许多个 Web 应用程序（甚至 Tomcat 安全域）同时使用 Cloudscape。但与临时场景不同的是，它添加了一个 Cloudscape 网络服务器，以便在 Web 应用程序使用该数据库时，远程应用程序和管理工具可以访问它。该场景具有以下特性。

• 需要对 Tomcat 配置进行修改。
  
  
• 修改 catalina.properties 文件，以使整个 Cloudscape 库都包含在公共类路径中。
  
  
• 将实现 Tomcat 的 Lifecycle Event 接口的 Java 类 ServerLifecycleListenerWithNetworkServer 添加到公共库中。
  
  
• 修改 tomcat 服务器配置（server.xml），以
  
  
• 注册 ServerLifecycleListenerWithNetworkServer 类。
  
  
• 为 Cloudscape 数据源定义一个全局 JNDI 资源。
  
  
• 定义链接全局 Cloudscape 数据源的默认语境。
  
  
• 无需将 jar 文件复制到 Tomcat 目录树中。而是将 Cloudscape JAR 文件包含在 Tomcat 和所有 Web 应用程序公共的类路径中。可以将补丁和更新应用于 Cloudscape 安装，而且 Tomcat 站点将自动使用它们。
  
  
• 当 Tomcat 启动时，ServerLifecycleListenerWithNetworkServer 将加载 Cloudscape JDBC 驱动程序，从而初始化 Cloudscape，并启动网络服务器来处理远程请求。
  
  
• 当 Tomcat 停止时，ServerLifecycleListenerWithNetworkServer 将关闭网络服务器和 Cloudscape，强制每个活动的数据库实施最后的检查点，并消除重新激活数据库时进行恢复处理的需要。
  
  
• 当向 HelloCloudscape.jsp 提交表单时，可以使用提供的数据源名称，从该数据源管理的连接池中获得连接。
  
  
• 像往常一样，对于给定的数据库，在第一次建立连接时，Cloudscape 将激活该数据库。
  
  
• 当数据库处于活动状态时，其他的 Cloudscape 系统仍然可以通过使用远程访问来访问它。

对于本场景，请按照这些指示执行操作。

1. 停止 Tomcat 服务器。
   
   
2. 下载 CloudscapeEnterprise.zip 和 ServerListener.zip 文件。
   
   
3. 将 CloudscapeEnterprise.zip 解压缩至 Tomcat webapps 目录（通常是 InstallDir\webapps ，其中 InstallDir 替换成 Tomcat 的安装目录名）。
   
   
4. 将 ServerListener.zip 解压缩至一个合适的目录中，并查看 ServerListener\org\apache\derby\tomcat\ServerLifecycleListenerWithNetworkServer.java.
   
   
5. 将 ServerListener\classes 目录复制到 Tomcat 的服务器目录中（通常是 InstallDir\server ，其中 InstallDir 替换成 Tomcat 的安装目录名）。
   
   
6. 备份并编辑 catalina.properties 文件（通常是 InstallDir\conf\catalina.properties ，其中 InstallDir 替换成 Tomcat 的安装目录名）。
   
   
1. 找到 common.loader 键。
   
   
2. 在该键所赋值的结尾添加一个逗号以及一个代表所有 Cloudscape jar 文件的通配符（wildcard）（通常是 CloudDir/lib/*.jar，其中 CloudDir 替换成 Cloudscape 的安装目录名）。这会将所有的 Cloudscape JAR 文件添加到 Tomcat 和所有 Web 应用程序公共的类路径中。
   
   
3. 保存已更新的文件。
   
   
7. 备份并编辑 Tomcat 的服务器配置（InstallDir\conf\server.xml ，其中 InstallDir 替换成 Tomcat 的安装目录名）。
   
   
1. 在配置文档中找到 <Server> 元素。
   
   
2. 在 <Server> 元素的开头添加下列元素。
   

   <Listener className="org.apache.derby.tomcat.ServerLifecycleListenerWithNetworkServer" debug="0" />

   
   
   
3. 在配置文档中找到 <GlobalNamingResources> 元素。
   
   
4. 将下列元素添加到 <GlobalNamingResources> 元素之中。
   

   <!-- Datasource for Cloudscape sample database --> <Resource name="jdbc/Tours" type="javax.sql.DataSource" auth="Container" description="Cloudscape sample database" />

   
   请注意，为 name 属性指定的值变成了数据源名称，而且它必须与其他元素中的引用相匹配。
   
   
5. 在添加了上面的 <Resource>之后，将下列元素添加到 <GlobalNamingResources> 元素中。
   

   <!-- Resource parameters for the Cloudscape sample database --> <ResourceParams name="jdbc/Tours"> <parameter> <name>maxWait</name> <value>5000</value> </parameter> <parameter> <name>maxActive</name> <value>4</value> </parameter> <parameter> <name>url</name> <value>jdbc:derby:C:\Program Files\IBM\Cloudscape_10.0\demo\databases \toursDB</value> </parameter> <parameter> <name>driverClassName</name> <value>org.apache.derby.jdbc.EmbeddedDriver</value> </parameter> <parameter> <name>maxIdle</name> <value>2</value> </parameter> </ResourceParams>

   
   请注意， name 属性的值必须与对应 <Resource>元素中为 name 属性指定的值相同。
   
   在本例中， url 参数指定了与 Cloudscape 一起提供的示例数据库，您可能需要修改该值以匹配您的环境。此外，如果您的数据库需要进行用户身份验证，那么还需要为 user 和 password 添加参数定义。
   
   
6. 在配置文档中找到 <Engine>>元素。
   
   
7. 如果当前的 <Engine>元素 不包含 <DefaultContext>，那么在 <Engine>元素的开头添加下列代码段。否则，将 <ResourceLink>元素从本示例复制到现有的 <DefaultContext>中。
   

   <!-- The default context element is used to provide configuration settings to represent default configuration properties for contexts that are automatically created. --> <DefaultContext> <!-- This resource link adds the global data source to all Web applications. --> <ResourceLink name="jdbc/Tours" global="jdbc/Tours" type="javax.sql.DataSource" /> </DefaultContext>

   
   请注意， name 属性的值必须与对应 <Resource>元素中为 name 属性指定的值相同。
   
   本示例假定该数据源将有一个全局范围。或者限制数据源的范围，可以将 <ResourceLink>元素放置在将引用该数据源的每个 Web 应用程序的上下文中。有关的更多信息，请参阅 Tomcat 的配置文档。
   
   
8. 保存已更新的文件。
   
   
8. 备份并编辑 Web 应用程序的部署描述符（ InstallDir\webapps\CloudscapeEnterprise\WEB-INF\web.xml，其中，将 InstallDir 替换成 Tomcat 的安装目录名）。
   
   
1. 在文档中找到示例的 <resource-ref>元素，如下所示。
   

   <resource-ref> <description> This element references a resource factory for a data source that provides java.sql.Connection instances that connect to a particular database that is configured in the server.xml file. Its resource reference name must match the resource name defined there. By using a resource reference, the servlets and JavaServer pages remain independent of the JDBC driver names and JDBC URLs while gaining the performance advantage of a connection pool. </description> <res-ref-name> jdbc/Tours </res-ref-name> <res-type> javax.sql.DataSource </res-type> <res-auth> Container </res-auth> </resource-ref>

   
   请注意， <res-ref-name>元素体必须与 Tomcat 配置中对应 <Resource>元素的name 属性值相同。
   
   
2. 如果您没有修改本示例中使用的资源名称，那么无需进行任何修改。如果您修改了资源名称，就需要相应地修改 <res-ref-name>元素体。如果添加了附加的数据源定义，那么需要使用该 <resource-ref>元素作为模板，并添加对将要测试的每个数据源的引用。
   
   
3. 保存已修改的文件。
   
   
9. 启动 Tomcat 服务器。
   
   
10. 启动浏览器，并导航至 HelloCloudscape.jsp（通常是 http://localhost:8080/CloudscapeEnterprise/HelloCloudscape.jsp）。
    
    
11. 通过在提供的表单中提交适当的 JDBC 数据源名称（如果您按照本示例进行，该名称是 "jdbc/Tours"）和 SQL 命令来测试集成。
    
    
12. 继续 Web 应用程序的开发。将 HelloCloudscape.jsp 中的数据库逻辑用作 Web 应用程序中数据库逻辑的示例代码。使用这里描述的配置修改作为模板，以便为应用程序创建 JDBC 数据源定义。请记住，每次修改服务器配置时，必须重启 Tomcat。
    
    
13. 必要时需要调优数据源。
    
    
14. 一旦可用，就从 Tomcat 配置中删除示例数据源，并从 Tomcat Web 应用程序中删除 CloudscapeEnterprise 目录。
    
    

回页首

用 Cloudscape 实现 Tomcat 域

域 是一个存储库，包括

• 标识用户的登录标识符（也称作用户名）。
• 用来验证给定登录标识符的密码。
• 每个用户授权担任的角色。

Tomcat 通过连接一个域，并使用那里存储的数据来验证用户及其访问 servlet 和 JavaServer 页面的权限，以实现容器管理的安全性。可以将 Cloudscape 表用作域的存储库。

为了在数据库中实现域，Tomcat 需要

• 一个通常被称作用户（users）表的表，至少包含两列，一列为登录标识符，一列为密码。
  
  
• 另一个通常被称作角色（roles）表的表，至少包含两列，一列为使用与用户表相同列名的登录标识符，一列为指派给该登录标识符的角色名称。

注意：给定的登录标识符必须是惟一的，但可以指派任意数目的角色。因为可以将 Tomcat 配置为使用您所选择的名称，所以您可以自由选择表名和列名。

>按照下列指示来创建域。

1. 下载 Sql.zip 文件。
   
   
2. 将 Sql.zip 解压到一个合适的目录中，并查看其中的文件。
   
   CrtUsers.bat 用于创建和初始化表。它使用 Cloudscape ij 实用程序处理 CrtUsers.sql SQL 脚本。
   
   DrpUsers.bat 用于删除表。当您犯了严重错误时，最好的选择就是删除表，重新来过，这时使用该文件就十分方便。与 CrtUsers.bat 相同，它使用 Cloudscape ij 实用程序处理 DrpUsers.sql SQL 脚本。
   
   
3. 在 CrtUsers.bat 中，检查环境变量 CLOUD_HOME 和 CATALINA_HOME 的值。如果有必要，还需要编辑该文件，并修改这些值，以匹配您的安装。
   
   
4. 同样，在 DrpUsers.bat 中，检查环境变量 CLOUD_HOME 和 CATALINA_HOME 的值。如果有必要，需要编辑该文件，并修改这些值，以匹配您的安装。
   
   
5. 编辑 CrtUsers.sql。
   
   
1. 如果有必要，需要修改 CONNECT 语句，使 JDBC URL 指定您将要在其中创建数据库的目录。
   
   
2. 如果有必要，需要修改 Users 和 Roles 表的模式。
   
   
3. 修改第一个 INSERT 语句，以定义您的站点管理员。如果已经修改了 Users 表的模式，那么一定要对 Insert 语句进行相应的修改。
   
   
4. 如果有必要，请为您将要在初始化期间添加的其他任何用户和角色添加 INSERT 语句。
   
   
5. 为了与 Tomcat 演示程序兼容，该脚本包含了 3 个用户的定义，用户名分别是 tomcat、 both 和 role1。如果打算使用示例程序，那么需要修改这些定义，以匹配您的模式修改。否则，需要删除用户定义及其角色定义。
   
   
6. 保存已修改的 SQL 脚本。
   
   
6. 编辑 DrpUsers.sql。
   
   
1. 如果有必要，需要修改 CONNECT 语句，以使 JDBC URL 匹配 CrtUsers.sql 中指定的值。
   
   
2. 如果有必要，需要修改 DROP 语句，使表名匹配 CrtUsers.sql 中指定的名称。
   
   
3. 保存已修改的脚本。
   
   
7. 打开命令提示符，将当前目录修改为包含这些脚本的目录，并执行 CrtUsers.bat。检查输出以验证是否成功处理了所有的命令。如果有错误，或者您决定修改语句，那么需要执行 DrpUsers.bat 来删除表，重新来过。

一旦在 Cloudscape 表中实现了域，就必须配置 Tomcat 来使用该域。有两种可供选择的方案。

1. 定义一个 JDBC 域。如果 Tomcat 仅用该数据库来获得容器管理的安全性，那么这就是最简单的解决方案。
   
   
2. 定义一个数据源域。如果 Web 应用程序也读取并/或更新域表中的信息，这就是最佳解决方案。本例中，您将从高效的连接池中获益，并使 Web 应用程序独立于数据库驱动程序和 JDBC URL。

回页首

配置使用 Cloudscape 的 JDBC 域

按照以下这些指示来配置使用 Cloudscape 的 JDBC 域。

1. 停止 Tomcat 服务器。
   
   
2. 备份并编辑 Tomcat 的服务器配置（ InstallDir\conf\server.xml，其中，将 InstallDir 替换成 Tomcat 的安装目录名）。
   
   
1. 在配置文档中找到 <Engine>元素。
   
   
2. 如果有必要，那么需要删除 <Engine>元素中嵌套的所有现有 <Realm>元素。
   
   
3. 将下列 <Realm>元素添加至 <Engine>元素中。
   

   <Realm className="org.apache.catalina.realm.JDBCRealm" debug="99" driverName="org.apache.derby.jdbc.EmbeddedDriver" connectionURL="jdbc:derby:C:\Program Files\Apache Software Foundation\Tomcat 5.0\Realm" userTable="Users" userNameCol="LogonId" userCredCol="Password" userRoleTable="Roles" roleNameCol="Role" />

   
   如果有必要，需要替换 userTable、 userNameCol、userCredCol、userRoleTable 和 roleNameCol 的属性值，以匹配您的模式中使用的值。
   
   在本示例中， connectionURL 参数指定使用该域的 Cloudscape 数据库。它将匹配用来创建表的 URL，因此，您可能需要修改该值以匹配您的环境。此外，如果您的数据库需要进行用户身份验证，就需要添加 connectionUser 和 connectionPassword 属性的值。
   
   
4. 保存已更新的文件。
   
   
3. 启动 Tomcat 服务器。
   
   
4. 测试初始域中定义的登录标识符和角色。确保 Tomcat 管理员可以使用管理 Web 应用程序。练习有效和无效用户这两种情况。
   
   
5. 一旦可用，就从该域中删除非必要的用户和角色。并在必要时对域进行更新。
   
   

回页首

配置使用 Cloudscape 的 Tomcat 数据源域

按照下列指示来配置使用 Cloudscape 的数据源域。

1. 停止 Tomcat 服务器。
   
   
2. 备份并编辑 Tomcat 的服务器配置（ InstallDir\conf\server.xml，其中，将 InstallDir 替换成 Tomcat 的安装目录名）。
   
   
1. 在配置文档中找到 <GlobalNamingResources>元素。
   
   
2. 将下列元素添加至 <GlobalNamingResources>元素中。
   

   <!-- Datasource for Cloudscape realm database --> <Resource name="jdbc/Realm" type="javax.sql.DataSource" auth="Container" description="Cloudscape realm database" />

   
   请注意，为 name 属性指定的值变成了数据源名称，而且它必须与其他元素中的引用相匹配。
   
   
3. 在添加了上面的 <Resource>元素之后，将下列元素添加至 <GlobalNamingResources> 元素中。
   
   

   <!-- Resource parameters for the Cloudscape realm database --> <ResourceParams name="jdbc/Realm"> <parameter> <name>maxWait</name> <value>5000</value> </parameter> <parameter> <name>maxActive</name> <value>4</value> </parameter> <parameter> <name>url</name> <value>jdbc:derby:C:\Program Files\Apache Software Foundation\ Tomcat 5.0\Realm</value> </parameter> <parameter> <name>driverClassName</name> <value>org.apache.derby.jdbc.EmbeddedDriver</value> </parameter> <parameter> <name>maxIdle</name> <value>2</value> </parameter> </ResourceParams>

   
   请注意， name 属性的值必须与对应 <Resource>元素中为 name 属性指定的值相同。
   
   本示例中， url 参数指定了实现该域的 Cloudscape 数据库。它将匹配用来创建这些表的 URL，因此，您可能需要修改该值以匹配您的环境。此外，如果您的数据库需要进行用户身份验证，那么还需要添加 user 和 password 的参数定义。
   
   
4. 在配置文档中找到 <Engine>>元素。
   
   
5. 如果当前的 <Engine>元素 不包含 <DefaultContext>，那么请在 <Engine>元素的开头添加下列代码段。否则，将本示例中的 <ResourceLink>元素复制到现有的 <DefaultContext>中。
   

   <!-- The default context element is used to provide configuration settings to represent default configuration properties for contexts that are automatically created. --> <DefaultContext> <!-- This resource link adds the global data source to all Web applications. --> <ResourceLink name="jdbc/Realm" global="jdbc/Realm" type="javax.sql.DataSource" /> </DefaultContext>

   
   注意：name 属性的值必须与对应 <Resource>元素中为 name 属性指定的值相同。
   
   本示例假定该数据源将有一个全局范围。或者将限制数据源的范围，可以将 <ResourceLink> 元素放置在将引用该数据源的每个 Web 应用程序的上下文中。有关的更多信息，请参阅 Tomcat 的配置文档。
   
   
6. 如果有必要，需要删除 <Engine>元素中嵌套的所有现有 <Realm> 元素。
   
   
7. 将下列 <Realm>元素添加至 <Engine>元素中。
   

   <Realm className="org.apache.catalina.realm.DataSourceRealm" debug="99" dataSourceName="jdbc/Realm" userTable="Users" userNameCol="LogonId" userCredCol="Password" userRoleTable="Roles" roleNameCol="Role" />

   
   如果有必要，需要替换 userTable、userNameCol、userCredCol、userRoleTable 和 roleNameCol 的属性值，以匹配您的模式中使用的值。
   
   
8. 保存已更新的文件。
   
   
3. 为每个将读取或更新 Cloudscape 域的 Web 应用程序，备份并编辑 Web 应用程序的部署描述符（ InstallDir\webapps\ AppName\WEB-INF\web.xml，其中，将 InstallDir 替换成 Tomcat 的安装目录名，将 AppName 替换成 Web 应用程序的目录名）。
   
   
1. 在由文档类型定义（DTD）指示的位置中，添加一个 <resource-ref>元素。然后使用以下模板。
   

   <resource-ref> <description> This element references a resource factory for a data source that provides the Cloudscape realm. </description> <res-ref-name> jdbc/Realm </res-ref-name> <res-type> javax.sql.DataSource </res-type> <res-auth> Container </res-auth> </resource-ref>

   
   注意： <res-ref-name>的元素体必须与 Tomcat 配置中相应 <Resource>元素的 name 属性值相同。
   
   
2. 保存已修改的文件。
   
   
4. 启动 Tomcat 服务器。
   
   
5. 测试初始域中定义的登录标识符和角色。确保 Tomcat 管理员可以使用管理 Web 应用程序。练习有效和无效用户这两种情况。
   
   
6. 一旦可用，就从该域中删除非必要的用户和角色。必要时对域进行更新并调优数据源。
   
   

回页首

下载

描述	名字	大小	下载方法
JavaServer Page to mix into your web application	HelloCloudscape.jsp	8KB	FTP|HTTP
Template for a prototype Web application	CloudscapeDemo.zip	4KB	FTP|HTTP
Template for a casual integration	CloudscapeCasual.zip	4KB	FTP|HTTP
Template for an enterprise integration	CloudscapeEnterprise.zip	4KB	FTP|HTTP
Classes that manage Cloudscape automatically	ServerListener.zip	12KB	FTP|HTTP
Sample for building a Tomcat realm with Cloudscape	Sql.zip	4KB	FTP|HTTP

关于下载方法的信息

参考资料

学习

• 您可以参阅本文在 developerWorks 全球站点上的 英文原文。
  
  
• Apache Tomcat 是 Jakarta 项目中的一个子项目。可以通过下载获得二进制代码和源码。
  
  
• IBM Cloudscape Information Center 包含最新的 Cloudscape 信息。其中包含了 PDF 文件格式的开发人员指南、参考手册、调优指南和其他有用文档。
  
  
• Tomcat: The Definitive Guide （O'Reilly & Associates；2003）是一本关于 Jakarta Tomcat 各个方面的优秀参考资料，包括所有平台上的安装、与 Web 服务器的交互、安全管理以及 Web 应用程序的部署。
  
  
• “Cloudscape 与 Tomcat 的集成”（developerWorks DB2, 2004 年 10 月）。
  
  
• “专家访谈: 为什么 IBM 要将 Cloudscape 源代码开放为 Derby”（developerWorks DB2, 2004 年 12 月）。
  
  
• “ Cloudscape Version 10：技术概述”（developerWorks DB2, 2004 年 8 月）。
  
  
• “IBM Cloudscape：了解 Java 类路径”（developerWorks DB2, 2004 年 10 月）。
  
  

获得产品和技术

• Cloudscape 是一个 IBM 提供的数据库产品。可以获得其评估版的下载和开发人员的支持。
  
  
• Apache Derby Project 是 Derby 孵化器项目的主站点。可以通过下载获得二进制代码和源码。
  
  

讨论

• 参与论坛讨论。
  
  

关于作者

Lance D Bader 是美国 Business Partner Technical Support 团队中的高级软件工程师。在该团队中，他为那些需要将其软件与 IBM WebSphere 产品进行集成的 IBM 合作伙伴提供支持。他拥有超过 25 年的数据通信方面的经验，研究领域包括 IBM Series/1 小型计算机中的哑终端支持、 IBM 系统网络体系结构（System Network Architecture，SNA）中的高性能路由（High Performance Routing），以及 IBM WebSphere Commerce 中的商业应用程序集成。他从北达科他州大学获得了计算机科学的理学士学位。

为本文评分

评论

回页首

内容

• 概述
• 原型场景
• 临时场景
• 企业场景
• 用 Cloudscape 实现 Tomcat 域
• 配置使用 Cloudscape 的 JDBC 域
• 配置使用 Cloudscape 的 Tomcat 数据源域
• 下载
• 参考资料
• 关于作者
• 建议