Writing a Java event handler class
To provide one or more Java event handlers for a scriptable BIRT element, create one class that contains all the Java event handlers for that element. Creating a class that contains event handler methods for more than one element is not advisable.
BIRT provides Java interfaces and Java adapter classes to simplify writing a Java event handler class. Every scriptable BIRT element has one interface and one adapter class. An element’s event handler interface defines all the event handler methods for that element. A handler class must implement every method defined in the interface, even if some of the methods are empty. You provide code for only the event handlers that you want to implement.
Locating the JAR files for a BIRT event handler
Each of two JAR files contains 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. Use either JAR file to develop a custom event handler.
The first JAR file that you can 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 second JAR file that you use when you develop and deploy your report is scriptapi.jar, which is located in the \WebViewerExample\WEB-INF\lib directory of BIRT Report Engine. Note that scriptapi.jar content has been folded into org.eclipse.birt.report.engine_<version>.jar as of version 3.7.
All JAR files in the \WebViewerExample\WEB-INF\lib directory are in the deployed report classpath, so scriptapi.jar is accessible at run time. To use the scriptapi.jar file in the development phase, download the report engine and reference scriptapi.jar from within the build path.
The required JAR files are also in the ReportEngine\lib directory of BIRT Report Engine. If you are using the Report Engine API to run reports, add the JAR files in this directory to the classpath and build path. If you are using the report engine plug‑in in an Eclipse application, this step is not required, because the plug‑in already contains the dependency and classpath entries.
Extending an adapter class
An element adapter class implements the element 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. The steps assume that the Java perspective is open and that a Java project exists in the workspace.
1 Add org.eclipse.birt.report.engine_<version>.jar to a Java project, as described in the following steps:
1 In Navigator, select a Java project and choose FileProperties. In Properties, select Java Build PathLibraries. In Java Build Path, choose Add External JARs.
2 In JAR Selection, navigate to the Eclipse /plugins directory. In a default Eclipse installation, this directory is in the following location:
<ECLIPSE_INSTALL>\eclipse\plugins
3 Select org.eclipse.birt.core_<version>.jar. Use control-click to select org.eclipse.birt.report.engine_<version>.jar. Choose Open. Java Build Path appears, as shown in Figure 38‑1. Choose OK.
Figure 23-1 The report engine JAR file in the build pathFigure 23-1 The report engine JAR file in the build path
Figure 38‑1 The report engine JAR file in the build path
2 Select the Java project and choose FileNewClass.
3 In New Java Class, follow these steps to set up the Java class properties:
1 Navigate to the folder where you want the Java source file to reside by choosing the Browse button beside Source Folder.
2 If the new Java class is a part of a package, type the fully qualified package name in Package.
3 In Name, type a name for the class.
4 In Modifiers, select Public.
5 To select the ROM element event adapter class to extend, choose the Browse button beside Superclass.
6 In Superclass Selection, in Choose a type, type the name of the event adapter class for the ROM element. For example, for a label element, type LabelEventAdapter, as shown in Figure 38‑2.
Figure 23-2 Selecting a SuperclassFigure 23-2 Selecting a Superclass
Figure 38‑2 Selecting a superclass
Choose OK.
4 In New Java Class, select Generate comments. New Java Class is similar to the one shown in Figure 38‑3.
Figure 23-3 New Java Class final propertiesFigure 23-3 New Java Class final properties
Figure 38‑3 New Java Class final properties
5 Choose Finish. The Java editor is similar to the one shown in Figure 38‑4.
Figure 23-4 The new class in the Java editorFigure 23-4 The new class in the Java editor
Figure 38‑4 The new class in the Java editor
6 Add the event handler method for the event handler class. Import all required classes. Figure 38‑5 shows the addition of an onPrepare( ) method that sets the background color of a label to red.
Figure 23-5 The onPrepare( ) method in the Java editorFigure 23-5 The onPrepare( ) method in the Java editor
Figure 38‑5 The onPrepare( ) method in the Java editor
7 Choose FileSave.
Making the Java class visible to BIRT
To make a Java event handler class visible to the BIRT report designer, create a Java development project to compile the class in the same workspace as the BIRT report project. Alternatively, place the class in a directory or JAR file specified in the BIRT classpath. To deploy the report to an application server, copy the Java class to the appropriate location on the server.
Associating a Java event handler class with a report element
After creating the Java event handler class and coding the appropriate handler methods, associate the class with a report element.
How to associate a Java class with a report element
The steps in this procedure make the following assumptions:
*A report design is open in the Report Design perspective.
*The report design includes a scriptable report item, such as a label.
*A Java class containing event handler methods for the scriptable report item is visible to the report.
1 In Outline, select the report element for which an event handler class is visible, as shown in Figure 38‑6.
Figure 23-6 Selecting a report elementFigure 23-6 Selecting a report element
Figure 38‑6 Selecting a report element
2 In Property Editor, choose Event Handler, as shown in Figure 38‑7.
Figure 23-7 Event handler propertiesFigure 23-7 Event handler properties
Figure 38‑7 Event handler properties
3 Choose Browse. Class Selection shows available event handler classes.
4 Select the event handler class that extends the BIRT ROM event adapter class, as shown in Figure 38‑8. Then, choose OK.
Figure 23-8 Selecting the event handler classFigure 23-8 Selecting the event handler class
Figure 38‑8 Selecting the event handler class
The fully qualified name of the event handler class appears in Property Editor, as shown in Figure 38‑9.
Figure 23-9 The event handler class nameFigure 23-9 The event handler class name
Figure 38‑9 The event handler class name
5 Preview the report. The label’s background color is red.
BIRT Java interface and class naming conventions
BIRT event handler class and interface names use the following conventions:
*Event handler interfaces
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.
*Event handler adapter classes
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.
*ROM element instance interfaces
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.
*ROM element design interfaces
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.