Oracle® Fusion Middleware Oracle WebLogic Server JMS プログラマーズ ガイド 11g リリース 1 (10.3.1) B55536-01 |
|
![]() 戻る |
![]() 次へ |
以下の節では、WebLogic JMS C API を使用する方法について説明します。
WebLogic JMS C API は、WebLogic JMS アプリケーションおよびリソースにアクセスできる C クライアント アプリケーションを作成するためのアプリケーション プログラム インタフェースです。作成した C クライアント アプリケーションでは、Java ネイティブ インタフェース (JNI) (http://java.sun.com/j2se/1.5.0/docs/guide/jni/index.html
) を使用してクライアントサイドの Java JMS クラスにアクセスします。図 13-1 を参照してください。
このリリースの WebLogic JMS C API は、Java JMS 1.1 コードの移植を容易にするため、JMS バージョン 1.1 仕様に準拠しています。詳細については、『Oracle Fusion Middleware Oracle WebLogic Server JMS C API Reference』を参照してください。
ここでは、それぞれの環境で WebLogic JMS C API を使用するためのシステム要件を示します。
WebLogic JMS C API でサポートされるオペレーティング システムの一覧については、『Oracle Fusion Middleware Supported System Configurations』(http://www.oracle.com/technology/software/products/ias/files/fusion_certification.html
) を参照。
使用しているオペレーティング システムでサポートされる JVM。
使用しているオペレーティング システム用の ANSI C コンパイラ。
C クライアント アプリケーションから JMS アプリケーションへの接続には、以下の WebLogic クライアントのいずれかを使用。
WebLogic アプリケーション クライアント (wlfullclient.jar
ファイル)。『Oracle Fusion Middleware Oracle WebLogic Server スタンドアロン クライアント プログラマーズ ガイド』の「WebLogic JarBuilder ツールの使用」を参照してください。
WebLogic JMS シン クライアント (wljmsclient.jar
ファイル)。『Oracle Fusion Middleware Oracle WebLogic Server スタンドアロン クライアント プログラマーズ ガイド』の「WebLogic JMS シン クライアント」を参照してください。
以下の節では、WebLogic JMS C API のアプリケーションを移植または開発する上での原則について説明します。
WebLogic JMS C API は、モジュール形式でコードを実装するハンドル ベースの API です。つまり、アプリケーションでは C コードのハンドルとして Java オブジェクトを実装します。JMS オブジェクトの実装方法の詳細はハンドル内に隠されます。ただし、Java とは異なり、ハンドルを使用して実装したら、対応する Close
または Destroy
メソッドを呼び出してハンドルを明示的に開放する必要があります。「メモリ割り当てとガベージ コレクション」を参照してください。
WebLogic JMS C API から返されるハンドルがスレッド セーフかどうかは、対応する Java 型がスレッド セーフかどうかによって決まります。次に例を示します。
javax.jms.Session
オブジェクトはスレッド セーフではない。これに対応する WebLogic JMS C API ハンドル JmsSession
もスレッド セーフではありません。
java.jms.Connection
オブジェクトはスレッド セーフである。これに対応する WebLogic JMS C API ハンドル JmsConnection
もスレッド セーフです。
同時実行性の制御を C クライアント アプリケーションで管理している限り、WebLogic JMS C API が返すすべてのオブジェクトはどのスレッドでも使用される可能性があります。
注意 : WebLogic JMS C API では、整数のリターン コードを使用します。 |
WebLogic JMS C API での例外は、実行スレッドに対してローカルです。WebLogic JMS C API には、以下の型の例外があります。
JavaThrowable
は、クラス java.lang.Throwable
を表す。
JavaException
は、クラス java.lang.Exception
を表す。
JmsException
は、クラス javax.jms.JMSException
を表す。JMSException
のすべての標準サブクラスは、例外の型記述子内のビットによって判別されます。型記述子は、JmsGetLastException
を呼び出すと返されます。
Java コードと C コードを相互運用する場合、主なタスクの 1 つになるのが C 型から Java 型への変換です。たとえば、short
型は、Java でも C でも 2 バイト エンティティです。以下の型変換では、特別な処理が必要になります。
Integer (int)
は、JMS32I
(4 バイト符号付き値) に変換します。
Long (long)
は、JMS64I
(8 バイト符号付き値) に変換します。
Character (char)
は、short
(2 バイト Java 文字) に変換します。
String
は、JmsString
に変換します。
Java 文字列は、2 バイト文字の配列です。C の文字列は、通常は UTF-8 エンコードの 1 バイト文字の配列です。純粋な ASCII 文字列は UTF-8 仕様にも適合します。UTF-8 文字列の詳細については、www.unicode.org
を参照してください。C プログラマにとって、すべての文字列を 2 バイト Java エンコーディングに変換するのは不便です。JmsString
構造体を使用すると、アプリケーションの要件に応じ、C クライアントでネイティブ文字列または Java 文字列を使用できます。
JmsString
では、以下の 2 種類の文字列がサポートされます。
ネイティブ C string (CSTRING)
JavaString (UNISTRING)
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 オブジェクトを区別できます。次に例を示します。
javax.jms.Session
オブジェクトには close
メソッドが含まれているので、WebLogic JMS C API には JmsSessionClose
関数がある。
javax.jms.ConnectionFactory
オブジェクトには close
メソッドが含まれていないので、WebLogic JMS C API には JmsConnectionFactoryDestroy
関数がある。
注意 : クローズまたは破棄したハンドルは、再び参照しないようにしてください。 |
Java JMS では、接続を暗黙的にクローズすると、従属するすべてのセッション、プロデューサ、およびコンシューマがクローズされます。WebLogic JMS C API では、接続をクローズしても、従属するセッション、プロデューサ、およびコンシューマはクローズされません。接続をクローズしたら、従属するすべてのハンドルは使用できなくなり、明示的にクローズする必要があります。
WebLogic JMS C API に用意されているヘルパー関数のなかには、WebLogic JMS に存在しないものもあります。これらのヘルパーの詳細については、『Oracle Fusion Middleware Oracle WebLogic Server JMS C API Reference』を参照してください。次に例を示します。
JmsMessageGetSubclass
は JmsMessage
ハンドルで動作し、メッセージのサブクラスに対応する整数を返します。JMS では、instanceof
を使用してこの機能を実現できます。
WebLogic JMS C API では、username
と password
に基づく WebLogic 互換性レルム セキュリティ モードがサポートされています。username
と password
は、InitialContext
オブジェクトの作成に使用するハッシュ テーブルの SECURITY_PRINCIPAL
および SECURITY_CREDENTIALS
フィールドの初期コンテキストに渡す必要があります。
WebLogic JMS C API を実装する際は、以下の点に注意してください。
WebLogic Server JMS 拡張 (XML メッセージを含む) はサポートされない。
JMS オブジェクト メッセージはサポートされない。
クライアントでエラーが検知されるとエラー ログが作成される。このエラー ログの名前は ULOG.mmddyy
(月/日/年) になります。このログ ファイルは、クライアントの NLSPATH
、LOCALE
、および LANG
環境変数を使用して完全にインターナショナライズされます。
メッセージ カタログを翻訳する場合は、Windows の gencat
ユーティリティまたはホスト プラットフォームの gencat
ユーティリティを使用できる。生成されたカタログ ファイルが NLSPATH
、LOCALE
、および LANG
変数に従って配置されていれば、ログ ファイルにメッセージを書き込む際に翻訳済みのカタログが使用されます。
クライアント環境では、以下の環境変数を設定できる。
JMSDEBUG
- クライアントからの出力の冗長デバッグを提供する。
JMSJVMOPTS
- クライアントによってロードされた JVM に追加の引数を提供する。
ULOGPFX
- エラー ログ ファイルを配置する場所のパス名とファイル プレフィックスをコンフィグレーションする。
JMS C クライアント ライブラリを使用する C プログラムは、JVM のエラーによりクラッシュする可能性があります。この問題は、特定の JVM 製品でのみ起きることが知られている断続的な競合状況に関連している可能性があります。エラーの可能性は JVM のバージョンとパッチ レベル、オペレーティング システム、およびハードウェアによって変わります。特に、JMS C クライアント ライブラリは暗黙的に C スレッドを JVM にアタッチしますが、実行後にそのスレッドをデタッチすることができません。推奨される回避策は、以下のとおりです。
新しい JVM にアップグレードする。Sun JVM のバージョン 1.5 以降、および JRockit JVM の R27.6 にはこの問題はありませんが、更新された JVM でもデタッチを呼び出すことをお勧めします。Sun JVM でのこの問題の詳細については、http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6219874
を参照してください。
以前に JMS C-API を呼び出した既存の C スレッドから JVM をデタッチするコードをクライアントに追加する。
以前に JMS C-API を呼び出した C スレッドがある場合、プロセス全体が終了する前にそのスレッドを終了しないようにする。
コード リスト 13-1 の Java JNI のサンプル コードでは、JVM からスレッドをデタッチする方法を示しています。
コード リスト 13-1 Java JNI のサンプル コード
#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++ の場合は、次のパラメータを追加します。
-I$(JAVA_HOME)/include
および -I$(JAVA_HOME)/include/win32
(コンパイル)
$(JAVA_HOME)/lib/jvm.lib
(リンク)