Using Java to Write an Event Handler

Creating a Java event handler is more complex than creating a JavaScript event handler. You cannot type Java code directly in BIRT Report Designer.

To create a Java event handler class, compile the source for the Java class and make the class visible to BIRT. Creating a Java event handler for BIRT is simplified, however, by the fact that Eclipse is a robust Java development environment and supports integrating a Java project with a BIRT project.

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 File→Properties. In Properties, select Java Build Path→Libraries. 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 24-1. Choose OK.

Figure 24-1  The report engine JAR file in the build path

2	Select the Java project and choose File→New→Class.

3	To set up the Java class properties, perform the following steps in New Java Class:

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	Select the ROM element event adapter class to extend:

Choose the Browse button beside Superclass.

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 24-2.

Figure 24-2  Selecting a Superclass

Choose OK.

4	In New Java Class, select Generate comments. New Java Class appears similar to the one shown in Figure 24-3.

Figure 24-3  New Java Class final properties

5	Choose Finish. The Java editor appears, similar to the one shown in Figure 24-4.

Figure 24-4  The new class in the Java editor

6	Add the event handler method for the event handler class. Import all required classes. Figure 24-5 shows the addition of an onPrepare( ) method that sets the background color of a label to red.

Figure 24-5  The onPrepare( ) method in the Java editor

7	Choose File→Save.

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 BIRT.

1	In Outline, select the report element for which an event handler class is visible to BIRT, as shown in Figure 24-6.

Figure 24-6  Selecting a report element

2	In Property Editor, choose Event Handler, as shown in Figure 24-7.

Figure 24-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 24-8. Then, choose OK.

Figure 24-8  Selecting the event handler class

The fully qualified name of the event handler class appears in Property Editor, as shown in Figure 24-9.

Figure 24-9  The event handler class name

5	Preview the report. The label’s background color is red.