5 メッセージの消費の理解

次の各項では、外部アプリケーション・サーバーでWebLogic JMSメッセージをインバウンド・メッセージとして非同期に消費するためのメッセージドリブンBean (MDB)を構成するように、JMSリソース・アダプタのra.xmlファイルを構成する方法について説明します。

インバウンド・メッセージを消費するための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が使用されます。

詳細なWebLogic JMSリソースの構成

次の各項では、インバウンド・メッセージに対して詳細なメッセージ処理を構成する方法について説明します。

JMSリソース・アダプタと共有可能なサブスクリプション

JMSリソース・アダプタは、インバウンド・メッセージの処理時に、構成済の接続ファクトリの設定をオーバーライドしてSHARABLEサブスクリプション共有ポリシーとUNRESTRICTEDクライアントIDポリシーを使用します。JMSリソース・アダプタのMDBはサブスクリプション名を生成しないため、恒久サブスクリプションにはsubscriptionNameを指定する必要があります。サブスクリプションは、恒久または非恒久の場合に、次のように共有されます。

恒久: 同じ分散トピック上のコンシューマは、同じclientID、メッセージ・セレクタおよびsubscriptionNameを持つ場合にのみ、恒久サブスクリプションを共有できます。
非恒久: 同じ分散トピック上のコンシューマは、同じclientIDとmessageSelectorを持つ場合にのみ、非恒久サブスクリプションを共有できます。

MDBが着信メッセージを消費していることを確認するために、常にclientIdを構成します。たとえば、次のように構成します。

. . .
<activation-config>
  <activation-config-property>
    
<activation-config-property-name>clientId</activation-config-property-name>
    <activation-config-property-value>myMDB</activation-config-property-value>
  </activation-config-property>
</activation-config> 
. . .

『Oracle WebLogic Server JMSリソースの管理』の共有サブスクリプションの構成に関する項を参照してください。

順序付けメッセージ処理の使用

アプリケーションでサブスクリプション・メッセージの単一スレッド式処理が必要な場合は、WebLogic JMSの順序単位(UOO)処理を使用するようアプリケーションを構成する必要があります。

『Oracle WebLogic Server JMSアプリケーションの開発』のメッセージ順序単位の使用に関する項を参照してください。

分散トピックから消費する場合の設計戦略

次の項では、分散トピックを使用して高可用性アプリケーションを開発する際に使用できる設計戦略について説明します。

レプリケートされた分散トピックとパーティション化された分散トピック

レプリケートされた分散トピックとパーティション化された分散トピック

レプリケートされた分散トピックとパーティション化された分散トピックは、インバウンド・メッセージの消費で次のようにサポートされています。

レプリケートされた分散トピック: すべての物理トピック・メンバーが送信された各メッセージを受信します。メッセージが物理的なトピック・メンバーのいずれかに着信すると、メッセージのコピーが内部で自動的に他のトピック・メンバーに転送されます。
パーティション化された分散トピック: メッセージを受信する分散トピック・メンバーは、メッセージを認識するメンバーのみです。メッセージは他のメンバーには転送されず、他のメンバーのサブスクライバはメッセージのコピーを受信しません。着信メッセージは、JMS AffinityおよびLoad Balance属性を使用して、分散トピック・メンバー間でロード・バランシングできます。詳細は、『Oracle WebLogic Server JMSリソースの管理』のパーティション化された分散トピックのロード・バランシングに関する項を参照してください。

分散トピックのOne-Copy-Per-Application設計戦略

One-Copy-Per-Applicationは、使用可能なデフォルトの設計パターンで、次の特徴があります。

各アプリケーションが全体として(つまり、アプリケーションのすべてのインスタンスをあわせて)、分散トピックにパブリッシュされる各メッセージのコピーを1つ取得します。つまり、各インスタンスは分散トピックに送信されるメッセージのサブセットのみを取得します。

クライアントIDポリシーはUNRESTRICTEDです。
サブスクリプション共有ポリシーはSHARABLEです。
サブスクライバが恒久の場合は、同じサブスクリプション名を使用します。
すべてのコンシューマが同じトピック・インスタンス(または分散トピックのメンバー)にサブスクライブします。

One-Copy-Per-Applicationの実装

One-Copy-Per-Application設計戦略を実装するには、activation-config要素にTopicMessageDistributionMode=One-Copy-Per-Applicationの値を持つ、ProviderPropertiesプロパティをEJBで指定する必要があります。

「One-Copy-Per-ApplicationのEJB構成の例」を参照してください。

注意:

TopicMessageDistributionMode=One-Copy-Per-Serverを指定しない場合は、JMSリソース・アダプタではメッセージの重複を避けるために、デフォルトでTopicMessageDistributionMode=One-Copy-Per-Applicationに設定されます。

One-Copy-Per-ApplicationのEJB構成の例

ejb-jar.xmlファイルからの次のコード・スニペットは、One-Copy-Per-Applicationメッセージ処理を実装しています。

. . .
<mdb-resource-adapter>
  <resource-adapter-mid>wljmsra</resource-adapter-mid>
    <activation-config>
      <activation-config-property>
        <activation-config-property-name>ClientId</activation-config-property-name>
        <activation-config-property-value>RDT2MDB</activation-config-property-value>
      </activation-config-property>
      <activation-config-property>
        <activation-config-property-name>ProviderProperties</activation-config-property-name>
        <activation-config-property-value>TopicMessageDistributionMode=One-Copy-Per-Application</activation-config-property-value>
      </activation-config-property>
    </activation-config>
</mdb-resource-adapter>
 
<!-- Mapping a Queue admin-object to the Resource-Adapter name -->
  <resource-env-ref>
    <resource-env-ref-name>jms/ResultTopic</resource-env-ref-name>
    <jndi-name>wljmsra/rtopic1</jndi-name>
  </resource-env-ref>
 
<!-- Mapping a Connection Factory to the Resource-Adapter name -->
  <resource-ref>
    <res-ref-name>jms/ResultXACFFactory</res-ref-name>
    <jndi-name>wljmsra/xacf</jndi-name>
  </resource-ref>
. . .

分散トピックのOne-Copy-Per-Server設計戦略

One-Copy-Per-Serverは、アプリケーションの各インスタンスが、トピックにパブリッシュされた各メッセージのコピーを1つ受信する設計パターンです。

One-Copy-Per-Serverの実装

One-Copy-Per-Server設計戦略を実装するには、次のことを行う必要があります。

外部サーバー・インスタンスの起動時に、weblogic.jms.ra.providers.wl.ServerIDプロパティを指定します。たとえば、-Dweblogic.jms.ra.providers.wl.ServerID=aUniqueIdForTheServerのように指定します。

上のプロパティ仕様で、aUniqueIdForTheServerは外部サーバーの一意の識別子を表します。

Oracle Glassfishの場合、asadminコマンドを使用して、次のようにこのプロパティを構成できます。

asadmin> create-jvm-options --user myUsername --password myPassword --host localhost --port 4848 -Dweblogic.jms.ra.providers.wl.ServerID="aUniqueIdForTheServer"
activation-config要素にTopicMessageDistributionMode=One-Copy-Per-Serverの値を持つ、ProviderPropertiesプロパティをEJBで指定します。「One-Copy-Per-ApplicationのEJB構成の例」を参照してください。

One-Copy-Per-Serverの例

ejb-jar.xmlファイルからの次のコード・スニペットは、One-Copy-Per-Serverメッセージ処理を実装しています。

. . .
<mdb-resource-adapter>
  <resource-adapter-mid>wljmsra</resource-adapter-mid>
    <activation-config>
      <activation-config-property>
        <activation-config-property-name>ClientId</activation-config-property-name>
        <activation-config-property-value>RDTMDB</activation-config-property-value>
      </activation-config-property>
      <activation-config-property>
        <activation-config-property-name>ProviderProperties</activation-config-property-name>
        <activation-config-property-value>TopicMessageDistributionMode=One-Copy-Per-Server</activation-config-property-value>
      </activation-config-property>
    </activation-config>
</mdb-resource-adapter>
<!-- Mapping a Queue admin-object to the Resource-Adapter name -->
  <resource-env-ref>
    <resource-env-ref-name>jms/ResultTopic</resource-env-ref-name>
    <jndi-name>wljmsra/rtopic1</jndi-name>
  </resource-env-ref>
<!-- Mapping a Connection Factory to the Resource-Adapter name -->
  <resource-ref>
    <res-ref-name>jms/ResultXACFFactory</res-ref-name>
    <jndi-name>wljmsra/xacf</jndi-name>
  </resource-ref>
. . .

スタンドアロン(非分散)トピックからの消費

MDBアプリケーションをホストする各外部アプリケーション・サーバー・インスタンスでは、トピックが同じクラスタ内または異なるクラスタ内のどちらで実行されているかに関係なく、トピックに対してMDBプールが作成されます。N個のノードのMDBクラスタでは、N個のMDBプールが作成されます。各MDBプールはトピック上に個別のサブスクリプションを作成し、異なるMDBプールからのサブスクライバは同じサブスクリプションを共有しません。

詳細は、「One-Copy-Per-Serverの実装」を参照してください。

インバウンド通信のベスト・プラクティス

インバウンド通信用のJMSリソース・アダプタを構成するために次に示したチューニングの推奨事項およびベスト・プラクティスに注意してください。

JMSリソース・アダプタで分散宛先メンバーより多いスレッドが割り当てられていることを確認します。
トピックの使用時には、常にclientIDを構成します。JMSリソース・アダプタは、インバウンド・メッセージの処理時に、恒久サブスクライバまたは非恒久サブスクライバに対して構成されたclientIdを必要とする、SHARABLEサブスクリプション共有ポリシーを使用します。

clientIDが設定されていない場合、MDBは、外部アプリケーション・サーバー・ログに記録されたメッセージおよびエラー条件を受信しません。

「JMSリソース・アダプタと共有可能なサブスクリプション」を参照してください。
キューの場合、maxListenerThreadsの値を2つ以上のスレッドに増やすと、メッセージが消費される速度が向上する可能性があります。
JMSリソース・アダプタでは、共有可能な接続はサポートされていません。アプリケーションのデプロイメント・ディスクリプタ・ファイル(web.xmlおよびejb-jar.xml)の<resource-ref>要素を使用して、そのアプリケーションでルックアップして使用されるJMS接続ファクトリを識別する場合、<res-sharing-scope>子要素をunsharableに設定する必要があります。この要素のデフォルト値はsharableです。

たとえば、次のように構成します。
```
. . .
<resource-ref>
   <res-ref-name>jms/ReplyFactory</res-ref-name>
   <res-type>javax.jms.ConnectionFactory</res-type>
   <res-auth>Application</res-auth>
   <res-sharing-scope>unsharable</res-sharing-scope>
</resource-ref>
```
アプリケーションで@Resourceインジェクションが使用されている場合は、http://docs.oracle.com/javaee/7/api/javax/annotation/Resource.html#shareable--を参照してください。