EGL-BIRT-Handler

Ein EGL-BIRT-Handlerabschnitt enthält Ereignishandler, bei denen es sich um Funktionen handelt, die bei der Berichterstellung aufgerufen werden. Eine Übersicht zur EGL-Unterstützung für BIRT finden Sie im Abschnitt zur Berichterstellung mit BIRT im Programmiererhandbuch ("Creating reports with BIRT", Programmer's Guide).

In jedem Ereignishandler ist die Parameterliste für den Ereignistyp, auf den die Funktion reagiert, spezifisch. Ein Entwurf für einen BIRT-Handlerabschnitt ist nachfolgend dargestellt:

handler myBIRTHandler type BIRTHandler
   function myEventHandler01 (Parameterliste)
      {eventType = Ereignistyp, elementName="Name01"...} end 	 
   function myEventHandler02 (Parameterliste)
      {eventType = Ereignistyp, elementName="Name02"...} end
end

Wie in diesem Entwurf dargestellt, gibt die Verwendung der Eigenschaften eventType und elementName (sowie bei Bedarf weiterer Ereignishandlereigenschaften) an, dass es sich bei der Funktion um einen Ereignishandler handelt.

Vor der Beschreibung der Eigenschaft eventType wird im Folgenden die Verwendung des BIRT-Handlerabschnitts im EGL-Code, z. B. in einem Programm, umrissen:
  1. Erstellen Sie eine Variable, die auf einem Handlerabschnitt basiert.
  2. Codieren Sie eine Anweisung, die die Variable einem EGL-BIRT-Bericht zuordnet:
  3. Optional können Sie mithilfe der Variablen eine Datenquelle zuweisen, die bei der Berichterstellung verwendet wird.
  4. Erstellen Sie den Bericht.

Diese Schritte bewirken, dass die BIRT-Berichtsengine bei der Berichterstellung eine Gruppe von Ereignishandlern aufrufen kann.

Beispielprogramm:
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
Das Programm führt die folgenden Aktionen aus:
  1. Erstellt ein Array sowie eine Variable auf der Basis eines Handlerabschnitts.
  2. Ordnet diese Variable und zwei Dateinamen einem EGL-BIRT-Bericht zu.
  3. Weist eine Datenquelle zu.
  4. Erstellt die Berichtsausgabe.

Ereignistypen

Der Name eines Ereignishandlers ist für die BIRT-Berichtsengine nicht aussagekräftig. Stattdessen bestimmt die Art der Definition des Ereignishandlers (die Parametertypen und Eigenschaften), wann der Handler aufgerufen wird. Der Ereignistyp (der Wert der Eigenschaft eventType) ist der wichtigste Faktor bei der Bestimmung des Zeitpunkts des Aufrufs.

Vor dem Auflisten der verfügbaren Ereignistypen werden im Folgenden einige Begriffe erläutert:
  • Eine Datenquelle ist eine Darstellung des Ursprungs der Daten. Eine Datenquelle kann entweder JDBC-Datenbankverbindungsdetails oder einen Dateinamen enthalten; die Berichtsengine ruft dann die Geschäftsdaten aus der entsprechenden Datenbank oder Datei ab. Alternativ dazu kann die Datenquelle eine Scriptdatenquelle darstellen; dies bedeutet, dass die Berichtsengine die Geschäftsdaten aus Ihrem EGL-Programm abruft. Ein Beispiel für eine Scriptdatenquelle ist ein Array mit Datensätzen. Wenn eine Scriptdatenquelle verwendet wird, schreiben Sie einen Ereignishandler, der jeweils eine Datenzeile an den Bericht liefert.
  • Ein Dataset ist eine Spaltengruppe, die die Berichtsengine aus einer Datei, einer SQL-Abfrage oder einer gespeicherten Prozedur abruft. Alternativ dazu kann ein Dataset auch eine Spaltengruppe sein, die der Berichtsengine über eine Scriptdatenquelle, in der das Dataset als Scriptdataset bezeichnet wird, bereitgestellt wird.
  • Die Begriffe Zeile und Spalte werden auch für Daten verwendet, die nicht aus einer relationalen Datenbank abgerufen werden. Nachfolgend sind zwei Beispiele beschrieben:
    • Die erste Zeile einer Textdatei, bei der es sich nicht um eine XML-Datei handelt, enthält durch Kommas getrennte Spaltennamen; die zweite Zeile enthält entweder durch Kommas getrennte Spaltentypen oder durch Kommas getrennte Spaltendaten; alle nachfolgenden Zeilen bestehen aus durch Kommas getrennten Spaltendaten.
    • In einem Array mit Datensätzen stellt jeder Datensatz eine Zeile dar; ein Feld in einem bestimmten Datensatz ist eine Spalte.
Die Ereignistypen stammen aus der 'EventTypeKind'-Auflistung, deren verfügbare Werte hier in der Reihenfolge ihres Auftretens aufgeführt sind; dabei geben die Einrückungen die Beziehung eines Ereignisses zum folgenden Ereignis an:

  beforeOpen (für eine Datenquelle eines beliebigen Typs)
  openEvent (für eine Scriptdatenquelle)
  afterOpen (für die Datenquelle, die im vorhergehenden
                      'beforeOpen'-Ereignis referenziert wird)
          beforeOpen (für ein Dataset, das von der soeben
                      referenzierten Datenquelle abgeleitet wird)
          openEvent (für ein soeben referenziertes Scriptdataset)
          afterOpen (für das im oben angeführten
                      'beforeOpen'-Ereignis referenzierte Dataset)
              [in einer Schleife wiederholen, bis alle Zeilen für das soeben referenzierte Dataset abgerufen sind: ]
                  fetchEvent (eine Zeile aus einem Scriptdataset abrufen)
                  onFetch (für ein Dataset als Reaktion auf
                      einen Abruf aufgerufen)
              [Schleife beenden]
              [für jede aus dem Dataset abgerufene Zeile in einer Schleife
               wiederholen, bis alle Berichtselemente erstellt sind: ]
                  onCreate (wird aufgerufen, wenn ein Berichtselement
                     für das Layout erstellt wird)
                  onPageBreak (wird aufgerufen, wenn ein Seitenumbruch angegeben ist)
              [Schleife beenden]
           beforeClose (für das Dataset, dessen Daten soeben abgerufen wurden)
           closeEvent (für ein soeben referenziertes Scriptdataset)
           afterCloseDataSet (für das im oben angeführten
                      'beforeClose'-Ereignis referenzierte Dataset)
  beforeClose (für die soeben referenzierte Datenquelle)
  closeEvent (für eine soeben referenzierte Scriptdatenquelle)
  afterCloseDataSource (für die Datenquelle, die im oben angeführten
                      'beforeClose'-Ereignis referenziert wird)

Die Bedeutung der meisten Ereignisse erschließt sich aus dem Ereignisnamen. So tritt beispielsweise das 'beforeOpen'-Ereignis (für eine Datenquelle) auf, bevor eine Datenquelle geöffnet wird:
  • Beim Zugriff auf eine relationale Datenbank tritt das Ereignis auf, bevor die Berichtsengine eine Verbindung zur Datenbank herstellt.
  • Beim Lesen einer XML-Datei oder sonstigen Datei tritt das Ereignis auf, bevor die Datei geöffnet wird.
  • Bei einer Scriptdatenquelle tritt das Ereignis kurz nach der Ausführung einer EGL-Erstellungsfunktion zum Starten der BIRT-Engine auf.

Jeder Ereignistyp, dessen Name mit dem Wort 'event' endet, d. h. 'openEvent', 'fetchEvent' und 'closeEvent', wird nur für eine Scriptdatenquelle oder ein Scriptdataset ausgeführt.

Im Folgenden wird die Bedeutung von 'fetchEvent'- und 'onFetch'-Ereignissen erläutert. Wie bereits erwähnt, ist 'fetchEvent' für ein Scriptdataset spezifisch, wogegen 'onFetch' für jedes beliebige Dataset verwendet werden kann (auch für ein Scriptdataset). Sie können das 'fetchEvent-Ereignis verwenden, um Inhalte für eine Zeile bereitzustellen, die Ihr Programm der Berichtsengine bereitstellt; und Sie können das 'onFetch'-Ereignis verwenden, um Daten aus einer einzelnen Zeile zu überprüfen, die von der Berichtsengine abgerufen wurde (bzw. die Sie soeben der Berichtsengine bereitgestellt haben). Jeder Ereignishandler wird wiederholt von der Berichtsengine aufgerufen, bis alle Zeilen abgerufen sind.

Wenn der Ereignistyp 'fetchEvent' lautet, muss der Ereignishandler einen booleschen Wert zurückgeben und es gelten die folgenden Regeln:
  • Der Ereignishandler stellt bei jedem Aufruf, der den Wert TRUE zurückgibt, eine Datenzeile bereit.
  • Wenn der Ereignishandler den Wert FALSE zurückgibt, hat dies zwei Effekte: zum einen verarbeitet die Berichtsengine keine Daten für diesen Aufruf, selbst wenn der Handler einen oder mehrere Spaltenwerte zugewiesen hat; zum anderen stoppt die Berichtsengine den Aufruf des 'fetchEvent'-Ereignishandlers.

Wenn der Ereignistyp 'onFetch' lautet, kann der Ereignishandler auf die zuletzt abgerufene Zeile zugreifen; er kann die Zeile jedoch nicht aktualisieren und gibt keinen booleschen Wert zurück.

Parametertypen in Ereignishandlern

Die für einen bestimmten Ereignishandler erforderlichen Parametertypen sind abhängig vom jeweiligen Ereignistyp. Anders ausgedrückt: Der Ereignistyp gibt die Argumenttypen an, die die BIRT-Berichtsengine zur Laufzeit an den Ereignishandler übergibt. In der folgenden Tabelle sind die Ereignistypen in alphabetischer Reihenfolge zusammen mit den zugehörigen Parametertypen in der Parameterreihenfolge aufgeführt.

Ereignistypen Parametertypen
afterCloseDataSet DataSetInstance
afterCloseDataSource DataSourceInstance
afterOpen (für ein Dataset) DataSetInstance, ReportContext
afterOpen (für eine Datenquelle) DataSourceInstance, ReportContext
beforeClose (für ein Dataset) DataSetInstance, ReportContext
beforeClose (für eine Datenquelle) DataSourceInstance, ReportContext
beforeOpen (für ein Dataset) DataSetInstance, ReportContext
beforeOpen (für eine Datenquelle) DataSourceInstance, ReportContext
closeEvent (für ein durch EGL-Code bereitgestelltes Dataset) DataSetInstance
closeEvent (für eine durch EGL-Code bereitgestellte Datenquelle) DataSourceInstance
fetchEvent (für ein durch EGL-Code bereitgestelltes Dataset) DataSetInstance, UpdatableDataSetRow

(die Funktion gibt einen booleschen Wert zurück)

onCreate Der Typ eines für das Layout verwendeten Berichtselements (z. B. LabelInstance); anschließend ReportContext
onFetch (für ein Dataset) DataSetInstance, DataSetRow, ReportContext
onPageBreak Zuerst der Typ des Berichtselements (z. B. 'LabelInstance'), das für ein Layout an einer beliebigen Stelle auf der Seite vor dem Seitenumbruch verwendet wird, danach 'ReportContext'.
openEvent (für ein durch EGL-Code bereitgestelltes Dataset) DataSetInstance
openEvent (für eine durch EGL-Code bereitgestellte Datenquelle) DataSourceInstance

Es wird unterschieden zwischen Ereignishandlern, die auf die Laufzeiterstellung von Berichtslayoutelementen wie Bezeichnungen und Images reagieren, und Ereignishandlern, die auf bestimmte Aspekte des Datenzugriffs reagieren. Auf den ersteren Ereignishandlertyp wird bei 'onCreate'- oder 'onPageBreak'-Ereignissen zugegriffen, auf den letzteren bei allen anderen Ereignisarten. Details hierzu finden Sie in den Abschnitten 'BIRT-Ereignishandler für den Datenzugriff' und 'BIRT-Ereignishandler für das Berichtslayout'.


Feedback