31.6. IBM MQ リソースアダプターのデプロイ

IBM MQ について

IBM MQ は、IBM のメッセージ指向ミドルウェア (MOM) 製品で、分散システム上のアプリケーションが互いに通信できるようにします。これは、メッセージとメッセージキューを使用して実行できます。IBM MQ は、メッセージキューにメッセージを配信し、メッセージチャネルを使用してデータを他のキューマネージャーへ転送します。IBM MQ の詳細は、IBM の製品 Web サイトの「IBM MQ」を参照してください。

概要

IBM MQ は、JBoss EAP 7.3 の外部 JMS プロバイダーとして設定できます。このセクションでは、JBoss EAP で IBM MQ リソースアダプターをデプロイして設定する手順を説明します。このデプロイメントと設定は、管理 CLI ツールまたは Web ベースの管理コンソールを使用して実行できます。IBM MQ のサポートされる設定に関する最新情報は、「JBoss EAP supported configurations」を参照してください。

注記

設定の変更を有効にするには、IBM MQ リソースアダプターの設定後にシステムを再起動する必要があります。

前提条件

作業を開始する前に、IBM MQ リソースアダプターのバージョンを検証し、その設定プロパティーを理解する必要があります。

  • IBM MQ リソースアダプターは、wmq.jmsra.rar というリソースアーカイブ (RAR) ファイルとして提供されます。wmq.jmsra.rar ファイルは、/opt/mqm/java/lib/jca/wmq.jmsra.rar から取得できます。JBoss EAP の各リリースでサポートされる特定のバージョンに関する詳細は、「JBoss EAP supported configurations」を参照してください。
  • 以下の 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)

    transaction-support 要素が XATransaction に設定されたことに注意してください。トランザクションを使用する場合は、以下の例にあるように、XA リカバリーデータソースのセキュリティードメインを提供してください。

    /subsystem=resource-adapters/resource-adapter=test/connection-definitions=test:write-attribute(name=recovery-security-domain,value=myDomain)

    XA リカバリーに関する詳細は、『JBoss EAP 設定ガイド』の「XA リカバリーの設定」を参照してください。

    トランザクション以外のデプロイメントの場合は、transaction-support の値を NoTransaction に変更します。

    /subsystem=resource-adapters/resource-adapter=wmq.jmsra.rar:add(archive=wmq.jmsra.rar, transaction-support=NoTransaction)
  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)
    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)
    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)
  4. JBoss EAP の EJB3 メッセージングシステムでデフォルトのプロバイダーを JBoss EAP 7 メッセージングから IBM MQ に変更する場合は、以下のように管理 CLI を使用して ejb3 サブシステムを変更します。

    /subsystem=ejb3:write-attribute(name=default-resource-adapter-name,value=wmq.jmsra.rar)
  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 {
    }

    @ResourceAdapter 値の VERSION は、RAR の名前に含まれる実際のバージョンに置き換えてください。

  6. リソースアダプターをアクティベートします。

    /subsystem=resource-adapters/resource-adapter=wmq.jmsra.rar:activate()

31.6.1. IBM MQ リソースアダプターの制限と既知の問題

以下の表に、IBM MQ リソースアダプターの既知の問題をまとめています。バージョン列のチェックマーク () は、そのバージョンのリソースアダプターに問題があることを示しています。

表31.1 IBM MQ リソースアダプターの既知の問題

JIRA問題の説明IBM MQ 8IBM MQ 9

JBEAP-503

IBM MQ リソースアダプターは、Queue.toString() メソッドと QueueBrowser.getQueue().toString() メソッドに異なる文字列の値を返します。Queuecom.ibm.mq.connector.outbound.MQQueueProxy クラスのインスタンスで、QueueBrowser.htmlQueueBrowser.getQueue() メソッドから返される com.ibm.mq.jms.MQQueue クラスとは異なります。これらのクラスには、toString() メソッドの異なる実装が含まれます。これらの toString() メソッドを使用して同じ値を返すことができないことに注意してください。

JBEAP-511JBEAP-550JBEAP-3686

以下の制限は、IBM MQ のメッセージプロパティー名に適用されます。

  • デプロイメント記述子の activation-config セクションでは、_&| などの特殊文字を使用して destinationName プロパティーを設定しないでください。これらの文字を使用すると、MDB デプロイメントは com.ibm.msg.client.jms.DetailedInvalidDestinationException 例外で失敗します。
  • デプロイメント記述子の activation-config セクションで、java:/ 接頭辞を使用して destinationName プロパティーを設定しないでください。この接頭辞を使用すると、MDB デプロイメントは com.ibm.msg.client.jms.DetailedInvalidDestinationException 例外で失敗します。
  • IBM MQ JMS クラスで使用するために予約されているため、プロパティーを「JMS」または「usr.JMS」で開始してはいけません。例外は、IBM Knowledge Center の Web サイトに記載されています。

リソースアダプターの各バージョンに対するメッセージプロパティー名の制限の完全なリストは、IBM Knowledge Center の Web サイトの「IBM MQバージョン 8.0 のプロパティー名の制限」と「IBM MQバージョン 9.0 のプロパティー名の制限」を参照してください。

JBEAP-549

@ActivationConfigProperty アノテーションを使用して MDB の destination プロパティー名の値を指定するときは、すべて大文字を使用する必要があります。例を以下に示します。

@ActivationConfigProperty(propertyName = "destination", propertyValue = "QUEUE")

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>"
    }
)

JBEAP-2339

IBM MQ リソースアダプターは、接続開始前からキューとトピックからメッセージを読み取ることができます。これは、接続開始前にコンシューマーがメッセージを消費できることを意味します。この問題を回避するには、external-context を使用してリモート IBM MQ ブローカーが作成した接続ファクトリーを使用し、IBM MQ リソースアダプターが作成した接続ファクトリーは使用しないでください。

JBEAP-3685

<transaction-support>XATransaction</transaction-support> が設定されると、インジェクションを使用して作成されたか、手動で作成されたかに関係なく、JMSContext は常に JMSContext.SESSION_TRANSACTED です。

以下のコード例では、@JMSSessionMode(JMSContext.DUPS_OK_ACKNOWLEDGE) は無視され、JMSContextJMSContext.SESSION_TRANSACTED のままになります。

@Inject
@JMSConnectionFactory("jms/CF")
@JMSPasswordCredential(userName="myusername", password="mypassword")
@JMSSessionMode(JMSContext.DUPS_OK_ACKNOWLEDGE)
transient JMSContext context3;

JBEAP-14633

JMS 仕様によると、QueueSession インターフェースを使用してパブリッシュ/サブスクライブドメインに固有のオブジェクトを作成することはできず、Session から継承する特定のメソッドは、javax.jms.IllegalStateException をスローする必要があります。このようなメソッドの 1 つが、QueueSession.createTemporaryTopic() です。javax.jms.IllegalStateException をスローする代わりに、IBM MQ リソースアダプターは java.lang.NullPointerException をスローします。

JBEAP-14634

MQTopicProxy.getTopicName() は、IBM MQ ブローカーによって設定されていたものとは異なるトピック名を返します。たとえば、トピック名が topic://MYTOPIC?XMSC_WMQ_BROKER_PUBQ_QMGR=QM に設定された場合、MQTopicProxytopic://MYTOPIC を返します。

JBEAP-14636

JMSContext のデフォルトの autoStart 設定は false です。これは、JMSContext が使用するベースとなる接続が、コンシューマーの作成時に自動的に開始されないことを意味します。この設定はデフォルトの true にする必要があります。

JBEAP-14640

無効な認証情報が使用されると、IBM MQ リソースアダプターは、JMSSecurityException ではなく DetailedJMSException をスローし、以下のエラーをサーバーコンソールに記録します。

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.

以下は、この問題を引き起こす可能性があるコードの例です。

QueueConnection qc = queueConnectionFactory.createQueueConnection("invalidUserName", "invalidPassword");

JBEAP-14642

MQMessageProducer.send(Destination destination, Message message) メソッドと MQMessageProducer.send(Destination destination, Message message, int deliveryMode, int priority, long 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

これは、キューまたはトピックルックアップで使用される 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

接続を閉じた直後に、同じ clientIDJMSContext を作成すると、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.

この問題は、同じ clientID の接続が閉じられた後に新しい JMSContext の作成で遅延がある場合は発生しません。

JBEAP-15535

コンテナー管理トランザクション (CMT) において、ステートフルセッション Bean がトピックにメッセージを送信しようとすると、メッセージ送信が失敗し、以下のメッセージが示されます。

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

スタックトレースは、以下の例外によって発生したことを示しています。

com.ibm.mq.MQException: JMSCMQ0001: IBM MQ call failed with compcode '2' ('MQCC_FAILED') reason '2072' ('MQRC_SYNCPOINT_NOT_AVAILABLE')

JBEAP-20758

IBM MQ v9.0.0.4 リソースアダプターをデプロイすると、JBoss EAP に 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/

IBM MQ v9.0.0.4 リソースアダプターは、JBoss EAP 7.3 の Jakarta Messaging プロバイダーテストの一部としてテストされています。この警告メッセージを無視するか、enabled 属性を false に設定するとアーカイブ検証を無効にできます。例を以下に示します。

/subsystem=jca/archive-validation=archive-validation:write-attribute(name=enabled, value=false)