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.java (FOUND)

 -Project2/
    src/
       eventHandler2.java  (FOUND)
 
     -SubProject2_1/
         src/
            eventHandler3 (NOT FOUND)

-Project_Side/
    src/
       eventHandler4.java (NOT FOUND)

As you can see the event handlers that are defined in Project1 and Project2 are automatically found and added to your class path. The event handlers defined in SubProject2_1 (which is not immediately below the WORKSPACE_ROOT) and Project_Side (which is not below the WORKSPACE_ROOT).

So the design environment will find classes that are in top level classes, or it will find jar files that are in the BIRT_VIEWER_SCRIPTLIB_DIR directory.

Runtime ClassPath

The runtime class path is far easier to describe. The BIRT application builds a ClassPath when it starts up. Typically this ClassPath contains entries for all of the lib files found under the RUNTIME_HOME/lib directory. You can add jar files to this ClassPath at either the EngineConfig time, or at the time you generate a task.

If you are using the WebViewer to deploy your application, the ClassPath will also contain the directory specified by BIRT_VIEWER_SCRIPTLIB_DIR. The default value for this ./scriptlib. So the easiest thing to do at runtime is to use the WebViewer and place your jar files into the RUNTIME_HOME/birt/scriptlib directory.

If you are not using the WebViewer, then you need to add your jar files that contain your event handlers to the class path. There are three context variables that can contain ClassPath information, they are all defined in the EngineContants class.

EngineConstants.WEBAPP_CLASSPATH_KEY = "webapplication.projectclasspath" EngineConstants.WORKSPACE_CLASSPATH_KEY = "workspace.projectclasspath" EngineConstants.PROJECT_CLASSPATH_KEY = "user.projectclasspath"

What you would do is add a ";" or ":" (Unix) separated list of jar files (or individual classes) that would be added to the overall class path. Using this mechanism, you can add some ClassPath entries when you build the EngineConfig context and then add additional entries within the TaskContext.

So adding a ClassPath to the EngineConfig would look like:

EngineConfig config = new EngineConfig();
config.setProperty(EngineConstants.WEBAPP_CLASSPATH_KEY, "c:\temp\eh.jar;c:\java\meh.jar");

This will add two jar files (eh.jar, meh.jar) to the EngineConfig which will be used by all instances of the report engine.