統合オブジェクトは、ホスト・アプリケーションとの対話をカプセル化する Java™ Bean です。 IBM® WebSphere® Host Publisher を使用したことがあれば、統合オブジェクトの特徴の多くについては理解されているでしょうが、その場合でも、HATS で統合オブジェクトをどのように使用できるかを理解する必要があります。HATS で統合オブジェクトを使用するには、Host Publisher の機能を深く理解していなくてもかまいません。
「HATS ユーザーと管理者のガイド」では、マクロから統合オブジェクトを作成する方法と統合オブジェクトを基にして Web ページを作成する方法について説明しています。IBM WebSphere Host Publisher を使用して作成した統合オブジェクトは、HATS にインポートし、HATS Toolkit で作成した統合オブジェクトと同じように使用できます。この資料では、次に示すような、統合オブジェクトの高度な使用方法について説明します。
統合オブジェクトのプロパティーには、WebSphere アプリケーションからアクセスできます。呼び出し側プログラムには、統合オブジェクトの名前および変数の名前がわかっていなければなりません。場合によっては、統合オブジェクトの名前がわからなくても呼び出し側プログラムが、すべての統合オブジェクトが共用しているプロパティーにアクセスできると便利なことがあります。Java クラス com.ibm.HostPublisher.IntegrationObject.HPubCommon は、すべての統合オブジェクトによって拡張されます。クラス com.ibm.HostPublisher.IntegrationObject.HPubHostAccess は HPubCommon を拡張したものであり、すべてのホスト・アクセス統合オブジェクトに共通です。クラス com.ibm.HostPublisher.IntegrationObject.HPubDBAccess は HPubCommon を拡張したものであり、すべてのデータベース統合オブジェクトに共通です。これらのクラスの情報は、統合オブジェクトの名前がわからなくても抽出できます。これらのクラスをイントロスペクトし、統合オブジェクトのメソッドを使用して抽出できる現行プロパティーの名前を見つけます。これらのメソッドの詳細については、統合オブジェクトのメソッドを参照してください。
デフォルトおよびカスタマイズ可能な統合オブジェクトの Java クラス階層は次のとおりです。
HPubCommon + -- HPubHostAccess + -- HPubHODCommon -- HPubTemplateHODBean.Default
| |
| + -- HPubTemplateHODBean.Customize
|
+ -- HPubDBAccess
HATS 統合オブジェクトには、統合オブジェクトを使用してプログラミングするときに使用できる Java メソッドが含まれています。一部のメソッドは、すべての統合オブジェクトに共通です。ホスト・アクセス統合オブジェクトのみに適用されるメソッドや、データベース・アクセス統合オブジェクトのみに適用されるメソッドもあります。このセクションでは、メソッドのリストを示し、各メソッドの機能について簡単に説明します。
以下のメソッドは、すべての統合オブジェクトに共通です。
次のメソッドは、Host Publisher で作成して HATS にインポートしたホスト統合オブジェクトの中で、HATS Toolkit で作成した統合オブジェクトと共に使用できます。これらのメソッドは、Host Publisher で作成したデータベース・アクセス統合オブジェクトでは使用できません。
詳しくは、接続オーバーライドの指定を参照してください。
このメソッドは、HATS EJB Access Bean に基づくクライアント・プログラム、または HATS Web サービスで使用する目的で生成された Web サービス・クライアントで使用します。
接続オーバーライドが指定されている場合、統合オブジェクトの doHPTransaction() メソッドまたは processRequest() メソッドが呼び出されると、その統合オブジェクト用の新規の接続プールが作成されます。この新規プールは、その統合オブジェクトの元の接続プールおよび指定された接続オーバーライドを基にして作成されます。統合オブジェクトは、この新規の接続プールを使用するように自動的に切り替えられます。新規プールの名前は、統合オブジェクト・インスタンスの getHPubStartPoolName() メソッドを使用して取得することができます。
詳しくは、接続オーバーライドの指定を参照してください。
統合オブジェクトの doHPTransaction() メソッドまたは processRequest() メソッドを呼び出す際に、その統合オブジェクトと関連付けられた接続オーバーライドがある場合は、その統合オブジェクト用の新規の接続プールが、その統合オブジェクトの接続プールおよび接続オーバーライドを基にして作成されます。新規プールの名前は、統合オブジェクト・インスタンスの getHPubStartPoolName() メソッドを使用して取得することができます。
詳しくは、接続オーバーライドの指定を参照してください。
次のメソッドは、Host Publisher で作成して HATS にインポートしたデータベース・アクセス統合オブジェクトでのみ使用できます。これらのメソッドは、Host Publisher で作成したホスト・アクセス統合オブジェクトと共に使用することはできません。また、HATS Toolkit で作成した統合オブジェクトと共に使用することもできません。データベースへのアクセス方法の詳細については、Rational® SDP の資料を参照してください。
接続オーバーライドは、動的に設定することも、ユーザーが設定することもできます。接続オーバーライドを指定することで、ユーザーは汎用アプリケーションを作成して、アプリケーションを実行するユーザーに応じて一部の設定をカスタマイズできるようになります。しかし、例えば、3270E 接続で使用する LUName や 5250 接続の workstationID は、実行時に動的に設定されます。
統合オブジェクトで接続オーバーライドを指定するには、その統合オブジェクトにアクセスするコードを変更して、doHPTransaction() メソッドまたは processRequest() メソッドを呼び出す前にその統合オブジェクト・インスタンスの setHPubConnectionOverrides(Properties overrides) メソッドまたは setHPubConnectionOverrides(String overrides) メソッドを呼び出すようにする必要があります。このメソッドは、統合オブジェクトの接続オーバーライドを設定します。統合オブジェクトの doHPTransaction() メソッドまたは processRequest() メソッドを呼び出す際に、その統合オブジェクトと関連付けられた接続オーバーライドがある場合は、その統合オブジェクト用の新規プールが、入力内のその統合オブジェクトの接続プールおよび接続オーバーライドを基にして作成されます。
IO.setHPubConnectionOverrides() メソッドを使用する JSP コードの例を以下に示します。
<% // Set the connection overrides
java.util.Properties overrides = new java.util.Properties();
overrides.setProperty("LUName", "LU00001");
// Apply overrides to the IO
SignOn.setHPubConnectionOverrides(overrides);
SignOn.doHPTransaction(request,response);
// Get new IO pool name to be used in following logic
String newPoolName = SignOn.getHPubStartPoolName();
%>
既存の統合オブジェクトに接続オーバーライドを指定する場合には、統合オブジェクトを再コンパイルすることなく、新規の com.ibm.HostPublisher.IntegrationObject.HPubPoolFactory クラスを使用することができます。 doHPTransaction() メソッドまたは processRequest() メソッドを呼び出す前に、その静的なメソッドである create() を使用できます。このメソッドは、入力内のプール・オブジェクトのクローンを作成して、それに関連付けられた Host On-Demand プロパティーに接続オーバーライドを適用することによって、新規のプール・オブジェクトを生成します。新規プールの名前が返されるので、setHPubStartPoolName() メソッドを使用して統合オブジェクトでその名前を設定する必要があります。入力内のプール名が無効である場合、create() メソッドはヌルを返します。
create メソッドの 3 番目のパラメーターがヌルである場合は、プール名を HATS アプリケーション名で修飾する必要があります。例えば、my_hats_project/main のようなプール名にします。
使用可能な静的メソッドは、以下の 2 つです。
static String create(String poolName,
Properties overrides,
javax.servlet.http.HttpServletRequest httpServletRequest)
static String create(String poolName,
String overrides,
javax.servlet.http.HttpServletRequest httpServletRequest)
これらのメソッドは、指定のプール定義および指定の接続オーバーライドを基にして新規のプール定義を作成します。
新規プールの名前は、ホスト接続を確立する統合オブジェクトの doHPTransaction() メソッドまたは processRequest() メソッドを呼び出す前に、インスタンスの setHPubStartPoolName() メソッドを使用して、その統合オブジェクトで設定する必要があります。
指定のプール名に対する接続定義がプロジェクト内にない場合、create() メソッドはヌルを返します。
create メソッドの 3 番目のパラメーターがヌルである場合は、プール名を HATS アプリケーション名で修飾する必要があります。例えば、「my_hats_project/main」のようなプール名にします。
2 番目のメソッド・シグニチャーを使用する場合、接続オーバーライドは「key1=value1, key2=value2」という形式にする必要があります。最初のメソッドでは、オーバーライドの指定に標準の Java プロパティー・オブジェクトを使用します。
com.ibm.HostPublisher.IntegrationObject.HPubPoolFactory,create() メソッドを使用する JSP コードの例を以下に示します。
<% // Set the connection overrides
java.util.Properties overrides = new java.util.Properties();
overrides.setProperty("LUName", "LU00001");
// Create a new Pool based on a the default pool and the connection overrides
String poolName = SignOn.getHPubStartPoolName();
String newPoolName =
com.ibm.HostPublisher.IntegrationObject.HPubPoolFactory.create
(poolName, overrides, request);
// If a valid poolName is returned, make the IO use the new pool
if (newPoolName != null) {
SignOn.setHPubStartPoolName(newPoolName);
SignOn.doHPTransaction(request,response);
}
else {
// Error condition
}
%>
チェーニングされた統合オブジェクトが正常に動作するための要件は以下のとおりです。
どちらの例でも、統合オブジェクトは、統合オブジェクトの元のプールのクローンを作成して接続オーバーライドを適用することによって作成した、新規のプール・オブジェクトを使用します。統合オブジェクトの元のプールに適用されるすべての設定 (プーリングを含む) は、新規のプールにも適用されます。接続オーバーライドは、統合オブジェクトにアクセスするユーザーごとに別々に指定することができます。 HATS ランタイムは、ユーザーごとにプール・オブジェクトを作成します。プーリングが無効になっている場合、接続オーバーライドの指定があるときに動的に作成されるこれらのプールは、最後のアクティブ接続が終了すると共に破棄されます。プロジェクト設定エディターの「その他」タブにある「接続パラメーターのオーバーライド」ページで指定された接続オーバーライド・パラメーターは、統合オブジェクトに適用されません。
プーリングが無効になっている場合、接続オーバーライドの指定があるときに動的に作成されるプールは、最後のアクティブ接続が終了すると共に自動的に破棄されます。
統合オブジェクト・チェーニングによって複雑なアプリケーションを複数のタスクに分割できます。各タスクは 1 つの統合オブジェクトによって表現されます。チェーニングを使用すると、複数の統合オブジェクトを順々に実行することができます。各統合オブジェクトの入力データは、直前の統合オブジェクトに依存させることができます。統合オブジェクトのチェーニングの概要については、「HATS ユーザーと管理者のガイド」を参照してください。統合オブジェクトのチェーニングはマクロのチェーニングとはまったく異なり、チェーン内の各統合オブジェクトは、チェーン内の次の統合オブジェクトが制御を取る前に実行を完了します。マクロのチェーニングは、PlayMacro アクションを使用し、現在のマクロ (PlayMacro アクションが発生しているマクロ) を終了させ、ターゲット・マクロの指定されたマクロ画面の処理を開始します。呼び出し側のマクロには何も戻りません。マクロ・チェーニングの詳細については「HATS 拡張マクロ・ガイド」を参照してください。
以下の場合は、統合オブジェクトのチェーニングは HATS によって処理されます。
このような場合は、doHPTransaction 実行メソッドを使用します。
以下の場合は、チェーニングを使用可能にするプロパティーを取得して設定する必要があります。
このような場合は、processRequest 実行メソッドを使用します。
doHPTransaction メソッドおよび processRequest メソッドの詳細については、統合オブジェクトのメソッドを参照してください。
HATS で提供されるメソッドを使用すると、チェーン内の最初の統合オブジェクトから統合オブジェクト・チェーンの接続を表現するキーを抽出したり、チェーン内の後続の統合オブジェクトのプロパティーを設定することができます。また、Web サービスのチェーニングを使用可能にするプロパティーも取得して設定する必要があります。
processRequest メソッドを使用して統合オブジェクト・チェーンを構築するには、次の手順を実行します。
IOChain1.setXyz(String)ここで、Xyz は入力変数の名前です。
IOChain1.processRequest()
IOChain1.getHPubErrorOccurred()
String myLinkkey = IOChain1.getHPubLinkKey();
IOChain2.setHPubLinkKey(myLinkkey);
IOChain2.setXyz(String)ここで、Xyz は入力変数の名前です。
IOChain2.processRequest()
IOChain2.getHPubErrorOccurred()
チェーン内のすべての後続の統合オブジェクトについて、ステップ 6 から 10 を繰り返します。
HATS でチェーニングされた Web サービス
HATS でチェーニングされた Web サービスを統合オブジェクトで使用する場合には、特別な考慮事項があります。チェーニングされた統合オブジェクトを HATS Web サービス内で使用する場合は、ステートフルな Web サービスを作成していることになります。 HATS ランタイムは、同じ Web サービス内にあるチェーニングされた統合オブジェクトの呼び出しと呼び出しの間でデータを保管しません。しかし、HATS ランタイムでは、チェーン内の次の Web サービスの呼び出しを、その HATS ランタイムの同じインスタンスに戻るようにルーティングする必要があるため、チェーン内の次の統合オブジェクトは、同じ Telnet 接続を使用します。
ステートフルな HATS Web サービスをクラスターに展開する場合は、以下のいずれかの方法を使用して行えます。
HATS では XML スタイル・シート HPubConvertToTableFormat.xsl を提供しており、表形式データの getHPubXMLProperties() 関数呼び出しに対してこれを適用できます。スタイル・シートを適用すると、テーブル名と列名を持つ XML 形式が生成され、データがレコード形式で再配列されます。HPubConvertToTableFormat.xsl スタイル・シートを適用するには、getHPubXMLProperties() 関数呼び出しを getHPubXMLProperties("HPubConvertToTableFormat.xsl") としてコーディングする必要があります。
WebSphere アプリケーションで使用できるメソッドの詳細については、統合オブジェクトのメソッドを参照してください。
統合オブジェクト出力に XML スタイル・シートを適用しない場合、XML データは次の文書タイプ定義 (DTD) で戻されます。
<?xml version=¥"1.0¥" standalone=¥"yes¥"?>
<!DOCTYPE com.ibm.HostPublisher.IntegrationObject.properties [
<!ELEMENT com.ibm.HostPublisher.IntegrationObject.properties
(inputProperties, outputProperties)>
<!ATTLIST com.ibm.HostPublisher.IntegrationObject.properties name CDATA "">
<!ELEMENT inputProperties (inputProperty*)>
<!ELEMENT inputProperty (value)>
<!ATTLIST inputProperty name CDATA "">
<!ELEMENT outputProperties (outputProperty*)>
<!ELEMENT outputProperty (value*)>
<!ATTLIST outputProperty name CDATA "" type (singlevalue|multivalue) 'multivalue'>
<!ELEMENT value (#PCDATA)>
]>
以下に例として、サンプル・データと XML データの結果を示します。
| 名前 | 電話番号 |
|---|---|
| Mary Smith | 765-4321 |
| John Doe | 123-4567 |
<com.ibm.HostPublisher.IntegrationObject.properties name=IntegrationObject.test1> <inputProperties> <inputProperty name=nameValue> <value>%</value> <inputProperty> </inputProperties? <outputProperties> <outputProperty name=tablename type=multivalue> <value>Mary Smith</value> <value>John Doe</value> </outputProperty> <outputProperty name=table1phonenumber type=multivalue> <value>867-5309</value> <value>123-4567</value> </outputProperty> <outputProperty name=databaseStatus type=singlevalue> <value>Ok</value> </outputProperty> <outputProperty name=hPubErrorOccurred" type=singlevalue> <value>0</value> </outputProperty> <outputProperty name=hPubErrorException" type=singlevalue> <value></value> </outputProperty> <outputProperty name=hPubErrorMessage" type=singlevalue> <value></value> </outputProperty> </outputProperties> </com.ibm.HostPublisher.IntegrationObject.properties>
すべてのデータは複数の <value> タグで囲まれており、<outputProperty> タグは列 (縦欄) の順序になっています。
統合オブジェクト出力に XML HPubConvertToTableFormat スタイル・シートを適用する場合、XML データは次の文書タイプ定義 (DTD) で戻されます。
<?xml version=¥"1.0¥" standalone=¥"yes¥"?>
<!DOCTYPE com.ibm.HostPublisher.IntegrationObject.properties [
<!ELEMENT com.ibm.HostPublisher.IntegrationObject.properties
(inputProperties, outputProperties)>
<!ATTLIST com.ibm.HostPublisher.IntegrationObject.properties name CDATA "">
<!ELEMENT inputProperties (inputProperty*)>
<!ATTLIST inputProperty name CDATA "">
<!ELEMENT outputProperties (outputProperty*,Table*)>
<!ATTLIST outputProperty name CDATA "">
<!ELEMENT Table (DataRecord*)>
<!ATTLIST Table name CDATA "">
<!ELEMENT DataRecord (outputProperty*)>
]>
表 3 に示すサンプル・データの結果の XML データは、次のようになります。
<com.ibm.HostPublisher.IntegrationObject.properties name=IntegrationObject.test1> <!-- Input Properties --> <inputProperties> <inputProperty name=inputName> % <inputProperty> </inputProperties? <outputProperties> <!-- Table (multivalued) output property --> <Table name=table1> <DataRecord> <outputProperty name=Name>Mary Smith</outputProperty> <outputProperty name=phoneNumber>867-5309</outputProperty> </DataRecord> <DataRecord> <outputProperty name=Name>John Doe</outputProperty> <outputProperty name=phoneNumber>123-4567</outputProperty> </DataRecord> </Table> <!-- Single Valued output Property --> <outputProperty name=databaseStatus> Ok </outputProperty> <!-- Standard Error output Properties --> <outputProperty name=hPubErrorOccurred">0</outputProperty> <outputProperty name=hPubErrorException"></outputProperty> <outputProperty name=hPubErrorMessage"></outputProperty> </outputProperties> </com.ibm.HostPublisher.IntegrationObject.properties>