BIRT data-access event handlers

A data-access event handler lets you work with a data source or a data set, as described in "EGL BIRT handler". Also, if you have access to a parameter of type ReportContext, you can access each report parameter at the time the event handler is invoked. You might set a report parameter to a particular customer number, for example, to specify which customer's data will be brought into the report.

Consider an event handler whose eventType is beforeOpen and whose purpose is to update a data source named myDataSource: 
function setUser( d DataSourceInstance, c ReportContext ) 
   { eventType = beforeOpen, elementName = "myDataSource" }
   d.setExtensionProperty( "odaUser", userName );
   d.setExtensionProperty( "odaPassword", password );
end

The example does not use a report parameter, but uses the event-handler parameter d (of type DataSourceInstance) to set a user ID and a password, which are both used by the BIRT report engine to connect to a relational database. The example assumes that the variables userName and password are global and were set outside of the function.

The previous example also includes two properties:
  • eventType, which is used in all the BIRT event handlers; and
  • elementName, which is used in most of the data-access event handlers. The value of the elementName property must match a name specified in the report design file, and the name refers to a data source or data set, depending on the purpose of the event handler.

Each of the parameters in a data-access event handler is based on an EGL external type that represents a Java™ interface. The next table tells the type and purpose of each data-access parameter, along with the unqualified name of the related Java™ interface.

Parameter type Purpose Java™ Interface
DataSetInstance To access overall details on a data set IDataSetInstance
DataSetRow To access column-specific details on a data set IDataSetRow
DataSourceInstance To access details on a data source IDataSourceInstance
ReportContext To get or set report-parameter values IReportContext
UpdatableDatasetRow To provide a row of data to the report. IUpdatableDatasetRow

You may never need to know the Java-specific details, but the Javadoc™ that describes each of the interfaces is in the BIRT Report Scripting API Reference, which is in your product help system under BIRT Programmer Reference > Reference > APIReference > BIRT Report Scripting API Reference. The Java™ interfaces IDataSourceInstance and IDataSetInstance are in org.eclipse.birt.report.engine.api.script.instance, whereas DataSetRow, UpdatableDatasetRow and ReportContext are in package org.eclipse.birt.report.engine.api.script.