Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

31.6. 部署 IBM MQ 资源适配器

关于 IBM MQ

IBM MQ 是来自 IBM 的消息传递导向型中间件(MOM)产品，允许分布式系统上的应用程序相互通信。这通过使用消息和消息队列来完成。IBM MQ 负责发送消息到消息队列，以及使用消息通道将数据传输到其他队列管理器。有关 IBM MQ 的更多信息，请参阅 IBM 产品网站上的 IBM MQ。

概述

IBM MQ 可以配置为 JBoss EAP 7.3 的外部 JMS 提供程序。本节介绍在 JBoss EAP 中部署和配置 IBM MQ 资源适配器的步骤。此部署和配置可使用管理 CLI 工具或基于 Web 的管理控制台来完成。有关 IBM MQ 支持配置的最新信息，请参阅 JBoss EAP 支持的配置。

注意

您必须在配置 IBM MQ 资源适配器后重启您的系统，使配置更改生效。

先决条件

开始之前，您必须验证 IBM MQ 资源适配器的版本并了解其配置属性。

  • IBM MQ 资源适配器作为名为 wmq.jmsra.rar 的 Resource Archive(RAR)文件提供。您可以从 /opt/ mqm/java/lib/jca/wmq.jmsra.rar 获取 w mq.jmsra.rar 文件。如需有关每个 JBoss EAP 版本支持的特定版本的信息，请参阅 JBoss EAP 支持的配置。

  • 您必须知道以下 IBM MQ 配置值：有关这些值的详情，请参阅 IBM MQ 产品文档。

    • MQ_QUEUE_MANAGER ：IBM MQ 队列管理器的名称
    • MQ_HOST_NAME ：用于连接到 IBM MQ 队列管理器的主机名
    • MQ_CHANNEL_NAME ：用于连接到 IBM MQ 队列管理器的服务器频道
    • MQ_QUEUE_NAME ：目标队列的名称
    • MQ_TOPIC_NAME ：目标主题的名称
    • MQ_PORT ：用于连接到 IBM MQ 队列管理器的端口
    • MQ_CLIENT ：传输类型

  • 对于出站连接，还必须熟悉以下配置值：

    • MQ_CONNECTIONFACTORY_NAME ：提供与远程系统连接的连接工厂实例的名称

流程

注意

以下是 IBM 提供的默认配置，可能随时更改。如需更多信息，请参阅 IBM MQ 文档。

  1. 首先，通过将 wmq.jmsra.rar 文件复制到 EAP_HOME/standalone/deployments/ 目录中来手动部署资源适配器。

  2. 接下来，使用管理 CLI 添加资源适配器并进行配置。 

    /subsystem=resource-adapters/resource-adapter=wmq.jmsra.rar:add(archive=wmq.jmsra.rar, transaction-support=XATransaction)
    Copy to Clipboard Toggle word wrap

    请注意，transaction-support 元素被设置为 XATransaction。在使用事务时，请务必提供 XA 恢复数据源的安全域，如下例所示。 

    /subsystem=resource-adapters/resource-adapter=test/connection-definitions=test:write-attribute(name=recovery-security-domain,value=myDomain)
    Copy to Clipboard Toggle word wrap

    有关 XA 恢复的更多信息，请参阅 JBoss EAP 配置指南中的配置 XA 恢复。

    对于非事务部署，将 事务支持 的值更改为 NoTransaction。 

    /subsystem=resource-adapters/resource-adapter=wmq.jmsra.rar:add(archive=wmq.jmsra.rar, transaction-support=NoTransaction)
    Copy to Clipboard Toggle word wrap

  3. 现在创建了资源适配器，您可以在其中添加必要的配置元素。

    1. 为队列添加一个 admin-object，并配置其属性。 

      /subsystem=resource-adapters/resource-adapter=wmq.jmsra.rar/admin-objects=queue-ao:add(class-name=com.ibm.mq.connector.outbound.MQQueueProxy, jndi-name=java:jboss/MQ_QUEUE_NAME)

/subsystem=resource-adapters/resource-adapter=wmq.jmsra.rar/admin-objects=queue-ao/config-properties=baseQueueName:add(value=MQ_QUEUE_NAME)

/subsystem=resource-adapters/resource-adapter=wmq.jmsra.rar/admin-objects=queue-ao/config-properties=baseQueueManagerName:add(value=MQ_QUEUE_MANAGER)
      Copy to Clipboard Toggle word wrap

    2. 为主题添加一个 admin-object，并配置其属性。 

      /subsystem=resource-adapters/resource-adapter=wmq.jmsra.rar/admin-objects=topic-ao:add(class-name=com.ibm.mq.connector.outbound.MQTopicProxy, jndi-name=java:jboss/MQ_TOPIC_NAME)

/subsystem=resource-adapters/resource-adapter=wmq.jmsra.rar/admin-objects=topic-ao/config-properties=baseTopicName:add(value=MQ_TOPIC_NAME)

/subsystem=resource-adapters/resource-adapter=wmq.jmsra.rar/admin-objects=topic-ao/config-properties=brokerPubQueueManager:add(value=MQ_QUEUE_MANAGER)
      Copy to Clipboard Toggle word wrap

    3. 为受管连接工厂添加连接定义，并配置其属性。 

      /subsystem=resource-adapters/resource-adapter=wmq.jmsra.rar/connection-definitions=mq-cd:add(class-name=com.ibm.mq.connector.outbound.ManagedConnectionFactoryImpl, jndi-name=java:jboss/MQ_CONNECTIONFACTORY_NAME, tracking=false)

/subsystem=resource-adapters/resource-adapter=wmq.jmsra.rar/connection-definitions=mq-cd/config-properties=hostName:add(value=MQ_HOST_NAME)

/subsystem=resource-adapters/resource-adapter=wmq.jmsra.rar/connection-definitions=mq-cd/config-properties=port:add(value=MQ_PORT)

/subsystem=resource-adapters/resource-adapter=wmq.jmsra.rar/connection-definitions=mq-cd/config-properties=channel:add(value=MQ_CHANNEL_NAME)

/subsystem=resource-adapters/resource-adapter=wmq.jmsra.rar/connection-definitions=mq-cd/config-properties=transportType:add(value=MQ_CLIENT)

/subsystem=resource-adapters/resource-adapter=wmq.jmsra.rar/connection-definitions=mq-cd/config-properties=queueManager:add(value=MQ_QUEUE_MANAGER)
      Copy to Clipboard Toggle word wrap

  4. 如果要将 JBoss EAP 中 EJB3 消息传递系统的默认提供程序从 JBoss EAP 7 消息传递更改为 IBM MQ，请使用管理 CLI 来修改 ejb3 子系统，如下所示： 

    /subsystem=ejb3:write-attribute(name=default-resource-adapter-name,value=wmq.jmsra.rar)
    Copy to Clipboard Toggle word wrap

  5. 在 MDB 代码 中配置 @ActivationConfigProperty 和 @ResourceAdapter 注释，如下所示： 

    @MessageDriven(name="IbmMqMdb", activationConfig = {
    @ActivationConfigProperty(propertyName = "destinationType",propertyValue = "javax.jms.Queue"),
    @ActivationConfigProperty(propertyName = "useJNDI", propertyValue = "false"),
    @ActivationConfigProperty(propertyName = "hostName", propertyValue = "MQ_HOST_NAME"),
    @ActivationConfigProperty(propertyName = "port", propertyValue = "MQ_PORT"),
    @ActivationConfigProperty(propertyName = "channel", propertyValue = "MQ_CHANNEL_NAME"),
    @ActivationConfigProperty(propertyName = "queueManager", propertyValue = "MQ_QUEUE_MANAGER"),
    @ActivationConfigProperty(propertyName = "destination", propertyValue = "MQ_QUEUE_NAME"),
    @ActivationConfigProperty(propertyName = "transportType", propertyValue = "MQ_CLIENT")
})

@ResourceAdapter(value = "wmq.jmsra-VERSION.rar")
@TransactionAttribute(TransactionAttributeType.NOT_SUPPORTED)
public class IbmMqMdb implements MessageListener {
}
    Copy to Clipboard Toggle word wrap

    务必将 @ResourceAdapter 值中的 VERSION 替换为 RAR 名称中的实际版本。

  6. 激活资源适配器： 

    /subsystem=resource-adapters/resource-adapter=wmq.jmsra.rar:activate()
    Copy to Clipboard Toggle word wrap

31.6.1. IBM MQ 资源适配器的限制和已知问题
复制链接

下表列出了 IBM MQ 资源适配器的已知问题。version 列中的复选标记(Auditor)表示该资源适配器版本存在问题。

Expand
表 31.1. IBM MQ 资源适配器已知问题
JIRA问题描述IBM MQ 8IBM MQ 9

JBEAP-503

IBM MQ 资源适配器返回 Queue.toString（）和 Queue Browser.getQueue（）.toString（） 方法的不同 String 值。队列 是 com.ibm.mq.connector.outbound.MQQueueProxy 类的实例，它与 QueueBrowser .htmlQueueBrowser.getQueue（）方法返回的 com.ibm.mq.jms.MQ Queue 类不同。这些类包含 toString（） 方法的不同实施。请注意，您不能依赖这些 toString（） 方法来返回相同的值。

✔

✔

JBEAP-511, JBEAP-550, JBEAP-3686

以下限制适用于 IBM MQ 的消息属性名称。

  • 在部署描述符的 activation-config 部分中，您不能使用 _、& 或 | 等特殊字符配置 destinationName 属性。使用这些字符会导致 MDB 部署失败，并显示 com.ibm.msg.client.jms.DetailedInvalidDestinationException 异常。
  • 在部署描述符的 activation-config 部分中，您不能使用 java:/ 前缀配置 destinationName 属性。使用这个前缀会导致 MDB 部署失败，并显示 com.ibm.msg.client.jms.DetailedInvalidDestinationException 异常。
  • 属性不得以"JMS"或"usr.JMS"开头，因为它们保留给 IBM MQ JMS 类使用。IBM 知识库网站上会记录例外。

请参阅 IBM MQ、版本 8.0 和属性名称限制(IBM MQ)、IBM 知识库网站上版本 9.0 的限制，以了解每个资源适配器的消息属性名称限制的完整列表。

✔

✔

JBEAP-549

在使用 @ActivationConfigProperty 注释为 MDB 指定 目的地 属性名称值时，您必须使用所有大写字母。例如： 

@ActivationConfigProperty(propertyName = "destination", propertyValue = "QUEUE")
Copy to Clipboard Toggle word wrap

✔

✔

JBEAP-624

如果使用 IBM MQ 资源适配器，以使用 @JMSConnectionFactoryDefinition 注释在 Jakarta EE 部署中创建连接工厂，您必须指定 resourceAdapter 属性。否则，部署将失败。 

@JMSConnectionFactoryDefinition(
    name = "java:/jms/WMQConnectionFactory",
    interfaceName = "javax.jms.ConnectionFactory",
    resourceAdapter = "wmq.jmsra",
    properties = {
        "channel=<channel>",
        "hostName=<hostname_wmq_broker>",
        "transportType=<transport_type>",
        "queueManager=<queue_manager>"
    }
)
Copy to Clipboard Toggle word wrap

✔

✔

JBEAP-2339

IBM MQ 资源适配器可以在连接开始前从队列和主题读取消息。这意味着使用者可以在连接启动之前使用消息。要避免出现这个问题，请使用 外部上下文（而非 IBM MQ 资源适配器） 创建的远程 IBM MQ 代理创建的连接工厂。

✔

✔

JBEAP-3685

旦设置了 <transaction-support>XATransaction</transaction-support>，JMSContext 始终为 JMSContext.SESSION_TRANSACTED，无论是使用注入还是手动创建。

在下面的代码示例中，@ JMSSessionMode(JMSContext.DUPS_OK_ACKNOWLEDGE)将 被忽略，JMSContext 则保留在 JMSContext.SESSION_TRANSACTED 中。 

@Inject
@JMSConnectionFactory("jms/CF")
@JMSPasswordCredential(userName="myusername", password="mypassword")
@JMSSessionMode(JMSContext.DUPS_OK_ACKNOWLEDGE)
transient JMSContext context3;
Copy to Clipboard Toggle word wrap

✔

✔

JBEAP-14633

根据 JMS 规范，Queue Session 接口无法用于创建特定于发布/订阅域的对象，从 Session 继承的某些方法应抛出 javax.jms.IllegalStateException。其中一种方法是 QueueSession.createTemporaryTopic( )。IBM MQ 资源适配器抛出 java. lang.NullPointerException，而不是抛出 javax.jms.IllegalState Exception。

✔

✔

JBEAP-14634

MQTopicProxy.getTopicName（） 返回与 IBM MQ 代理设置的不同主题名称。例如，如果将主题名称设置为 topic://MYTOPIC?XMSC_WMQ_BROKER_PUBQ_QMGR=QM，MQTopicProxy 会返回 topic://MYTOPIC。

✔

✔

JBEAP-14636

JMSContext 的默认 autoStart 设置为 false，表示 JMSContext 使用的底层连接在创建使用者时不会自动启动。此设置应默认为 true。

✔

✔

JBEAP-14640

在使用无效凭证时，IBM MQ 资源适配器抛出 DetailedJMSException 而不是 JMSSecurityException，并将以下错误记录到服务器控制台。 

WARN  [org.jboss.jca.core.connectionmanager.pool.strategy.PoolByCri] (EJB default - 7) IJ000604: Throwable while attempting to get a new connection: null: com.ibm.mq.connector.DetailedResourceException: MQJCA1011: Failed to allocate a JMS connection., error code: MQJCA1011 An internal error caused an attempt to allocate a connection to fail. See the linked exception for details of the failure.
Copy to Clipboard Toggle word wrap

以下是可能导致此问题的代码示例： 

QueueConnection qc = queueConnectionFactory.createQueueConnection("invalidUserName", "invalidPassword");
Copy to Clipboard Toggle word wrap

✔

✔

JBEAP-14642

由于 MQMessageProducer.send(Destination destination, Message message) 和 MQMessageProducer.send(Destination destination, Message message, int deliveryMode), int 优先级, 长 timeToLive, CompletionListener completionListener） 方法， IBM MQ 资源适配器抛出 JMSException，并将以下错误消息记录到服务器控制台。 

SVR-ERROR: Expected JMSException, received com.ibm.mq.connector.outbound.MQQueueProxy cannot be cast to com.ibm.mq.jms.MQDestination
Copy to Clipboard Toggle word wrap

这是因为队列或主题查找中使用的 JNDI 名称为 com.ibm.mq.connector.outbound.MQQueueProxy/MQTopicProxy。

✔

✔

JBEAP-14643

JMSProducer 接口上的 setDeliveryDelay(expDeliveryDelay) 方法不会更改设置。调用此方法后，它将保留为 0 的默认设置。

✔

✔

JBEAP-14670

如果在 UserTransaction.begin（） 之前创建的 QueueSession 上完成了工作，则该工作不被视为事务的一部分。这意味着，任何使用此会话发送到队列的消息都不是由 UserTransaction.commit（）提交，在 UserTransaction.rollback（） 之后，消息仍会保留在队列中。

✔

✔

JBEAP-14675

如果您关闭了连接，然后立即创建具有相同 clientID 的 JMSContext，IBM MQ 资源适配器有时会将以下错误记录到服务器控制台。 

ERROR [io.undertow.request] (default task-1) UT005023: Exception handling request to /jmsServlet-1.0-SNAPSHOT/: com.ibm.msg.client.jms.DetailedJMSRuntimeException: MQJCA0002: An exception occurred in the IBM MQ layer. See the linked exception for details.
A call to IBM MQ classes for Java(tm) caused an exception to be thrown.
Copy to Clipboard Toggle word wrap

当与同一 clientID 连接关闭后创建新的 JMSContext 时，不会出现此问题。

✔

✔

JBEAP-15535

如果有状态会话 Bean 尝试在容器管理事务(CMT)中同时发送消息到主题，则发送的消息会失败并显示以下消息： 

SVR-ERROR: com.ibm.msg.client.jms.DetailedJMSException: JMSWMQ2007: Failed to send a message to destination 'MDB_NAME TOPIC_NAME'
Copy to Clipboard Toggle word wrap

堆栈追踪显示它是由以下异常导致的： 

com.ibm.mq.MQException: JMSCMQ0001: IBM MQ call failed with compcode '2' ('MQCC_FAILED') reason '2072' ('MQRC_SYNCPOINT_NOT_AVAILABLE')
Copy to Clipboard Toggle word wrap

✔

✔

JBEAP-20758

当您在 JBoss EAP 上部署 IBM MQ v9.0.0.4 资源适配器 wmq.jmsra.rar 时，服务器控制台中会出现以下错误消息： 

WARN  [org.jboss.as.connector.deployers.RADeployer] (MSC service thread 1-8) IJ020017: Invalid archive: file:/<path-to-jboss>/jboss-eap-7.3/standalone/tmp/vfs/temp/tempa02bdd5ee254e590/content-135e13d4f38704fc/contents/
Copy to Clipboard Toggle word wrap

IBM MQ v9.0.0.4 资源适配器已作为 JBoss EAP 7.3 的 Jakarta 消息传递提供商测试的一部分进行测试。您可以选择忽略此警告消息，或者您可以通过将 enabled 属性设置为 false 来禁用存档验证。例如： 

/subsystem=jca/archive-validation=archive-validation:write-attribute(name=enabled, value=false)
Copy to Clipboard Toggle word wrap

✔

✔

返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2025 Red Hat