Java ゲートウェイの概要

前提条件

Java ゲートウェイ・サーバは JVM 環境で実行します。これは、Ensemble と同じマシンにインストールすることも、別のマシンにインストールすることもできます。Java ゲートウェイを実行するマシン上で、以下の設定手順を完了してください。

1. Java ランタイム環境をインストールします (例 : JRE 1.7.0_67)。

2. JRE のインストール・ディレクトリの場所をメモしておきます。これは、サブディレクトリ bin と lib が含まれているディレクトリです。

   この値は、JAVA_HOME 環境変数に使用します。例 : c:\Program Files\Java\jre7

   この情報は、あとでプロダクションを構成する際に使用します。

3. Java バージョンもメモしておきます。Java バージョンが不明の場合は、DOS ウィンドウを開き、Java インストール先の bin サブディレクトリに移動して、以下のコマンドを入力します。

   java.exe -version
   

   

   使用しているプラットフォームに応じて、以下のような出力が表示されます。

   java version "1.7.0_67"
   Java(TM) SE Runtime Environment (build 1.7.0_67-b24)
   Java HotSpot(TM) 64-Bit Server VM (build 23.19-b22, mixed mode)
   
   

   

環境変数を設定する必要はありません。JVM にアクセスするために、Ensemble ではプロダクションに含まれる情報を使用します。

ゲートウェイの開始と停止

Java ゲートウェイを使用するには、何らかのメカニズムを使用して Java ゲートウェイ・サーバを起動し、Java ゲートウェイ・サーバが稼働しているホスト名を Ensemble に通知する必要があります。以下のいずれかの方法で Java ゲートウェイ・サーバを起動できます。

• 自動 ： プロダクションに Java ゲートウェイ・ビジネス・サービスを追加します。プロダクションを開始すると、Java ゲートウェイ・サーバが起動します。

• 手動 ： ビジネス・サービス・メソッド StartGateway() を呼び出します。

• 手動 ： ターミナル・コマンド・プロンプトでコマンドを入力します。

起動した Java ゲートウェイ・サーバは、明示的にシャットダウンするまで稼働します。以下のいずれかの方法で Java ゲートウェイ・サーバを停止できます。

• 自動 ： プロダクションに Java ゲートウェイ・ビジネス・サービスを追加します。プロダクションを停止すると、Java ゲートウェイ・サーバが停止します。

• 手動 ： ビジネス・サービスの StopGateway() メソッドを呼び出して行います。

• 手動 ： Java ゲートウェイ API (EnsLib.JavaGateway.JavaGatewayOpens in a new tab) の %Shutdown() メソッドを呼び出して行います。

Ensemble プロダクションで Java ゲートウェイを使用する場合は、プロダクションを開始すると Java ゲートウェイ・サーバが起動し、プロダクションをシャットダウンすると Java ゲートウェイ・サーバも停止するようにすることをお勧めします。プロダクションに Java ゲートウェイ・ビジネス・サービスを追加すると、自動的にこの動作が行われます。

接続と切断

Java ゲートウェイ・サーバが起動した後、Java クラス・メソッドを呼び出す Ensemble セッションは、それぞれ Java ゲートウェイ・サーバとの専用の接続を作成する必要があります。Ensemble と Java ゲートウェイ・サーバを接続するには、ビジネス・サービスの ConnectGateway メソッドまたは Java ゲートウェイ API の %Connect() メソッドを呼び出します。

Connect コマンドは、以下の図 "Java ゲートウェイ・ワーカー・スレッドへの接続" にあるシーケンシャル・イベント 1、2、および 3 のチェーンをトリガします。

1. Caché Basic または ObjectScript のコードで接続要求を送信します。

2. Java ゲートウェイは、この要求を受信するとワーカー・スレッドを開始します。このスレッドで Java クラスのメソッドが続いて実行されます。

3. この Java ゲートウェイ・ワーカー・スレッドと対応する Ensemble セッションとの間の接続は、明示的に切断されるまで、確立した状態に維持されます。

ワーカー・スレッドを確立した Caché Basic または ObjectScript コードは、終了する際に明示的にそのスレッドを切断する必要があります。明示的に切断しないと、接続に割り当てられたポートが “使用中” のままになり、他の接続で使用できなくなります。Caché Basic または ObjectScript コードでは、Java ゲートウェイ API メソッド %Disconnect() を呼び出すことによってそのスレッドを切断できます。

Java ゲートウェイのモード

Java ゲートウェイには、Java オブジェクトのメイン操作モードとして次の 2 つがあります。

• プロキシ・オブジェクト・モード — Ensemble 内から Java オブジェクトをステートフルに操作できます。

• ステートレス・サービス・モード — Ensemble 内からシンプルな Java メソッド呼び出しを実行して、結果を返すことができます。

プロキシ・オブジェクト・モード

プロキシ・オブジェクト・モードでは、Ensemble と Java コンポーネントの間で相互運用を簡単に実現できます。このモードでは、Java ゲートウェイは外部 Java オブジェクトをインスタンス化して、Ensemble 内のネイティブ・オブジェクトと同じようにその外部オブジェクトを操作できます。

プロキシ・オブジェクト・モードのアーキテクチャ

Ensemble 内で、外部 Java オブジェクトは、“wrapper” クラスまたは “proxy” クラスによって表されます。他の Ensemble オブジェクトと同様にプロキシ・オブジェクトが現れて動作しますが、プロキシ・オブジェクトは、TCP/IP 接続を介してローカルまたはリモートに Java 仮想マシン (JVM) に対してメソッド呼び出しを発行できます。プロキシ・オブジェクト上でメソッド呼び出しがあると、JVM に存在する適切なクラス・メソッドがトリガされます。

Java ゲートウェイを使用して、カスタム Java コンポーネント用にプロキシ Caché クラスを作成できます。ただし、Java ゲートウェイの最も優れた機能は、Java Database Connection (JDBC)、Java Message Service (JMS)、Enterprise Java Beans (EJB)、Java Connector Architecture (JCA) などの Java インタフェース仕様全体に対して、容易にプロキシ・マッピングを作成できることです。Ensemble はこのマッピングを使用して、これらのいずれかの仕様に準拠するあらゆる実装と連携できます。

一般に、Java ゲートウェイを活用するには、必要な機能のみを公開する小型のラッパ・クラスを構築し、このラッパのプロキシを作成します。これによって、Ensemble と Java との間の API をきわめてクリーンなものとすることができ、高度な機能をプロキシ・オブジェクトにマッピングする際に発生しやすい多くの問題を排除できます。

以下の図に、プロキシ・オブジェクト・モードを使用している場合の Ensemble と Java ゲートウェイの実行時の概念を示します。

Java ゲートウェイのオペレーショナル・モデル

Java ゲートウェイ・サーバは JVM で実行します。Ensemble と JVM は、同じマシンでも異なるマシンでも実行できます。前述の図中の項目 (1)、(2)、および (3) は、この運用モデルを設定するコマンドによって確立される関係を表しています。

1. Start

2. Connect

3. Import

この章で後出する各節では、Java コードの Ensemble プロキシ・クラスを設定するためにこれらのコマンドがどのように機能するか、およびこれらの関係が設定された後にプロキシがどのように機能するかを説明します。詳細は、“プロキシ呼び出しシーケンス” を参照してください。

Java クラスのインポート

Java ゲートウェイ API の %Import() メソッドは、下図に示す連続イベント (1)、(2)、および (3) のチェーンをトリガします。

Java クラスのインポート

1. Ensemble セッションがインポート要求を送信します。

2. 要求を受信した Java ゲートウェイ・ワーカー・スレッドは、Java の指定されたパッケージおよびクラスをイントロスペクトします。

3. 新しい Java クラス、変更された Java クラス、または Ensemble 側にプロキシ・クラスがない Java クラスが見つかると、スレッドは、その Java クラスの新しいプロキシ・クラスを生成します。

Important:

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

プロキシ呼び出しシーケンス

Ensemble プロキシ・メソッドへの呼び出しによって、以下の一連のイベントが開始されます。

1. すべての Ensemble プロキシ・パラメータが、ワイヤ上にマーシャルされます。ほとんどの場合、これは、出力 TCP/IP バッファにパラメータを書き込むだけの非常に簡単なプロセスです。

2. メッセージは、TCP/IP 接続を介して Java ゲートウェイ・ワーカー・スレッドに送信されます。メッセージには、メソッド名、マーシャルされたパラメータ、および、インスタンスによってはその他の小規模なロードが含まれます。

3. Java ゲートウェイ・ワーカー・スレッドはこのメッセージを使用し、パラメータをアンマーシャルします。次いで、適切なメソッドまたはコンストラクタの呼び出しを検索し、Java リフレクションを使用して呼び出します。オーバーロードされたメソッドが指定されている場合、ゲートウェイでは、メソッドのオーバーロード・アルゴリズムを使用して、適切なバージョンの Java メソッドを検索します。詳細は、“マッピング仕様” の章の “オーバーロードされたメソッド” を参照してください。

4. メソッド呼び出しに結果が存在する場合は接続上でマーシャルされ、同じ TCP/IP チャネルを介して Ensemble 側に返されます。

5. Ensemble プロキシはこの応答を使用し、戻り値があればアンマーシャルして、メソッド呼び出しを終了します。

ステートレス・サービス・モード

ステートレス・サービス・モードでは、特定の Java サービスに対するシンプルで効率的な呼び出しを実行できます。Java サービスは、com.intersys.gateway.Service インタフェースの任意の実装です。次のメソッドのみを実装する必要があります。

public byte[] execute(byte[] args) throws Throwable;

このメソッドはバイト配列を受け取って、必要なサービスを実行して、byte[] 結果を生成します。上記の Java サービス・メソッドを Ensemble から呼び出すためには、次の %Net.Remote.Gateway メソッドを呼び出します。

Method %ServiceRequest(serviceName As %String, arguments As %String, ByRef response As %String) As %Status

ここで、serviceName は実装元 Java サービス・クラスの名前であり、arguments は Java サービスの args に対応しています。

response は Java サービスの result に対応しています。arguments と result は、Caché 上では %Strings として表現され、Java 側ではバイト配列として表現されるため、このような形でシリアル化されたいずれの値も基盤となるエンジンで受け付けられます。

%Net.Remote.Gateway に対する次の静的メソッドを使用すると、外部 Java サービスを呼び出すことができます。

ClassMethod %RemoteService(host As %String, port As %Integer, serviceName As %String, arguments As %String, additionalClassPaths As %ListOfDataTypes = "") As %String;

Note:

Java サービスの実装には、Ensemble へのコールバックは決して含めないでください。この新たに追加されたコンポーネントは再入可能として設計されていないからです。

GSON を使用したシンプルな実装については、"ステートレス・サービス・モードの例" を参照してください。