Report developers distribute reports to users by publishing them to BIRT iHub. Sometimes a report requires information about the iHub environment to implement application or business logic based on, for example, the security credentials of the user running the report, the browser in which the report is viewed, the server volume on which the report is run, and so on. BIRT provides an API, referred to in this chapter as the iHub API, that enables access to this type of information.

To use the iHub API in a report, you write event handler scripts in either Java or JavaScript. BIRT event handlers are associated with all the elements that make up a report, such as data sources, data sets, tables, charts, and labels. When a report is run, BIRT fires events and executes event handlers in a specific sequence to generate and render the report.

Writing event handlers in a report requires knowledge of the BIRT event model. For information about the event model and details about writing event handlers in Java and JavaScript, see Integrating and Extending BIRT. This chapter describes the additional requirements for accessing and debugging the iHub API in an event handler.

You write a JavaScript event handler that uses the iHub API the same way you write other event handlers. In Actuate BIRT Designer Professional, you select an element, such as the report design or a table, then use the script editor to select an event, such as beforeFactory or onCreate, for which to write an event handler.

Figure 7‑1 shows the script editor displaying event-handling code written for the report design’s beforeFactory event.

Writing a Java event handler that uses the iHub API is similar to writing other types of event handlers. You create a Java event handler class, make the class available to BIRT, and associate the class with a report element. The difference is the additional JAR files required to access the iHub API.

You must add the following JAR files in the build path and classpath when configuring the Java event handler project:

Figure 7‑2 shows the build path of a Java project that uses the iHub API. In this example, BIRT Designer Professional is installed on the same machine where iHub is installed. If Actuate BIRT Designer Professional is installed on a different machine, you must copy the JAR files from the iHub machine to your workspace.

The BIRT engine uses an object called serverContext to store information about the iHub environment. The serverContext methods and properties are defined in the IServerContext interface. The container for the serverContext object is the application context object appContext. The appContext object stores objects and values that are used in all phases of report generation and presentation.

The appContext object, in turn, is a property of the reportContext object. This object stores information associated with the instance of the report that is being generated or viewed. For example, the reportContext object stores information about report parameters, global variables, report output format, locale, the request that runs the report, and the application context. The report context class defines methods for setting and retrieving these properties. Every event handler in a BIRT report has access to the reportContext object. In Java, the report context object is an argument to all event-handler methods.

To call a method to retrieve iHub environment information, the code must reflect the relationships between the serverContext, appContext, and reportContext objects.

The following JavaScript code snippet shows how to call the getVolumeName( ) method to retrieve the name of the iHub volume in which a report runs:

The following example shows the equivalent code snippet in Java:

The code example in Listing 7‑1 uses the getUserRoles( ) method to retrieve the user’s roles and displays the contents of a report element if the user role is Manager. This code can be used, for example, in the onPrepare event of a table element to hide or display the table depending on the user role. The code example also uses the appendToJobStatus( ) method to write messages about the user’s roles to the server job status.

Like the JavaScript event handler in the previous section, the Java code example in Listing 7‑2 uses the getUserRoles( ) method to retrieve the user’s roles and displays the contents of a table if the user role is Manager. The TableEH class extends the TableEventAdapter class and implements the event-handler script in the onPrepare event method.