级别： 初级 李 萍 (xiaobei19@gmail.com), 上海交通大学研究生
2006 年 8 月 14 日 本文将针对使用 WebSphere Adapter for JDBC V6.0 开发应用程序过程中可能会遇到的一些常见问题和注意事项进行集中讨论，比如数据类型的不匹配、异常机制、事件表的轮询等等。作者结合自身的经验教训与实例，希望与大家分享这方面的一些最佳实践，以便在开发及应用过程中避免这些问题的出现。
引言
IBM WebSphere Adapter 是基于 J2EE 的符合 JCA1.5 标准的新一代适配器，也被称作资源适配器或 JCA 适配器。它实现了在 EIS 资源和 WebSphere Process Server（WPS）或 WebSphere Enterprise Service Bus（WESB）等应用服务器支持的 J2EE 组件之间进行双向连接和数据交换。而 IBM WebSphere Adapter for JDBC 是专门针对于支持 JDBC 2.0 规范的数据库开发的，目前最新版本是 6.0。
本文将针对使用 WebSphere Adapter for JDBC V6.0 开发应用程序过程中可能会遇到的一些常见问题和注意事项进行集中讨论，比如数据类型的不匹配、异常机制、事件表的轮询等等。作者结合自身的经验教训与实例，给出相应的解决方法和意见建议。
本文的目标读者是那些对 WebSphere Adapter for JDBC 有一定了解，需要用它来开发应用程序的开发人员，希望与大家分享这方面的一些最佳实践，以便在开发及应用过程中避免这些问题的出现。
WebSphere Adapter for JDBC 简介
WebSphere Adapter for JDBC 提供与企业应用在数据层面的整合。它基于 JCA 1.5 标准，实现了企业元数据发现规范（Enterprise Metadata Discovery, EMD）来进行向导式配置，并且交换的数据遵循业务数据对象规范（Service Data Objects, SDO）。
WebSphere Adapter for JDBC 通过 JDBC 的 API 提供符合 JCA 标准的数据库访问的两种方式：Inboud 和 Outbound。Outbound 操作支持对数据库中关系型数据的访问，包括表、视图、存储过程等，主要提供了对"创建"、"更新"、"删除"、"查询"操作的支持。而 Inbound 操作则提供了一种事件 polling 模式，能够在任何基于关系型数据库的应用中监测特定事件的发生并且传递事件信息。
下面，我们将分别就 Outbound 和 Inbound 操作讨论一些常见的问题和需要特别注意的地方。
Outbound Service
1. 有关 Business Object
在开发 Adapter Outbound 项目时，我们首先需要在 WebSphere Integration Developer（WID）中通过企业服务发现组件（Enterprise Service Discovery）连接数据库，并且生成访问数据库的接口 JDBCOutboundInterface。在此过程中，对应每张你需要进行操作的数据库表，Adapter 都会自动生成一个 Business Object（BO），其属性（attributes）与数据库表中的字段一一对应，如图1所示。
图1 生成的 BO 与数据库表一一对应
然而，对于某些数据库字段类型，例如 BIGINT、TIME、TIMESTAMP，Adapter 在生成 Business Object 的时候却不能将其转换成合适的对应类型，如果不加以处理的话，到程序执行期读取数据库信息时就会报错。
对于 BIGINT 类型，Adapter 会自动将其转换为 int，如图 2 所示。
图2 BIGINT 转换成 int
到程序执行期，若是查询该表，Adapter 便会抛出 javax.resource.ResourceException，错误信息如下：
com.ibm.websphere.sca.ServiceRuntimeException: Fail to invoke
[sca.component.java.impl.Component1Impl.public java.lang.String
sca.component.java.impl.Component1Impl.test(java.lang.String) throws
com.ibm.websphere.sca.ServiceBusinessException] for component
[{OGADTest}Component1]: caused by:
com.ibm.websphere.sca.ServiceUnavailableException:
javax.resource.ResourceException: javax.resource.ResourceException:
com.ibm.db2.jcc.b.zd: Invalid data conversion:Requested conversion would
result in a loss of precision of 1111111111111112: caused by:
javax.resource.ResourceException: javax.resource.ResourceException:
com.ibm.db2.jcc.b.zd: Invalid data conversion:Requested conversion would
result in a loss of precision of 1111111111111112
|
因此，你需要在生成该 Business Object 后手动将其类型由 int 改为 long，如图3所示。
图3 手动将 int 改为 long 型
类似的情况也发生在数据库字段类型为 TIME 或 TIMESTAMP 的时候。Adapter 会在生成 Business Object 时，将对应的属性类型设为 date，即 java.sql.Date 类，如图4所示。
图4 TIME,TIMESTAMP 转为 date
问题就此产生。因为 java.sql.Date 中只包含 date 信息，不包含 time 信息，因此，当查询数据库时，Adapter 就会在这种类型转换过程中丢失时间信息，并抛出 javax.resource.ResourceException，错误信息如下：
com.ibm.websphere.sca.ServiceRuntimeException: Fail to invoke
[sca.component.java.impl.Component1Impl.public java.lang.String
sca.component.java.impl.Component1Impl.test(java.lang.String) throws
com.ibm.websphere.sca.ServiceBusinessException] for component
[{OGADTest}Component1]: caused by:
com.ibm.websphere.sca.ServiceUnavailableException:
javax.resource.ResourceException: javax.resource.ResourceException:
com.ibm.db2.jcc.b.xd: Invalid data conversion: Wrong result column type for
requested conversion.: caused by: javax.resource.ResourceException:
javax.resource.ResourceException: com.ibm.db2.jcc.b.xd: Invalid data
conversion: Wrong result column type for requested conversion.
|
要解决这个问题，就必须生成 Business Object 后手动将相应属性类型由 date 改为 time 或 string，然后用 DataObject.getString() 取出，如图5 所示。
图5 手动将date改为time或string
此外，如果你在将项目部署到 WebSphere Process Server（WPS）或 WebSphere Enterprise Service Bus（WESB）上之后，发现又有需要对项目中的某些 Business Object 数据类型进行修改的话，那就要格外小心了。往往你会发现即使你已经将修改后的EAR包重新部署到服务器上，到程序执行期调用的时候，调到的数据类型仍然是更改前的属性。这是因为 WPS 或 WESB 上有一些临时 cache 文件，需要先将这些临时文件删除，数据类型的更改才能真正生效。建议大家先将服务器上的项目卸载掉，然后删除下面两个目录下的相应临时文件：
/opt/ibm/WebSphere/ESB1/profiles/<ProfileName>/wstemp/
/opt/ibm/WebSphere/ESB1/profiles/<ProfileName>/config/
temp/download/cells/<CellName>/applications/
|
最后再将修改后的项目重新打成 EAR 包部署到服务器上。如果这样仍没有效果，就重启一下服务器，基本上就不会再有问题了。
2. 有关 Outbound 操作
在 WID 中通过 Enterprise Service Discovery 生成访问数据库的接口 JDBCOutboundInterface 之后，J2EE 应用程序就能通过调用该接口来实现对相应数据库的操作，包括 "Create"、"Update"、"Delete"、"Retrieve" 以及 "RetrieveAll"。一般来说，WebSphere Adapter 根据应用程序传递给它的 Business Object 中指定的操作来连接数据库并进行相应操作。如果操作成功，Adapter 正常返回；如果操作失败，Adapter 则会抛出执行期异常。
在使用 Adapter Outbound 操作前，建议大家在设计数据库表的时候一定别忘了添加主键（primary key），因为大多数 Outbound 操作都需要用到主键，否则就会抛出执行期异常，具体情况会在下面逐一介绍。至于视图也一样，需要在生成相应的 Business Object 之后，把 xsd 文件中的相应字段设置为主键，如图6 所示：
图6 为视图设置主键
下面我们就分别来谈谈这些 Outbound 操作有哪些需要特别注意的地方。
2.1 Create 操作
"Create" 操作即是在数据库表中添加一行条目。根据数据库设计的不同，"Create" 的操作会略有不同。在一般情况下，你只需设置相应 Business Object 的各个属性值，以及你所要进行的操作（"Create"），然后将其作为输入传递给 Adapter，调用 JDBCOutboundInterface 的相应 Create 函数就行了，就像下面这一段代码。Adapter 会将输入的 Business Object 再作为输出值返回给应用程序。
DataObject dbticket =
boFactory.create("http://OGADTest/DataTypes/db2inst1ticket",
"Db2inst1Ticket");
DataObject dbticketbg =
boFactory.create("http://OGADTest/DataTypes/db2inst1ticketbg",
"Db2inst1TicketBG");
dbticket.setLong("ticketid", 1111111111111111L);
...... //设置相应字段值
dbticketbg.setString("verb", "Create"); //设置操作类型
dbticketbg.setDataObject("Db2inst1Ticket", dbticket);
try {
dbticketbg = jdbcOutboundInterface.createDb2inst1Ticket(dbticketbg); //创建条目
} catch (Exception e) {
logger.error(e.getMessage());
}
|
然而，如果你要创建的条目中含有某个键值字段被设计成由数据库自动生成的，那就不能在输入的 Business Object 中指定该字段的值，否则会抛出 com.ibm.db2.jcc.b.SqlException，错误信息如下：
com.ibm.websphere.sca.ServiceRuntimeException: Fail to invoke
[sca.component.java.impl.Component1Impl.public java.lang.String
sca.component.java.impl.Component1Impl.test(java.lang.String) throws
com.ibm.websphere.sca.ServiceBusinessException] for component
[{OGADTest}Component1]: caused by:
com.ibm.websphere.sca.ServiceUnavailableException:
javax.resource.ResourceException: com.ibm.db2.jcc.b.SqlException: DB2 SQL
error: SQLCODE: -798, SQLSTATE: 428C9, SQLERRMC: TICKETID: caused by:
javax.resource.ResourceException: com.ibm.db2.jcc.b.SqlException: DB2 SQL
error: SQLCODE: -798, SQLSTATE: 428C9, SQLERRMC: TICKETID
|
正确的做法是让数据库自动生成该键值，然后再调用 RetrieveAll 方法得到创建的条目信息。（因为 Create 操作的返回值只是输入的 Business Object 的拷贝，并不包含数据库自动生成的键值信息，因此需要再调用一次 RetrieveAll 才能得到完整的新建条目信息。至于为什么调用 RetrieveAll 而非 Retrieve 方法，可以参考 2.4 小节。）
示例代码如下：
DataObject dbticket =
boFactory.create("http://OGADTest/DataTypes/db2inst1ticket", "Db2inst1Ticket");
DataObject dbticketbg =
boFactory.create("http://OGADTest/DataTypes/db2inst1ticketbg",
"Db2inst1TicketBG");
dbticket.setDouble("totalprice", price);
...... //设置除键值以外的字段信息
dbticketbg.setString("verb", "Create");
dbticketbg.setDataObject("Db2inst1Ticket", dbticket);
try {
jdbcOutboundInterface.createDb2inst1Ticket(dbticketbg); //创建条目
} catch (Exception e) {
logger.error(e.getMessage());
}
dbticketbg.setString("verb", null);
List ticketList = new ArrayList();
try {
DataObject dbticketcontainer =
jdbcOutboundInterface.retrieveallDb2inst1Ticket(dbticketbg);
ticketList = dbticketcontainer.getList("Db2inst1TicketBG"); //查询条目
} catch (Exception e) {
logger.error(e.getMessage());
}
dbticketbg = (DataObject) ticketList.get(ticketList.size() - 1); //得到最新创建的条目信息
|
2.2 Update 操作
"Update" 操作即是更新数据库表中某行条目的值。你只需在输入的 Business Object 中设置需要更改的属性值，以及所要进行的操作（"Update"），然后将其传递给 Adapter，调用 JDBCOutboundInterface 的相应 Update 函数就行。示例代码如下：
DataObject dbticket =
boFactory.create("http://OGADTest/DataTypes/db2inst1ticket", "Db2inst1Ticket");
DataObject dbticketbg =
boFactory.create("http://OGADTest/DataTypes/db2inst1ticketbg",
"Db2inst1TicketBG");
dbticket.setLong("ticketid", ticketID); //输入键值
dbticket.setString("seatclass", seatClass);
...... //设置需要更改的字段值
dbticketbg.setString("verb", "Update"); //设置操作类型
dbticketbg.setDataObject("Db2inst1Ticket", dbticket);
try {
jdbcOutboundInterface.updateDb2inst1Ticket(dbticketbg); //更新条目
} catch (Exception e) {
logger.error(e.getMessage());
}
|
其中有一点需要特别注意，就是输入的 Business Object 中必须指定要更改的条目的键值，否则 Adapter 无法定位你要进行 Update 操作的数据库条目，就会抛出 javax.resource.ResourceException，错误信息如下：
com.ibm.websphere.sca.ServiceRuntimeException: Fail to invoke
[sca.component.java.impl.Component1Impl.public java.lang.String
sca.component.java.impl.Component1Impl.test(java.lang.String) throws
com.ibm.websphere.sca.ServiceBusinessException] for component
[{OGADTest}Component1]: caused by:
com.ibm.websphere.sca.ServiceUnavailableException:
javax.resource.ResourceException: javax.resource.ResourceException: Update
Operation failed - No primary or foreign keys specified on the business object
Db2inst1Ticket: caused by: javax.resource.ResourceException:
javax.resource.ResourceException: Update Operation failed - No primary or
foreign keys specified on the business object Db2inst1Ticket
|
若是数据库表中没有符合输入键值的条目，Adapter 则会抛出 com.ibm.db2.jcc.b.SqlException，错误信息如下：
com.ibm.websphere.sca.ServiceRuntimeException: Fail to invoke
[sca.component.java.impl.Component1Impl.public java.lang.String
sca.component.java.impl.Component1Impl.test(java.lang.String) throws
com.ibm.websphere.sca.ServiceBusinessException] for component
[{OGADTest}Component1]: caused by:
com.ibm.websphere.sca.ServiceUnavailableException:
javax.resource.ResourceException: com.ibm.db2.jcc.b.SqlException: Invalid
operation: result set closed: caused by: javax.resource.ResourceException:
com.ibm.db2.jcc.b.SqlException: Invalid operation: result set closed
|
2.3 Delete 操作
"Delete" 操作即是删除数据库表中的一条记录。为了定位到你要删除的那条记录，在输入的 Business Object 中必须且只需指定键值信息，以及所要进行的操作（"Delete"），再将其传递给 Adapter，调用 JDBCOutboundInterface 的相应 Delete 函数。示例代码如下：
DataObject dbticket =
boFactory.create("http://OGADTest/DataTypes/db2inst1ticket", "Db2inst1Ticket");
DataObject dbticketbg =
boFactory.create("http://OGADTest/DataTypes/db2inst1ticketbg",
"Db2inst1TicketBG");
dbticket.setLong("ticketid", ticketID); //输入键值
dbticketbg.setString("verb", "Delete"); //设置操作类型
dbticketbg.setDataObject("Db2inst1Ticket", dbticket);
try {
jdbcOutboundInterface.deleteDb2inst1Ticket(dbticketbg); //删除条目
} catch (Exception e) {
logger.error(e.getMessage());
}
|
若是你没有在输入的 Business Object 中指定键值，即使你输入了其他字段信息，Adapter 仍然无法定位你要删除的那条记录，它会认为数据库表中的所有条目都是符合条件的，于是抛出 com.ibm.j2ca.base.exceptions.MultipleMatchingRecordsException，错误信息如下：
com.ibm.websphere.sca.ServiceRuntimeException: Fail to invoke
[sca.component.java.impl.Component1Impl.public java.lang.String
sca.component.java.impl.Component1Impl.test(java.lang.String) throws
com.ibm.websphere.sca.ServiceBusinessException] for component
[{OGADTest}Component1]: caused by:
com.ibm.websphere.sca.ServiceUnavailableException:
com.ibm.j2ca.base.exceptions.MultipleMatchingRecordsException: Expected one
match in EIS; found 20. Refine search appropriately.: caused by:
com.ibm.j2ca.base.exceptions.MultipleMatchingRecordsException: Expected one
match in EIS; found 20. Refine search appropriately.
|
同样的，若是数据库表中没有符合输入键值的条目，Adapter 会抛出 com.ibm.db2.jcc.b.SqlException，错误信息同 "Update" 操作的情况。
2.4 Retrieve 操作
"Retrieve" 操作即是查询数据库表中的单条记录。它用在数据库表中有且只有一条记录符合查询条件的情况。若是有多条记录符合或是没有记录符合，Adapter 都会抛出执行期异常。因此，为了保证只有一条记录符合，同 "Delete" 操作一样，在输入给 Adapter 的 Business Object 中必须且只需指定键值信息。调用 JDBCOutboundInterface 的相应 Retrieve 函数，Adapter 会将查询到的记录信息以 Business Object 返回。示例代码如下：
DataObject dbticket =
boFactory.create("http://OGADTest/DataTypes/db2inst1ticket", "Db2inst1Ticket");
DataObject dbticketbg =
boFactory.create("http://OGADTest/DataTypes/db2inst1ticketbg",
"Db2inst1TicketBG");
dbticket.setLong("ticketid", ticketID); //输入键值
dbticketbg.setString("verb", null); //设置操作类型为null，代表查询
dbticketbg.setDataObject("Db2inst1Ticket", dbticket);
try {
dbticketbg = jdbcOutboundInterface.retrieveDb2inst1Ticket(dbticketbg);
//查询单条记录
} catch (Exception e) {
logger.error(e.getMessage());
}
|
同样的，若是在传递给 Adapter 的 Business Object 中没有指定键值，即使输入了其他字段信息，Adapter 仍然会认为数据库表中的所有记录都符合查询条件，于是抛出 com.ibm.j2ca.base.exceptions.MultipleMatchingRecordsException，错误信息同 "Delete" 操作的情况。因此，如果你想以除键值以外的字段来进行查询，应该调用 "RetrieveAll" 函数。
此外，若是数据库表中没有符合输入键值的条目，Adapter 也会抛出 com.ibm.db2.jcc.b.SqlException，错误信息同 "Update" 和 "Delete" 操作的情况。
2.5 RetrieveAll 操作
"RetrieveAll" 操作即是查询数据库表中所有符合查询条件的记录。与 "Retrieve" 不同，"RetrieveAll" 能够返回多条记录，因此你可以在输入的 Business Object 中以任何字段的组合来设置查询条件。调用 JDBCOutboundInterface 的相应 RetrieveAll 函数，Adapter 会将所以符合条件的记录以 Business Object 返回。示例代码如下：
DataObject dbticket =
boFactory.create("http://OGADTest/DataTypes/db2inst1ticket", "Db2inst1Ticket");
DataObject dbticketbg =
boFactory.create("http://OGADTest/DataTypes/db2inst1ticketbg",
"Db2inst1TicketBG");
dbticket.setString("userid", userID);
...... //设置查询条件
dbticketbg.setString("verb", null); //设置操作类型为null，代表查询
dbticketbg.setDataObject("Db2inst1Ticket", dbticket);
List ticketList = new ArrayList();
try {
DataObject dbticketcontainer = j.retrieveallDb2inst1Ticket(dbticketbg);
//查询多条记录
ticketList = dbticketcontainer.getList("Db2inst1TicketBG");
//得到查询结果列表
} catch (Exception e) {
logger.error(e.getMessage());
}
|
虽然可以用除键值以外的字段来进行 RetrieveAll 查询，你所查询的表或视图所对应的 Business Object 中仍需设置一个主键，因为 Adapter 在执行 RetrieveAll 操作之后，会对返回的 Container 里的每一个 BO 进行一次 Retrieve 查询。因此，如果相应的BO里没有主键信息，Adapter 就会抛出 com.ibm.j2ca.base.exceptions.MultipleMatchingRecordsException，错误信息同 "Retrieve" 操作的情况。
还有一点需要注意，如果数据库表中没有任何一条记录符合查询条件，Adapter 会抛出 com.ibm.j2ca.base.exceptions.RecordNotFoundException，而不是返回一个空的 Business Object。因此在开发时，你需要考虑到这种情况并捕获相应的异常。该异常的错误信息如下：
com.ibm.websphere.sca.ServiceRuntimeException: Fail to invoke
[sca.component.java.impl.Component1Impl.public java.lang.String
sca.component.java.impl.Component1Impl.test(java.lang.String) throws
com.ibm.websphere.sca.ServiceBusinessException] for component
[{OGADTest}Component1]: caused by:
com.ibm.websphere.sca.ServiceUnavailableException:
com.ibm.j2ca.base.exceptions.RecordNotFoundException: Record not found in EIS
corresponding to business object 'Db2inst1Ticket' with key values: key
value(s)={ticketid=0}: caused by:
com.ibm.j2ca.base.exceptions.RecordNotFoundException: Record not found in EIS
corresponding to business object 'Db2inst1Ticket' with key values: key
value(s)={ticketid=0}
|
3. 有关异常的捕捉
从以上的 Outbound 操作可以看出，Adapter 在执行期可能会抛出各种各样的执行期异常。因此建议大家在捕捉异常的 catch 声明中使用 Exception而非ServiceBusinessException 等具体的执行期异常类型，这样就可以确保捕捉到所有的异常。
4. 有关项目的部署
要将开发完成的项目部署到 WPS 或 WESB 服务器上，只需将项目以 EAR 包导出，然后登录服务器管理控制台安装就行，安装过程中的参数设置只需保持默认值。安装完成后，别忘了将项目所用的 JDBC 驱动拷贝到服务器的如下文件夹：
/opt/ibm/WebSphere/ESB1/lib/
|
最后启动程序。如果程序启动失败，如图7所示：
图7 程序启动失败
且服务器的日志里打出如下错误信息：
00000086 RAWrapperImpl E J2CA0128E: An Exception occurred while trying to
start ResourceAdapter
cells/ogadesb1Node03Cell/applications/OGADTestApp.ear/deployments/OGADTestApp/
deployment.xml#J2CResourceAdapter_1152103796444. The exception is:
javax.resource.spi.ResourceAdapterInternalException: One or more adapter
configuration properties are invalid
|
这说明你的 Outbound 项目配置有问题。你可以检查一下项目的 J2C Authentication Data Entry 是否设置正确，如图8所示：
图8 J2C Authentication Data Entry
J2C Authentication Data Entry 是程序执行期连接数据库时认证用的，提供了访问数据库的用户名和密码，可登录 WPS 或 WESB 服务器管理控制台进行设置，如图9 所示：
图9 设置 J2C Authentication Data Entry
Inbound Service
在开发 Inbound 项目的时候，我们首先需要在数据库中创建触发器，使得当数据库表中的记录发生改变时，会触发相应的事件，并且将相关记录信息插入到 EventStore 表中。然后创建 Inbound 项目，在设置 Artifacts 参数时指定 EventStore 表。在程序运行时，Adapter 便会轮询监测 EventStore 表，一旦发现有新的事件记录被插入，它就会处理这些事件，为每个事件构建 JDBC Business Graph，并且将这些 Business Graph 发送到订阅相应的数据库改变事件的应用程序，从而使应用程序获得数据库改变的通知。当处理完事件，Adapter 会清空 EventStore 中的相关记录，然后继续监测。
然而，在 Inbound Service 运行一段时间之后，你可能会发现应用程序再也收不到数据库改变的通知了，这时去查询 EventStore 表，会发现数据库改变所触发的事件信息仍然停留在 EventStore 表中没有被处理，而服务器的日志里也打出很多下面这样的错误信息：
00000070 ResourceAdapt E com.ibm.j2ca.jdbc.inbound.JDBCEventStore getEvents
CWYJB0606E: An operation on the database failed with a SQL exception for the
following reason: DB2 SQL error: SQLCODE: -805, SQLSTATE: 51002, SQLERRMC:
NULLID.SYSLH209 0X5359534C564C3031.
00000070 ResourceAdapt E com.ibm.j2ca.jdbc.inbound.JDBCEventStore getEvents
CWYJB0607E: Polled events were not retrieved.
|
这说明 Adapter Inbound Service 对 EventStore 的轮询机制出现了问题。你只要将 Inbound 应用程序重新启动一下，Inbound Service 便会恢复正常工作。但这是治标不治本的做法，过一段时间后，同样的问题很可能再次出现。要避免这类问题，建议大家使用 WebSphere Adapter for JDBC 6.0.0.2 Fix Pack，该补丁包已将 Adapter Inbound 的这个问题修复。
结束语
本文讨论了 WebSphere Adapter for JDBC V6.0 开发和应用时的一些常见问题和注意事项，结合作者自身的经验教训，给出了相应的解决方法和意见建议，希望能对 WebSphere Adapter for JDBC 的使用开发人员有所帮助，以便少走弯路。
参考资料
关于作者
对本文的评价
| 
