1. Oracle WebLogic Serverのスタンドアロン・クライアントの開発
  2. JMS SAFクライアントによる確実なメッセージ送信

3 JMS SAFクライアントによる確実なメッセージ送信

JMS SAFクライアントを構成および使用してスタンドアロンのJMSクライアントからサーバー側のJMS宛先にJMSメッセージを確実に送信する方法を学習します。

この章の内容は次のとおりです。

  • JMSクライアントでのストア・アンド・フォワードの使い方の概要
    JMS SAFクライアントは、JMSストア・アンド・フォワード・サービスをスタンドアロンJMSクライアントに拡張したものです。JMSクライアントが宛先にアクセスできない場合(たとえば、一時的なネットワーク接続障害のため)でも、JMSクライアントはサーバー側のJMS宛先にメッセージを確実に送信できます。サーバーとの接続が切断されている間、JMS SAFクライアントによって送信されたメッセージはクライアントのファイル・システム上でローカルに格納され、クライアントが再接続したら、サーバー側のJMS宛先に転送されます。
  • クライアント側のSAFを使用するためのJMSクライアントの構成
    サーバー側では構成を行う必要がありませんが、クライアント側では各クライアントで構成を行う必要があります。クライアント側のSAFを使用するためのJMSクライアントの構成方法を学習します。
  • JMS SAFクライアント管理ツール
    JMS SAFクライアント実装で使用できるJMS SAFクライアント初期化APIおよびクライアント側ストア管理ユーティリティ機能について学習します。
  • JMS SAFクライアントでのJMSプログラミングの考慮事項
    JMS SAFクライアントを使用する場合のJMSプログラミングの考慮事項について学習します。
  • JMS SAFクライアントの相互運用のガイドライン
    相互運用のガイドラインは、JMS SAFクライアントを使用してサーバー側のWebLogic JMS宛先にメッセージを転送する場合に適用されます。
  • JMS SAFクライアントのチューニング
    JMS SAFクライアントでは、サーバー側のSAFサービスで使用可能なパラメータのチューニングを利用することができます。
  • JMS SAFクライアントの使用に関する制限
    JMS SAFクライアントの使用時にサポートされない機能および例外について学習します。
  • JMS SAFクライアントのメッセージ格納動作の変更
    Weblogic JMS SAFクライアントでは、メッセージはローカル記憶域に保持されてから、リモート宛先に転送されます。リモート宛先はそれぞれ、カーネル・キューと呼ばれるローカル記憶域ユニットに対応しています。Oracle WebLogic Server 10.3.3.0より前のリリースでは、JMS SAFクライアント・インスタンスを閉じて再度開くたびに、異なるカーネル・キューが使用されます。この動作は、1つの宛先に対して複数のカーネル・キューが対応する原因となっていました。

JMSクライアントでのストア・アンド・フォワードの使い方の概要

JMS SAFクライアントは、JMSストア・アンド・フォワード・サービスをスタンドアロンJMSクライアントに拡張したものです。JMSクライアントが宛先にアクセスできない場合(たとえば、一時的なネットワーク接続障害のため)でも、JMSクライアントはサーバー側のJMS宛先にメッセージを確実に送信できます。サーバーとの接続が切断されている間、JMS SAFクライアントによって送信されたメッセージはクライアントのファイル・システム上でローカルに格納され、クライアントが再接続したら、サーバー側のJMS宛先に転送されます。

JMS SAFクライアントは、次の2つの主要部分で構成されています。

  • JMS SAFクライアント実装。これは、メッセージをローカル・ファイル・システム上のクライアント側永続ストアに直接書き込みます。

  • SAFフォワーダ。これは、ストアに書き込まれたメッセージを取得し、WebLogic Serverインスタンスに送信します。

また、必要に応じてJMS SAFクライアントがSAFフォワーダ・メカニズムを使用するかしないかを設定できる、オプションのClientSAF初期化API (weblogic.jms.extensions)も用意されています。「JMS SAFクライアントの初期化API」を参照してください

ノート:

サーバー側WebLogic JMS SAFを使用して、利用できない可能性のある宛先にJMSメッセージを確実に送信する方法の詳細。『Oracle WebLogic Serverストア・アンド・フォワード・サービスの管理』のJMSメッセージに対するSAFの構成に関する項を参照してください。

親トピック: JMS SAFクライアントによる確実なメッセージ送信

クライアント側のSAFを使用するためのJMSクライアントの構成

サーバー側では構成を行う必要がありませんが、クライアント側では各クライアントで構成を行う必要があります。クライアント側のSAFを使用するためのJMSクライアントの構成方法を学習します。

以下の節では、クライアント側のSAFを使用するためのJMSクライアントの構成方法について説明します。

親トピック: JMS SAFクライアントによる確実なメッセージ送信

JMS SAFクライアントの構成ファイルの生成

各クライアント・マシンには、JMS SAFクライアントの構成ファイルが必要です。構成ファイルには、JMS SAFクライアント環境での処理に必要なサーバー側の接続ファクトリと宛先に関する情報を指定します。指定のJMSモジュールの構成ファイルからJMS SAFクライアントの構成ファイルを生成するには、インストールしたWebLogic Serverに付属しているClientSAFGenerateユーティリティを使用します。

ClientSAFGenerateユーティリティは、ソースJMSの構成ファイルに記述されているすべての接続ファクトリ、スタンドアロンの宛先、および分散宛先のエントリを作成します(「JMSモジュールからJMS SAFクライアントの構成ファイルを生成するためのステップ」を参照)。生成されたファイルには、「JMS SAFクライアントの初期JNDIプロバイダを使用できるようにJMSクライアント・アプリケーションの変更」で説明する初期JNDIコンテキストを通じてJMS SAFクライアントが直接対話する接続ファクトリとインポート済み宛先が定義されますただし、生成されたファイルには、外部のJMS宛先やサーバーサドのJMSモジュールのSAF宛先のエントリは含まれません。しかも、SAFエクスポート・ポリシーがAllに設定されたJMS宛先のみが、ファイルに追加されます(宛先のデフォルト設定)。

親トピック: クライアント側のSAFを使用するためのJMSクライアントの構成

JMS SAFクライアントの構成ファイルの仕組み

JMS SAFクライアントのXMLファイルは、JMSモジュールがWebLogic Server weblogic-jms.xsdスキーマに準拠し、ルート要素weblogic-client-jmsを持っています。weblogic-jms.xsdスキーマには、サーバー側のWebLogic SAF JMS機能に対応する最上位要素がいくつかあります。詳細については、「JMS SAFクライアントの構成での有効なSAF要素」を参照してください

ファイルの最上位要素には、JMS SAFクライアントが直接対話する接続ファクトリとインポート済み宛先の要素が記述されています。SAF送信エージェント、リモートSAFコンテキスト、およびSAFエラー処理の要素には、SAFフォワーダの機能が記述されています。永続ストアの要素は、JMS SAFクライアントAPIとSAFフォワーダの両方で使用されます。

JMSモジュールからJMS SAFクライアントの構成ファイルを生成するためのステップ

ClientSAFGenerateユーティリティを使用して、WebLogic ServerドメインのJMSモジュール構成ファイルからJMS SAFクライアントの構成ファイルを生成します。また、構成ファイルは既存のJMS SAFクライアントの構成ファイルから生成することもできます。詳細については、「ClientSAFGenerateユーティリティの構文」を参照してください

ノート:

クライアント・マシン上でClientSAFGenerateユーティリティを実行して、既存のJMS SAFクライアントの構成ファイルから構成ファイルを生成する場合、シンT3 JMSクライアントやJMS SAFクライアントではなく、CLASSPATH内のインストール・クライアント(weblogic.jar)を使用する必要があります。「クライアント・マシンへのJMS SAFクライアントのJARファイルのインストール」を参照してください

次のステップは、ClientSAFGenerateユーティリティを使用して、インストールしたWebLogic Serverに付属しているexamples-jms.xmlモジュール・ファイルからJMS SAFクライアントの構成ファイルを生成する方法を示しています。

  1. JMS SAFクライアントの構成ファイルのベースとして使用するJMSモジュール・ファイルが含まれる、WebLogic Serverドメインのディレクトリに移動します:

    $DOMAIN_HOME/domains/wl_server/config/jms

  2. Javaコマンドラインから、ClientSAFGenerateユーティリティを実行します: 

    > java weblogic.jms.extensions.ClientSAFGenerate -url http://10.61.6.138:7001 -username myusername -moduleFile examples-jms.xml -outputFile d:\temp\ClientSAF-jms.xml

    表3-1に、有効なClientSAFGenerateの引数を示します。

  3. SAFClient-jms.xmlという構成ファイルがカレント・ディレクトリに作成されます。以下に、その主な内容の例を示します。 

    <weblogic-client-jms xmlns="http://www.bea.com/ns/weblogic/100" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <connection-factory name="exampleTrader">
    <jndi-name>jms.connection.traderFactory</jndi-name>
    <transaction-params>
      <xa-connection-factory-enabled>false
      </xa-connection-factory-enabled>
    </transaction-params>
  </connection-factory>
  <saf-imported-destinations name="examples">
    <saf-queue name="exampleQueue">
      <remote-jndi-name>weblogic.examples.jms.exampleQueue
      </remote-jndi-name>
      <local-jndi-name>weblogic.examples.jms.exampleQueue
      </local-jndi-name>
    </saf-queue>
    <saf-topic name="quotes">
      <remote-jndi-name>quotes</remote-jndi-name>
      <local-jndi-name>quotes</local-jndi-name>
    </saf-topic>
  </saf-imported-destinations>
  <saf-remote-context name="RemoteContext0">
    <saf-login-context>
      <loginURL>t3://localhost:7001</loginURL>
      <username>weblogic</username>
    </saf-login-context>
  </saf-remote-context>
</weblogic-client-jms>

    ヒント:

    クラスタまたはドメインにデプロイされた他のJMSモジュールからリモートSAF接続ファクトリと宛先を追加するには、これらのJMSモジュールに対してClientSAFGenerateユーティリティを再実行します。その際、-outputFileパラメータに同じJMS SAF構成ファイル名を指定します。「ClientSAFGenerateユーティリティの構文」を参照してください

  4. 生成された構成ファイルには、SAFリモート・コンテキストがリモート・サーバーに接続する際に使用する暗号化されたパスワードが含まれていません。暗号化されたリモートSAFコンテキストのパスワードを作成して、構成ファイルに追加するには、「リモートJMS SAFコンテキストのパスワードの暗号化」の説明に従ってください

  5. 生成された構成ファイルを、JMS SAFクライアント・アプリケーションを実行するクライアント・マシンにコピーします。「クライアント・マシンへのJMS SAFクライアントのJARファイルのインストール」を参照してください

ノート:

デフォルトでは、JMSクライアントの現在の作業ディレクトリにClientSAF.xmlが作成されますが、「JMS SAFクライアントの初期JNDIプロバイダを使用できるようにJMSクライアント・アプリケーションの変更」の説明に従って、JMSクライアントに引数を渡すことによりファイル名を明示的に指定することもできます。

ClientSAFGenerateユーティリティの構文

weblogic.jms.extensions.ClientSAFGenerateユーティリティは、JMSモジュール・ファイルまたは既存のJMS SAFクライアントの構成ファイルを使用して、JMS SAFクライアントの構成ファイルを生成します。 

java [ weblogic.jms.extensions.ClientSAFGenerate ] 
[ -url server-url ]
[ -username name-of-user ]
[ -existingClientFile file-path ]
[ -moduleFile file-path ['@' plan-path ]]*
[ -outputFile file-path  ]

表3-1 ClientSAFGenerateの引数

引数 定義

url

JMS SAFクライアントが接続するWebLogic ServerインスタンスのURL。

username

このJMS SAFクライアント・インスタンスがメッセージを転送する際に使用する有効なユーザーの名前。

existingClientFile

既存のJMS SAFクライアントの構成ファイルの名前。このパラメータを指定すると、既存のファイルが読み取られ、新しいエントリが追加されます。追加される項目とすでにJMS SAFクライアントの構成ファイルに存在する項目との間で競合が検出された場合は、警告が発生して新しい項目は追加されません。指定されたJMS SAFクライアントの構成ファイルが見つからない場合は、エラーが出力されてユーティリティは終了します。

moduleFile

JMSモジュール構成ファイルとプラン・ファイル(オプション)の名前。

outputFile

stdout

デフォルトでは、JMSクライアントの現在の作業ディレクトリにClientSAF.xmlが作成されます。ただし、JMSクライアントに引数を渡すことによってファイル名を明示的に指定することもできます。

JMS SAFクライアントの構成での有効なSAF要素

weblogic-jms.xsdスキーマのweblogic-client-jmsルート要素には、サーバー側のWebLogic SAF JMS機能に対応する最上位要素がいくつか含まれています。表3-2に、スキーマの最上位要素とそれらに対応する管理MBeanを示します。

表3-2 weblogic-client-safの要素

weblogic-client-jms要素 WebLogic Serverの管理Bean

connection-factory

JMSConnectionFactoryBean

saf-agent

SAFAgentMBean

saf-imported-destinations

SAFImportedDestinationsBean

saf-remote-context

SAFRemoteContextBean

saf-error-handling

SAFErrorHandlingBean

persistent-store

「JMS SAFクライアントのデフォルト・ストア・オプション」を参照してください。

ノート:

JMS SAFクライアントの構成ファイルで指定できるのは、1つのpersistent-storeおよびsaf-agent要素のみです。

これらの管理MBeanのすべてのプロパティは、JMS SAFクライアント実装でもサーバー側のSAF JMS構成の場合と同じように機能します。ただし、次の表に示すものは除きます。

表3-3に、標準のSAFAgentMBeanフィールドとJMS SAFクライアントの構成ファイルのフィールドとの相違点を示します。

表3-3 SAFAgentMBeanフィールドの変更点

サーバー側のSAFフィールド JMS SAFクライアントの構成ファイルとの相違点

PersistentStore

使用不可。定義される永続ストアは1つのみです。

ServiceType

使用不可。これは送信エージェントにしかなれません。

BytesThresholdHigh

しきい値プロパティは使用不可です。

BytesThresholdLow

しきい値プロパティは使用不可です。

MessagesThresholdHigh

しきい値プロパティは使用不可です。

MessagesThresholdLow

しきい値プロパティは使用不可です。

ConversationIdleTimeMaximum

使用不可。このフィールドはメッセージの受信でのみ有効です。

AcknowledgeInterval

使用不可。このフィールドはメッセージの受信でのみ有効です。

IncomingPausedAtStartup

使用不可。休止を解除する方法はありません。JMS SAFクライアント・プロパティを設定しないことにより、同じ効果を得られます。

ForwardingPausedAtStartup

使用不可。休止を解除する方法はありません。JMS SAFクライアント・プロパティを設定しないことにより、同じ効果を得られます。

ReceivingPausedAtStartup

使用不可。休止を解除する方法はありません。JMS SAFクライアント・プロパティを設定しないことにより、同じ効果を得られます。

ノート:

JMS SAFクライアントの構成ファイルで指定できるのは、1つのsaf-agent要素のみです。

表3-4に、標準のJMSConnectionFactoryBeanフィールドとJMS SAFクライアントの構成ファイルのフィールドとの相違点を示します。

表3-4 JMSConnectionFactoryBeanフィールドの変更点

サーバー側のSAFフィールド JMS SAFクライアントの構成ファイルとの相違点

SubDeploymentName

無視されます。これらの接続ファクトリはターゲットになりません。

ClientParamsBean: MulticastOverrunPolicy

無視されます。このクライアントはマルチキャスト受信を実行できません。

TransactionParamsBean: XAConnectionFactoryEnabled

無視されます。JMS SAFクライアントはXAトランザクションを実行できません。

FlowControlParamsBean

すべてのフィールドが無視されます。JMS SAFクライアントはメッセージを受信できません。

LoadBalancingParamsBean

すべてのフィールドが無視されます。JMS SAFクライアントはサーバーに接続されていないため、ロード・バランシングができません。

表3-5に、標準のSAFImportedDestinationsBeanフィールドとJMS SAFクライアントの構成ファイルのフィールドとの相違点を示します。

表3-5 SAFImportedDestinationsBeanフィールドの変更点

サーバー側のSAFフィールド JMS SAFクライアントの構成ファイルとの相違点

SubDeploymentName

無視されます。これらは、このファイルで定義される1つのSAFエージェントをターゲットにしています。

UnitOfOrderRouting

無視されます。メッセージ順序単位はサポートしません。
JMS SAFクライアントのデフォルト・ストア・オプション

各JMS SAFクライアントには構成の必要がないデフォルト・ストアが含まれており、それを複数のJMS SAFクライアント間で共有できます。デフォルト・ストアはファイル・ベースのストアで、JMS SAFクライアントの構成ディレクトリ直下のファイル・グループにデータを保持します。

persistent-store要素を使用すると、デフォルト・ストアに別の場所を指定でき、次の要素をJMS SAFクライアントの構成ファイルに指定することによって、デフォルトの書込みポリシーを変更することもできます。

表3-6 persistent-storeの要素

要素名 機能

directory-path

ファイル・ストアを保持するディレクトリのファイル・システム上のパス名を指定します。

synchronous-write-policy

ファイル・ストアがディスクにレコードをフラッシュする方法を定義します。指定できる値は、「Direct-Write」 (デフォルト)、「Cache-Flush」、および「Disabled」です。

ノート:

JMS SAFクライアントの構成ファイルで指定できるのは、1つのpersistent-store要素のみです。

次に、JMS SAFクライアントの構成ファイルにおけるカスタマイズされたJMS SAFクライアントのデフォルト・ストアの例を示します。

  <persistent-store>
    <directory-path>config/jms/storesdom</directory-path>
    <synchronous-write-policy>Disabled</synchronous-write-policy>
  </persistent-store>

ファイル・ストアに対して同期書込みポリシーを使用する方法の詳細は、『WebLogic永続ストアの管理』のWebLogic永続ストアの使用方法に関する項を参照してください。

リモートJMS SAFコンテキストのパスワードの暗号化

生成されたSAF構成ファイルには、ソースJMSモジュール・ファイルに構成されているかどうかに関係なく、暗号化されたSAFリモート・コンテキストのパスワードが含まれていません。JMS SAFクライアントの構成ファイルで定義されるリモートのクラスタまたはサーバーのコンテキストに対しセキュリティ資格証明が構成される場合、リモートのサーバーまたはクラスタに接続する際に、暗号化されたパスワードが必要になります。

暗号化されたリモートSAFコンテキストのパスワードを作成するには、インストールしたWebLogicにバンドルされたClientSAFEncryptユーティリティを使用する必要があります。これは、クリア・テキストの文字列をJMS SAFクライアントで使用できるように暗号化するものです。

ノート:

既存のweblogic.security.Encryptコマンド・ライン・ユーティリティは、ドメイン・セキュリティ・ファイルへのアクセスが想定されるため、クライアントでは使用できません。

親トピック: クライアント側のSAFを使用するためのJMSクライアントの構成

暗号化されたパスワードの生成ステップ

次のステップは、ClientSAFEncryptを使用して暗号化されたパスワードを生成する方法を示しています:

  1. Javaコマンドラインから、ClientSAFEncryptユーティリティを実行します:
    > java -Dweblogic.management.allowPasswordEcho=true weblogic.jms.extensions.ClientSAFEncrypt [ key-password ] [ remote-password ]*
  2. key-passwordフィールドまたはremote-passwordフィールドが指定されていない場合は、key-passwordとremote-passwordを指定するよう対話形式で求められます。
  3. 次に、暗号化されたパスワードを取得する例を示します。
    Password Key ("quit" to end):
Password ("quit" to end):
<password-encrypted>{Algorithm}PBEWithMD5AndDES{Salt}9IsTPAuZdcQ={Data}d6SSPp3GwPAfEXn8izyZA0IRCV/izT8H</password-encrypted>
Password ("quit" to end):
  4. JMS SAFクライアントの構成ファイルに定義されているリモート・コンテキストに必要な数だけリモート・パスワードを生成します。
  5. 暗号化されたリモート・パスワードをコピーして、JMS SAFクライアントの構成ファイルの</saf-login-context>スタンザの前に貼り付けます。たとえば:
    <saf-remote-context name="RemoteContext0">
<saf-login-context>
<loginURL>http://10.61.6.138:7001</loginURL>
<username>weblogic</username>
<password-encrypted>{Algorithm}PBEWithMD5AndDES{Salt}dWENfrgXh8U={Data}u8xZ968dElHckso/ZYm2LQ6xVNBPpBGQ</password-encrypted>
</saf-login-context>
</saf-remote-context>

    JMS SAFクライアントの構成ファイルに定義されているリモート・コンテキストで必要になるすべてのパスワードに対して、同じkey-passwordを指定してClientSAFEncryptユーティリティを使用します。クライアントがJMS SAFクライアントの使用を開始する際、ClientSAFEncryptユーティリティに指定した同じkey-passwordを使用する必要があります。

  6. quitと入力して、ClientSAFEncryptユーティリティを終了します。
ClientSAFEncryptユーティリティの構文

weblogic.jms.extensions.ClientSAFEncryptユーティリティは、リモートSAFコンテキストにアクセスするために、クリア・テキストの文字列をJMS SAFクライアントで使用できるように暗号化します。 

java [ -Dweblogic.management.allowPasswordEcho=true ]  weblogic.jms.extensions.ClientSAFEncrypt [ key-password ]  weblogic.jms.extensions.ClientSAFEncrypt [ remote-password ]

表3-7 ClientSAFEncryptの引数

引数 定義

weblogic.management.allowPasswordEcho

オプション。コマンド(weblogic.jms.extensions.ClientSAFEncrypt)に入力された文字のエコーを許可します。no-echoが使用可能になっていることが期待されます。no-echoが使用可能でない場合は、このプロパティをtrueに設定します。

key-password

JMS SAFクライアントの構成ファイルに定義されているリモート・コンテキストに必要なすべてのリモート・パスワードを暗号化する際に使用するキー。

コマンド・ラインで省略した場合は、key-passwordの入力を求められます。

remote-password

暗号化するクリア・テキスト文字列。1つのセッションで生成される各リモート・コンテキストに対する複数のパスワード。

コマンド・ラインで省略した場合は、remote-passwordの入力を求められます。

クライアント・マシンへのJMS SAFクライアントのJARファイルのインストール

WebLogic Serverには、2つのJMS SAFクライアント・オプションが用意されています:

必要なJARファイルは、WebLogic Serverインストール・ディレクトリのWL_HOME\server\libサブディレクトリにあります。WL_HOMEは、インストールしたWebLogic Server製品全体の最上位インストール・ディレクトリ(たとえば、c:\Oracle\Middleware\Oracle_Home\wlserver\server\lib)です。

親トピック: クライアント側のSAFを使用するためのJMSクライアントの構成

JMS SAFクライアントの初期JNDIプロバイダを使用できるようにJMSクライアント・アプリケーションの変更

JMS SAFクライアントには、JMSモジュールからJMS SAFクライアントの構成ファイルを生成するためのステップで生成したJMS SAFクライアントの構成ファイルに指定されたサーバー側のJMS接続ファクトリと宛先をルックアップするために、初期JNDIプロバイダが必要になります

親トピック: クライアント側のSAFを使用するためのJMSクライアントの構成

JMS SAFクライアントに必要なJNDIコンテキスト・ファクトリ

JMSクライアント・アプリケーションを変更して、標準のサーバー初期コンテキストのかわりにJMS SAFクライアントのJNDIコンテキスト・ファクトリを使用するようにします。JMS SAFクライアントのJNDIプロパティjava.naming.factory.initialに使用する名前は、weblogic.jms.safclient.jndi.InitialContextFactoryImplです。

JMS SAFクライアント・アプリケーションのJNDI初期コンテキスト・ファクトリの例は、次のようになります。

   public final static String JNDI_FACTORY="weblogic.jms.safclient.jndi.InitialContextFactoryImpl";

標準のJNDIルック・アップを使用して、JMS SAFクライアントは自動的に起動され、構成ファイルに指定されたサーバー側のJMS接続ファクトリと宛先をルック・アップします。デフォルトでは、JMSクライアントの現在の作業ディレクトリにClientSAF.xmlという構成ファイルが作成されます。ただし、JMSクライアントに引数を渡すことによって構成ファイルの名前を明示的に指定することもできます。

JMS SAFクライアントで作成された初期コンテキストから返される項目は、サード・パーティのJMSプロバイダからのJMS呼出しでは処理できません。また、JMS SAFクライアントの初期コンテキストとサーバーの初期コンテキストを混在させることはできません。詳細については、「JMS SAFクライアントのコンテキストとサーバーのコンテキストは混在できない」を参照してください

また、JMSクライアント・アプリケーションを更新して「weblogic.jms.extensions.ClientSAF」拡張クラスを使用可能にすることができます。これによって、JMSクライアントがJMS SAFクライアント・システムの使用を制御することができるようになります。「JMS SAFクライアントの初期化API」を参照してください

JMS SAFクライアントの任意指定のJNDIプロパティ

次のような2つの任意指定のJMS SAFクライアントのJNDIプロパティがあります。

  • Context.PROVIDER_URL - JMS SAFクライアントの構成ファイルを指すURLである必要があります。これを指定しない場合は、JVMの現在の作業ディレクトリにClientSAF.xmlというファイルがデフォルトで作成されます。

  • Context.SECURITY_CREDENTIALS - セキュリティを使用する場合、構成ファイルのリモート・コンテキスト・パスワードを暗号化するのに使用するキー・パスワードを指定します。

ローカルJNDIプロバイダでは、lookup(String) APIおよびclose() APIしかサポートされていません。その他のAPIではすべて、機能がサポートされていない旨の例外がスローされます。

JMS SAFクライアント管理ツール

JMS SAFクライアント実装で使用できるJMS SAFクライアント初期化APIおよびクライアント側ストア管理ユーティリティ機能について学習します。

次の管理機能は、JMS SAFクライアント実装で使用できます。

親トピック: JMS SAFクライアントによる確実なメッセージ送信

JMS SAFクライアントの初期化API

weblogic.jms.extensions.ClientSAF拡張クラスを使用すると、JMSクライアントがJMS SAFクライアント・システムの使用を制御することができるようになります。JMSクライアントではこの拡張メカニズムを使用する必要はありませんが、これを使用すると、JMS SAFクライアント・システムをきめ細かく制御することができます。たとえば、close()メソッドを使用すると、JMSクライアントがメッセージを転送しないようにすることができます。

親トピック: JMS SAFクライアント管理ツール

クライアント側のストア管理ユーティリティ

JMS SAFクライアントには、JMS SAFクライアントが使用するデフォルトのファイル・ストアを管理するユーティリティが用意されています。サーバー側のWebLogicストア・ユーティリティと同様に、JMS SAFクライアント・ストアのトラブルシューティングを行ったり、データを抽出したりできます。このユーティリティは、Javaコマンド・ラインからでもWebLogic Scripting Tool (WLST)からでも実行することができます。ストア・ユーティリティで操作できるのは、実行中のJMS SAFクライアントが現在開いていないストアのみです。

ストア管理の最も一般的な使用例は、サイズを減らすためにファイル・ストアを圧縮する場合や、トラブルシューティングの目的でファイル・ストアの内容をXMLファイルにダンプする場合です。『WebLogic永続ストアの管理』の永続ストアの使用方法に関する項を参照してください。

親トピック: JMS SAFクライアント管理ツール

JMS SAFクライアントでのJMSプログラミングの考慮事項

JMS SAFクライアントを使用する場合のJMSプログラミングの考慮事項について学習します。

JMS SAFクライアントを使用する場合、次のJMSプログラミングの考慮事項が適用されます。

親トピック: JMS SAFクライアントによる確実なメッセージ送信

JMS SAFクライアント・メッセージでのJMSReplyToフィールドの処理方法

一般的に、JMSアプリケーションはJMSReplyToヘッダー・フィールドを使用して、一時的な宛先の名前を他のアプリケーションに対して公開できます。ただし、サーバー側のJMS SAFインポート済み宛先の場合と同様に、JMSReplyToフィールドを持つ一時的な宛先の使用はJMS SAFクライアントでサポートされていません。

JMS一時宛先の使用方法の詳細は、『Oracle WebLogic Server JMSアプリケーションの開発』の一時宛先の使用に関する項を参照してください。

親トピック: JMS SAFクライアントでのJMSプログラミングの考慮事項

JMS SAFクライアントのコンテキストとサーバーのコンテキストは混在できない

JMS SAFクライアントのネーミング・コンテキストから返される項目をサーバーの初期コンテキストから返される項目と一緒に使用すると、JMS APIが失敗し、その旨の例外メッセージが表示されます。同様に、サーバーの初期コンテキストから返される項目をJMS SAFクライアントのネーミング・コンテキストから返される項目と一緒に使用すると、JMS APIが失敗し、その旨の例外メッセージが表示されます。

親トピック: JMS SAFクライアントでのJMSプログラミングの考慮事項

JMS SAFクライアントでのトランザクション・セッションの使用

JMS SAFクライアントでのトランザクション・セッションはサポートされていますが、クライアントSAF操作は、グローバル(XA)トランザクションへ一切参加しません。XAトランザクションがある場合、メッセージ送信処理はXAトランザクションの外部で行われ、例外はスローされません。

親トピック: JMS SAFクライアントでのJMSプログラミングの考慮事項

JMS SAFクライアントの相互運用のガイドライン

相互運用のガイドラインは、JMS SAFクライアントを使用してサーバー側のWebLogic JMS宛先にメッセージを転送する場合に適用されます。

このトピックの内容は次のとおりです。

親トピック: JMS SAFクライアントによる確実なメッセージ送信

Java Runtime

各クライアント・マシンには、Java SE 1.4以降のランタイムがインストールされている必要があります。

親トピック: JMS SAFクライアントの相互運用のガイドライン

WebLogic Serverのバージョン

WebLogicのJMS SAFクライアント・システムは、WebLogic Server 9.2以降でのみ機能します。

クライアント側のJMS SAFクライアント・コードは、リリース9.2以降のWebLogic Server JARファイルで実行される必要があります。WebLogic Server JARファイルのインストールの詳細は、「クライアント・マシンへのJMS SAFクライアントのJARファイルのインストール」を参照してください

親トピック: JMS SAFクライアントの相互運用のガイドライン

JMS C API

クライアント側のSAFは、JMS C APIを使用するC環境から使用できます。このJMS C APIの実装では、Java仮想マシン(JVM)へのアクセスにJNIを使用します。ただし、JMS C APIは、非標準のJMS APIあるので、「weblogic.jms.extensions.ClientSAF」インタフェースを使用できません。

JMS C APIでSAFを使用するには、SAFコンテキストをjndiFactoryに設定します。デフォルトでは、jndiFactoryとしてNULLを渡すと、通常のWebLogic Serverコンテキストを取得できます。たとえば: 

int JmsContextCreate(JmsString *uri, JmsString *jndiFactory, JmsString *username, JmsString *password, JmsContext **context, JMS64I flags)

『Oracle WebLogic Server JMSアプリケーションの開発』のWebLogic C APIに関する項を参照してください。

親トピック: JMS SAFクライアントの相互運用のガイドライン

JMS SAFクライアントのチューニング

JMS SAFクライアントでは、サーバー側のSAFサービスで使用可能なパラメータのチューニングを利用することができます。

『Oracle WebLogic Serverのパフォーマンスのチューニング』のWebLogic JMSのストア・アンド・フォワードのチューニングに関する項を参照してください。

親トピック: JMS SAFクライアントによる確実なメッセージ送信

JMS SAFクライアントの使用に関する制限

JMS SAFクライアントの使用時にサポートされない機能および例外について学習します。

JMS SAFクライアントでは、「JMS SAFクライアントの構成での有効なSAF要素」で説明したフィールド・レベルの制限の他、次の制限も適用されます。

  • JMSメッセージ順序単位および作業単位JMSメッセージ・グループ機能はサポートされません。

  • インポート済みSAF宛先の宛先コンシューマはサポートされません。JMS SAFクライアント環境でこのようなコンシューマを作成しようとすると、例外がスローされます。

  • インポート済みSAF宛先の宛先ブラウザはサポートされません。JMS SAFクライアント環境でこのようなブラウザを作成しようとすると、例外がスローされます。

  • ユーザー(XA)トランザクションを除き、トランザクション・セッションはサポートされません。クライアントSAF操作は、グローバル・トランザクションへ一切参加しません。「JMS SAFクライアントでのトランザクション・セッションの使用」を参照してください

  • JMS SAFクライアントはJavaアプレットではサポートされません。

  • JMS SAFクライアントの構成ファイルで指定できるのは、1つのpersistent-storeおよびsaf-agent要素のみです。

  • クライアントにjava.sql.ResultSetを戻すことのできるWebLogic Server CMP 2.x拡張がサポートされていません。

親トピック: JMS SAFクライアントによる確実なメッセージ送信

JMS SAFクライアントのメッセージ格納動作の変更

Weblogic JMS SAFクライアントでは、メッセージはローカル記憶域に保持されてから、リモート宛先に転送されます。リモート宛先はそれぞれ、カーネル・キューと呼ばれるローカル記憶域ユニットに対応しています。Oracle WebLogic Server 10.3.3.0より前のリリースでは、JMS SAFクライアント・インスタンスを閉じて再度開くたびに、異なるカーネル・キューが使用されます。この動作は、1つの宛先に対して複数のカーネル・キューが対応する原因となっていました。

ノート:

  • 宛先が単一のリモート宛先である場合、状況によっては、JMS SAFクライアントでメッセージが転送されないか誤った順序で転送される可能性があります。

  • 宛先が分散された宛先である場合、状況によっては、メッセージが永久に失われるか重複して送信される可能性があります。

このリリースでは、JMS SAFクライアントを何度開いて閉じても、1つのリモート宛先に対して同じカーネル・キューが使用されます。JMSクライアントのSAFインスタンスを一度しか開かないアプリケーション環境では、動作に変更はありません。

親トピック: JMS SAFクライアントによる確実なメッセージ送信

アップグレード・プロセス、ツールおよびシステム・プロパティ

この後の項では、JMS SAFクライアントのアップグレードに使用するプロセス、ツールおよびシステム・プロパティについて説明します。アップグレードを行うことで、クライアントがカーネル・キューを何度開いて閉じても、各宛先に対して1つのカーネル・キューが使用されるようになります。

  • JMS SAFクライアントを一度しか開かないアプリケーション環境では、操作は不要です。

  • 新しいJMS SAFクライアントは変更不要です。

  • JMS SAFクライアントを複数回開いて閉じるアプリケーション環境では、既存のメッセージがクライアントの複数のカーネル・キューに存在する可能性があります。Oracleには、アップグレード後初めてJMS SAFクライアントが起動したときに、メッセージを複数のカーネル・キューから単一のカーネル・キューに移行するプロセスが用意されており、このプロセスはユーザーによる調整が可能です。移行の際に、メッセージが失われないことは保証されていますが、メッセージの重複が発生する可能性がわずかにあります。移行されたメッセージはすべて、通常のSAF QoSを維持しています。ローカル・ストアを削除するか、weblogic.jms.safclient.MigrateExistingMessages=falseと指定すれば、既存のメッセージが移行されないようにすることができます。「JMS SAFクライアント移行プロパティ」を参照してください。なんらかの理由でメッセージの移行に失敗した場合、JMS SAFクライアントは起動しません。

親トピック: JMS SAFクライアントのメッセージ格納動作の変更

JMS SAFクライアント検出ツール

JMS SAFクライアント検出ツールは、WebLogic Server JMSクライアント・ライブラリにパッケージ化されたJavaプログラムであり、アップグレード前に既存のローカルSAFメッセージを調査する目的で使用できます。このツールでは、次のことが可能です。

  1. 各リモート宛先および対応するカーネル・キューの確認など、クライアント構成を確認します。

  2. 各カーネル・キュー内のメッセージの数を出力します。

  3. 各カーネル・キュー内の最初のメッセージから、メッセージID、相関ID、SAFシーケンス名、SAFシーケンス番号および順序単位などの選択ヘッダー情報を出力します。

この調査結果を使用して、アップグレード後のシステム・プロパティをチューニングできます。「JMS SAFクライアント移行プロパティ」を参照してください。

使用方法: java weblogic.jms.extensions.ClientSAFDiscover options

前述の構文では、optionsは、次の表に示されている1つ以上の値を示します。

表3-8 JMS SAFクライアント検出ツールの説明およびデフォルト値

オプション 説明

-help

使用方法に関する情報を出力します。

-clientSAFRootDir client-saf-root-directory

オプション。デフォルトは現在のディレクトリです。

検出するターゲットとなるSAFクライアントのルート・ディレクトリを指定します。SAFクライアント構成ファイル内の相対パスは、このディレクトリを基準としています。

-configurationFile config-file

オプション。デフォルトはClientSAF.xmlです。

ターゲットとなるJMS SAFクライアントが使用する構成ファイルの場所を指定します。このオプションは、clientSAFRootDirオプションを指定した場合に必要です。clientSAFRootDirオプションまたはこのオプションを指定すると、現在の作業ディレクトリにあるClientSAF.xmlファイルが使用されます。指定した構成ファイルが存在しない場合は、例外がスローされます。

-cutoffFormat pattern

オプション。デフォルトはyyyy-MM-dd'T'HH:mm:ss.SSSZです。

オプションで使用するカットオフ時間について日時パターンを指定します。http://docs.oracle.com/javase/8/docs/api/java/text/DateFormat.htmlを参照してください。

-cutoffTime cutoff-time

オプション。デフォルトはnullです。

weblogic.jms.safclient.MigrationCutoffTimeが設定されている場合に、アップグレード中に破棄されるメッセージのデータを出力します。メッセージは破棄されません。カットオフ時間の形式は、-cutoffFormatプロパティの値によって異なります。指定したカットオフ時間がcutoffFormatパターンと一致しない場合は、例外がスローされます。カットオフ時間が指定されていない場合は、メッセージは破棄されず、出力されません。

-discoveryFile discovery-file

オプション。デフォルトはSAF_DISCOVERYです。

JMS SAFクライアント検出ツールによって生成された出力を含むファイルを指定します。出力は、絶対パスを指定しないかぎり、ルート・ディレクトリを基準として配置されます。指定したファイルがすでに存在する場合、そのファイルは削除され、新しいファイルが作成されます。
例

次のコマンドを使用してJMS SAFクライアントを作成したとします。

ClientSAFFactory.getClientSAF(new File("c:\\foo"), new FileInputStream("c:\\ClientSAF-jms.xml"));

JMS SAFクライアントをアップグレードする前に、ClientSAFDiscoverツールを使用して既存のメッセージを調査できます。たとえば:

java weblogic.jms.client.ClientSAFDiscover -clientSAFRootDir c:\foo -configurationFile c:\ClientSAF-jms.xml

検出情報は、デフォルトの場所であるc:\foo\SAF_DISCOVERYに書き込まれます。

JMS SAFクライアント移行プロパティ

メッセージの移行は自動化されていても複雑な問題であるため、移行プロセスを管理するための次のシステム・プロパティが用意されています。

  • weblogic.jms.safclient.MigrateExistingMessages—falseに設定されている場合、このプロパティでは、複数のキューから単一のキューへのメッセージの移行は行われません。デフォルトはtrueです。

  • weblogic.jms.safclient.MigrationCutoffTime—このプロパティを使用して、メッセージが単一のカーネル・キューに移行されるまでの時間を指定します。残っているメッセージはすべて破棄されます。このプロパティを指定しない場合、すべての既存メッセージがアップグレードされます。このプロパティをweblogic.jms.safclient.MigrationCutoffTimeFormatプロパティとともに使用して、時間形式を指定します。

    たとえば、カットオフ時間形式がデフォルトの場合、有効なカットオフ時間は2009-12-16T10:34:17.887-0800です。指定した時間がその形式のパターンに一致しない場合は、例外がスローされ、JMS SAFクライアントですべてのメッセージ処理が停止されます。

  • weblogic.jms.safclient.MigrationCutoffTimeFormat—weblogic.jms.safclient.MigrationCutoffTimeの形式を指定します。

    デフォルトはyyyy-MM-dd‘T’HH:mm:ss.SSSZです。詳細は、java.text.SimpleDateFormatクラスの説明を参照してください。