第 16 章 Java 连接器架构(JCA)管理

16.1. 关于 Java 连接器架构(JCA)

Java EE 连接器架构(Java EE Connector Architecture,简称 JCA)为 Java EE 系统和外部的异构企业级信息系统(EIS)间定义一个标准的架构。EIS 的例子包括 ERP 系统、大型机事务处理(TP)、数据库和消息系统。资源适配器是一个实现 Java EE Connector API 架构的组件。它和数据源对象类似。

JCA 1.7 提供这些管理功能:

  • 连接
  • 事务
  • 安全
  • 生命周期
  • 工作实例
  • 事务流
  • 消息流

JCA 1.7 是根据 Java Community Process JSR-322 开发的。

16.2. 关于资源适配器

资源适配器是提供 Java EE 应用程序和使用 JCA 规格的 EIS 系统间通讯的可部署 Java EE 组件。EIS 厂商经常提供资源适配器,允许他们的产品与 Java EE 应用程序轻易集成。

企业信息系统(Enterprise Information System,EIS )可以是机构里的其他软件包系统。如 ERP 系统、数据库系统、电子邮件服务器和专有消息系统。

资源适配器打包在资源适配器归档(Resource Adapter Archive,RAR)文件里,它可以部署至 JBoss EAP 服务器。RAR 文件也可以包含在 EAR 部署里。

16.3. 配置 JCA 子系统

jca 子系统用来控制 JCA 容器和资源适配器部署的常用设置。您可以使用管理控制台或管理 CLI 来配置 jca 子系统。

要配置的主要的 JCA 元素是:

用管理控制台配置 JCA 设置

jca 子系统可以在管理控制台里配置,请选择 ConfigurationSubsystemsJCA。然后,选择适当的标签页:

  • Common Config - 包含缓存连接管理者、归档校验、Bean 校验的设置。每个设置都有自己的标签页。打开相应的标签页并点击 Edit 按钮来修改这些设置。
  • Bootstrap Contexts - 包含配置的引导上下文列表。您可以添加、删除和配置新的引导上下文对象。每个引导上下文都必须分配一个工作管理者(Work Manager)。
  • Work Manager - 包含配置的工作管理者的列表。您可以添加、删除新的工作管理者并配置其线程池。每个工作管理者都可以有一个短期线程池和可选的长期线程池。

    线程池属性可以点击所选工作管理者的 View 来进行配置。

用管理 CLI 配置 JCA 设置
jca 子系统可以通过 /subsystem=jca 地址使用管理 CLI 进行配置。在受管域里,您必须在这个命令之前使用 /host=PROFILE_NAME

归档校验

确定是否在部署单元上进行归档校验。下表描述了您可以为归档校验设置的属性。

表 16.1. 归档校验属性

属性默认值描述

enabled

true

指定是否启用归档校验。

fail-on-error

true

指定归档校验错误报告是否使部署失败。

fail-on-warn

false

指定归档校验警告报告是否使部署失败。

如果归档没有正确实现 JCA 规格且启用了归档校验,部署期间将出现一个描述该问题的错误信息。例如:

Severity: ERROR
Section: 19.4.2
Description: A ResourceAdapter must implement a "public int hashCode()" method.
Code: com.mycompany.myproject.ResourceAdapterImpl

Severity: ERROR
Section: 19.4.2
Description: A ResourceAdapter must implement a "public boolean equals(Object)" method.
Code: com.mycompany.myproject.ResourceAdapterImpl

如果没有指定归档校验,它会认为是启用的,且 enabled 属性默认是 true

Bean 校验

这个设置确定是否在部署单元上执行 Bean 校验(JSR-303)。下表描述了您可以设置的 Bean 校验属性。

表 16.2. Bean 校验属性

属性默认值描述

enabled

true

指定是否启用 Bean 校验。

如果没有指定 Bean 校验,它会认为是启用的,且 enabled 属性默认是 true

工作管理者

有两种类型的工作管理者:

默认的工作管理者
默认的工作管理者及其线程池。
自定义的工作管理者
自定义的工作管理者及其线程池。

下表描述了您可以为工作管理者设置的属性。

表 16.3. 工作管理者属性

属性描述

name

指定工作管理者的名称。

short-running-threads

标准 Work 实例的线程池。每个工作管理者都有一个短期线程池。

long-running-threads

设置 LONG_RUNNING 提示的 JCA 1.7 Work 实例的线程池。每个工作管理者可以有一个可选的长期线程池。

下表描述了您可以为工作管理者线程池设置的属性。

表 16.4. 线程池属性

属性默认值描述

name

default

指定线程池的名称。

keepalive-time

10 seconds

指定池线程在完成工作后应该保持的时间。

allow-core-timeout

false

布尔值,确定核心线程是否会超时。默认值是 false。

thread-factory

 

对线程工厂的引用。

max-thread

50

线程池的最大尺寸。

core-threads

50

核心线程池的大小。这必须等于或小于最大的线程池尺寸。

queue-length

50

最大的队列长度。

引导上下文

用于定义自定义引导上下问。下表描述了您可以为引导上下文设置的属性。

表 16.5. 引导上下文属性

属性描述

name

指定引导上下文的名称。

workmanager

指定用于这个上下文的工作管理者的名称。

缓存的连接管理者

这用于调试连接和支持事务里的连接的惰性征募(lazy enlistment),跟踪应用程序是否正确地使用和释放它们。下表描述了您可以为缓存连接管理者设置的属性。

表 16.6. 缓存连接管理者属性

属性默认值描述

debug

false

在失败时输出警告来显性地关闭连接。

error

false

在失败时抛出异常来显性地关闭连接。

ignore-unknown-connections

false

指定不会缓存未知的连接。

16.4. 配置资源适配器

16.4.1. 部署资源适配器

资源适配器可以像其他部署一样用管理 CLI 或管理控制台进行部署。当运行为独立服务器时,您也可以将归档复制到部署目录,让部署扫描器检测到。

用管理 CLI 部署资源适配器

要部署资源适配器至独立服务器,请输入下列管理 CLI 命令。

deploy /path/to/resource-adapter.rar

要部署资源适配器至受管域里的所有服务器组,请输入下列管理 CLI 命令。

deploy /path/to/resource-adapter.rar --all-server-groups
用管理控制台部署资源适配器
  1. 登录至管理控制台并点击 Deployments 标签页。
  2. 点击 Add。在受管域里,您首先需要选择 Content Repository
  3. 选择 Upload a new deployment 选项并点击 Next
  4. 浏览资源适配器归档并点击 Next
  5. 检验要上传的文件并点击 Finish
  6. 在受管域里,分配部署至合适的服务器组并启用部署。
用部署扫描器部署资源适配器。

要手动部署资源适配器至独立服务器,请将资源适配器归档复制到服务器的 deployments 目录,例如 EAP_HOME/standalone/deployments/。部署扫描器将检测并部署它。

注意

这个选项对于受管域不可用。您必须使用管理控制台或管理 CLI 来部署资源适配器至服务器组。

16.4.2. 配置资源适配器

您可以用管理界面来配置资源适配器。下面的例子展示了如何用管理 CLI 配置资源适配器。关于受支持的属性和其他重要信息,请参考资源适配器厂商的相关文档。

添加资源适配器配置

添加资源适配器配置。

/subsystem=resource-adapters/resource-adapter=eis.rar:add(archive=eis.rar, transaction-support=XATransaction)
配置资源适配器设置

按需要配置下列设置。

  • 配置 config-properties

    添加 server 配置属性。

    /subsystem=resource-adapters/resource-adapter=eis.rar/config-properties=server:add(value=localhost)

    添加 port 配置属性。

    /subsystem=resource-adapters/resource-adapter=eis.rar/config-properties=port:add(value=9000)
  • 配置 admin-objects

    添加一个 admin 对象。

    /subsystem=resource-adapters/resource-adapter=eis.rar/admin-objects=aoName:add(class-name=com.acme.eis.ra.EISAdminObjectImpl, jndi-name=java:/eis/AcmeAdminObject)

    配置 admin 对象的属性。

    /subsystem=resource-adapters/resource-adapter=eis.rar/admin-objects=aoName/config-properties=threshold:add(value=10)
  • 配置 connection-definitions

    为受管连接工厂添加连接定义。

    /subsystem=resource-adapters/resource-adapter=eis.rar/connection-definitions=cfName:add(class-name=com.acme.eis.ra.EISManagedConnectionFactory, jndi-name=java:/eis/AcmeConnectionFactory)

    配置受管连接工厂的配置属性。

    /subsystem=resource-adapters/resource-adapter=eis.rar/connection-definitions=cfName/config-properties=name:add(value=Acme Inc)

    配置是否记录征募跟踪信息。您可以将 enlistment-trace 属性设置为 false 来禁用征募跟踪信息的记录。

    /subsystem=resource-adapters/resource-adapter=eis.rar/connection-definitions=cfName:write-attribute(name=enlistment-trace,value=false)
    警告

    禁用登记跟踪会使在事务登记的过程中查找错误变得比较困难。

关于资源适配器的所有可用的配置属性,请参考资源适配器属性

激活资源适配器

激活资源适配器。

/subsystem=resource-adapters/resource-adapter=eis.rar:activate
注意

您也可以定义资源适配器的功能策略。更多的信息请参考功能策略章节。

16.4.3. 部署和配置 Websphere MQ 资源适配器

您可以在《为 JBoss EAP 配置消息系统》部署 Websphere MQ 资源适配器里找到相关的说明。

16.4.4. 部署和配置通用的 JMS 资源适配器

您可以在《为 JBoss EAP 配置消息系统》配置通用的 JMS 资源适配器里找到相关的说明。

16.5. 配置受管连接池

JBoss EAP 提供了三个 ManagedConnectionPool 接口的实现。

org.jboss.jca.core.connectionmanager.pool.mcp.SemaphoreConcurrentLinkedQueueManagedConnectionPool
这是 JBoss EAP 7 的默认连接池且提供了最佳开箱即用性能。
org.jboss.jca.core.connectionmanager.pool.mcp.SemaphoreArrayListManagedConnectionPool
这是之前的 JBoss EAP 版本里的默认连接池。
org.jboss.jca.core.connectionmanager.pool.mcp.LeakDumperManagedConnectionPool
这个连接池仅用于调试目的,它将在关闭或冲刷时报告任何泄漏。

您可以用下列管理 CLI 命令为数据源设置受管连接池实现。

/subsystem=datasources/data-source=DATA_SOURCE:write-attribute(name=mcp,value=MCP_CLASS)

您可以用下列管理 CLI 命令为资源适配器设置受管连接池实现。

/subsystem=resource-adapters/resource-adapter=RESOURCE_ADAPTER/connection-definitions=CONNECTION_DEFINITION:write-attribute(name=mcp,value=MCP_CLASS)

您可以用下列管理 CLI 命令为消息服务器设置受管连接池实现。

/subsystem=messaging-activemq/server=SERVER/pooled-connection-factory=CONNECTION_FACTORY:write-attribute(name=managed-connection-pool,value=MCP_CLASS)

16.6. 查看连接统计信息

您可以从 /deployment=NAME.rar 子树读取连接的统计信息。这使您可以访问任何 RAR 的统计信息,即使它没有在 standalone.xmldomain.xml 配置里定义。

/deployment=NAME.rar/subsystem=resource-adapters/statistics=statistics/connection-definitions=java\:\/testMe:read-resource(include-runtime=true)
注意

请确保指定了 include-runtime=true 参数,因为所有统计都只是运行时信息。

关于可用的统计信息的详情,请参考资源适配器统计