プロダクションでの Java ゲートウェイの使用

Java ゲートウェイのビジネス・サービスの追加

コマンド・プロンプトから Java ゲートウェイ・サーバを起動することもできますが、Ensemble プロダクションで Java ゲートウェイを使用する最も簡単な方法は、プロダクションのビジネス・サービスとして EnsLib.JavaGateway.ServiceOpens in a new tab クラスを追加し、構成する方法です。Ensemble を実行しているローカル・マシン上に Java ゲートウェイ・サーバがある場合のみ、この方法を使用できます。

それ以外の場合は、コマンド・プロンプトから Java ゲートウェイ・サーバを起動する必要があります。詳細は、“コマンド・プロンプトの使用法” を参照してください。

プロダクションにビジネス・サービスとして EnsLib.JavaGateway.ServiceOpens in a new tab クラスを追加するには、管理ポータルの Ensemble, プロダクション構成 ページを使用します。以下の手順は、構成手順をまとめたものです。

1. [サービス] 列の横にある追加アイコン () をクリックしてビジネス・サービス・ウィザードを開始します。

2. [すべてのサービス] タブをクリックし、[サービス・クラス] で EnsLib.JavaGateway.ServiceOpens in a new tab を選択します。その他の設定については、デフォルトの値を使用できます。

3. [OK] をクリックすると、更新されたプロダクション・ダイアグラムが表示されます。

4. 新しい Java ゲートウェイ・ ビジネス・サービス構成項目をクリックし、[設定] タブをクリックして、これを構成します。

Ensemble プロダクション内のほとんどのビジネス・ホストと異なり、EnsLib.JavaGateway.ServiceOpens in a new tab は、Ensemble メッセージを処理しません。

Java ゲートウェイのビジネス・サービスの設定

以下の Java ゲートウェイ・サービス固有の設定が [設定] タブに表示されます。設定名をマウスでポイントすると、その設定について "クラスリファレンス" に記載されている内容をヘルプ・テキストとして表示できます。また、設定名をクリックすると、別のポップアップ・ウィンドウにこのヘルプ・テキストを表示することもできます。

ClassPath

JVM の起動時に引数として渡されるファイルが保存されたクラス・パス。Java ゲートウェイ経由でインポートするクラスが定義されたすべての jar ファイルを含める必要があります。Java ゲートウェイで使用される InterSystems の .jar ファイルは含める必要がありません。スペースまたは複数のファイルを含むファイル・パスを指定する場合は、クラスパスを引用符で囲って、プラットフォームに適切なセパレータを付ける必要があります。

Microsoft Windows プラットフォーム用のファイル・パスをセミコロンで区切ったリストの例を以下に示します。

C:\Library\Ensemble\mygateway.jar;"C:\Jar files\utilities.jar"

クラスパスの追加のパスは、EnsLib.JavaGateway.AbstractOperationOpens in a new tab から派生したビジネス・オペレーションの中で指定できます。そのクラスのプロパティ AdditionalPaths を参照してください。

その他の設定はほとんどの Ensemble ビジネス・サービスに共通しています。"Ensemble プロダクションの構成" の “すべてのビジネス・サービスに含まれる設定” を参照してください。

Java ゲートウェイ・ビジネス・サービスを追加および構成すると、以下のように、Java ゲートウェイが自動的に管理されます。

• プロダクションを開始すると、Java ゲートウェイ・ビジネス・サービスでは、構成ページで指定した設定で Java ゲートウェイ・サーバのインスタンスが開始されます。

• プロダクションが停止の信号を受信すると、Java ゲートウェイ・ビジネス・サービスが Java ゲートウェイ・サーバにアタッチして停止を指示します。

詳細は、"クラス・リファレンス" で EnsLib.JavaGateway.ServiceOpens in a new tab を参照してください。

ビジネス・サービス・メソッドの呼び出し

Java ゲートウェイ・ビジネス・サービスは、Java ゲートウェイ・エンジンの開始、接続、停止に使用できるメソッドを提供します。Java ゲートウェイ・ビジネス・サービスをプロダクションのメンバとして構成した後、以下のメソッドを Ensemble コードから呼び出すことができます。

• StartGateway()

• ConnectGateway()

• StopGateway()

これらのメソッドの詳細は、"Class Reference" で EnsLib.JavaGateway.ServiceOpens in a new tab のエントリを参照してください。

StartGateway() メソッド

EnsLib.JavaGateway.Service:StartGateway(pJavaHome As %String,
     pClassPath As %String,
     pJVMArgs As %String,
     pPort As %String,
     pLogFile As %String = "",
     pDebug As %Boolean = 0,
     pJDKVersion As %String = "",
     ByRef pDevice As %String = "",
     pAddress As %String = "127.0.0.1",
     pCmdLine As %String = "")

このクラス・メソッドは、指定された引数を使用して Java ゲートウェイ・サーバを起動します。pDebug が真の場合、JVM が開始されると、TCP を介してデバッガをアタッチできます。pLogFile が有効なファイル名を指定する場合、ゲートウェイのアクティビティに関するメッセージがこのファイルに書き込まれます。このメッセージでは、サーバへの接続が開かれたことの通知、閉じられたことの通知、Java クラスを Ensemble プロキシ・クラスにマッピングするときに生じた問題 (存在する場合) などを扱います。

ConnectGateway() メソッド

EnsLib.JavaGateway.Service:ConnectGateway(pEndpoint As %String,
     ByRef pGateway As EnsLib.JavaGateway.JavaGateway,
     pDebug As %Boolean = 0,
     pTimeout As %Integer = 5,
     pAdditionalPaths As %String = "")

このクラス・メソッドは、指定された pEndpoint (ホスト名 : ポート : ネームスペース) の Java ゲートウェイ・サーバに接続し、EnsLib.JavaGateway.JavaGatewayOpens in a new tab クラスのインスタンスを返します。pDebug が真の場合、Eclipse や JSwat などの Java デバッガがアタッチできるように、接続のタイムアウトが長くなります。

StopGateway() メソッド

EnsLib.JavaGateway.Service:StopGateway(pPort As %String,
     pAddress As %String = "127.0.0.1",
     pTimeout As %Integer = 5)

このクラス・メソッドは、Java ゲートウェイ・サーバに接続し、サーバをシャットダウンします。

ビジネス・オペレーションの作成

Ensemble プロダクション用に Java ゲートウェイ指向のビジネス・オペレーションを構築するための基礎として、抽象ビジネス・オペレーションを使用できます。EnsLib.JavaGateway.AbstractOperationOpens in a new tab 抽象クラスのサブクラスを定義し、適切なメッセージ・ハンドラを実装するだけでこの処理が可能です。

GetConnection() メソッドを呼び出して接続を確認し、必ず GetConnection() メソッドによって返されたゲートウェイ接続オブジェクトを介して Java ゲートウェイ接続オブジェクトにアクセスします。以下に例を示します。

 Set tSC = ..GetConnection(.tJavaGateway)
     If $$$ISOK(tSC)
     {
        // Now, start using the tJavaGateway instance ...
     }  

このメソッドは、プロキシ・クラスで使用するプライベート・ゲートウェイ接続オブジェクトを返します。

Java ゲートウェイの IP アドレスおよびポートは、プロダクションにビジネス・オペレーションを追加するときに、そのビジネス・オペレーションの設定で構成できます。Java ゲートウェイのインスタンスへの接続は、OnInit() で作成され、OnTearDown() で閉じられます。ビジネス・オペレーション・クラスでこれらのメソッドを上書きして、独自のセットアップおよびティアダウン手順を実装できます。

これらのメソッドおよび AdditionalPaths、Address、 ConnectTimeout、Port の各プロパティの詳細は、"Class Reference" で EnsLib.JavaGateway.AbstractOperationOpens in a new tab のエントリを参照してください。

API メソッドの呼び出し

ビジネス・サービスへの接続、ビジネス・サービスからの切断、および停止に加えて、EnsLib.JavaGateway.JavaGatewayOpens in a new tab クラスでは以下のメソッドも使用できます。ビジネス・サービス・モデルが不適切な状況の場合に、これらを使用できます。

EnsLib.JavaGateway.JavaGatewayOpens in a new tab クラスは、以下の種類のメソッドを提供します。

• Java ゲートウェイ・サーバに接続する %Connect()、Java ゲートウェイ・サーバから切断する %Disconnect()、および Java ゲートウェイ・サーバをシャットダウンする %Shutdown() の各 API メソッド。

• JVM から Java クラスまたはパッケージをインポートし、Ensemble 側に必要なすべてのプロキシ・クラスを生成する、%Import メソッド。

• %Connect()、%Import()、および %Disconnect()　に対する呼び出しを組み合わせた %ExpressImport() メソッド。

• ユーティリティ・メソッドの %ClassForName() および %GetAllClasses()。

%Connect() メソッド

Method %Connect(host As %String,
                port As %Integer,
                namespace As %String,
                timeout As %Numeric = 5,
                additionalClassPaths As %ListOfDataTypes = "")
     As %Status [ Final ]

%Connect() メソッドは、Java ゲートウェイ・エンジンとの接続を確立します。以下の引数を使用できます。

引数	説明
host	Java ゲートウェイ・サーバを実行しているマシンを特定します。
port	プロキシ・クラスが Java クラスと通信するポート番号。
namespace	Ensemble ネームスペース。
timeout	タイムアウトとなるまで待機する秒数。デフォルトは 5 です。
additionalClassPaths	オプション — 追加のクラス・パスを指定する場合にこの引数を使用します。このパスはシステム・クラス・ローダに追加され、セッションが終了するまで使用できます。

%Disconnect() メソッド

Method %Disconnect() As %Status [ Final ]

%Disconnect() メソッドは、Java ゲートウェイ・エンジンへの接続を閉じます。

%Shutdown() メソッド

Method %Shutdown() As %Status [ Final ]

%Shutdown() メソッドは、Java ゲートウェイ・エンジンをシャットダウンします。

%Import() メソッド

Method %Import(javaClass As %String,
               ByRef imported As %ListOfDataTypes,
               additionalClassPaths As %ListOfDataTypes = "",
               exclusions As %ListOfDataTypes = "")
    As %Status [ Final ]

%Import() メソッドは、必要なすべてのプロキシ・クラスを作成およびコンパイルすることによって、指定された javaClass およびそのすべての依存関係をインポートします。%Import() メソッドは、生成された Ensemble プロキシ・クラスのリストを imported で参照渡しで返します。Java クラス定義がどのように Ensemble プロキシ・クラスにマッピングされるかについての詳細は、“マッピング仕様” の章を参照してください。

%Import() は、一回限りのスタートアップ・オペレーションです。初めて Ensemble プロキシ・クラスを生成する場合にのみ、呼び出す必要があります。再度必要になるのは、Java コードをリコンパイルし、プロキシを再生成する場合のみです。

Note:

以前のバージョンとは異なり、実行時に接続するたびに %Import() を呼び出す必要はありません。

以下の節では、%Import() メソッドについて詳しく説明します。

• %Import 引数

• インポートの依存関係と除外

%Import() 引数

%Import() を呼び出す前に、%ListOfDataTypesOpens in a new tab 引数の additionalClassPaths および exclusions を用意します。つまり、引数ごとに新しい %ListOfDataTypesOpens in a new tab オブジェクトを作成し、その Insert() メソッドを呼び出してリストの内容を設定します。

オプションの additionalClassPaths 引数を使用して追加の CLASSPATH 引数を指定できます。例えば、Java ゲートウェイ経由でインポートするクラスを含む jar ファイルの名前を指定できます。リストの各要素は、追加クラス・パスの個々のエントリに対応している必要があります。そのためには以下の形式にする必要があります。

"rootdirectory\..."
"rootdir\...\myjarfile.jar"

追加パスは、システム・クラス・ローダに追加され、セッションの終了時まで使用できます。CLASSPATH 引数ではワイルドカードを使用できません。名前の全体を指定する必要があります。

Note:

このトピックの例では Windows のパス名規則を使用していますが、その他のサポートされている Ensemble プラットフォームでも機能します。

インポートの依存関係と除外

Java クラスを Ensemble プロキシ・クラスにマッピングして Ensemble にインポートするときに、Java ゲートウェイでは、プロパティとして参照されているクラスおよび引数リストで参照されているすべてのクラスを含め、指定した Java クラス内で見つかったすべてのクラス依存関係がループ処理されます。言い換えると、Java ゲートウェイは、指定されたクラスを正しくインポートするために必要なすべてのクラス依存関係のリストを収集し、その依存関係リストを調べて、必要なすべてのプロキシ・クラスを生成します。

Important:

Java ゲートウェイのインポート機能では、public とマークされたクラス、メソッド、およびフィールドのみをインポートできます。

このプロセスから除外したいパッケージおよびクラス名の接頭語のリストを指定することによって、このプロセスを制御できます。このような状況はまれですが、インポートするクラスを制御できる柔軟性があります。Java ゲートウェイでは、sun.*、COM.rsa.*、ほとんどの com.sun.* のような、パッケージの小さなサブセットが自動的に除外されます。

以前のリリースの Java ゲートウェイでは、どの com.sun.* クラスであってもインポートすることはできませんでした。これは、一部が Java 内部クラスであるためです。しかし、以降のリリースではこの制限が緩和され、com.sun.* クラス (com.sun.tools.javac.Main および com.sun.messaging を含む) もインポートできるようになっています。

%ExpressImport() メソッド

ClassMethod %ExpressImport(name As %String,
                           port As %Integer,
                           host As %String = "127.0.0.1",
                           silent As %Boolean = 0,
                           additionalClassPaths As %ListOfDataTypes = "",
                           exclusions As %ListOfDataTypes = "")
     As %ListOfDataTypes

%ExpressImport() は、%Connect()、%Import()、および %Disconnect() への呼び出しを組み合わせた、1 つの手順の便利なクラス・メソッドです。このメソッドは、生成されたプロキシのリストを返します。また、silent 引数を 0 に設定している場合は、そのリストがログに記録されます。name 引数は、クラスまたは jar ファイルのセミコロン区切りリストです。

%ClassForName() メソッド

Method %ClassForName(className As %String)
     As %Status [ Final ]

Caché Basic または ObjectScript コードで Java メソッド Class.forName を呼び出して Java クラスをロードする必要がある場合は、Java ゲートウェイ API メソッド %ClassForName() を使用して呼び出しを行います。この引数は、クラスの名前です。Java クラス名ではなく、Ensemble プロキシ・クラス名を引数として使用します。

%GetAllClasses() メソッド

Method %GetAllClasses(jarFileOrDirectoryName As %String,
                      ByRef allClasses As %ListOfDataTypes)
     As %Status

このメソッドでは、最初の引数 jarFileOrDirectoryName で指定した jar ファイルまたはディレクトリにあるすべてのパブリック・クラスのリストが ByRef 引数 allClasses に返されます。

コマンド・プロンプトの使用法

通常は、プロダクションのメンバとして EnsLib.JavaGateway.ServiceOpens in a new tab ビジネス・サービスを構成することによって、Java ゲートウェイ・サーバを自動的に起動および停止します。この構成を行うと、Java ゲートウェイ・サーバはプロダクションと共に自動的に起動および停止します。クラス・メソッド StartGateway() を利用して、手動で Java ゲートウェイ・サーバを起動することもできます。

ただし、開発時やデバッグ時、または Ensemble と Java ゲートウェイ・サーバを別々のマシンで実行している場合は、コマンド・プロンプトから Java ゲートウェイ・サーバを起動すると便利な場合があります。そのためには、以下のコマンドを入力します。このコマンドは、全体を 1 行で入力します。このコマンド内で、サービス名の長さは最大 255 文字までです。

java -classpath classpath com.intersys.gateway.JavaGateway portlogfile

JMS モードで Java ゲートウェイを起動するコマンド・ラインは、Java ゲートウェイを起動するコマンド・ラインに似ています。コマンドの JavaGateway を JMSGateway に置き換え、コマンド全体を 1 行で記述します。このコマンドでは、サービス名の長さは最大 255 文字までです。

java -classpath classpath com.intersys.gateway.JMSGateway portlogfile

Java ゲートウェイを JMS と共に使用している場合にのみ、JMS ゲートウェイを開始する必要があります。それ以外の場合は、Java ゲートウェイを開始するだけです。

Java ゲートウェイ・ウィザードの使用法

スタジオに組み込まれた Java ゲートウェイ・ウィザードを使用して、Java クラスや .jar ファイル全体をインポートできます。ウィザードを開始するには、以下の手順を実行します。

1. スタジオを起動します。

2. [ツール] メニューで [アドイン] をクリックします。

3. [Java ゲートウェイ・ウィザード] をクリックして、Java ゲートウェイ・ウィザードのダイアログを開始します。

4. [Jarファイル] をクリックし、パス名を入力するか、[参照] をクリックして適切な .jar ファイルを検索します。例えば、以下は Ensemble に含まれるサンプル jar ファイルの名前です。ここで、MyEnsemble はインストール・ディレクトリの名前を示しています。

   C:\MyEnsemble\dev\java\samples\remote\test\javagatewaysamples.jar
   

   または

   [クラス名] をクリックし、完全パス名を入力するか、[参照] をクリックして適切な Java クラス・ファイルを検索します。例えば、以下は Ensemble に含まれるサンプル Java クラスの名前です。ここで、MyEnsemble はインストール・ディレクトリの名前を示しています。

   C:\MyEnsemble\dev\java\samples\remote\test\Address.class
   

5. Java ゲートウェイ・サーバの [ホスト] および [ポート] を入力します。

6. ダイアログの指示に従って、[クラスパス] および [除外] を入力します。

7. 手順 4 で [Jar ファイル] を選択した場合は、[表示] をクリックすると jar ファイルにあるクラスのリストを表示できます。

   または

   手順 4 で [クラス名] を入力した場合は、次の手順に進みます。

8. [インポート] をクリックして、Ensemble プロキシ・クラスを生成します。各プロキシ・クラスが生成されると、ウィザードにクラス名が表示されます。

9. インポート操作が完了したら、[終了] をクリックしてウィザードを終了します。

エラーのチェック

Java ゲートウェイには、以下のようなエラー・チェック機能が用意されています。

• Ensemble プロキシ・メソッドの実行中にエラーが発生した場合、そのエラーの多くは、元の Java メソッド自体または Java ゲートウェイ・エンジンに起因する Java の例外です。これが発生すると、<ZJGTW> エラーがトラップされます。

• %Import() や %Connect()　などの Java ゲートウェイ API メソッドは、通常の Ensemble %StatusOpens in a new tab 変数を返します。

どちらの場合も、Java クラスから返された最新のエラー値 (多くの場合、スローされた実際の Java の例外) が、Ensemble ローカル変数 %objlasterror で記録されます。

以下のように、$system.OBJ.DisplayError() を呼び出すことによって、エラー・メッセージの完全なテキストを取得できます。

 Do $system.OBJ.DisplayError(%objlasterror)

トラブルシューティング

Java ゲートウェイの使用中に問題が発生する場合は、ログ機能を常に有効にしておくことをお勧めします。これによって、インターシステムズのスタッフは問題を効率よくトラブルシューティングできます。ログ機能を有効にするには、Java ゲートウェイの開始時にログ・ファイルを指定します。コマンドラインから起動する場合、ビジネス・サービスを構成して起動する場合、StartGateway() ビジネス・サービス・メソッドを使用して起動する場合のいずれでも、この方法でログ機能を有効にすることができます。

デバッグやテストに Java ゲートウェイを使用しているときに、場合によって、ターミナル・セッションが使用できなくなるという問題やターミナル・ウィンドウにエラーを書き込む問題が発生することがあります。原因として、Java ゲートウェイ接続の終了時に、適切に切断されなかったことが考えられます。この場合、その接続に使用したポートが開いたままになっている可能性があります。

この状況になっていると考えられる場合は、ポートを閉じるために、ターミナル・プロンプトで以下のコマンドを入力します。

 Close "|TCP|port"

ここで port は、閉じるポートの番号です。