EGL BIRT ハンドラー
EGL BIRT ハンドラー・パーツには、レポート作成時に呼び出される機能であるイベント・ハンドラーが含まれます。 EGL での BIRT のサポートの概要は、「プログラマー・ガイド」の『BIRT によるレポートの作成』を参照してください。
それぞれのイベント・ハンドラーにおいて、パラメーター・リストは関数が応答するイベントのタイプに固有となります。 BIRT ハンドラー・パーツの概略を次に示します。
handler myBIRTHandler type BIRTHandler
function myEventHandler01 (parameterList)
{eventType = eventType, elementName="name01"...} end
function myEventHandler02 (parameterList)
{eventType = eventType, elementName="name02"...} end
end
この概要に示すように、eventType と elementName プロパティー (および必要に応じて他のイベント・ハンドラー・プロパティー) は、関数がイベント・ハンドラーであることを示します。
- ハンドラー・パーツに基づく変数を作成する
- 変数を EGL BIRT レポートに関連付けるステートメントをコーディングする
- 必要に応じて、変数を使用して、レポートの作成時に使用するデータ・ソースを割り当てる
- レポートを作成する
これらのステップを受けて、BIRT レポート・エンジンはレポートの作成時に一連のイベント・ハンドラーを呼び出すことができます。
package EGLDataSources;
program arrayProg type BasicProgram {}
function main()
arr customer[0];
cust customer;
cust.customerNumber = 102;
cust.firstName = "Jonathan";
cust.lastName = "Swift";
arr.appendElement(cust);
cust.customerNumber = 103;
cust.firstName = "Mark";
cust.lastName = "Twain";
arr.appendElement(cust);
designFile string = "eglDataSourcesRpt.rptdesign";
rptFile string = "eglDataSourcesArrayRpt.pdf";
myHandler arrayHandler = new arrayHandler;
rpt BIRTReport = new BIRTReport
(designFile, null, rptFile, "pdf", myHandler);
myHandler.setCustomerArray(arr);
rpt.createReportFromDesign();
end
end
record customer type basicrecord
customerNumber int;
firstName string;
lastName string;
end
- 配列、およびハンドラー・パーツに基づく変数を作成する
- その変数と 2 つのファイル名を EGL BIRT レポートに関連付ける
- データ・ソースを割り当てる
- レポート出力を作成する
イベント・タイプ
イベント・ハンドラーの名前は、 BIRT レポート・エンジンに対して意味を持ちません。その代わり、イベント・ハンドラーの定義方法 (パラメーター・タイプとプロパティー) により、ハンドラーの呼び出し時期が決まります。 イベント・タイプ (eventType プロパティーの値) は、呼び出し時期を決める上で最も重要な要因となります。
- データ・ソース は、データのソースを表したものです。データ・ソースには、 JDBC データベース接続の詳細またはファイル名を含むことができます。 この場合、レポート・エンジンは、 データベースまたはファイルからビジネス・データを取得します。 このほかにも、データ・ソースはスクリプト設定されたデータ・ソース を表すこともあります。 この場合、レポート・エンジンは EGL プログラムからビジネス・データを取得します。 スクリプト設定されたデータ・ソースの例として、レコードの配列が挙げられます。スクリプト設定されたデータ・ソースを使用する場合は、 レポートに対して一度に 1 つのデータ行を渡すイベント・ハンドラーを記述します。
- データ・セット は、レポート・エンジンがファイル、 SQL 照会、またはストアード・プロシージャーから取得する列のセットです。 または、スクリプト設定されたデータ・ソースにより レポート・エンジンに渡される列のセットです (この場合、データ・セットは スクリプト設定されたデータ・セット と呼ばれます)。
- 行 と列 という用語は、派生元がリレーショナル・データベースでないデータについても用いられます。
以下に 2 つの例を挙げます。
- 非 XML テキスト・ファイルの最初の行にコンマ区切りの列名が含まれ、 2 行目にはコンマ区切りの列型が含まれるか、または 2 行目がコンマ区切りの列データによる行であり、 以降の各行が、コンマ区切りの列データによる行である場合。
- レコードの配列で、各レコードが行から構成され、所定のレコード内のフィールドが列である場合。
beforeOpen (あらゆる種類のデータ・ソース用)
openEvent (スクリプト設定されたデータ・ソース用)
afterOpen (前の beforeOpen イベントで参照されるデータ・ソース用)
beforeOpen (先に参照したデータ・ソースから派生するデータ・セット用)
openEvent (先に参照したスクリプト設定されたデータ・セット用)
afterOpen (先にリストされた beforeOpen イベントで参照されるデータ・セット用)
[先に参照したデータ・セットについてすべての行を取得するまでループ: ]
fetchEvent (スクリプト設定されたデータ・セットから行を取り出す)
onFetch (フェッチに応答してデータ・セットに対して呼び出される)
[ループ終了]
[データ・セットから取得される各行について、
すべてのレポート要素が作成されるまでループ: ]
onCreate (レイアウトに使用されるレポート要素の作成時に呼び出される)
onPageBreak (改ページが指定された場合に呼び出される)
[ループ終了]
beforeClose (先にデータを取り出したデータ・セット用)
closeEvent (先に参照したスクリプト設定されたデータ・セット用)
afterCloseDataSet (先にリストされた beforeClose イベントで参照される
データ・セット用)
beforeClose (先に参照したデータ・ソース用)
closeEvent (先に参照したスクリプト設定されたデータ・ソース用)
afterCloseDataSource (先にリストされた beforeClose イベントで参照されるデータ・ソース用)
- リレーショナル・データベースへのアクセスには、レポート・エンジンがデータベースに接続する前にイベントが発生します。
- XML またはその他ファイルの読み取りには、ファイルを開く前にイベントが発生します。
- スクリプト設定されたデータ・ソースについては、EGL が関数実行を作成して BIRT エンジンを開始した直後に発生します。
名前の末尾に「event」が付く各イベント・タイプ (openEvent、fetchEvent、および closeEvent) は、スクリプト設定されたデータ・ソースまたはデータ・セットにのみ機能します。
fetchEvent および onFetch イベントの意味を説明します。 先述のとおり、fetchEvent はスクリプト設定されたデータ・セットに固有であるのに対し、 onFetch は、スクリプト設定されたものも含め、あらゆるデータ・セットに使用できます。fetchEvent イベントを使用することで、プログラムがレポート・エンジンに渡す行の内容を提供できます。 また、 onFetch イベントを使用すると、レポート・エンジンが取得した (またはレポート・エンジンに渡した) 単一行のデータを検討できます。各イベント・ハンドラーは、すべての行が取得されるまで、 レポート・エンジンにより繰り返し呼び出されます。
- イベント・ハンドラーは、値 TRUE を戻す呼び出しごとに、データの行を渡します。
- イベント・ハンドラーが値 FALSE により応答した場合の結果は 2 とおりに分かれます。 1 つに、ハンドラーが 1 つ以上の列値を割り当てた場合でも、レポート・エンジンはその呼び出しではデータを処理しません。 もう 1 つに、レポート・エンジンは fetchEvent イベント・ハンドラーの呼び出しを停止します。
イベント・タイプが onFetch である場合、 イベント・ハンドラーは最後に取得した行にアクセスできますが、行を更新することはできず、 ブール値を戻しません。
イベント・ハンドラーのパラメーター・タイプ
イベント・ハンドラーで必要とされるパラメーター・タイプは、 イベント・タイプによって異なります。別の見方をすると、 イベント・タイプは、BIRT レポート・エンジンが実行時にイベント・ハンドラーに渡す引数のタイプを示すことになります。 次の表は、 イベント・タイプをアルファベット順に示し、関連するパラメーター・タイプがパラメーターの順に示されています。
| イベント・タイプ | パラメーター・タイプ |
|---|---|
| afterCloseDataSet | DataSetInstance |
| afterCloseDataSource | DataSourceInstance |
| afterOpen (データ・セット用) | DataSetInstance、ReportContext |
| afterOpen (データ・ソース用) | DataSourceInstance、ReportContext |
| beforeClose (データ・セット用) | DataSetInstance、ReportContext |
| beforeClose (データ・ソース用) | DataSourceInstance、ReportContext |
| beforeOpen (データ・セット用) | DataSetInstance、ReportContext |
| beforeOpen (データ・ソース用) | DataSourceInstance、ReportContext |
| closeEvent (EGL コードで提供されるデータ・セット用) | DataSetInstance |
| closeEvent (EGL コードで提供されるデータ・ソース用) | DataSourceInstance |
| fetchEvent (EGL コードで提供されるデータ・セット用) | DataSetInstance、UpdatableDataSetRow (関数はブール値を戻す) |
| onCreate | レイアウトに使用されるレポート要素のタイプ (例、 LabelInstance) と続けて ReportContext |
| onFetch (データ・セット用) | DataSetInstance、DataSetRow、ReportContext |
| onPageBreak | 最初に、改ページの前のページ内のレイアウトに使用されるレポート要素のタイプ (例、LabelInstance)、 2 番目に ReportContext |
| openEvent (EGL コードで提供されるデータ・セット用) | DataSetInstance |
| openEvent (EGL コードで提供されるデータ・ソース用) | DataSourceInstance |
レポートのレイアウト要素 (ラベルやイメージなど) の実行時作成に応答するイベント・ハンドラーと、 データ・アクセスの面から応答をするイベント・ハンドラーを区別して扱うことができます。前者のタイプのイベント・ハンドラーは onCreate または onPageBreak イベントの場合にアクセスし、後者はあらゆるタイプのイベントの場合にアクセスします。詳しくは、 『BIRT データ・アクセス・イベント・ハンドラー』および『BIRT レポート・レイアウト・イベント・ハンドラー (BIRT report-layout event handlers)』を参照してください。