インバウンド・メッセージを消費するためのMDBの構成

WebLogic宛先からのメッセージを非同期に消費するためのMDBを必要とするアプリケーションでは、JMSリソース・アダプタのインバウンド実装を使用します。MDBの動作は、アプリケーションをデプロイする前に、次のファイルのプロパティ値を構成することによって決定されます。

ra.xmlファイルでのinbound-resourceadapterプロパティの構成

次の各項では、ra.xmlファイルでインバウンド構成のinbound-resourceadapterプロパティを定義する方法について説明します。

必須のactivation-configプロパティ

必須のinbound-resourceadapterプロパティは、WebLogic JMSリソース・アダプタのra.xmlファイルで指定されます。このファイルは、使用中のWebLogic ServerインストールのWL_HOME\server\libディレクトリにあります。

指定する必要があるJMSのプロパティには、次のものがあります。

ConnectionFactory
destination
destinationType

ConnectionFactory、destinationおよびdestinationTypeプロパティの値は、ejb-jar.xmlファイルのactivation-configプロパティとして定義されます。また、ejb-jar.xmlで構成されたJNDI名は、connection-definitionおよびadminobject要素のJMSリソース・アダプタ値に割り当てられたJNDI名にマッピングする必要があります。

次のトピックも参照してください。

オプションのactivation-configプロパティ

JMSリソース・アダプタでは、その他多数のactivation-configプロパティがサポートされています。

ejb-jar.xmlファイルでのactivation-configプロパティの構成およびJMSリソース・アダプタのインバウンド・プロパティを参照してください。

inbound-resourceadapterの構成例

次のコード例は、inbound-resourceadapter構成を示しています。

. . .
<inbound-resourceadapter>
      <messageadapter>
        <messagelistener>
          <messagelistener-type>
            javax.jms.MessageListener
          </messagelistener-type>
          <activationspec>
            <activationspec-class>
              weblogic.jms.ra.ActivationSpecImpl
            </activationspec-class>
            <required-config-property>
              <config-property-name>ConnectionFactory</config-property-name>
            </required-config-property>
            <required-config-property>
              <config-property-name>Destination</config-property-name>
            </required-config-property>
            <required-config-property>
              <config-property-name>DestinationType</config-property-name>
            </required-config-property>
          </activationspec>
        </messagelistener>
      </messageadapter>
</inbound-resourceadapter>
. . .

ejb-jar.xmlファイルでのactivation-configプロパティの構成

次の各項では、ejb-jar.xmlファイルでactivation-configプロパティを構成する方法について説明します。

ejb-jar.xmlファイルと注釈

ejb-jar.xmlの要素については、http://java.sun.com/xml/ns/javaee/ejb-jar_3_0.xsdでスキーマを参照してください。

ejb-jar.xmlはEJB 3.0の時点でオプションです。注釈を使用すると、ディスクリプタ要素のかわりにメタデータを宣言できます。

EJB 3.2に準拠したMDBをプログラムおよび実装する方法は、Oracle WebLogic ServerメッセージドリブンBeanの開発のEJB 3.2に準拠したMDBの使用を参照してください。

ejb-jar.xmlファイルでの必須のactivation-configプロパティの構成

ra.xmlファイルのinbound-resourceadapterのすべてのrequired-config-propertyプロパティに、activation-config-propertyプロパティを構成する必要があります。

一般的な必須のJMSプロパティには次のものがあります。

ConnectionFactory: JMSコネクタの接続ファクトリのJNDIロケーション。
destination: JMSコネクタの宛先のJNDIロケーション。
destinationType: 次のいずれかのタイプになります。
- javax.jms.Topic
- javax.jms.Queue
- javax.jms.Destination

また、MDBアプリケーションがオプションのactivation-configプロパティを使用している場合は、外部アプリケーション・サーバーで、これらのオプションのactivation-configプロパティがra.xmlファイルにrequired-config-property要素として定義されている必要がある場合があります。

詳細は、アプリケーション・サーバーのベンダーが提供するドキュメントで確認してください。

キューの構成例

次の例は、キューの構成のactivation-configプロパティを示しています。この例では、MDBは、JNDI名wljmsra/xacfを持つ接続ファクトリからの接続を使用して、JNDI名wljmsra/queueを持つキューからメッセージをデキューします。

. . .
<activation-config-property>
  <activation-config-property-name>
    ConnectionFactory
  </activation-config-property-name>
  <activation-config-property-value>
    wljmsra/xacf
  </activation-config-property-value>
</activation-config-property>
<activation-config-property>
  <activation-config-property-name>
    Destination
  </activation-config-property-name>
  <activation-config-property-value>
    wljmsra/queue
  </activation-config-property-value>
</activation-config-property>
<activation-config-property>
  <activation-config-property-name>
    DestinationType
  </activation-config-property-name>
  <activation-config-property-value>
    javax.jms.Queue
  </activation-config-property-value>
</activation-config-property>
. . .

トピックの構成例

次の例は、トピックの構成のactivation-configプロパティを示しています。この例では、MDBは、JNDI名wljmsra/txacf1を持つ接続ファクトリからの接続を使用して、JNDI名wljmsra/pdtopic1を持つトピックからメッセージをデキューします。

. . .
<activation-config-property>
  <activation-config-property-name>
    ConnectionFactory
  </activation-config-property-name>
  <activation-config-property-value>
    wljmsra/txacf1
  </activation-config-property-value>
</activation-config-property>
<activation-config-property>
  <activation-config-property-name>
    Destination
  </activation-config-property-name>
  <activation-config-property-value>
    wljmsra/pdtopic1
  </activation-config-property-value>
</activation-config-property>
<activation-config-property>
  <activation-config-property-name>
    DestinationType
  </activation-config-property-name>
  <activation-config-property-value>
    javax.jms.Topic
  </activation-config-property-value>
</activation-config-property>
. . .

ejb-jar.xmlファイルでのオプションのactivation-configプロパティの構成

使用環境に合った適切なMDB動作を取得するのに必要な追加プロパティを構成します。詳細は、JMSリソース・アダプタ・インバウンド・プロパティを参照してください。

JMSリソース・アダプタactivation-configプロパティを含むejb-jar.xmlファイルの例

次の例は、JMSリソース・アダプタactivation-configプロパティを含むejb-jar.xmlファイルを示しています。

<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar xmlns="http://java.sun.com/xml/ns/javaee">
    <display-name>WebLogic RA Demo</display-name>
    <enterprise-beans>
        <message-driven>
            <display-name>My queue MDB</display-name>
            <ejb-name>queueMDB</ejb-name>
            <ejb-class>jms.ra.DisQueueMDB</ejb-class>
            <messaging-type>javax.jms.MessageListener</messaging-type>
            <transaction-type>Container</transaction-type>
            <activation-config>
                <activation-config-property>
                    <activation-config-property-name>
                            ConnectionFactory
                    </activation-config-property-name>
                    <activation-config-property-value>
                            java:sample/factory
                    </activation-config-property-value>
                </activation-config-property>
                <activation-config-property>
                    <activation-config-property-name>
                            Destination
                    </activation-config-property-name>
                    <activation-config-property-value>
                            java:sample/destination/queue
                    </activation-config-property-value>
                </activation-config-property>
                <activation-config-property>
                    <activation-config-property-name>
                            DestinationType
                    </activation-config-property-name>
                    <activation-config-property-value>
                            javax.jms.Queue
                    </activation-config-property-value>
                </activation-config-property>
                <activation-config-property>
                    <activation-config-property-name>UserName</activation-config-property-name>
                    <activation-config-property-value></activation-config-property-value>                </activation-config-property>
                <activation-config-property>
                    <activation-config-property-name>Password</activation-config-property-name>
                    <activation-config-property-value></activation-config-property-value>
                </activation-config-property>
                <activation-config-property>
                    <activation-config-property-name>ClientId</activation-config-property-name>
                    <activation-config-property-value>queueMDB</activation-config-property-value>
                </activation-config-property>
                <activation-config-property>
                    <activation-config-property-name>MessageSelector</activation-config-property-name>
                    <activation-config-property-value></activation-config-property-value>
                </activation-config-property>
            </activation-config>
        </message-driven>
       . . .           
      </message-driven>
    </enterprise-beans>
   . . .
</ejb-jar>

その他のejb-xml.jarファイルの例については、JMSリソース・アダプタの例に説明されているWebLogic Server環境のJMSリソース・アダプタのサンプル・アプリケーション例を確認してください。

スレッド管理

JMSリソース・アダプタでは、インバウンド・メッセージを消費するMDBによって使用される宛先のスレッドを管理するために、次のプロパティを提供しています。

minListenerThreads: 個々の物理宛先に対して作成されるリスナー・スレッドの最小数。
maxTotalListenerThreads: 宛先に使用できるリスナー・スレッドの最大数。
maxListenerThreads: 宛先内の個々の物理宛先に対して作成されるリスナー・スレッドの最大数。

物理宛先の最大スレッドの設定

宛先に対して最大数のスレッド(maxListenerThreads)を構成する場合、次に注意してください。

キュー: 2つ以上のスレッドを使用すると、メッセージが消費される速度の向上に役立つ場合があります。
トピック: この値は常に1に設定する必要があります。各リスナー・スレッドは、独自のセッションとTopicSubscriberを取得します。
- 恒久サブスクライバ: 同じサブスクリプション名のサブスクライバを複数持てない場合があります。
- 非恒久サブスクライバ: この値は常に1に設定する必要があります。スレッドを増加すると、サブスクライバが増加し、処理する各メッセージのコピーが過剰になります。

分散宛先の最大スレッドの設定

maxTotalListenerThreadsプロパティを使用すると、分散宛先のスレッドの追加処理を制限または指定できます。

maxTotalListenerThreadsの値が関連付けられている分散宛先内の物理宛先の数より小さい場合、JMSリソース・アダプタは、分散宛先内の物理宛先の数と同じ値を使用し、警告メッセージを記録します。
外部アプリケーション・サーバーが分散宛先内の物理宛先の数以上のスレッドを指定できない場合、JMSリソース・アダプタは警告メッセージを記録します。
JMSリソース・アダプタでは、スレッドを割り当てるための公平性ポリシーを実装しているので、maxListenerThreadsより小さい数が現在設定され、より多くのスレッドを必要としている個々の物理宛先は、同じ分散宛先内の他の物理宛先(少なくともさらに2つ多いスレッドを持つ)からスレッドを再割当てできます。この公平性ポリシーは、外部アプリケーション・サーバーのWorkManagerインスタンス(JMSリソース・アダプタによるmaxTotalListenerThreadsでの新規スレッドの追加リクエストを許可しない)からは独立しています。

スレッド不足の決定および既存のスレッドの転送の両方が、メッセージの処理中(onMessageのコール中)に行われるため、ある宛先から別の宛先へのスレッドの再割当てのプロセスには時間がかかります。2つのスレッドが含まれているため、転送プロセスは2つ分のonMessage処理時間がかかります。

例外キューの使用

JMSリソース・アダプタを使用すると、インバウンド通信の例外キューを構成して、インバウンドMDBキューのポイズン・メッセージを処理できます。UseExceptionQueueプロパティが有効になっている場合、他の場合には破棄されてしまうメッセージが例外キューに送信されます。メッセージは通常、maxDeliveryCount値を超えた場合に、例外キューに送信されます。詳細は、maxDeliveryCountを参照してください。

メッセージは、次のルールを使用して例外キューへ処理されます。

メッセージは、例外キューに直接設定されません。
同じタイプの新しいメッセージが作成されます。
- 元のメッセージのプロパティおよびボディが新しいメッセージにコピーされます。
  
  リソース・プロバイダによって元のヘッダーがオーバーライドされないようにするために、それぞれがGJRA_CopyOfJMS{Header}プロパティにコピーされます。javax.jms.Destinationは有効なプロパティ・タイプではないため、各宛先ヘッダーは説明メッセージに変換されます。JMSX*のプロパティ(たとえばJMSXDeliveryCount)は変換されないことに注意してください。
  
  注意:
  コピー・プロセスの一部が失敗した場合、次のルールを使用して処理は続行されます。Bytes、MapおよびStreamメッセージ・タイプでは、メッセージ・ボディの一部のみがコピーされることになる場合があります。
- コピー・プロセスが成功したら、値trueが設定されたブール・プロパティGJRA_CopySuccessfulが追加されます。
- メッセージが配信されなかった理由を説明した文字列プロパティGJRA_DeliveryFailureReasonが追加されます。
- 配信障害の直前にMDBのonMessageメソッドが例外を生成する場合、例外情報を含む文字列プロパティGJRA_onMessageExceptionsが追加されます。
元のメッセージのコピーが例外キューに送信されます。

注意:
例外キューへの元のメッセージのコピーの送信は、1回のみ試行されます。この試行に失敗すると、メッセージは例外キューに配置されることなく破棄されます。詳細は、includeBodiesInExceptionQueueを参照してください。

プライマリ宛先に使用される接続ファクトリは、例外キューに対しても使用されます。(Destinationプロパティで指定された)プライマリ宛先がトピックの場合、接続ファクトリはキューとトピックの両方をサポートしている必要があります。たとえば、<connectionfactory-interface>要素はjavax.jms.ConnectionFactoryまたはjavax.jms.XAConnectionFactoryのいずれかである必要があります。

ユーザー名とパスワードのプロパティの設定

ユーザー名とパスワードのプロパティを使用すると、リソース・プロバイダに認証パラメータを渡せます。これらのプロパティのどちらも設定されていない場合、このMDBのインバウンド・メッセージ処理に使用される接続が、引数なしのcreateConnectionメソッドを使用して作成されます。これらのいずれかまたは両方が設定されている場合、userNameまたはpasswordプロパティ、あるいはその両方が、ユーザー名とパスワードの引数としてcreateConnectionメソッドに渡されます。これらのいずれか1つのみが設定されている場合、createConnection引数リストのそのプロパティ値にかわってnullが使用されます。