ソフトウェア > Lotus > Lotus Developer Domain > 製品別技術情報 > Lotus Forms >

IBM Workplace Forms V2.7 ストリーミング API ガイド

	コンテンツ

ストリーミング API の新機能について

API のノード構造

ストリーミング API のインストール

2 つの API のインターフェースの比較

Gu Yi (guyi@cn.ibm.com), Lead Software Engineer, IBM

レベル：中級
原文の掲載：2007年 5月 15日
原文はこちら (US)

IBM Workplace Forms V2.7 の新機能であるピュア Java ストリーミング API について説明します。ピュア Java ストリーミング API を、C 言語で記述された従来の API と比較します。サンプル・コードを示しながら、ピュア Java ストリーミング API の使用法を説明します。

IBM Workplace Forms V2.7 において、Workplace Forms ファミリーにストリーミング API が追加されました。この新しいストリーミング API は 100% ピュア Java ベースの API であるため、従来の C 言語 API とは異なります。

この記事では、このストリーミング API の機能を説明し、従来の API と比較します。ストリーミング API のインターフェースは従来の API のインターフェースと同じですが、実行できる操作が限られています。IBM Workplace Forms のストリーミング API にはさまざまな新機能が組み込まれています。

この記事では、ストリーミング API の使用例を解説します。この記事の最後のセクションには、ストリーミング API の使用法を示すサンプル・コードを収録しています。

ストリーミング API の新機能について

IBM Workplace Forms Server API は、階層型の DOM データ構造体セットに基づき、完全に機能する IBM Workplace Forms Viewer の機能要件に対応するよう設計されています。この API は不必要なサービスも提供するため、サーバー・アプリケーションの側から見ると、メモリーを大量に消費し、リアルタイム操作を多数実行するという特徴があります。また、従来の API では一部の Java アプリケーションで安定性の問題が発生する可能性があります。従来の API は C 言語で記述されており、Java C ブリッジを使用して呼び出されるため、Java 仮想マシン (JVM) の保護範囲外で稼働します。したがって、API で障害が発生すると、これが原因で JVM がクラッシュする可能性があります。さらには、この API の障害が原因となってアプリケーション・サーバーがクラッシュする可能性もあります。

Workplace Forms Server API で生じるこれらの問題に対処するため、最新バージョンの IBM Workplace Forms には、ストリーミング API と呼ばれる新たなピュア Java API が組み込まれました。ストリーミング API は、XFDL 解析を実行する Java パーサーとして SAX (Simple API for XML) を採用した 100% Java ベースの API です。

このJava 実装はサーバー環境で安全に稼働し、JVM により障害が円滑に処理され、個々のアプリケーションが相互に切り離されます。Java ベース API で障害が発生しても、アプリケーション・サーバーがクラッシュすることはありません。ストリーミング API は、完全機能ビューアーではなくサーバー・アプリケーションの要件に対応するよう調整されています。Workplace Forms Server API に比べ、ストリーミング API は実行時に使用するメモリー・フットプリントが小さく、Workplace Forms 処理のリアルタイム性が低くなります。

上に戻る

API のノード構造

ストリーミング API のオブジェクト・ツリー構造は、従来の API と同一です。FormNodeP ノードによる XFDL フォームの内部表現を図 1 に示します。ストリーミング API では、XFDL ファイルを解析する際にこの構造が内部で使用されることはありませんが、ストリーミング API でノードを作成または取得する際にこの構造の概念が適用されます。

図 1. API のノード構造

ツリーのルート・ノードはフォーム・ノードです。このルート・ノードには複数の子ノード (ページ) があります。各ページ・ノードには、さらに子ノード (項目) があります。同一タイプのノードは常に、ツリーの同一レベルに位置します。ノード構造のすべてのノードは、FormNodeP (項目ノード、オプション・ノード、または引数ノードなど) とみなすことができます。アプリケーションでは、このオブジェクト・ツリーをナビゲートするときに、任意の FormNodeP オブジェクトに対して dereferenceEx() を呼び出すことができます。ナビゲート操作は相対的です。1 つ上のレベルに移動して参照先項目を検索します。

上に戻る

ストリーミング API のインストール

従来の API に比べ、ストリーミング API のインストールは非常に単純です。Java クラスパスに追加する必要のある JAR ファイルは 1 つだけです。ストリーミング API では、従来の API の構成ファイル (PugeEdgeAPI.ini や Prefs.config など) は無視されます。ただし、ログの印刷用に PureEdge.pel がサポートされています。

クラスパスではストリーミング API と従来の API が共存できます。この共存により、2 つの API を置き換える操作が容易になります。ストリーミング API を使用するには、クラスパスでストリーミング API JAR ファイルが pe_api.jar より前に位置していることを確認してください。クラスパスで最初に pe_api.jar が検出されると、ストリーミング API ではなく従来の API がロードされます。

上に戻る

2 つの API のインターフェースの比較

ストリーミング API では、従来の API のメソッドの一部がサポートされています。ストリーミング API は一部の呼び出しをネイティブ API として使用するため、完全な後方互換性と前方互換性を備えています。ストリーミング API を使用する場合に従来の API のアプリケーションを簡単に移動できます。また、従来の API を使用する場合にストリーミング API を移動する操作も簡単です。

ストリーミング API と従来の API の両方でサポートされているメソッドのリストを表 1 に示します。

表 1. サポートされているメソッド

クラス名	メソッド名	説明
DTK	initialize(String progName, String progVer, String apiVer);	このメソッドは、API を初期化します。ストリーミング API は、初期化を実行するときにパラメーターを使用しません。パラメーターは後方互換性または前方互換性を維持する目的でのみ必要です。
	initializeWithLocale(String progName, String progVer, String apiVer, String theLocale) ;	同上
IFSSingleton	getXFDL();	このメソッドは、XFDL クラスを取得するときに使用されます。XFDL オブジェクトとは、ユーザーがフォームのルート・ノードにアクセスするためのインターフェースです。
XFDL	readForm(String fileName, …);	このメソッドは、指定された fileName (パス・ストリング) または InputStream からフォームを読み取ります。
FormNodeP	writeForm(String fileName, FormNodeP triggerItem, 0);	このメソッドは、指定された fileName または OutputStream にフォームを書き込みます。ストリーミング API では、triggerItem は NULL でなければなりません。
	destroy();	このメソッドは明示的に呼び出す必要があります。
	dereferenceEx(String theScheme, String theReference, int theReferenceCode, int referenceType, FormNodeP theNSNode) ;	dereferenceEx() は、フォームのオプション・ノードまたは項目ノードへの参照を取得します。従来の API と異なり、dereferenceEx() を使用してグループ間をナビゲートすることはできません。パラメーター FormNodeP.UFL_GROUP_REFERENCE はサポートされていません。
	getLiteralEx(String theCharSet);	このメソッドは、指定された FormNodeP からリテラル文字列を取得します。
	setLiteralEx(String theCharSet, String theLiteral);	このメソッドは、指定された FormNodeP でリテラル文字列を設定します。
	getLiteralByRefEx(String theScheme, String theReference, int theReferenceCode String theCharSet, FormNodeP theNSNode);	これは、dereferenceEx() と getLiteralEx() を組み合わせたメソッドです。このメソッドは、オプション・レベルでのみ機能します。
	setLiteralByRefEx(String theScheme, String theReference, int theReferenceCode, String theCharset, FormNodeP theNSNode, String theLiteral);	これは、dereferenceEx() と setLiteralByRefEx() を組み合わせたメソッドです。このメソッドは、オプション・レベルでのみ機能します。
	encloseInstance(); extractInstance();	これらのメソッドは、XFDL データ・インスタンスを更新またはコピーするときに、フォームのルート・ノードまたは XML インスタンス・ノードに対して呼び出されます。
	extractXFormsInstance(); updateXFormsInstance();	これらのメソッドは、XForms データ・インスタンスを更新またはコピーするときに、フォームのルート・ノードまたはインスタンス・ノードに対して呼び出されます。

ストリーミング API でサポートされない関数のリストを表 2 に示します。

表 2. ストリーミング API でサポートされない関数

クラス名	メソッド名	説明
XFDL	create ();	このメソッドは、新規ノードを作成し、フォーム階層の指定された位置にその新規ノードを追加します。
FormNodeP	getChildren() getNext() getInfoEx()	ストリーミング API では、これらのクラスを呼び出して FormNodeP のツリー構造をナビゲートすることはできません。ナビゲート操作が必要な場合は、従来の API を使用してください。
	setAttribute() getAttribute()	現時点では、ストリーミング API では属性に対する操作がサポートされていません。
	getSignature(); verifySignature(); Other functions related to signature	これらの関数は、シグニチャーの検証に関連しています。
	getNamespaceURI(); addNamespace( ); Other functions related to namespace	特定のノードで名前空間を追加するか、または名前空間 URI を取得します。
	extractFile(); encloseFile();	ストリーミング API は、フォームの添付ファイルを操作できません。
	setFormula(); Other computation-related functions	ストリーミング API では、計算エンジンと XForms エンジンの両方を実行することはできません。バインドされている XForms 項目の値を取得する操作を実行すると、NULL が戻されます。

ストリーミング API でのみ使用可能な新規関数のリストを表 3 に示します。

表 3. ストリーミング API の新規関数

クラス名	メソッド名	説明
FormNodeP	addHint(String theReference, int theReferenceType) ; addHints(java.util.List theReferences, int theReferencesType);	ストリーミング API に対し、参照するヒントまたはパターンのセットを指示できます。これにより、API は初回パスの後にこれらのヒントとパターンをキャッシュに入れます。
	clearHints();	この関数は、すべてのヒントを消去します。

ストリーミング API は、Java アプリケーションで高いパフォーマンスを実現することを目的としています。SAX パーサーの制限により、ツリー・モデル内のナビゲートなどの一部の機能がサポートされていません。ストリーミング API の機能制限から、以下に示す状況においては、従来の API ではなくストリーミング API の使用を検討してください。

アプリケーションが Java プラットフォームで実行されており、拡張機能開発用のアプリケーションではない。
単純なフォーム操作 (ノードの遅延処理やノードのリテラルの設定など) のみが必要である。複雑なツリー・ナビゲート機能が不要である。
アプリケーションのパフォーマンスの基準が高い。同時接続ユーザー数が多く、応答時間が重要である。フォームのサイズが非常に大きい場合に従来の DOM ベースの API を使用すると、メモリーを大量に消費する。
アプリケーションが複数のプラットフォームにデプロイされている。従来の API は各種プラットフォームに対応していますが、構成が複雑であり、対応 OS が限られています。ストリーミング API は 1 つのファイルに記述されており、任意の Java 環境に配布できるので、Web アプリケーションには最適です。

計算エンジンと XForms エンジンはストリーミング API では機能しないため、アプリケーションでこれらのエンジンを実行する場合に使用できるのは従来の API のみです。

上に戻る

API サンプル・コード

API を使用してフォームを読み取り、値を変更する例と、API を使用してフォームのデータ・インスタンスを変更する例の2 つの使用例のサンプル・コードを以下に示します。

API を使用したフォームの読み取りと値の変更

次に示すコード・スニペットは、フォームの読み取り、フォームの値の変更、および新規ファイルへのフォームの出力の方法を示します。

1. API を初期化し、XFDL オブジェクトを取得します。
DTK.initialize("FormReader", "1.0.0", "7.1.0"); XFDL theXFDL = IFSSingleton.getXFDL();
readForm() API を使用してフォームをロードします。
String fileName = "order.xfdl"; FormNodeP theForm = theXFDL.readForm(fileName, XFDL.UFL_SERVER_SPEED_FLAGS);

リスト 1 に示すように、適切な theForm.addHint(String reference, int referenceType) 呼び出しを追加して、ストリーミング API による文書の解析回数を減らします。

リスト 1. Form.addHint(String reference, int referenceType) 呼び出しの追加



	theForm.addHint("PAGE1.productColumn.value", FormNodeP.UFL_OPTION_REFERENCE);
	theForm.addHint("PAGE1.unitCostColumn.value", FormNodeP.UFL_OPTION_REFERENCE);
	theForm.addHint("PAGE1.qtyColumn.value", FormNodeP.UFL_OPTION_REFERENCE);
	theForm.addHint("PAGE1.Subtotal.value", FormNodeP.UFL_OPTION_REFERENCE);
	theForm.addHint("PAGE1.Total.value", FormNodeP.UFL_OPTION_REFERENCE);
	theForm.addHint("PAGE1.Title.value", FormNodeP.UFL_OPTION_REFERENCE);

リスト 2 に示すコードは、フォームから値を読み取り、フォームに値を書き込みます。

リスト 2. フォームからの値の読み取りとフォームへの値の書き込み


String subTotal = theForm.getLiteralByRefEx(null, "PAGE1.Subtotal.value", 0, null, null);
	FormNodeP totalValueNode = theForm.dereferenceEx(null, 
	"PAGE1.Total.value", 0,FormNodeP.UFL_OPTION_REFERENCE, null);

	String total = totalValueNode.getLiteralEx(null);
	theForm.setLiteralByRefEx(null, "PAGE1.Title.value", 0, null, null, 
	"You have been billed " + total);
	String theTitle = theForm.getLiteralByRefEx(null, "PAGE1.Title.value", 0, null, null);
	theForm.setLiteralByRefEx(null, "PAGE1.productColumn.value", 0, null, null, 
	"NAME OF PRODUCT");
	theForm.setLiteralByRefEx(null, "PAGE1.unitCostColumn.value", 0, null, null, 
	"COST PER UINIT");
	theForm.setLiteralByRefEx(null, "PAGE1.qtyColumn.value", 0, null, null, "QUANT");

		theForm.writeForm("newForm.xfdl", null, 0);

最後に、destroy() を呼び出してフォーム・ノードを破棄します。

theForm.destroy();

API を使用したフォームのデータ・インスタンスの変更

ストリーミング API を使用して、読み取ったフォームのデータ・インスタンスを抽出して置換できます。次に示すコード・スニペットは、API を使用してデータ・インスタンスを抽出および置換する方法を示します。

ByteArrayOutputStream を使用して結果を取り込み、適切な extractXFormsInstance() メソッド呼び出しを追加して、XPathRef パラメーターに属するデータを抽出します。
ByteArrayOutputStream stream = new ByteArrayOutputStream(); theForm.extractXFormsInstance(null, xPathRef, false, true, null, stream);
extractXFormsInstance() は、(モデル ID またはインスタンス ID により示される) XForms インスタンスの全体または一部を抽出し、指定されたパス (String) または OutputStream に結果を格納します。
渡された値 String を使用して、適切な updateXFormsInstance() メソッド呼び出しを追加して、xPathRef パラメーターが指し示すモデルにそのデータを追加します。

String pathtoXMLFile = “C:\\somexmlfile.xml”; theForm.updateXFormsInstance(null, "instance(‘po')", null, pathToXMLFile, null, XFDL.UFL_XFORMS_UPDATE_APPEND);

ストリーミング API を使用して、ファイル、ストリーム、またはリーダーにある (モデル ID およびノード参照により示される) XForms インスタンスで、XML データを置換したり、XML データを追加したりできます。最終パラメーターは、データを置換するか、または示されているノードの前後のどちらかの位置にデータを追加するかを制御するフラグです。XForms インスタンスを置換するには、次のコードを使用します。

theForm.updateXFormsInstance(null, "instance(‘po')", null, pathToXMLFile, null, XFDL.UFL_XFORMS_UPDATE_REPLACE);

上に戻る

まとめ

IBM Workplace Forms のストリーミング API は、新しい Java ベースの API です。この API は、従来の API と大幅に異なります。サポートされている従来の API のインターフェースは限られていますが、Java アプリケーションでのツリー・ナビゲーション以外の操作では優れたパフォーマンスを実現します。

リソース

学ぶために

developerWorks の記事『Integrating XML forms-based processes into Service-Oriented Architectures using IBM Workplace Forms Services Platform』(US)をお読みください。
developerWorks の記事『Extending the XML data model to XFDL forms using IBM Workplace Forms V2.6』(US)をお読みください。
developerWorks の記事『IBM Workplace Forms V2.6 integration with IBM DB2 V9』(US) をお読みください。
developerWorks の記事『Integrating IBM Workplace Forms with WebSphere Portal to create a form-centric application』(US)をお読みください。
developerWorks の記事『Extending the functionality of IBM Workplace Forms with the Function Call Interface』(US)をお読みください。
developerWorks の記事『Create a form with IBM Workplace Forms Designer』(US)をお読みください。
製品資料の『Java API User’s Manual』(US)を参照してください。

製品や技術を入手するために

IBM Workplace Forms V2.7 Viewer and Designer (US) の試用版をダウンロードしてください。

議論するために

ディスカッション・フォーラム (US) にご参加ください。
John Boyer のブログの記事『IBM Lotus Forms and the Next Generation Web Applications(US)』を参照してください。

筆者について


		Gu Yi は、IBM の China Development Lab の IBM Software Services for Lotus (ISSL) Emerging Services Team に所属する上級ソフトウェア・エンジニアです。Gu Yi は 2005 年から IBM Software Services のプロジェクトに携わっており、IBM Workplace Forms に関連するさまざまなプロジェクトへの参加経験があります。また、2 年の IBM WebSphere Portal 開発経験と、業界内で 4 年の J2EE 開発経験もあります。

上に戻る