Web コンテナーでの統合オブジェクトの使用 (カスタム・サーブレットまたは JSP)

この説明では、統合オブジェクトのメソッドに言及します。このメソッドについては、統合オブジェクトのメソッドを参照してください。

統合オブジェクトを実行する独自の Web プロジェクトを作成できます。ここでは、ZIETrans プロジェクトから別の Web プロジェクトへファイルを移動し、統合オブジェクトを実行するようにそれを設定する手順を示します。この手順を実行すると、1 つ以上の統合オブジェクトを個別にエクスポートして使用することができます。統合オブジェクトのチェーンを使用する場合は、以降の説明に従ってすべてのファイルをコピーし、統合オブジェクトが正しい順序で実行されるようにする必要があります。

ZIETrans 保守は、個別の Web プロジェクトで配置される統合オブジェクトには適用されません。このように使用される統合オブジェクトに保守を適用する最良の方法は、ZIETrans プロジェクト内の統合オブジェクトを更新してから、次の手順に従ってそれらを再エクスポートすることです。

Web プロジェクトが存在しない場合、作成します。これが統合オブジェクトをエクスポートする先のターゲット・プロジェクトになります。統合オブジェクトおよび BeanInfo ソース・ファイルを Web プロジェクトのソース・ディレクトリーにコピーします。IntegrationObject パッケージは保持してください。
Web Content/WEB-INF/profiles にある profiles ディレクトリーを新規プロジェクトの WEB-INF ディレクトリーにコピーします。ディレクトリー全体をコピーすることもでき、ディレクトリー構造を再作成して profiles ディレクトリーの connections サブディレクトリーと macros サブディレクトリーだけをコピーし、統合オブジェクトが使用する接続とマクロだけを反映させることもできます。どちらの方法でも、次のファイルが必要です。
```
WEB-INF\profiles\application.hap
WEB-INF\profiles\connections\ioconn.hco
WEB-INF\profiles\macros\iomacro.hma
```
application.hap ファイルを編集して不必要な情報を削除します。ファイルを右クリックして「オープン先を指定」を選択します。テキスト・エディターに変更を保存すると、非ワークベンチ・エンコードでリソースを保存しようとしているというメッセージが表示される場合があります。これは、ファイルが必須の処理として UTF-8 でエンコードされているためです。「はい」をクリックして先に進みます。必要に応じて、application.hap のバックアップ・コピーを作成してからそれを Web プロジェクトへコピーし、ZIETrans エディターを使用して編集します。
application.hap に組み込む必要のある情報は、接続だけです。
```
<?xml version="1.0" encoding="UTF-8"?>
<application active="true" configured="true" description="" 
				template="Simple1.jsp">
    <connections default="ioconn">
        <connection name="ioconn"/>
			<connection name="io2conn"/>
    </connections>
</application>
```
ZIETrans EAR ファイル内のすべての jar ファイルを、Web プロジェクトの WEB-INF/lib ディレクトリーへコピーすることによって、Web プロジェクトのクラスパスに追加します。
注: また、ZIETrans EAR ファイル内のすべての jar ファイルを独自の EAR ファイルにコピーすることもできます。ただし、このコピーを実行する前に、プロジェクトの Java™ ビルド・パスを明示的に更新してこれらのファイルを指示し、また Web プロジェクトの MANIFEST.MF を更新して CLASSPATH 上のそれらのファイルを含めるように各ファイルを指示する必要があります。
jar ファイルを追加したディレクトリーと同じディレクトリーに runtime.properties ファイルをコピーします。ログ・ディレクトリーの場所は、runtime.properties ファイルと同じディレクトリーになります。
注: プロジェクトをローカル・テスト環境でテストする場合は、runtime-debug.properties ファイルもコピーします。

サーブレットまたは JSP で ZIETrans ランタイムを開始するには、3 つの関数呼び出しを追加します。

// Initialize and activate the ZIETrans runtime RAS functions,
//  including tracing, logging, PII retrieval, locale.
com.ibm.hats.util.Ras.initializeRas(getServletConfig());
  
// Create the license manager
com.ibm.hats.util.LicenseManager.getInstance(); 
  
// Initialize Host Publisher / connection management runtime
com.ibm.hats.runtime.connmgr.Runtime.initRuntime(getServletConfig());

これらの手順の実行後は、統合オブジェクトを Web プロジェクト内で通常の Java™ Bean として使用できます。

統合オブジェクトを起動するサーブレットを書き込むには、次の手順を実行します。

コンストラクターを呼び出して、統合オブジェクトのインスタンスを作成します。
統合オブジェクトの setter メソッドを呼び出して、入力変数のプロパティーを設定します。setter メソッドの命名規則は次のとおりです。
```
void setXyz(String)
```
ここで、Xyz は入力変数の名前です。
統合オブジェクトの作成時に指定した接続プールとは別の接続プールを使用することもできます。別の接続プールを指定するには、使用する接続プールの名前を指定して以下のメソッドを呼び出します。
```
void setHPubStartPoolName(String)
```
統合オブジェクトを起動してタスク (マクロの実行など) を実行します。
```
void doHPTransaction(HttpServletRequest, HttpServletResponse)
```
エラーを調べます。統合オブジェクトにエラーがある場合、doHPTransaction(HttpServletRequest, HttpServletResponse) メソッドは例外 (タイプ com.ibm.HostPublisher.IntegrationObject.BeanException) をスローします。
統合オブジェクトが JSP によって呼び出されると、JSP プロセッサーは例外をキャッチし、page ディレクティブの errorPage="errorPageName" 属性で指定されたエラー・ページにブラウザーをリダイレクトします。ZIETrans デフォルト・エラー・ページの DefaultErrorPage.jsp に例があるので、参照してください。
統合オブジェクトがカスタム・サーブレットによって呼び出される場合は、スローされた例外をコードがキャッチする必要があります。
```
try {
     integrationObject.doHPTransaction(request, response);
    } catch (Exception e) {
    // Handle the exception condition and recover
    }
```
統合オブジェクトからの結果を要求します。
- 次のメソッドのいずれかを呼び出して、出力変数の値を検索します。
  - 単純なテキスト
```
String getAbc()
```
    ここで、Abc は出力変数の名前です。
  - テーブル
    - 結果の列全体を取得するには、次のメソッドを呼び出します。
```
String[] getAbc()
```
      ここで、Abc は出力変数の名前です。
    - 結果の列から単一値を取得するには、次のメソッドを呼び出します。
```
String getAbc(int) throws ArrayIndexOutOfBoundsException
```
      ここで、Abc は出力変数の名前で、int は必要な値の索引です。この手順を配列で繰り返していくと、配列の終わりに達したときに、メソッドによって ArrayIndexOutOfBoundsException 例外がスローされます。
- 次のメソッドを呼び出すと、統合オブジェクトの作成に使用したアプリケーションに関係なく、出力データを XML 形式で取り出すことができます。
```
String getHPubXMLProperties()
```
  これは、統合オブジェクトのプロパティーと値を XML 形式のストリングとして戻します。
必要に応じて値を取り出せるよう、すべての統合オブジェクトの入力変数に、各 setter メソッドに対応する getter メソッドが含まれています。これらのメソッドのシグニチャーは次のようになります。
```
void getXyz(String)
```
ここで、Xyz は入力変数の名前です。
入力したデータから生成される入力変数名または出力変数名を確認するには、統合オブジェクトの BeanInfo java ファイル内で定義されたプロパティーを参照します。統合オブジェクトの BeanInfo .java ファイルは、IntegrationObject パッケージ内のプロジェクトのソース・フォルダーにあります。ZIETrans Toolkit では、BeanInfo ファイルが表示されるのは「ナビゲーター」ビューだけです。