Almost every event handler has access to an object called the reportContext object. Table 37-1 lists commonly used reportContext object methods.

The output format for a report is available in the rendering phase of report generation. Call the getOutputFormat( ) method of the reportContext object to determine the output format in the beforeRender, onRender, or afterRender event handlers. For example, to change styling for an element depending on the output format, add code to the onRender event handler, as shown in Listing 37‑3.

You can use the reportContext object to retrieve the report design handle in the beforeFactory event handler. You can modify the currently running design before the design executes.

Place the following event handler examples in the beforeFactory method, which executes only during the generation phase of report creation. The examples use the Design Engine API, which is described in a later chapter.

The example in Listing 37‑4 uses the design handle to add a filter based on report parameters to a table.

The example in Listing 37‑5 is similar to the filter example. It adds a sort condition to a table.

A report developer may hide a portion of report content using the visibility property. Hidden content can customize the display of data based on report parameters or perform an unrendered calculation. A report item hidden by its visibility property is still processed, which may or may not be desirable.

As an alternative to using the visibility property, use the report design handle to drop elements from a running design, as shown in the following code:

You can alter additional properties of report items. Listing 37‑6 shows how to resize the width of a column within a table and change the bound data set. If the bound data set for a report item changes, the new data set must contain the same columns as the previous data set.

You can change the styles property in the beforeFactory event. Listing 37‑7 uses one style for PDF generation and another style for all others. This example requires the report document be recreated to effect the change. Alternatively, use the RunAndRender task.

A global JavaScript variable cannot pass a value between processes, but scripts often need to pass a value from the factory process to the render process. The BIRT report context object uses persistent global variables to pass values between the processes. These variables must be serializable Java objects. The setPersistentGlobalVariable( ) method creates a variable that is accessible using the getPersistentGlobalVariable( ) method.

For example, generate two strings at run time and display one string when rendering in PDF and a different string in other format contexts. Use the setPersistentGlobalVariable( ) method at generation time to store the variables in the report document. At render time, retrieve the variables in a render event handler using the getPersistentGlobalVariable( ) method.

Listing 37‑8 calls the setPeristentGlobalVariable( ) method in the onCreate event handler of a label element to initialize two strings then calls the getPersistentGlobalVariable( ) method in the onRender event handler to specify the format context.

BIRT uses an application context map to store values and objects for use in all phases of report generation and presentation. To add an object to the application context, use the Report Engine API or the setAttribute( ) method of the request object.

The JSP example shown in Listing 37‑9 adds an object to the application context. AppContextKey is the name that references the object and AppContextValue contains the value of the object.

Reference an object in the application context. Listing 37‑10 uses a try‑catch block to detect whether the object is not found and returns an appropriate error message.

Use the EngineConfig class or the EngineTask class in the Report Engine API to add an object, as shown in Listing 37‑11.

The application context object contains many useful settings. For example, set the driver location for JDBC drivers using code similar to the following lines:

Setting a location for JDBC drivers precludes putting the driver JAR file in the JDBC plug‑in, eliminating the possible deployment of multiple copies of a JDBC driver to the application server. Additionally, the connection object can be passed in to the BIRT engine using the OdaJDBCDriverPassInConnection setting of the application context. The value of the object must be an instance of a java.sql.Connection object. By passing in a connection, you can control whether the engine closes the external connection object by using the OdaJDBCDriverPassInConnectionCloseAfterUse setting. The value for this setting is a Boolean value.

Setting application context objects from script is also possible. Properties must be set before use. Many settings apply to all tasks that the engine spawns. Changed settings affect all subsequent report runs.

Use the reportContext.getAppContext method to iterate through all the objects in the application context, as shown in Listing 37‑12.

This code makes the variables, kys and vls, available for display in a data element or text element. Use kys and vls in an expression for a data element or <VALUE‑OF>kys</VALUE-OF> and <VALUE-OF>vls</VALUE-OF> in a text element.

The HTTP servlet request object contains methods to retrieve information about the request to run the report. One useful method of the HTTP request object gets the query string that follows the path in the request URL. The query string contains all the parameters for the request. By parsing the query string, the code can extract the parameters in the request URL conditionally to determine the report output. For example, use this feature to pass in a user ID or to set or override a report parameter. Listing 37‑13 gets the query string.

You can retrieve a Session object using reportContext, as shown in the following code: