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

この概要に示すように、eventTypeelementName プロパティー (および必要に応じて他のイベント・ハンドラー・プロパティー) は、関数がイベント・ハンドラーであることを示します。

eventType プロパティーについて説明する前に、EGL コードでの BIRT ハンドラーの使用方法の概略を説明します。 例えばプログラム内で次の操作をするとします。
  1. ハンドラー・パーツに基づく変数を作成する
  2. 変数を EGL BIRT レポートに関連付けるステートメントをコーディングする
  3. 必要に応じて、変数を使用して、レポートの作成時に使用するデータ・ソースを割り当てる
  4. レポートを作成する

これらのステップを受けて、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
このプログラムの動作は、以下のとおりです。
  1. 配列、およびハンドラー・パーツに基づく変数を作成する
  2. その変数と 2 つのファイル名を EGL BIRT レポートに関連付ける
  3. データ・ソースを割り当てる
  4. レポート出力を作成する

イベント・タイプ

イベント・ハンドラーの名前は、 BIRT レポート・エンジンに対して意味を持ちません。その代わり、イベント・ハンドラーの定義方法 (パラメーター・タイプとプロパティー) により、ハンドラーの呼び出し時期が決まります。 イベント・タイプ (eventType プロパティーの値) は、呼び出し時期を決める上で最も重要な要因となります。

使用可能なイベント・タイプのリストを挙げる前に、いくつかの語句を明確にしておきましょう。
  • データ・ソース は、データのソースを表したものです。データ・ソースには、 JDBC データベース接続の詳細またはファイル名を含むことができます。 この場合、レポート・エンジンは、 データベースまたはファイルからビジネス・データを取得します。 このほかにも、データ・ソースはスクリプト設定されたデータ・ソース を表すこともあります。 この場合、レポート・エンジンは EGL プログラムからビジネス・データを取得します。 スクリプト設定されたデータ・ソースの例として、レコードの配列が挙げられます。スクリプト設定されたデータ・ソースを使用する場合は、 レポートに対して一度に 1 つのデータ行を渡すイベント・ハンドラーを記述します。
  • データ・セット は、レポート・エンジンがファイル、 SQL 照会、またはストアード・プロシージャーから取得する列のセットです。 または、スクリプト設定されたデータ・ソースにより レポート・エンジンに渡される列のセットです (この場合、データ・セットは スクリプト設定されたデータ・セット と呼ばれます)。
  • という用語は、派生元がリレーショナル・データベースでないデータについても用いられます。 以下に 2 つの例を挙げます。
    • 非 XML テキスト・ファイルの最初の行にコンマ区切りの列名が含まれ、 2 行目にはコンマ区切りの列型が含まれるか、または 2 行目がコンマ区切りの列データによる行であり、 以降の各行が、コンマ区切りの列データによる行である場合。
    • レコードの配列で、各レコードが行から構成され、所定のレコード内のフィールドが列である場合。
イベント・タイプは、EventTypeKind 列挙型から取得されます。 このイベント・タイプの有効な値をその出現順にリストします。また、字下げして、次のイベントへの関連も示しています。

  beforeOpen (あらゆる種類のデータ・ソース用)
  openEvent (スクリプト設定されたデータ・ソース用)
  afterOpen (前の beforeOpen イベントで参照されるデータ・ソース用)
          beforeOpen (先に参照したデータ・ソースから派生するデータ・セット用)
          openEvent (先に参照したスクリプト設定されたデータ・セット用)
          afterOpen (先にリストされた beforeOpen イベントで参照されるデータ・セット用)
              [先に参照したデータ・セットについてすべての行を取得するまでループ: ]
                  fetchEvent (スクリプト設定されたデータ・セットから行を取り出す)
                  onFetch (フェッチに応答してデータ・セットに対して呼び出される)
              [ループ終了]
              [データ・セットから取得される各行について、
               すべてのレポート要素が作成されるまでループ: ]
                  onCreate (レイアウトに使用されるレポート要素の作成時に呼び出される)
                  onPageBreak (改ページが指定された場合に呼び出される)
              [ループ終了]
           beforeClose (先にデータを取り出したデータ・セット用)
           closeEvent (先に参照したスクリプト設定されたデータ・セット用)
           afterCloseDataSet (先にリストされた beforeClose イベントで参照される
                                     データ・セット用)
  beforeClose (先に参照したデータ・ソース用)
  closeEvent (先に参照したスクリプト設定されたデータ・ソース用)
  afterCloseDataSource (先にリストされた beforeClose イベントで参照されるデータ・ソース用)

ほとんどのイベント名の意味は、イベント名が示すとおりです。 例えば、(データ・ソースの) beforeOpen イベントは、データ・ソースを開く前に発生します。
  • リレーショナル・データベースへのアクセスには、レポート・エンジンがデータベースに接続する前にイベントが発生します。
  • XML またはその他ファイルの読み取りには、ファイルを開く前にイベントが発生します。
  • スクリプト設定されたデータ・ソースについては、EGL が関数実行を作成して BIRT エンジンを開始した直後に発生します。

名前の末尾に「event」が付く各イベント・タイプ (openEvent、fetchEvent、および closeEvent) は、スクリプト設定されたデータ・ソースまたはデータ・セットにのみ機能します。

fetchEvent および onFetch イベントの意味を説明します。 先述のとおり、fetchEvent はスクリプト設定されたデータ・セットに固有であるのに対し、 onFetch は、スクリプト設定されたものも含め、あらゆるデータ・セットに使用できます。fetchEvent イベントを使用することで、プログラムがレポート・エンジンに渡す行の内容を提供できます。 また、 onFetch イベントを使用すると、レポート・エンジンが取得した (またはレポート・エンジンに渡した) 単一行のデータを検討できます。各イベント・ハンドラーは、すべての行が取得されるまで、 レポート・エンジンにより繰り返し呼び出されます。

イベント・タイプが fetchEvent である場合、 イベント・ハンドラーはブール値を戻す必要があります。 次の規則が適用されます。
  • イベント・ハンドラーは、値 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)』を参照してください。


フィードバック