BIRT/FAQ/JavaEventHandlers

< To: BIRT/FAQ

This is dedicated to questions about the use of Java Event Handlers for BIRT. There are a couple of major themes in the event handlers. There are additional resources for Java Event Handlers. The first is the excellent scripting primer on the main BIRT web site. Also the reference book on the subject Integrating and Extending BIRT.

One additional reference is the BirtWorld blog where a number of articles on Java Event Handlers have been written. In particular:

• Test and Debug
• Cast to DEAPI
• Part 2 of Casting

Class Loader

One of the most fundamental questions that comes up when working with Java Event Handlers is "where do should my classes go". The answer, like all good answers, is "It Depends".

BIRT has two sets of behavior one for the Design Environment and one for the Runtime Environment.

Design Time Class Loader

The design time environment is a little bit messy. The problem is that the developers of BIRT came up with a new set of rules to make it easy to develop Java Event Handlers at design time. So it takes a bit more to understand how things work. The first thing you need to be aware of is that when you run a report from the Design Time enviroment, the report is run using the web viewer plug-in.

You can find this plug-in at here: $ECLIPSE_HOME/plugins/org.eclipse.birt.report.viewer_VERSION_INFO

Inside the plug-in directory you will find a sub-directory called birt, this is where all the good things happen. The birt sub-directory is the root of a web application which is run by the design environment. You can see the WEB-INF folder there. In addition, you can look inside the WEB-INF folder and find a web.xml file.

One of the parameters in the web.xml file is BIRT_VIEWER_SCRIPTLIB_DIR, which contains a directory that contains JAR files for Java Event Handlers. So if you have jar files that contain your event handlers that you want to reference at design time, you can reference the path to the directory that they sit in within the web.xml.

You do need to restart Eclipse if you change the BIRT_VIEWER_SCRIPTLIB_DIR value. The good news is once the path is set, you can change the jar files and they will be re-loaded each time you run a report.

At this point you may say, "I am confused, I don't have to jar up my class files from my projects, they just seem to be found automatically", at least I did. The other thing that BIRT does in the design environment is that it searches across all of the top level projects in your workspace looking for BIRT Java Event Handlers. All of these get automatically added to your Preview Class Path.

The tricky part here is that in 2.2 and before, BIRT only looks at the top level projects. So if you have a workspace that is hierarchical or that contains projects that do not sit directly under the workspace root, then your classes will not be found. See the imaginary workspace project structure:

WORKSPACE_ROOT
 -Project1/
    src/
       eventHandler1
 -Project2/
    src/
       eventHandler2
      -SubProject2_1/
         src/
            eventHandler3 (NOT FOUND)