EGL report handler

The standard features of the JasperReports open-source reporting library allow you to create quite complex output. If you need more sophisticated reports, you may create an EGL report handler.

The EGL report handler is an EGL handler part of type JasperReport. The JasperReports engine sees the report handler as a scriptletClass. For those unfamiliar with Java™, the implication is that the JasperReports design file can call methods (similar to functions) of the report handler.

Here is a quick list of common uses for a report handler, with details to follow afterward:

You can create the report handler from a blank file or use the EGL New Report Handler wizard. The report handler wizard starts you off with an outline that includes the name of each predefined (event-related) function that the JasperReports engine can invoke while filling the report. For a complete list of these events, see Predefined EGL report handler functions.

Responding to events

EGL has a number of predefined function names that correspond to events that may occur when JasperReports fills a report. Such events include entering or leaving a page, beginning or ending a line item, and others. When one of these events occurs, the JasperReports engine checks to see if the report handler contains a function that corresponds to the event. If so, the JasperReports engine will invoke that function automatically.

One of the events that EGL recognizes is the initialization of a user-defined group. The <group> tag in the XML design source file allows you to specify an expression that defines a group. For example, you might group customers together whose numbers range from 2000 to 2999. You can print subtotals for the group through the standard XML design source tags, or you can perform more complex manipulations using the report handler.

Creating explicitly invoked functions

You cannot perform any complex (multi-line) Java coding within the JasperReports XML source file itself. By writing EGL code in the report handler, however, you can create functions that the JasperReports engine will be able to access at run time. These functions do not have to be tied to any specific event or be invoked from within one of the predefined event-related functions. For example, you might create a function that looks up a SQL variable of type DATE and returns the date in a formatted character string. You can call this function directly from the XML source that prints the detail for a transaction.

The operation works because EGL generates a scriptletClass from the report handler source file. The scriptletClass is a Java class that the JasperReports engine can access, and during printing, the engine can invoke the methods of that class. Those methods are the functions you created.

The report handler has full access to other EGL resources, such as record parts, system functions, and libraries.

Storing and retrieving data

Passing data to a subprogram is a two-step process.
  1. Use the system function ReportLib.addReportData() in the report handler to store data for later use by a subreport.
  2. Inside the design file's <subreport> tag, set up a <dataSourceExpression> tag to pass data to the subreport's design file. Within the <dataSourceExpression> tag, invoke the built-in getDataSource() method of the report handler. This method returns the data in an internal format. You must cast the return value as a JRDataSource for the subreport to be able to use the data.
The subreport can then use the retrieved data to provide detail for each line item.

For more details and examples, see Creating an EGL report handler and Additional EGL report handler functions.

Generated output

When generating a report handler, EGL creates these files:
  • handlerName.java is the actual report handler. JasperReports makes calls to this program using Java data types.
  • handlerName_lib.java is a library that contains translated EGL functions. The report handler (handlerName.java) calls these functions with data types translated from Java.
handlerName
Name of the EGL report handler source file (less .egl extension)

At generation time, EGL uses the EGL report handler source file to create a JRDefaultScriplet class, which is a subclass of the JasperReports scriptlet class. That subclass contains a method for each function that you coded. At run time, the JasperReports engine checks for a scriptletClass attribute in the <jasperReports> tag. If this attribute exists, the report engine loads the scriptlet class and makes the class methods available to the report design. For more information on JasperReports scriptlets and scriptlet class, see the JasperReports documentation.

When EGL generates .java files, the class names are lower case. Be sure that any class name you enter in an XML design document is in lower case.

Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.