Externe Typen in einem BIRT-Ereignishandler für den Datenzugriff

In diesem Abschnitt werden die externen EGL-Typen beschrieben, die Sie bei der Codierung eines Ereignishandlers für den Datenzugriff verwenden. Hintergrundinformationen finden Sie in den Abschnitten 'EGL-BIRT-Berichte', 'BIRT-Handler' und 'BIRT-Ereignishandler für den Datenzugriff'.

ColumnMetaData

Eine Variable des Typs ColumnMetaData enthält Informationen zum Namen und Typ jeder Spalte im Dataset. Sie erhalten eine solche Variable, wenn Sie mit einer Variablen des Typs DataSetInstance arbeiten und die Funktion getColumnMetaData aufrufen.

Die Variable des Typs 'ColumnMetaData' macht die folgenden Funktionen verfügbar:
  • getColumnCount gibt die Anzahl der Spalten in einer Zeile des Datasets zurück.
     element.getColumnCount() returns (INT)
  • getColumnName gibt den Namen einer Spalte zurück, die durch eine Indexnummer identifiziert wird.
     element.getColumnName( index INT in ) returns (STRING)
  • getColumnDisplayName gibt den Anzeigenamen der Spalte zurück, die durch eine Indexnummer identifiziert wird. Der BIRT Report Designer verwendet den Namen bei der Anzeige der Spalte in der Datenexploreransicht sowie für die automatische Generierung von Spaltenüberschriften in einer Tabelle, wenn die Spalte während des Berichtsdesignprozesses aus der Datenexploreransicht gezogen und in der Tabelle abgelegt wird.
     element.getColumnDisplayName( index INT in ) returns (STRING)

    Die Java™-Methode, die dieser EGL-Funktion zugeordnet ist, lautet 'getColumnLabel'.

  • getColumnAlias gibt den Aliasnamen einer Spalte zurück, die durch eine Indexnummer identifiziert wird. Der Report Designer kann diesen Aliasnamen als kürzeren oder aussagekräftigeren Namen für eine Spalte verwenden, wenn er im Berichtsdesign darauf verweist. So kann einer Spalte mit dem Namen '$FN' der Aliasname 'firstName' zugewiesen werden, sodass in einem Ausdruck 'row["firstName"]' anstelle von 'row["$FN"]' verwendet werden kann.
     element.getColumnAlias( index INT in ) returns (STRING)
  • getColumnTypeName gibt den Typ der Spalte zurück, die durch eine Indexnummer identifiziert wird, die die Position der Spalte in der Zeile darstellt. Ein zurückgegebener Wert kann 'Integer', 'Double', 'Decimal', 'String', 'Date' oder 'Any' lautetn.
     element.getColumnTypeName( index INT in )returns (STRING)

    Die erste Spalte weist die Nummer 1 auf, nicht 0.

  • getColumnNativeTypeName gibt den nativen Typ der Spalte zurück, die durch eine Indexnummer identifiziert wird, die die Position der Spalte in der Zeile darstellt. Der native Typ ist einer der gültigen Typen für die Datenquelle und abhängig von der Art der Datenquelle. Zum Beispiel kann der native Typ für eine Flatfile 'bigdecimal', 'time', 'timestamp', 'date', 'double', 'int' oder 'string' sein. Bei einer JDBC-Datenquelle sind die unterstützten nativen Typen abhängig vom Typ des Datenbankverwaltungssystems, auf das zugegriffen wird.
     element.getColumnNativeTypeName( index INT in )returns (STRING)

    Die erste Spalte weist die Nummer 1 auf, nicht 0.

  • isComputedColumn gibt einen booleschen Wert zurück, der angibt, ob die Spalte berechnet und nicht aus der Datenquelle abgerufen ist. Eine berechnete Spalte enthält das Ergebnis eines Ausdrucks, in dem normalerweise eine oder mehrere aus der Datenquelle abgerufene Spalten verwendet werden. Beispiel: Wenn jede aus der Datenquelle abgerufene Zeile Spalten mit den Namen 'firstName' und 'lastName' enthält, kann eine berechnete Spalte mit dem Namen 'fullName' mithilfe des folgenden Ausdrucks definiert werden:
     row["firstName"] + " " + row["lastName"]

    Sie definieren eine berechnete Spalte für ein Dataset, wenn Sie in der Datenexploreransicht arbeiten.

     element.isComputedColumn(index INT in) returns (BOOLEAN)

DataSetInstance

Eine Variable des Typs 'DataSetInstance' referenziert ein Berichtselement, das ein Dataset, d. h. eine Gruppe von Spalten, darstellt; eine Beschreibung hierzu finden Sie im Abschnitt 'BIRT-Handler'. Die Variable macht die folgenden Funktionen verfügbar:
  • getName gibt den Namen für das Dataset zurück, der in der Designdatei angegeben ist.
     element.getName()returns (STRING)
  • getExtensionID gibt den Wert der BIRT-ODA-Erweiterungs-ID (ODA = Open Data Access) zurück. Für eine Datenquelle, die eine SQL-Abfrage verwendet, kann der Wert beispielsweise 'org.eclipse.birt.report.data.oda.jdbc.JdbcSelectDataSet' lauten.
     element.getExtensionID()returns (STRING)
  • getExtensionProperty gibt den Wert einer BIRT-ODA-Erweiterungseigenschaft zurück.
     element.getExtensionProperty(propertyName STRING in) returns (STRING)
  • setExtensionProperty legt den Wert einer ODA-Erweiterungseigenschaft fest.
     element.setExtensionProperty
       (propertyName STRING in, value STRING in) 
  • getDataSource ruft die für das Dataset spezifische Datenquelle ab.
     element.getDataSource () returns (DataSourceInstance)
  • getColumnMetaData ruft eine Variable des Typs 'ColumnMetaData' ab, die Informationen zum Typ und Namen jeder Spalte im Dataset enthält. Weitere Details zur Art der verfügbar gemachten Informationen finden Sie im Abschnitt zu getColumnMetaData.
     element.getColumnMetaData () returns (ColumnMetaData)
Die Variable des Typs 'DataSetInstance' macht darüber hinaus das folgende Feld verfügbar:
  • queryText ist ein Feld des Typs STRING, das die SQL-Abfrage enthält, aus der die Berichtsengine ein Dataset ableitet. Wenn eine SQL-Abfrage nicht verfügbar ist, wird als Wert für queryText eine leere Zeichenfolge zurückgegeben.
    Im folgenden Beispiel ruft die Berichtsengine einen Ereignishandler (für den Ereignistyp 'beforeOpen' und das Dataset 'dataSet') auf, bevor sie eine SQL-Abfrage öffnet.
    function setQuery( d DataSetInstance, c ReportContext ) 
       { eventType = beforeOpen, elementName = "dataSet" }
       queryStr string;
       if( region == "EUR" )
          queryStr = "select region, country, city from locations 
             where region = \"EUROPE\"";
       else 
          queryStr = "select region, country, city from locations 
             where region = \"ASIA\"";
    	  end
    	  d.queryText = queryStr;
    end

    In diesem Beispiel legt der Ereignishandler eine SQL-Abfragezeichenfolge oder eine alternative SQL-Abfragezeichenfolge als Reaktion auf eine Geschäftssituation fest. Es wird davon ausgegangen, dass die Variable region deklariert und global gesetzt ist, und zwar außerhalb der Funktion.

Im Folgenden ist das Beispielprogramm dargestellt, zu dem der Abschnitt 'EGL-BIRT-Handler' eine Einführung und eine Beschreibung enthält:
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
Im folgenden Code ist das Scriptdataset (ein vom EGL-Code bereitgestelltes Dataset) aus Feldern in den einzelnen Elementen eines dynamischen Arrays zusammengesetzt. Ein Scriptdataset kann aus einer beliebigen Gruppe von Feldern bestehen, die Sie der Berichtsengine bereitstellen, indem Sie Ereignishandler verwenden, deren Ereignistypen 'openEvent' und 'fetchEvent' lauten.
package EGLDataSources;  

Handler arrayHandler type BIRTHandler 
   index int;
   customerArr customer[];	

   function setCustomerArray(a customer[])
      customerArr = a;	
   end 	 	

   function openFunction( d DataSetInstance )
      { eventType = openEvent, elementName = "myDataSet" }
      index = 0; 	
   end

   function fetchFunction(d DataSetInstance, row UpdatableDataSetRow )
      returns( boolean ) 	
      { eventType = fetchEvent, elementName = "myDataSet" } 		

      index = index + 1; 		

      if( index <= customerArr.getSize() )
         row.setColumnValue( "customer_num", customerArr[index].customerNumber ); 			
         row.setColumnValue( "fname", customerArr[index].firstName );
         row.setColumnValue( "lname", customerArr[index].lastName );
         return (TRUE); 		
      else 			
         return (FALSE); 		
      end
   end
end

Datasetspaltennamen (wie z. B. customer_num, fName und lName) können von den entsprechenden EGL-Feldnamen (z. B. customerNumber, firstName und lastName) abweichen.

Zusätzliche Details hierzu finden Sie im Abschnitt zu 'DataSetRow' und 'UpdatableDataSetRow'.

DataSetRow

Eine Variable des Typs DataSetRow referenziert eine von der Berichtsengine bereitgestellte Datenzeile. Die Variable macht die folgenden Funktionen verfügbar:
  • getDataSet gibt das Dataset zurück.
     element.getDataSet()returns (DataSetInstance)
  • getColumnValue gibt den Wert einer Spalte zurück, die durch eine Indexnummer identifiziert wird.
     element.getColumnValue(index INT in)returns (ANY)

    Die erste Spalte weist die Nummer 1 auf, nicht 0.

  • getColumnValue gibt den Wert einer Spalte zurück, die durch einen Namen identifiziert wird.
     element.getColumnValue(columnName STRING in) returns (ANY)

Diese Funktionen sind auch für eine Variable des Typs UpdatableDataSetRow verfügbar.

DataSourceInstance

Eine Variable des Typs 'DataSourceInstance' referenziert ein Berichtselement, das eine Datenquelle, d. h. eine Darstellung der Quelle der Daten, repräsentiert; eine Beschreibung hierzu finden Sie im Abschnitt 'BIRT-Handler'. Die Variable macht die folgenden Funktionen verfügbar:
  • getName gibt den Namen für die Datenquelle zurück, der in der Designdatei angegeben ist.
     element.getName()returns (STRING)
  • getExtensionID gibt den Wert der BIRT-ODA-Erweiterungs-ID (ODA = Open Data Access) zurück. Für eine JDBC-Datenquelle kann der Wert beispielsweise 'org.eclipse.birt.report.data.oda.jdbc' lauten.
     element.getExtensionID()returns (STRING)
  • getExtensionProperty gibt den Wert einer BIRT-ODA-Erweiterungseigenschaft zurück, wie zum Beispiel:
    • odaDriverClass (für die Treiberklasse, die für den JDBC-Zugriff auf eine relationale Datenbank verwendet wird)
    • odaUser (für die Benutzer-ID, die zum Herstellen einer Verbindung zur Datenbank verwendet wird)
    • odaPassword (für das Kennwort, die zum Herstellen einer Verbindung zur Datenbank verwendet wird)
     element.getExtensionProperty(propertyName STRING in) returns (STRING)
  • setExtensionProperty legt den Wert einer ODA-Erweiterungseigenschaft fest.
     element.setExtensionProperty
       (propertyName STRING in, value STRING in) 

Sie können den Parameter des Typs 'DataSourceInstance' dazu verwenden, die Benutzer-ID und das Kennwort festzulegen, die von der BIRT-Berichtsengine zum Herstellen einer Verbindung zu einer relationalen Datenbank verwendet werden. In diesem Beispielcode wird davon ausgegangen, dass es sich bei den Variablen userName und password um globale Variablen handelt, die außerhalb der Funktion definiert wurden:

   function setUser( d DataSourceInstance, c ReportContext ) 
      { eventType = beforeOpen, elementName = "myDataSource" }
      d.setExtensionProperty( "odaUser", userName );
      d.setExtensionProperty( "odaPassword", password );
   end

ReportContext

Ein Ereignishandlerparameter des Typs 'ReportContext' ermöglicht den Zugriff auf die Berichtsparameter. Es sind zwei Funktionen verfügbar:
  • setParameterValue legt den Wert eines Berichtsparameters fest, der anhand des Namens identifiziert wird:
     reportContext.setParameterValue
     ( parameterName STRING in, parameterValue ANY in ) 
  • Entsprechend ruft getParameterValue den Wert eines Berichtsparameters ab:
     reportContext.getParameterValue
     ( parameterName STRING in) returns (ANY)  

UpdatableDataSetRow

Eine Variable des Typs UpdatableDataSetRow stellt der Berichtsengine eine Datenzeile bereit. Die Variable kann jede der Funktionen verwenden, die im Zusammenhang mit DataSetRow beschrieben werden.

Darüber hinaus stehen zweit Setter-Funktionen zur Verfügung:
  • setColumnValue legt den Wert einer Spalte fest, die durch eine Indexnummer identifiziert wird.
     element.setColumnValue(index INT in, value ANY in)

    Die erste Spalte weist die Nummer 1 auf, nicht 0.

  • setColumnValue legt den Wert einer Spalte fest, die durch einen Namen identifiziert wird.
     element.setColumnValue(columnName STRING in, value ANY in)

Feedback