There are two JAR files that contain all the classes and interfaces that an event handler requires. One of the JAR files is a part of BIRT Report Designer and SDK and the other one is a part of BIRT Report Engine.

The JAR file that you use for developing a Java event handler is org.eclipse.birt.report.engine_Version.jar, which is located in the Eclipse plugins directory for BIRT Report Designer and SDK.

The JAR file that you use when you deploy your report is scriptapi.jar, which is located in the WebViewerExampleWEB-INFlib directory of BIRT Report Engine. All JAR files in the WebViewerExampleWEB-INFlib directory are in a deployed report’s classpath, so there is no need to do anything special to make scriptapi.jar accessible at run time.

An element’s adapter class implements the element’s interface and provides empty stubs for every method. To use the adapter class, extend the adapter class and override the methods for which you are providing handler code. Eclipse recommends extending an adapter class rather than implementing an interface directly.

BIRT naming conventions for the event handler interfaces and adapter classes are discussed later in this chapter.

How to create an event handler class and add it to the Java project

This section describes the process for using the Eclipse Java development environment to create an event handler class for a scriptable BIRT element.

All BIRT ROM element interface names begin with the letter I, which is followed by the name of the ROM element and then EventHandler. For example, the interface for the Label element is ILabelEventHandler.

All BIRT ROM element adapter class names begin with the name of the element, followed by EventAdapter. For example, the name of the adapter class for a Label element is LabelEventAdapter.

All BIRT ROM element instance interface names begin with the letter I, followed by the name of the element and then Instance. For example, the ROM element instance interface for a Label element is ILabelInstance.

All BIRT ROM element instance design interface names begin with the letter I, followed by the name of the element. For example, the design interface for a Label element is ILabel.

BIRT provides event handler adapter classes for every scriptable report element. An event handler adapter class contains empty methods for every event handler method for the element. If your class extends an adapter class, you need to override only the methods for the events for which you want to provide handler code.

One advantage of using an adapter class instead of implementing an interface is that your class will compile even if methods are added to the interface in a future release. If the signature of an event handler method changes in a future release, however, you must change your implementation of that method to reflect the signature change. The class will compile even if you do not change the method with the changed signature, but the method with the wrong signature will never be called.

BIRT provides event handler interfaces for every scriptable report element. If your event handler class extends an adapter class, the adapter class implements the correct interface. If your class does not extend an adapter class, then your class must implement the appropriate interface for the report element you are scripting.

There are some advantages of specifying an interface instead of extending an adapter class. Eclipse generates stubs for every method the interface specifies. The stubs show the method arguments, so you can see the argument types of the methods you must implement. If your class extends an adapter class, there are no generated stubs for you to examine. You also have more freedom in the design of your class structure if you avoid using an adapter class. For example, you might want two or more event handler classes to extend a single base class. Because Java does not support multiple inheritance, the event handler class cannot extend both the adapter class and the base class. However, if the event handler class implements an interface instead of extending an adapter class, there is nothing to prevent the event handler class from extending the base class.

The disadvantage of using an interface over an adapter class is that if additional methods are added to an interface in a future release, a class that implements the interface fails to compile.

You can write an event handler for any or all the events that BIRT fires for a report item. Table 10-1 describes the events BIRT fires for each report item.

The DataSource event handler interface has four methods that you can implement to respond to events. A Java class to handle these events must implement the IDataSourceEventHandler interface or extend the DataSourceAdapter class.

All the event methods receive an IReportContext object. All the methods except the afterClose( ) method also receive an IDataSetInstance object. The onFetch( ) method also receives an IDataSetRow object. These interfaces are discussed later in this chapter. Table 10-2 lists the four methods that you can implement for a DataSource element.

BIRT fires five events for the DataSet element. A Java class to handle these events must implement the IDataSetEventHandler interface or extend the DataSetAdapter class. All DataSet event handler methods receive an IReportContext object. Additionally, all DataSet event handler methods except the afterClose( ) method receive an IDataSetInstance object. The onFetch( ) method receives a third object, an IDataSetRow object. These interfaces are described later in this chapter. Table 10-3 lists the five methods that you can implement for a DataSet element.

The ScriptedDataSource interface extends the IDataSourceEventHandler interface, which has four methods. The ScriptedDataSource interface adds two new methods to the four of the IDataSourceEventHandler interface. A Java class that provides the ScriptedDataSource event handlers must implement IScriptedDataSourceEventHandler interface or extend the ScriptedDataSourceAdapter class. A Java class that provides the ScriptedDataSource event handlers must implement the two methods of the IScriptedDataSourceEventHandler interface plus the four methods of the IDataSourceEventHandler interface, which it extends.

Both of the two event handler methods of IScriptedDataSourceEventHandler receive an IDataSourceInstance object. Table 10-4 lists the two additional methods that you must implement for a ScriptedDataSource element.

The ScriptedDataSet interface extends the IDataSetEventHandler interface, which has four methods. The ScriptedDataSet interface adds four new methods to the four of the IDataSourceEventHandler interface. Of the four new methods, three must be fully implemented and the fourth may be empty. A Java class that provides the ScriptedDataSet event handlers must implement IScriptedDataSetEventHandler interface or extend the ScriptedDataSetAdapter class. A Java class that provides the ScriptedDataSet event handlers must implement the four methods of the IScriptedDataSetEventHandler interface plus the four methods of the IDataSourceEventHandler interface, which it extends.

Table 10-5 lists the four additional methods that you must implement for a ScriptedDataSet element.

BIRT fires several events that the ReportDesign element handles. A Java class to handle these events must implement the IReportEventHandler interface or extend the ReportEventAdapter class. All of the event handler methods receive an IReportContext object. The beforeFactory( ) method also receives an IReportDesign object. Table 10-6 lists the methods that you can implement for a ReportDesign element in the order in which they fire.

Every element has a unique element design interface. The element design is a Java interface that specifies methods for accessing and setting specific features of the element’s design. Every element design interface inherits methods from IReportElement.

The element instance interfaces are available at run time, but not at design time. They contain the run-time instance of the element. The element instance interface is passed to both onCreate( ), the generation phase event handler, and to onRender( ), the presentation phase event handler.

Through instance interfaces, you have access to a different set of properties than you do at design time. There is no superinterface from which all element instance interfaces inherit. Like the element design interface, the set of methods in the instance interfaces varies from element to element.

For example, ICellInstance, the Cell instance interface, contains the following methods:

By comparison, IRowInstance, the Row instance interface, contains these methods:

For a complete list of all instance interfaces, see the BIRT Javadoc in the BIRT online help.

An object of type IReportContext is passed to all event handlers except those for ScriptedDataSource and ScriptedDataSet objects. The IReportContext interface includes the methods shown in Table 10-7.

The IColumnMetaData interface provides information about the columns of the data set. Table 10-8 lists the methods in the IColumnMetaData interface class.

The IDataSetInstance interface provides access to many aspects of the data set and associated elements. An IDataSetInstance object is passed to every DataSet event handler method.

Table 10-9 describes the methods in the interface IDataSetInstance.

An object of the IDataSetRow type is passed to the DataSet.onfetch( ) event handler method. Table 10-10 lists the methods in the IDataSetRow interface. Note that there are two getColumnValue( ) methods. The two methods differ only in the argument that specifies the column containing the value. They both return a java.lang.Object object, which you must cast to the appropriate type for the column.

An object of the IRowData type is returned from the getRowData( ) method of IReportElementInstance, which every report element instance interface extends.

IRowData provides access to the bound values that appear in the table. The IRowData interface has two getExpressionValue( ) methods. Both methods return the display value for a specific column in the table. The two methods differ in the argument you pass to specify the column that you require. Table 10-11 lists the methods in the IRowData interface.