|
|
以下の節では、WebLogic JMS C API を使用する方法について説明します。
WebLogic JMS C API は、WebLogic JMS アプリケーションおよびリソースにアクセスできる C クライアント アプリケーションを作成するためのアプリケーション プログラム インタフェースです。作成した C クライアント アプリケーションでは、Java ネイティブ インタフェース (JNI) を使用してクライアントサイドの Java JMS クラスにアクセスします。図 13-1 を参照してください。
このリリースの WebLogic JMS C API は、Java JMS 1.1 コードの移植を容易にするため、JMS バージョン 1.1 仕様に準拠しています。詳細については、WebLogic JMS C API の Javadoc を参照してください。
ここでは、それぞれの環境で WebLogic JMS C API を使用するためのシステム要件を示します。
wlfullclient.jar ファイル)。『スタンドアロン クライアント プログラマーズ ガイド』の「
WebLogic JarBuilder ツールの使用」を参照してください。wljmsclient.jar ファイル)。『スタンドアロン クライアント プログラマーズ ガイド』の「WebLogic JMS シン クライアント」を参照してください。
以下の節では、WebLogic JMS C API のアプリケーションを移植または開発する上での原則について説明します。
WebLogic JMS C API は、モジュール形式でコードを実装するハンドル ベースの API です。つまり、アプリケーションでは C コードのハンドルとして Java オブジェクトを実装します。JMS オブジェクトの実装方法の詳細はハンドル内に隠されます。ただし、Java とは異なり、ハンドルを使用して実装したら、対応する Close または Destroy メソッドを呼び出してハンドルを明示的に開放する必要があります。「メモリ割り当てとガベージ コレクション」を参照してください。
WebLogic JMS C API から返されるハンドルがスレッド セーフかどうかは、対応する Java 型がスレッド セーフかどうかによって決まります。次に例を示します。
同時実行性の制御を C クライアント アプリケーションで管理している限り、WebLogic JMS C API が返すすべてのオブジェクトはどのスレッドでも使用される可能性があります。
| 注意 : | WebLogic JMS C API では、整数のリターン コードを使用します。 |
WebLogic JMS C API での例外は、実行スレッドに対してローカルです。WebLogic JMS C API には、以下の型の例外があります。
Java コードと C コードを相互運用する場合、主なタスクの 1 つになるのが C 型から Java 型への変換です。たとえば、short 型は、Java でも C でも 2 バイト エンティティです。以下の型変換では、特別な処理が必要になります。
Integer (int) は、JMS32I (4 バイト符号付き値) に変換します。
Long (long) は、JMS64I (8 バイト符号付き値) に変換します。
Character (char) は、short (2 バイト Java 文字) に変換します。
Java 文字列は、2 バイト文字の配列です。C の文字列は、通常は UTF-8 エンコードの 1 バイト文字の配列です。純粋な ASCII 文字列は UTF-8 仕様にも適合します。UTF-8 文字列の詳細については、www.unicode.org を参照してください。C プログラマにとって、すべての文字列を 2 バイト Java エンコーディングに変換するのは不便です。JmsString 構造体を使用すると、アプリケーションの要件に応じ、C クライアントでネイティブ文字列または Java 文字列を使用できます。
JmsString では、以下の 2 種類の文字列がサポートされます。
uniOrC という UNISTRING と CSTRING のユニオンには string という文字ポインタがあり、これを NULL で終了する UTF-8 エンコードの C 文字列に使用できます。uniOrC ユニオンは、文字列データと整数長 (バイト) の void ポインタを含む uniString という構造体を提供します。
JmsString の stringType 要素を入力として使用する場合、文字列入力の型に応じて CSTRING または UNISTRING を設定する必要があります。対応するデータ フィールドには、入力として使用する文字列が含まれます。
UNISTRING エンコーディングでは、すべての 2 バイトが単一の Java 文字としてエンコードされます。2 バイト シーケンスはビッグエンディアンです。Unicode では、このエンコーディングを UTF-16BE と呼びます (2 バイト シーケンスがリトルエンディアンの場合は UTF-16LE)。CSTRING エンコーディングでは、UTF-8 でエンコードされた文字列が想定されます。
JmsString の stringType 要素を出力として使用する場合、API が malloc を使用して出力に十分なスペースを割り当てるようにするか、呼び出し側でスペースを割り当てて、返された文字列がそのスペースにコピーされるようにするかを選択できます。ユニオン内の適切なフィールド (string または data) が NULL である場合は、API が malloc を使用して出力に十分なスペースを割り当てます。この方法で割り当てたスペースは、メモリをそれ以上使用しなくなったときに、呼び出し側で free を使用して開放する必要があります。ユニオン内の適切なフィールド (string または data) が NULL でない場合は、JmsString の allocatedSize フィールドに書き込み可能なバイト数が指定されている必要があります。
文字列内に出力全体を格納するための十分なスペースがない場合は、allocatedSize に必要なスペースの量が設定され、呼び出された API が JMS_NEED_SPACE を返します。JmsString の適切なフィールド (string または data) には、allocatedSize バイトを限度として格納できるだけのデータが格納されます。この場合、返される C 文字列データの最後に、NULL 文字が書き込まれる場合と書き込まれない場合があります。次に例を示します。
テキスト メッセージからの文字列出力に 100 バイトを割り当てるため、データ ポインタを設定し、allocatedSize フィールドを 100 に設定したとします。JmsMessageGetTextMessage API は、allocatedSize が 200 に設定された JMS_NEED_SPACE を返します。元の文字列で realloc を呼び出してデータ ポインタをリセットし、関数をもう一度呼び出します。今回は呼び出しが成功し、メッセージ ハンドルから文字列を抽出できます。代わりに、元のバッファを開放して、正しいサイズの新しいバッファを割り当てることも可能です。
割り当てるすべてのリソースも、適切に破棄する必要があります。Java では、参照されなくなったすべてのオブジェクトは、ガベージ コレクションによってクリーンアップされます。しかし、C ではすべてのオブジェクトを明示的にクリーンアップする必要があります。ユーザに提供されたすべての WebLogic JMS C API ハンドルは、明示的に破棄しなければなりません。ハンドルの動詞が、Close で終わる場合と Destroy で終わる場合があることに注意してください。この規約に基づいて、close メソッドを含む Java オブジェクトと含まない Java オブジェクトを区別できます。次に例を示します。
| 注意 : | クローズまたは破棄したハンドルは、再び参照しないようにしてください。 |
Java JMS では、接続を暗黙的にクローズすると、従属するすべてのセッション、プロデューサ、およびコンシューマがクローズされます。WebLogic JMS C API では、接続をクローズしても、従属するセッション、プロデューサ、およびコンシューマはクローズされません。接続をクローズしたら、従属するすべてのハンドルは使用できなくなり、明示的にクローズする必要があります。
WebLogic JMS C API に用意されているヘルパー関数のなかには、WebLogic JMS に存在しないものもあります。これらのヘルパーの詳細については、WebLogic JMS C API の Javadoc を参照してください。次に例を示します。
JmsMessageGetSubclass は JmsMessage ハンドルで動作し、メッセージのサブクラスに対応する整数を返します。JMS では、instanceof を使用してこの機能を実現できます。
WebLogic JMS C API では、username と password に基づく WebLogic 互換性レルム セキュリティ モードがサポートされています。username と password は、InitialContext オブジェクトの作成に使用するハッシュ テーブルの SECURITY_PRINCIPAL および SECURITY_CREDENTIALS フィールドの初期コンテキストに渡す必要があります。
WebLogic JMS C API を実装する際は、以下の点に注意してください。
ULOG.mmddyy (月/日/年) になります。このログ ファイルは、クライアントの NLSPATH、LOCALE、および LANG 環境変数を使用して完全にインターナショナライズされます。gencat ユーティリティまたはホスト プラットフォームの gencat ユーティリティを使用できる。生成されたカタログ ファイルが NLSPATH、LOCALE、および LANG 変数に従って配置されていれば、ログ ファイルにメッセージを書き込む際に翻訳済みのカタログが使用されます。
JMS C クライアント ライブラリを使用する C プログラムは、JVM のエラーによりクラッシュする可能性があります。この問題は、特定の JVM 製品でのみ起きることが知られている断続的な競合状況に関連している可能性があります。エラーの可能性は JVM のバージョンとパッチ レベル、オペレーティング システム、およびハードウェアによって変わります。特に、JMS C クライアント ライブラリは暗黙的に C スレッドを JVM にアタッチしますが、実行後にそのスレッドをデタッチすることができません。推奨される回避策は、以下のとおりです。
コード リスト 13-1 の Java JNI のサンプル コードでは、JVM からスレッドをデタッチする方法を示しています。
#include <jni.h>
...
JavaVM *jvmList[JVM_LIST_SIZE];
jsize retSize = -1;
jint retVal = JNI_GetCreatedJavaVMs(jvmList, JVM_LIST_SIZE, &retSize);
if ((retVal != 0) || (retSize < 1) ) {
printf('ERROR: got %d/%d on JNI_getCreatedJavaVMs\n', retVal, retSize);
return;
}
printf('INFO: got %d/%d on JNI_getCreatedJavaVMs\n', retVal, retSize);
/* 次の行は JVM が 1 つしかないことを前提としている */
(*(jvmList[0]))->DetachCurrentThread(jvmList[0]);
プログラムが直接 JNI 呼び出しを実行しない場合は、Java JNI ライブラリにアクセスするためにコンパイラおよびリンカのパラメータを追加しなければならない場合があります。たとえば、MicroSoft Visual C++ の場合は、次のパラメータを追加します。
  
|