この章では、統合オブジェクト Java™ コードのカスタマイズ、統合オブジェクト・テンプレート (その選択および変更を含む)、WebSphere® Java EE アプリケーションでの統合オブジェクトの使用、および接続管理 API について説明します。
統合オブジェクトをマクロから作成する場合や、マクロの保存時に HATS によって統合オブジェクトが自動的に作成される場合、HATS は統合オブジェクト・テンプレート を使用して統合オブジェクトを作成します。これらのテンプレートには、各統合オブジェクトに組み込まれている Java コードが含まれています。
HATS を使用すると、 Java コード・レベルで、基礎となるサブシステムとの統合オブジェクトの対話方法を変更し、追加機能を実行することができます。
Java コード・テンプレートには、デフォルト・テンプレートとカスタマイズ可能テンプレートの 2 つのタイプがあります。テンプレートは、次のディレクトリーに保管されています。
<shared_install_directory>\plugins\com.ibm.hats_nnn\predefined\ IOTemplates\
ここで、shared_install_directory は、IBM® Installation Manager を使用して HATS オファリングをインストールした共用リソース・ディレクトリーです。nnn は、HATS のバージョンおよびビルド・レベルです。
デフォルト・テンプレートは、HPubTemplateHODBean.Default と HPubTemplateHODBeanInfo.Default です。カスタマイズ可能テンプレートは、HPubTemplateHODBean.Customize と HPubTemplateHODBeanInfo.Customize です。デフォルト・テンプレートには、HATS および Host On-Demand コードとは別個の Java コードが含まれています。HATS または Host On-Demand コードが機能拡張またはサービス用に変更されていれば、デフォルト・テンプレートを使用して作成した統合オブジェクトを再コンパイルおよび再配置する必要はありません。
デフォルト・テンプレートは、スーパークラスからメソッドを呼び出します。カスタマイズ可能テンプレートには、カスタマイズできるメソッドが含まれています。HPubTemplateHODBean.Customize テンプレートを変更して、統合オブジェクトに機能を追加できます。例えば、ホスト画面上のテキストだけでなく、カラーや強調表示などの特性も検索することができます。
カスタマイズ可能テンプレートには、HATS コード、Host On-Demand オブジェクト、イベント、およびその他の Java 構成体と対話する重要な Java コードが含まれています。これらのテンプレートを使用すると、統合オブジェクトを変更して追加機能を実行できます。カスタマイズ可能テンプレートを使用して作成された統合オブジェクトには、HATS および Host On-Demand コードと直接対話し、ほとんどのデータ処理を実装するコードが組み込まれます。HATS または Host On-Demand コードの何らかの変更が統合オブジェクト内のコードに影響を与える場合は、統合オブジェクトを再コンパイルおよび再配置する必要がある場合があります。
HATS が使用するテンプレートは、Host Publisher が使用するテンプレートとは異なります。Host Publisher で統合オブジェクト・テンプレートを変更した場合は、統合オブジェクト内で同じ機能を達成するため、HATS が提供するテンプレートに同じ変更を加えて統合オブジェクトを再作成する必要があります。変更したテンプレートで作成された Host Publisher 統合オブジェクトや、そのような統合オブジェクトを使用するアプリケーションをインポートまたはマイグレーションすると、カスタマイズされたテンプレートから Java Bean が作成されたことを示すメッセージが表示されます。
統合オブジェクトが HATS または稼働環境と対話する方法を変更する必要がない場合は、デフォルト・テンプレートの HPubTemplateHODBean.Default および HPubTemplateHODBeanInfo.Default を使用してください。前に別のテンプレートを選択していない限り、特にデフォルト・テンプレートを使用するためのアクションを実行する必要はありません。
統合オブジェクトで追加機能を実行する場合は、HPubTemplateHODBean.Customize および HPubTemplateHODBeanInfo.Customize テンプレートのコピーを作成して、名前を変更します。新規テンプレート・ファイルを変更して、統合オブジェクトで実行する機能に対する Java コードを追加します。
カスタマイズ可能テンプレートまたは名前変更したテンプレートのコピーを使用する場合は、統合オブジェクトの作成時にどのテンプレートを使用するかを HATS に知らせる必要があります。HATS Toolkit で統合オブジェクト・テンプレートを選択するには、「ウィンドウ」>「設定」をクリックします。「HATS」を展開し、「統合オブジェクト」をクリックします。参照して、使用する統合オブジェクト・テンプレートを見付けます。
双方向コード・ページを使用する HATS プロジェクト用の追加機能として、2 つのテンプレートが提供されています。次の 2 つのテンプレートです。
双方向コード・ページを使用する HATS プロジェクトを作成する場合、統合オブジェクトを作成する際に、HPubTemplateHODBeanBIDI.Default がデフォルトで使用されます。統合オブジェクトをカスタマイズする場合は、HPubTemplateHODBeanBIDI.Customize を変更し、統合オブジェクト作成の際に使用する HATS プリファレンスのページでそれを選択してください。
これらのテンプレートで、統合オブジェクトのテキスト出力を再配列するかどうか指定することができます。また、データを論理モードで動作しているアプリケーションから取得し、ビジュアル・モードで動作しているアプリケーションによって表示することができます。従って、挿入と抽出のための双方向の再配列を個別に制御できます。次のプロパティーが使用可能です。
これらのプロパティーを取得し設定するために、次のメソッドが用意されています。
public String getPromptReordering(); public String getExtractReordering(); public String getPreventRoundTrip(); public void setPromptReordering(String value); public void setExtractReordering(String value); public void setPreventRoundTrip(String value);
プロンプト・アクションからのデータに RTL 方向がある場合は、パラメーター v を true に設定します。
抽出アクションからのデータに RTL 方向がある場合は、パラメーター v を true に設定する。
これらのマーカーの使用を許可するようにパラメーター v を設定する。
ここで、value は true または false のどちらかになります。デフォルトでは、これらのプロパティーは false に設定されているため、統合オブジェクトは双方向でないテンプレートで作成されたオブジェクトのように動作します。しかし、これらのテンプレートで作成された統合オブジェクトを基にしたモデル 1 または JSF の Web ページ (つまりボトムアップの Web サービスの場合) を、HATS Toolkit を使用して作成する場合、これらの値は Studio の GUI で選択したオプションに従って true に設定されます。
HPubTemplateHODBean.Customize および HPubTemplateHODBeanInfo.Customize テンプレートには、統合オブジェクトのコンパイル時に統合オブジェクトの Java Bean コード (.java) ファイルに組み込まれる Java コードが含まれています。テンプレートには HATS 専用の構成体も含まれており、その前に % 記号が付けられています。これらの構成体により、HATS は、統合オブジェクトの作成時にユーザーが指定したデータから Java Bean を作成できます。テンプレート・ファイルを変更する際は、HATS 構成体を含むステートメントを削除しないよう注意してください。テンプレート・ファイルに変更を加える前に、HPubTemplateHODBean.Customize および HPubTemplateHODBeanInfo.Customize テンプレートのバックアップ・コピーを作成してください。
例えば、統合オブジェクトが処理する Host On-Demand Extract Events の名前および画面の x 座標と y 座標をトレースするとします。
以下の手順を実行してください。
// --- Trace X and Y screen coordinates example ---
if (HPubTracingOn) {
String strg = "Extracting variable: " + stringExtractNameForThisEvent +
" from screen location (" +
haovWorkOnThis.intXScreenLocation + "," +
haovWorkOnThis.intYScreenLocation + ")";
Ras.trace( this.getClass().getName(),"macroExtractEvent", strg);
}
例えば、次のように設定します。
...
public void macroExtractEvent(MacroExtractEvent oMacroExtractEvent)
{ // a HOD macroExtractEvent was fired for this macro
..
pullVariableValueFromExtractData( haovWorkOnThis, data);
// --- Trace X and Y screen coordinates example ---
if (HPubTracingOn) {
String strg = "Extracting variable: " + stringExtractNameForThisEvent +
" from screen location (" +
haovWorkOnThis.intXScreenLocation + "," +
haovWorkOnThis.intYScreenLocation + ")";
Ras.trace( this.getClass().getName(),"macroExtractEvent", strg);
}...付録C. 統合オブジェクト・テンプレート変更のサンプルを参照してください。HPubTemplateHODBean.Customize にコードを追加して作成された統合オブジェクト・テンプレートの例が含まれています。
この例では、カスタム画面認識基準の使用法を示します。この基準は、該当する画面の記述内のマクロに追加され、テンプレートで定義された DoReco() メソッドを呼び出します。DoReco() は、extendedxml という XML ストリング内にホスト画面のフィールドをすべて保存します。統合オブジェクトの実行後に JSP で値を抽出できるようにするため、getter メソッド getExtendedxml() が提供されています。テンプレートに加えられた変更には、// ADDED FOR XML TABLE というコメントが付けられます。
カスタム画面認識基準 (ディスクリプター) を使用すると、統合オブジェクトによって検出されたあらゆる画面のコンテンツを取り込むことができるので、注目に値します。ホスト画面が変更された場合や画面が認識された場合、統合オブジェクトには通知がされません。カスタム画面認識基準を挿入することにより、任意の画面を処理できます。
テンプレートに追加されたコードを呼び出すには、統合オブジェクトの構築に使用するマクロを変更する必要があります。情報の取り込み元となる画面を見付けて、次の行を最後のディスクリプターとして追加します。
<customreco id="HPubExtractFieldAttributes|" optional="false" invertmatch="false" />
このディスクリプターは、希望する画面でのみ使用されるように、その他のディスクリプターの後に追加してください。そうしないと、別の画面からデータが収集される場合があります。customreco ID は「HPubExtractFieldAttributes」ですが、マクロに追加される行では「HPubExtractFieldAttributes|」となっています。バー文字 (|) は、パラメーター間の分離文字として使用されていますが、パラメーターがない場合でも組み込む必要があります。
マクロが uselogic 属性を使用してディスクリプターを結合する場合は、新規ディスクリプターを組み込むために uselogic 値を更新する必要があります。そうしないと、新規ディスクリプターは無視されます。マクロに加える変更の例を次に示します。元の画面が次のような記述であるとします。
<screen name="Screen2.2" entryscreen="true" exitscreen="true" transient="false">
<description uselogic="1 and 2" >
<oia status="NOTINHIBITED" optional="false" invertmatch="false" />
<string value="Ready; T" row="1" col="1" erow="-1" ecol="-1"
casesense="true" optional="false" invertmatch="false" />
</description>この場合、新規ディスクリプターを追加し、uselogic を変更した画面記述は次のようになります。
<screen name="Screen2.2" entryscreen="true" exitscreen="true" transient="false">
<description uselogic="1 and (2 and 3)" >
<oia status="NOTINHIBITED" optional="false" invertmatch="false" />
<string value="Ready; T" row="1" col="1" erow="-1" ecol="-1"
casesense="true" optional="false" invertmatch="false" />
<customreco id="HPubExtractFieldAttributes|" optional="false"
invertmatch="false" />
</description>
DoReco() メソッドが呼び出されると、テンプレートは、それが「HPubExtractFieldAttributes|」カスタム・ディスクリプターを処理するために呼び出されているのかどうかを確認します。そうである場合は、画面から情報が取り込まれ、そうでない場合は、他のいずれかのディスクリプターを使用して画面認識を実行するために制御を親メソッドに渡します。統合オブジェクトの完了後、呼び出し側の JSP は getter メソッドを使用して XML ストリングを取得し、処理できます。
統合オブジェクトのためのマクロにおける非テキスト平面からのデータの抽出は、Visual Macro Editor ではサポートされていません。ただし、統合オブジェクト・テンプレートを変更することにより、非テキスト平面からデータを抽出できます。
この例には、「Callback for HOD Custom screen recognition」を記述したセクションがあります。このメソッドを使用すると、データの他の平面を 1 回の入出力で抽出できます。例えば、カラー・データを取得するには、DoReco メソッドで次のコードを使用します。
char[] buff = new char[2]; evt.GetPS().GetScreen(buff, 2, i, startCol, 1, ECLConstants.COLOR_PLANE); int val = buff[0];
ここでは、2 種類のアプリケーションで統合オブジェクトを使用する方法を説明します。
この説明では、統合オブジェクトのメソッドに言及します。このメソッドについては、統合オブジェクトのメソッドを参照してください。
統合オブジェクトを実行する独自の Web プロジェクトを作成できます。ここでは、HATS プロジェクトから別の Web プロジェクトへファイルを移動し、統合オブジェクトを実行するようにそれを設定する手順を示します。この手順を実行すると、1 つ以上の統合オブジェクトを個別にエクスポートして使用することができます。統合オブジェクトのチェーンを使用する場合は、以降の説明に従ってすべてのファイルをコピーし、統合オブジェクトが正しい順序で実行されるようにする必要があります。
HATS 保守は、個別の Web プロジェクトで配置される統合オブジェクトには適用されません。このように使用される統合オブジェクトに保守を適用する最良の方法は、HATS プロジェクト内の統合オブジェクトを更新してから、次の手順に従ってそれらを再エクスポートすることです。
WEB-INF¥profiles¥application.hap WEB-INF¥profiles¥connections¥ioconn.hco WEB-INF¥profiles¥macros¥iomacro.hma
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>// Initialize and activate the HATS 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 として使用できます。
統合オブジェクトを起動するサーブレットを書き込むには、次の手順を実行します。
void setXyz(String)ここで、Xyz は入力変数の名前です。
統合オブジェクトの作成時に指定した接続プールとは別の接続プールを使用することもできます。別の接続プールを指定するには、次のメソッドを呼び出します。使用したい接続プールの名前を指定します。
void setHPubStartPoolName(String)
void doHPTransaction(HttpServletRequest, HttpServletResponse)
統合オブジェクトが JSP によって呼び出されると、JSP プロセッサーは例外をキャッチし、page ディレクティブの errorPage="errorPageName" 属性で指定されたエラー・ページにブラウザーをリダイレクトします。HATS デフォルト・エラー・ページの 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 例外がスローされます。
String getHPubXMLProperties()これは、統合オブジェクトのプロパティーと値を XML 形式のストリングとして戻します。
必要に応じて値を取り出せるよう、すべての統合オブジェクトの入力変数に、各 setter メソッドに対応する getter メソッドが含まれています。これらのメソッドのシグニチャーは次のようになります。
void getXyz(String)
ここで、Xyz は入力変数の名前です。
入力したデータから生成される入力変数名または出力変数名を確認するには、統合オブジェクトの BeanInfo java ファイル内で定義されたプロパティーを参照します。統合オブジェクトの BeanInfo .java ファイルは、IntegrationObject パッケージ内のプロジェクトのソース・フォルダーにあります。HATS Toolkit では、BeanInfo ファイルが表示されるのは「ナビゲーター」ビューだけです。
この説明では、統合オブジェクトのメソッドに言及します。このメソッドについては、統合オブジェクトのメソッドを参照してください。
統合オブジェクトを実行する独自の EJB プロジェクトを作成できます。ここでは、HATS プロジェクトから別の EJB プロジェクトへファイルを移動し、統合オブジェクトを実行するようにそれを設定する手順を示します。この手順を実行すると、1 つ以上の統合オブジェクトを個別にエクスポートして使用することができます。統合オブジェクトのチェーンを使用する場合は、以降の説明に従ってすべてのファイルをコピーし、統合オブジェクトが正しい順序で実行されるようにする必要があります。
HATS 保守は、個別の EJB プロジェクトで配置される統合オブジェクトには適用されません。このように使用される統合オブジェクトに保守を適用する最良の方法は、HATS プロジェクト内の統合オブジェクトを更新してから、次の手順に従ってそれらを再エクスポートすることです。また、HATS ランタイム .jar ファイルを HATS EAR からプロジェクトへエクスポートする場合は、HATS 保守を適用する際にそれらを再エクスポートする必要があります。
ejbModule¥application.hap ejbModule¥connections¥ioconn.hco ejbModule¥macros¥*.hma ejbModule¥IntegrationObject¥*.java
// obj is the EJB object reference, // e.g., com.ibm.hats.util.Ras.initializeRas(this); com.ibm.hats.util.Ras.initializeRas(obj); com.ibm.hats.util.LicenseManager.getInstance(); // appName is a String representing the EJB project // and obj is the EJB object reference // e.g. com.ibm.hats.runtime.Runtime.initRuntime(My_EJB, this); com.ibm.hats.runtime.connmgr.Runtime.initRuntime(appName, obj);
カスタム EJB から統合オブジェクトを使用するには、次の手順を実行します。
void setXyz(String)ここで、Xyz は入力変数の名前です。
void setHPubStartPoolName("My_EJB/main");
ここで、My_EJB は EJB プロジェクトの名前、main は統合オブジェクトの接続プールの名前です。void processRequest() throws BeanException
統合オブジェクトにエラーがある場合、processRequest() メソッドは例外 (タイプ com.ibm.HostPublisher.IntegrationObject.BeanException) をスローします。
入力変数をリセットして、processRequest() メソッドを複数回、呼び出すことができます。エラー表示と結果の値は、呼び出しごとにリセットされます。
int getHPubErrorOccurred()結果がゼロ以外である場合は、エラーが発生しています。エラー例外が示されます。エラーの特定の例外を取得するには、次のメソッドを呼び出します。
Exception getHPubErrorException()例外オブジェクトで getMessage() を呼び出すことによって、エラー・メッセージを検索します。メッセージは、「HATS メッセージ」に記載されています。最初の 7 文字は HATxxxx または HPSxxxx に設定されています。ここで、xxxx はメッセージ番号です。
String getAbc()ここで、Abc は出力変数の名前です。
String[] getAbc()ここで、Abc は出力変数の名前です。
String getAbc(int) throws ArrayIndexOutOfBoundsExceptionここで、Abc は出力変数の名前で、int は必要な値の索引です。この手順を配列で繰り返していくと、配列の終わりに達したときに、メソッドによって ArrayIndexOutOfBoundsException 例外がスローされます。
String getHPubXMLProperties()これは、統合オブジェクトのプロパティーと値を XML 形式のストリングとして戻します。
必要に応じて値を取り出せるよう、すべての統合オブジェクトの入力変数に、各 setter メソッドに対応する getter メソッドが含まれています。これらのメソッドのシグニチャーは次のようになります。
void getXyz(String)
ここで、Xyz は入力変数の名前です。
入力したデータから生成される入力変数名または出力変数名が不確実の場合は、統合オブジェクトの BeanInfo .java ソース・ファイル内で定義されたプロパティーを参照します。統合オブジェクトの BeanInfo .java ソース・ファイルは、IntegrationObject パッケージ内のプロジェクトのソース・フォルダーにあります。BeanInfo が表示されるのは「ナビゲーター」ビューだけです。
HATS ランタイムに新規 API が追加されました。ユーザーはこの API を使用することで、変換接続 (「デフォルト接続」とも言います) に対する中間チェーン統合オブジェクトの実行に備えて、その変換接続をサーブレット・コンテキスト内で獲得することができます。この新規 API の目的は、HATS アプリケーションと HATS 以外の他の Web アプリケーションとの間のさらなる統合を提供することです。この API は、com.ibm.hats.runtime パッケージ内の RuntimeFunctions クラスに追加された acquireExistingTransformationConnection および releaseExistingTransformationConnection という新規の 2 つの静的メソッドから構成されます。
メソッドのシグニチャーは以下のとおりです。
acquireExistingTransformationConnection メソッドの目的は以下の 2 つです。
つまり、ユーザーが変換接続が取得された後、それを解放する前に変換接続へのアクセスを試みた場合は、ブラウザーが「アプリケーションは使用中です。」というメッセージ・ページを表示します。このページは、考えられる原因がアプリケーションが準備完了になる前に Web ページを再ロードしていることを示しています。呼び出し元は、返されたラベルを使用して、統合オブジェクトの setHPubStartChainName() メソッドを呼び出します。統合オブジェクトは、このラベルを使用して実行対象の接続を見つけます。ヌルのラベルが返された場合は、接続は統合オブジェクトにアクセスできません。 HostConnectionException がスローされた場合は、アプリケーション・インスタンスは存在しますが、変換接続が存在しません。 ApplicationUnavailableException がスローされた場合は、アプリケーション・インスタンスが存在しないか、または存在する場合は現在チェックアウトされています。エラーが発生した場合に、統合オブジェクトが変換接続を破棄することを回避するために、doHPTransaction() を呼び出す前に setHPubSaveConnOnError(true) メソッドを呼び出して統合オブジェクトを実行します。
releaseExistingTransformationConnection メソッドの目的は、エントリー・サーブレットまたは他の統合オブジェクト・チェーンがアプリケーションを使用できるように、アプリケーションにチェックインすることです。呼び出し元は、統合オブジェクト・チェーン内のすべての統合オブジェクトが実行された後に releaseExistingTransformationConnection を呼び出す必要があります。統合オブジェクトの実行中にエラーが発生した場合でも、変換接続を再度使用可能にするために、この releaseExistingTransformationConnection 呼び出しを使用する必要があります。この呼び出しは、統合オブジェクト・チェーンが変換接続へのアクセスをすでに必要としないことを意味しています。