Soloman Barghouthi
顾问兼软件工程师, IBM
2005 年 7 月 4 日

本文介绍 IBM® Cloudscape™ Version 10（也称为 Derby 版本）中的变化和新功能，以及如何配置 IBM WebSphere® Application Server 来使用这个新版本的过程。

引言
本文重点介绍 IBM Cloudscape Version 10（也称为 Derby 版本）中的一些重要变化。最显著的新变化之一就是，Cloudscape V10 现在是一个 IBM DB2® 兼容数据库。此外，还有一些重要的变化会影响 IBM WebSphere Application Server V6 的配置。这些变化将是本文讨论的重点。

截止本文撰写时，IBM WebSphere Application Server V6 software support site 尚未明确地将 Cloudscape V10 列为它所支持的数据库（由于 Cloudscape 版本发布较晚）。然而，根据支持声明中的定义，Cloudscape V10 应作为一种“其他配置”而得到 WebSphere Application Server V6 的支持。Cloudscape V10 有望在 WebSphere Application Server 即将发布的版本中得到正式支持。

影响 WebSphere Application Server 配置的变化
Cloudscape V10 发生了一些变化，这些变化影响着 WebSphere Application Server V6 的配置方式。

新的程序包名称
Cloudscape V10 使用新的程序包名称，这可使其与以前版本的 Cloudscape（例如 Cloudscape 5.1.60）共存于 WebSphere Application Server 环境中。新的程序包名称已经从 com.ibm.db2j.* 更改为 org.apache.derby.*。新的程序包名称为：

org.apache.derby.drda
org.apache.derby.jdbc
org.apache.derby.tools

其他命名更改包括：

• db2j.properties 文件已改为 derby.properties
• db2j.system.home 文件已改为 derby.system.home。

DB2 兼容性
Cloudscape V10 是一种 DB2 兼容数据库，其兼容性体现在以下方面：

• 数据定义语言 (DDL) 和数据操作语言 (DML)
  Cloudscape V10 DDL 和 DML 是 DB2 的子集。
• 错误代码和 SQLState
  在 Cloudscape V10 中，最常见的 SQLState 和错误代码已进行更改，以便与 DB2 的相匹配。例如：

  以前代码	新代码	说明
  23000	23502	列 {0} 无法接受 NULL 值。
  23500	23505	此语句已放弃，因为它会在唯一键约束或主键约束中或在 {1} 上定义的 {0} 标识的唯一索引中导致重复键值。
  23L01	23505
  23501	23503	表 {1} 上的 Descr{2} 会导致违反键 {3} 的外键约束 {0}。该语句已回滚。
  23L02	23513	在表 {0} 上执行 INSERT 或 UPDATE 时违反检查约束 {1}。
  42X11	42622	名称 {0} 太长。最大长度为 {1}。
  42X18	42818	不支持 {0} 和 {1} 之间的比较。
  42X42	42821	类型 {0} 的列不能包含类型 {1} 的值。如果用户定义的类不在类路径中，就可能出现该错误。
  42Y18	42846	不能将类型 {0} 转换为 {1}。
  XJZZZ	0A000	未实现的特性：{0}。

  用户将从 Cloudscape V10 基于标准的特性中受益匪浅，因为它使用户能够在开发环境中开发针对 Cloudscape V10 的应用程序、在中小生产环境中进行部署以及在企业环境中针对 DB2 运行。

请参见 Migrating IBM Cloudscape 以获得 Cloudscape V5.1 和 Cloudscape V10 之间的完整变化列表。

您可以从 Cloudscape 获得新的 Version 10 JAR。

在 WebSphere Application Server V6 环境中安装 Cloudscape V10
要在 WebSphere Application Server V6 环境中安装 Cloudscape V10，请执行以下操作：

1. 将所提供的 derbyInstall.zip 下载文件解压缩到 WAS_HOME 目录中（其中安装了 WebSphere Application Server，例如 c:\Program Files\WebSphere\AppServer），步骤如下：
   • 将 derbyInstall.zip 文件复制到 ${WAS_HOME}。
   • 输入命令 cd ${WAS_HOME}。
   • 解压缩 derbyInstall.zip。
2. 将 Cloudscape V10 JAR 文件下载到 ${WAS_HOME}\derby\lib，步骤如下：
   • Locale 文件放入 ${WAS_HOME}\derby\lib\locales。
   • db2jcc.jar 放入 ${WAS_HOME}\derby\lib\otherJars。
   • derbytools.jar、derby.jar、derbynet.jar 和 db2jcc_license_c.jar 放入 ${WAS_HOME}\derby\lib。
3. 修改 ${WAS_HOME}\bin\setupCmdLine.bat/sh 并添加：
   • 对于 Windows®：SET DERBY_HOME=%WAS_HOME%\derby。
   • 对于 UNIX® 或 Linux®：DERBY_HOME="$WAS_HOME"/derby。
   最终的目录结构应如图 1 所示。

图 1. Derby 目录结构

现在，您应能够在 Cloudscape V10 中运行与 Cloudscape 5.1 相同的命令了（例如 ij、startNetworkServer 和 stopNetworkServer 等）。注意 cview.sh/bat 不会出现，因为 Cloudscape 已经终止了对该工具的支持。

为 Cloudscape V10 配置 WebSphere Application Server V6
在配置 WebSphere Application Server V6 以便使其与 Cloudscape Version 10 一起运行时，首先需要为新版本的 Cloudscape 配置一个 Java™ Database Connectivity (JDBC) 提供程序，然后为新的 JDBC 提供程序配置数据源。

为 Cloudscape V10 配置 JDBC 提供程序
与往常一样，运行数据库的第一步是为应用服务器配置一个 JDBC 提供程序。在 WebSphere Application Server V6 中，可以为 Cloudscape V10 配置三种不同类型的提供程序：

1. 为 Cloudscape V10 配置 JDBC 提供程序
   1. 登录到 WebSphere 管理控制台（位于 http://localhost:9060/ibm/console）。
   2. 选择 Resources => JDBC Providers，然后选择 Scope => Server。单击 Apply ，然后单击 New（图 2）。

      图 2. 管理控制台
      

   3. 在 New JDBC 提供程序对话框（图 3）中，选择以下值：
      • Step 1: Cloudscape
      • Step 2: Cloudscape JDBC Provider
      • Step 3: Connection pool data source
      然后选择 Next。

      图 3. 新 JDBC 提供程序
      

   4. 在 Embedded JDBC 提供程序对话框（图 4）中，输入以下字段的值：
      • Name（可选字段但建议输入）
      • Description（可选字段）
      • Class path（必需字段）：必须指向新的 CloudscapeV10 JAR 文件（例如 ${WAS_INSTALL_ROOT}/derby/lib/derby.jar）
      • Implementation class: 输入 org.apache.derby.jdbc.EmbeddedConnectionPoolDataSource
      然后选择 Apply。

      图 4. Cloudscape V10 嵌入式 JDBC 提供程序
      

2. 配置 Cloudscape 嵌入式 JDBC 提供程序 (XA)
   1. 登录到 WebSphere 管理控制台（位于 http://localhost:9060/ibm/console）。
   2. 选择 Resources => JDBC Providers，然后选择范围。单击 Apply ，然后单击 New。
   3. 在新 JDBC 提供程序对话框（图 5）中，选择以下值：
      • Step 1: Cloudscape
      • Step 2: Cloudscape JDBC Provider
      • Step 3: XA data source
      然后选择 Next。

      图 5. 新 JDBC 提供程序
      

   4. 在下一个对话框（图 6）中，输入以下字段的值：
      • Name（可选字段但建议输入）
      • Description（可选字段）
      • Class path（必需字段）：必须指向新的 Cloudscape V10 JAR 文件（例如 ${WAS_INSTALL_ROOT}/derby/lib/derby.jar）
      • Implementation class: 输入 org.apache.derby.jdbc.EmbeddedXADataSource
      然后选择 Apply。

      图 6. JDBC 提供程序配置
      

3. 配置 Cloudscape Network Server JDBC 提供程序
   1. 登录到 WebSphere 管理控制台（位于 http://localhost:9060/ibm/console）。
   2. 选择 Resources => JDBC Providers，然后选择范围。单击 Apply ，然后单击 New。
   3. 在新 JDBC 提供程序对话框（图 7）中，选择以下值：
      • Step 1: Cloudscape
      • Step 2: Cloudscape Network Server Using Universal JDBC Driver
      • Step 3: connection pool data source
      然后选择 Next。

      图 7. 新 JDBC 提供程序
      

   4. 在下一个对话框（图 8）中，修改说明（可选字段），然后将类路径中的 db2j.jar 条目替换为 derby.jar，它是新的 Cloudscape V10 JAR。类路径的值应如下所示：

      ${DB2UNIVERSAL_JDBC_DRIVER_PATH}/db2jcc.jar ${CLOUDSCAPE_JDBC_DRIVER_PATH}/otherJars/db2jcc.jar ${WAS_INSTALL_ROOT}/derby/lib/derby.jar ${UNIVERSAL_JDBC_DRIVER_PATH}/db2jcc_license_cu.ja

      选择 Apply。

      图 8. JDBC 提供程序配置
      

为新的 JDBC 提供程序配置数据源
创建和定义 WebSphere 数据源：

1. 登录到 WebSphere Application Server 管理控制台（位于 http://localhost:9060/admin）。
2. 选择 Resources => JDBC providers，然后选择范围并单击 Apply。
3. 选择上面创建的 JDBC 提供程序。
4. 在“Additional Properties”下，选择 Data sources => New 以创建新数据源。
5. 本页面中显示的最重要部分是“Data store helper class name”，在这里需要创建和定义一个用户定义的数据存储，具体步骤如下所述。
6. 根据自己的应用程序的需要，定义组件托管的或容器托管的身份验证别名，具体步骤如下所述。仅当运行 Cloudscape V10 Network Server 框架时才需要定义这些别名。
7. 选择 OK，然后选择 Save。

创建身份验证别名
要创建身份验证别名（如果下拉列表中未定义任何身份验证别名），请执行以下操作：

1. 从 WebSphere Application Server 管理控制台，选择 Security => Global security => JAAS Configuration => J2C Authentication Data => New。
2. 输入 Alias、User ID 和 Password 字段的值。
3. 选择 OK，然后选择 Save 保存配置。

创建新的数据存储帮助程序
由于 Cloudscape V10 中已更改了一些异常错误代码和 SQLState，因此需要在 WebSphere Application Server 中创建和定义一个用户定义的数据存储帮助程序，以包括 StaleConnectionExceptions 和 DuplicateKeyExceptions 的新映射。请按照以下步骤创建新的用户定义数据存储帮助程序：

1. 创建一个扩展 com.ibm.websphere.rsadapter.CloudscapeDataStoreHelper（清单 1）或 com.ibm.websphere.rsadapter.CloudscapeNetworkServerDataStoreHelper的类（清单 2）。
2. 编译新创建的 DataStoreHelper 类。为了编译它们，类路径中需要有以下 JAR 文件（全部位于 {WAS_HOME}/lib）：
   • utils.jar
   • j2ee.jar
   • rsaexternal.jar。
3. 创建所编译类的 JAR 文件并将它们放到 {WAS_HOME}/lib/ext 中。

现在已经创建了数据存储帮助程序，您需要在上面创建的 WebSphere 数据源中配置它们。请参见图 9（如果是 NetworkServer，则请参见图 10），以获得如何设置它们的示例。

清单 1. 嵌入式（xa 和非 xa）用户定义帮助程序

package myCompany.helper; import java.util.Properties; import com.ibm.websphere.ce.cm.DuplicateKeyException; import com.ibm.websphere.rsadapter.CloudscapeDataStoreHelper; public class MyDerbyDataStoreHelper extends CloudscapeDataStoreHelper { //static final long serialVersionUID = ; //to be generated by user public MyDerbyDataStoreHelper(Properties props) { super(props); java.util.HashMap myErrorMap = new java.util.HashMap(3); myErrorMap.put("23505", DuplicateKeyException.class); myErrorMap.put("23500", Void.class); myErrorMap.put("23L01", Void.class); setUserDefinedMap(myErrorMap); } }

清单 2. 网络服务器用户定义帮助程序

package myCompany.helper; import java.util.Properties; import com.ibm.websphere.ce.cm.DuplicateKeyException; import com.ibm.websphere.ce.cm.StaleConnectionException; import com.ibm.websphere.rsadapter.CloudscapeNetworkServerDataStoreHelper; public class MyDerbyNetworkServerDataStoreHelper extends CloudscapeNetworkServerDataStoreHelper { //This value should change only if the class evolves to an incompatible class. //static final long serialVersionUID = ; //to be generated by user public MyDerbyNetworkServerDataStoreHelper(Properties props) { super(props); java.util.HashMap myErrorMap = new java.util.HashMap(4); myErrorMap.put("23505", DuplicateKeyException.class); myErrorMap.put("23500", Void.class); myErrorMap.put("23L01", Void.class); myErrorMap.put(new Integer(-4499), StaleConnectionException.class); setUserDefinedMap(myErrorMap); } }

图 9. 定义用户定义数据存储帮助程序

图 10. 在网络服务器中定义用户定义数据存储帮助程序

部署 Cloudscape V10 应用程序
部署一个在 WebSphere Application Server V6 中使用 Cloudscape V10 的应用程序时，必须选择 DB2UDB_V81 作为数据库类型。这是使用 Cloudscape V10 与使用 Cloudscape 5.1 部署应用程序之间的唯一差别。图 11 显示了如何从管理控制台执行此操作。（因为您是使用 DB2UDB_V81 而非专门使用 Cloudscape V10 数据库模式来进行部署的，所以可能存在某种限制，阻止所生成的部署代码在 Cloudscape V10 上运行（仅限于 CMP（容器管理的持久性）情况下）。不过请注意，出现这种问题的可能性很小，因为 Cloudscape 生成代码非常接近于 DB2 的生成代码。）

图 11. 从管理控制台执行 EJB 部署

结束语
本文介绍了 IBM Cloudscape Version V10 中的一些影响 WebSphere Application Server 的重要变化，解释了如何在 WebSphere Application Server V6.0 中安装这一新版本的 Cloudscape、如何配置 WebSphere Application Server 以便与 Cloudscape V10 一起运行，以及如何部署应用程序以在 Cloudscape V10 中运行。本文介绍的大部分信息仅适用于 WebSphere Application Server V6。