| Oracle® Fusion Middleware Oracle WebLogic Serverスタンドアロン・クライアントのプログラミング 12c リリース1 (12.1.1) B65897-02 |
|
 前 |
 次 |
| Oracle® Fusion Middleware Oracle WebLogic Serverスタンドアロン・クライアントのプログラミング 12c リリース1 (12.1.1) B65897-02 |
|
前 |
次 |
この章では、JMS SAFクライアント機能を構成および使用して、スタンドアロンのJMSクライアントからサーバー側のJMS宛先にメッセージを確実に送信する方法について説明します。
JMS SAFクライアント機能は、WebLogic Server 9.0で導入したJMSストア・アンド・フォワード・サービスをスタンドアロンJMSクライアントに拡張したものです。この機能を使用することで、JMSクライアントは(一時的なネットワーク接続の障害などが原因で)サーバー側のJMS宛先にアクセスできない場合でも、メッセージを宛先に確実に送信できるようになります。サーバーとの接続が切断されている間、JMS SAFクライアントによって送信されたメッセージはクライアントのファイル・システム上でローカルに格納され、クライアントが再接続したら、サーバー側のJMS宛先に転送されます。
JMS SAFクライアント機能は、主にJMS SAFクライアント実装とSAFフォワーダで構成されています。前者は、ローカルのファイル・システムにあるクライアント側の永続ストアにメッセージを直接書き込むために使用され、後者は、永続ストアに書き込まれたメッセージを取得してWebLogic Serverインスタンスに送信するために使用されます。また、必要に応じてJMS SAFクライアントがSAFフォワーダ・メカニズムを使用するかしないかを設定できるSAFClient初期化API (weblogic.jms.extensions)も用意されています。詳細については、「JMS SAFクライアントの初期化API」を参照してください。
|
注意: サーバー側のWebLogic JMS SAFによって、アクセスできない可能性のある宛先にJMSメッセージを確実に送信する方法の詳細は、『Oracle WebLogic Serverストア・アンド・フォワードの構成と管理』のJMSメッセージに対するSAFの構成に関する項を参照してください。 |
サーバー側では構成を行う必要がありませんが、クライアント側では各クライアントで構成を行う必要があります。以下の節では、クライアント側のSAFを使用するためのJMSクライアントの構成方法について説明します。
各クライアント・マシンには、JMS SAFクライアントの構成ファイルが必要です。構成ファイルには、JMS SAFクライアント環境での処理に必要なサーバー側の接続ファクトリと宛先に関する情報を指定します。指定のJMSモジュールの構成ファイルからJMS SAFクライアントの構成ファイルを生成するには、インストールしたWebLogicに付属しているClientSAFGenerateユーティリティを使用します。
JMSモジュールからJMS SAFクライアントの構成ファイルを生成するための手順で説明しているように、ClientSAFGenerateユーティリティはソースのJMS構成ファイルで見つかったすべての接続ファクトリ、スタンドアロン宛先および分散宛先用にエントリを作成します。JMS SAFクライアントの初期JNDIプロバイダを使用できるようにJMSクライアント・アプリケーションの変更に記述された初期のJNDIコンテキストを通してJMS SAFクライアントが直接相互作用する接続ファクトリおよびインポート済み宛先が、生成されたファイルで定義されます。しかも、SAFエクスポート・ポリシーがAllに設定されたJMS宛先のみが、ファイルに追加されます(宛先のデフォルト設定)。
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フォワーダの両方で使用されます。
ClientSAFGenerateユーティリティを使用して、WebLogicドメインのJMSモジュール構成ファイルからJMS SAFクライアントの構成ファイルを生成します。また、構成ファイルは既存のJMS SAFクライアントの構成ファイルから生成することもできます。詳細については、「ClientSAFGenerateユーティリティの構文」を参照してください。
|
注意: クライアント・マシン上で |
次の手順は、ClientSAFGenerateユーティリティを使用して、インストールしたWebLogic Serverに付属しているexamples-jms.xmlモジュール・ファイルからJMS SAFクライアントの構成ファイルを生成する方法を示しています。
JMS SAFクライアントの構成ファイルのベースとして使用するJMSモジュール・ファイルが存在するWebLogicドメインのディレクトリに移動します。
c:\Oracle\Middleware\wlserver_12.1\samples\domains\wl_server\config\jms
Javaコマンド・ラインでClientSAFGenerateユーティリティを実行します。
> java weblogic.jms.extensions.ClientSAFGenerate -url http://10.61.6.138:7001 -username weblogic -moduleFile examples-jms.xml -outputFile d:\temp\ClientSAF-jms.xml
表7-1に、有効なClientSAFGenerateの引数を示します。
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モジュールに対して |
生成された構成ファイルには、SAFリモート・コンテキストがリモート・サーバーに接続する際に使用する暗号化されたパスワードが含まれていません。暗号化されたリモートSAFコンテキストのパスワードを作成して、構成ファイルに追加するには、「リモートJMS SAFコンテキストのパスワードの暗号化」の説明に従ってください。
JMS SAFクライアント・アプリケーションが実行されるクライアント・マシンに、生成された構成ファイルをコピーします。「クライアント・マシンへのJMS SAFクライアントのJARファイルのインストール」を参照してください。
|
注意: デフォルトでは、JMSクライアントの現在の作業ディレクトリに |
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 ]
表7-1 ClientSAFGenerateの引数
| 引数 | 定義 |
|---|---|
|
|
JMS SAFクライアントが接続するWebLogic ServerインスタンスのURL。 |
|
|
このJMS SAFクライアント・インスタンスがメッセージを転送する際に使用する有効なユーザーの名前。 |
|
|
既存のJMS SAFクライアントの構成ファイルの名前。このパラメータを指定すると、既存のファイルが読み取られ、新しいエントリが追加されます。追加される項目とすでにJMS SAFクライアントの構成ファイルに存在する項目との間で競合が検出された場合は、警告が発生して新しい項目は追加されません。指定されたJMS SAFクライアントの構成ファイルが見つからない場合は、エラーが出力されてユーティリティは終了します。 |
|
|
JMSモジュール構成ファイルとプラン・ファイル(オプション)の名前。 |
|
|
デフォルトでは、JMSクライアントの現在の作業ディレクトリに |
weblogic-jms.xsdスキーマのweblogic-client-jmsルート要素には、サーバー側のWebLogic SAF JMS機能に対応する最上位要素がいくつか含まれています。表7-2に、スキーマの最上位要素とそれらに対応する管理MBeanを示します。
表7-2 weblogic-client-safの要素
| weblogic-client-jms要素 | WebLogic Serverの管理Bean |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
詳細については、「JMS SAFクライアントのデフォルト・ストア・オプション」を参照してください。 |
|
注意: JMS SAFクライアントの構成ファイルで指定できるのは、1つの |
これらの管理MBeanのすべてのプロパティは、JMS SAFクライアント実装でもサーバー側のSAF JMS構成の場合と同じように機能します。ただし、次の表に示すものは除きます。
表7-3に、標準のSAFAgentMBeanフィールドとJMS SAFクライアントの構成ファイルのフィールドとの相違点を示します。
表7-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つの |
表7-4に、標準のJMSConnectionFactoryBeanフィールドとJMS SAFクライアントの構成ファイルのフィールドとの相違点を示します。
表7-4 JMSConnectionFactoryBeanフィールドの変更点
| サーバー側のSAFフィールド | JMS SAFクライアントの構成ファイルとの相違点 |
|---|---|
|
無視されます。これらの接続ファクトリはターゲットになりません。 |
|
|
無視されます。このクライアントはマルチキャスト受信を実行できません。 |
|
|
無視されます。JMS SAFクライアントはXAトランザクションを実行できません。 |
|
|
すべてのフィールドが無視されます。JMS SAFクライアントはメッセージを受信できません。 |
|
|
すべてのフィールドが無視されます。JMS SAFクライアントはサーバーに接続されてないため、ロード・バランシングができません。 |
表7-5に、標準のSAFImportedDestinationsBeanフィールドとJMS SAFクライアントの構成ファイルのフィールドとの相違点を示します。
各JMS SAFクライアントは、構成を必要としないデフォルト・ストアを持っており、このストアは複数のJMS SAFクライアントで共有できます。デフォルト・ストアはファイル・ベースのストアで、JMS SAFクライアントの構成ディレクトリ直下のファイル・グループにデータを保持します。
persistent-store要素を使用すると、デフォルト・ストアに別の場所を指定でき、次の要素をJMS SAFクライアントの構成ファイルに指定することによって、デフォルトの書込みポリシーを変更することもできます。
表7-6 persistent-storeの要素
| 要素名 | 機能 |
|---|---|
|
directory-path |
ファイル・ストアを保持するディレクトリのファイル・システム上のパス名を指定します。 |
|
synchronous-write-policy |
ファイル・ストアがディスクにレコードをフラッシュする方法を定義します。指定できる値は、「Direct-Write」 (デフォルト)、「Cache-Flush」、および「Disabled」です。 |
|
注意: JMS SAFクライアントの構成ファイルで指定できるのは、1つの |
次に、JMS SAFクライアントの構成ファイルにおけるカスタマイズされたJMS SAFクライアントのデフォルト・ストアの例を示します。
<persistent-store>
<directory-path>config/jms/storesdom</directory-path>
<synchronous-write-policy>Disabled</synchronous-write-policy>
</persistent-store>
ファイル・ストアに対して同期書込みポリシーを使用する方法の詳細は、『Oracle WebLogic Serverサーバー環境の構成』のWebLogic永続ストアの使用方法に関する項を参照してください。
生成されたSAF構成ファイルには、ソースJMSモジュール・ファイルに構成されているかどうかに関係なく、暗号化されたSAFリモート・コンテキストのパスワードが含まれていません。JMS SAFクライアントの構成ファイルで定義されるリモートのクラスタまたはサーバーのコンテキストに対しセキュリティ資格証明が構成される場合、リモートのサーバーまたはクラスタに接続する際に、暗号化されたパスワードが必要になります。
暗号化されたリモートSAFコンテキストのパスワードを作成するには、インストールしたWebLogicに付属しているClientSAFEncryptユーティリティを使用する必要があります。このユーティリティを使用すると、クリア・テキストの文字列をJMS SAFクライアント用に暗号化することができます。
|
注意: 既存の |
以下に、ClientSAFEncryptを使用して暗号化されたパスワードを生成する手順を示します。
Javaコマンド・ラインでClientSAFEncryptユーティリティを実行します。
> java -Dweblogic.management.allowPasswordEcho=true weblogic.jms.extensions.ClientSAFEncrypt [ key-password ] [ remote-password ]*
key-passwordフィールドまたはremote-passwordフィールドが指定されていない場合は、key-passwordとremote-passwordを指定するよう対話形式で求められます。
次に、暗号化されたパスワードを取得する例を示します。
Password Key ("quit" to end):
Password ("quit" to end):
<password-encrypted>{Algorithm}PBEWithMD5AndDES{Salt}9IsTPAuZdcQ={Data}d6SSPp3GwPAfEXn8izyZA0IRCV/izT8H</password-encrypted>
Password ("quit" to end):
JMS SAFクライアントの構成ファイルに定義されているリモート・コンテキストに必要な数だけリモート・パスワードを生成します。
暗号化されたリモート・パスワードをコピーして、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を使用する必要があります。
quitと入力して、ClientSAFEncryptユーティリティを終了します。
weblogic.jms.extensions.ClientSAFEncryptユーティリティは、クリア・テキストの文字列をJMS SAFクライアント用に暗号化して、リモートSAFコンテキストにアクセスできるようにします。
java [ -Dweblogic.management.allowPasswordEcho=true ] weblogic.jms.extensions.ClientSAFEncrypt [ key-password ] weblogic.jms.extensions.ClientSAFEncrypt [ remote-password ]
表7-7 ClientSAFEncryptの引数
| 引数 | 定義 |
|---|---|
|
|
オプション。コマンド・ラインで入力した文字がエコー表示されるようにします。 |
|
|
JMS SAFクライアントの構成ファイルに定義されているリモート・コンテキストに必要なすべてのリモート・パスワードを暗号化する際に使用するキー。 コマンド・ラインで省略した場合は、 |
|
|
暗号化するクリア・テキストの文字列。1つのセッションで生成される各リモート・コンテキストに対する複数のパスワード。 コマンド・ラインで省略した場合は、 |
WebLogic Serverでは、JMS SAFクライアントを次の3種類から選択できます。
weblogic.jar(「WebLogicインストール・クライアント」を参照)
wlfullclient.jar(「WebLogicフル・クライアント」を参照してください)
wlsafclient.jar、wljmsclient.jarおよびwlclient.jarを使用するシン・クライアント
必要なJARファイルは、WebLogic Serverインストール・ディレクトリのWL_HOME\server\libサブディレクトリにあります。WL_HOMEは、インストールしたWebLogic製品全体の最上位インストール・ディレクトリ(たとえば、c:\Oracle\Middleware\wlserver_12.1\server\lib)です。
JARのサイズの小ささが重要視される場合を除き、パフォーマンスの高いWebLogicフル・クライアントまたはインストール・クライアントを使用することをお薦めします。wlfullclient.jarを使用するには、これをクライアント・マシンのファイル・システム上のディレクトリにコピーし、クライアント・マシンのCLASSPATHに追加します。また、JMSモジュールからJMS SAFクライアントの構成ファイルを生成するための手順で説明しているように、wlfullclient.jarファイルを使用してClientSAFGenerateユーティリティをクライアント・マシン上で実行して、既存のJMS SAFクライアント構成ファイルから構成ファイルを生成できます。シン・クライアント用にサイズのより小さいJARが必要な場合、JMS SAFクライアントのファイル・システム上のディレクトリに次のJARファイルをインストールし、それらをCLASSPATHに追加する必要があります。
wlsafclient.jar
wljmsclient.jar
wlclient.jar
wljmsclient.jarはwlclient.jarを参照するので、CLASSPATHにはどちらか一方のJARを指定するだけでかまいません。
シン・クライアントのデプロイの詳細は、シン・クライアントの概要に関する項を参照してください。
|
注意: WebLogicシンT3クライアントはJMS SAFクライアントをサポートしていません。 |
JMS SAFクライアントには、JMSモジュールからJMS SAFクライアントの構成ファイルを生成するための手順で生成したJMS SAFクライアントの構成ファイルに指定されたサーバー側のJMS接続ファクトリと宛先をルックアップするために、初期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」を参照してください。
次のような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クライアント実装で使用できます。
weblogic.jms.extensions.ClientSAF拡張クラスを使用すると、JMSクライアントがJMS SAFクライアント・システムの使用を制御することができるようになります。JMSクライアントではこの拡張メカニズムを使用する必要はありませんが、これを使用すると、JMS SAFクライアント・システムをきめ細かく制御することができます。たとえば、close()メソッドを使用すると、JMSクライアントがメッセージを転送しないようにすることができます。
JMS SAFクライアントには、JMS SAFクライアントが使用するデフォルトのファイル・ストアを管理するユーティリティが用意されています。サーバー側のWebLogicストア・ユーティリティと同様に、JMS SAFクライアント・ストアのトラブルシューティングを行ったり、データを抽出したりできます。このユーティリティは、Javaコマンド・ラインからでもWebLogic Scripting Tool (WLST)からでも実行することができます。ストア・ユーティリティで操作できるのは、実行中のJMS SAFクライアントが現在開いていないストアのみです。
ストア管理の最も一般的な使用例は、サイズを減らすためにファイル・ストアを圧縮する場合や、トラブルシューティングの目的でファイル・ストアの内容をXMLファイルにダンプする場合です。詳細は、『Oracle WebLogic Serverサーバー環境の構成』の永続ストアの管理に関する項を参照してください。
JMS SAFクライアントを使用する場合、次のJMSプログラミングの考慮事項が適用されます。
一般的に、JMSアプリケーションはJMSReplyToヘッダー・フィールドを使用して、一時的な宛先の名前を他のアプリケーションに対して公開できます。ただし、サーバー側のJMS SAFインポート済み宛先の場合と同様に、JMSReplyToフィールドを持つ一時的な宛先の使用はJMS SAFクライアントでサポートされていません。
JMS一時宛先の使用方法の詳細は、『Oracle WebLogic Server JMSのプログラミング』の一時的な宛先の使用に関する項を参照してください。
JMS SAFクライアントのネーミング・コンテキストから返される項目をサーバーの初期コンテキストから返される項目と一緒に使用すると、JMS APIが失敗し、その旨の例外メッセージが表示されます。同様に、サーバーの初期コンテキストから返される項目をJMS SAFクライアントのネーミング・コンテキストから返される項目と一緒に使用すると、JMS APIが失敗し、その旨の例外メッセージが表示されます。
JMS SAFクライアントでのトランザクション・セッションはサポートされていますが、クライアントSAF操作は、グローバル(XA)トランザクションへ一切参加しません。XAトランザクションがある場合、メッセージ送信処理はXAトランザクションの外部で行われ、例外はスローされません。
相互運用のガイドラインは、JMS SAFクライアントを使用してサーバー側のWebLogic JMSにメッセージを転送する場合に適用されます。
各クライアント・マシンには、Java SE 1.4以降のランタイムがインストールされている必要があります。
WebLogicのJMS SAFクライアント・システムは、WebLogic Server 9.2以降でのみ機能します。
クライアント側のJMS SAFクライアント・コードは、リリース9.2以降のWebLogic Server JARファイルで実行される必要があります。WebLogic Server JARファイルのインストールの詳細は、「クライアント・マシンへのJMS SAFクライアントのJARファイルのインストール」を参照してください。
クライアント側の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クライアントでは、サーバー側のSAFサービスで使用可能なパラメータのチューニングを利用することができます。詳細については、『WebLogicパフォーマンスおよび・チューニング・ガイド』のWebLogic JMSストア・アンド・フォワードのチューニングに関する項を参照してください。
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拡張がサポートされていません。
Weblogic JMS SAFクライアントでは、メッセージはローカル記憶域に格納されてから、リモート宛先に転送されます。リモート宛先はそれぞれ、カーネル・キューと呼ばれるローカル記憶域ユニットに対応しています。WebLogic Server 10.3.3.0より前のリリースでは、JMS SAFクライアント・インスタンスを閉じて再度開くたびに、異なるカーネル・キューが使用されます。この動作は、1つの宛先に対して複数のカーネル・キューが対応する原因となっていました。宛先の種類によって、次のような問題が考えられます。
単一のリモート宛先の場合: 状況によっては、JMS SAFクライアントからメッセージが転送されない、または誤った順序で転送される可能性があります。
分散した宛先: 状況によっては、メッセージが永久に失われる、または重複して送信される可能性があります。
このリリースでは、JMS SAFクライアントを何度開いて閉じても、1つのリモート宛先に対して同じカーネル・キューが使用されます。JMSクライアントのSAFインスタンスを一度しか開かないアプリケーション環境では、動作に変更はありません。
この後の項では、JMS SAFクライアントのアップグレードに使用するプロセス、ツールおよびシステム・プロパティについて説明します。アップグレードを行うことで、クライアントがカーネル・キューを何度開いて閉じても、各宛先に対して1つのカーネル・キューが使用されるようになります。
JMS SAFクライアントを一度しか開かないアプリケーション環境では、操作は不要です。
新しいJMS SAFクライアントは変更不要です。
JMS SAFクライアントを複数回開いて閉じるアプリケーション環境では、既存のメッセージがクライアントの複数のカーネル・キューに存在する可能性があります。オラクル社は、アップグレード後初めてJMS SAFクライアントが起動したときに、メッセージを複数のカーネル・キューから単一のカーネル・キューに移行するプロセスを用意しており、このプロセスはユーザーによる調整が可能です。移行の際に、メッセージが失われないことは保証されていますが、メッセージの重複が発生する可能性がわずかにあります。移行されたメッセージはすべて、通常のSAF QoSを維持しています。ローカル・ストアを削除するか、weblogic.jms.safclient.MigrateExistingMessages=falseと指定すれば、既存のメッセージが移行されないようにすることができます。第7章「JMS SAFクライアント移行プロパティ」を参照してください。メッセージの移行が何らかの原因で失敗した場合、JMS SAFクライアントは起動できなくなります。
検出ツールは、WLS JMSクライアント・ライブラリにパッケージ化されたJavaプログラムで、アップグレード前に既存のローカルSAFメッセージを調査する目的で使用できます。各リモート宛先と対応するカーネル・キューのチェックなど、クライアント構成の確認を行い、各カーネル・キューのメッセージ数、および各カーネル・キューの最初のメッセージのヘッダー情報(メッセージID、相関ID、SAFシーケンス名、SAFシーケンス番号、順序単位など)を出力します。調査の結果は、アップグレード・システム・プロパティのチューニングに利用できます。第7章「JMS SAFクライアント移行プロパティ」を参照してください。
使用方法: java weblogic.jms.extensions.ClientSAFDiscover options
optionsについては、次の表で説明します。
| オプション | 説明 |
|---|---|
|
-help |
使用方法に関する情報を出力します。 |
|
-clientSAFRootDir <client-saf-root-directory> |
オプション。デフォルトは現在のディレクトリです。 検出するターゲットとなるSAFクライアントのルート・ディレクトリ。SAFクライアント構成ファイル内の相対パスは、このディレクトリを基準としています。 |
|
-configurationFile <configuration-file> |
オプション。デフォルトは ターゲットとなるJMS SAFクライアントが使用する構成ファイルの場所。このオプションは、 |
|
-cutoffFormat <pattern> |
オプション。デフォルトは オプションで使用するカットオフ時間の日時パターン。詳細は、 |
|
-cutoffTime <cutoff-time> |
オプション。デフォルトはnullです。
|
|
-discoveryFile <discovery-file> |
オプション。デフォルトは
|
次のコマンドを使用して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に書き込まれます。
メッセージの移行は自動化されていても複雑な問題であるため、移行プロセスを管理するための次のシステム・プロパティが用意されています。
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クラスのjavadocを参照してください。
