EGL JasperReport Handler

You can use the standard features of the JasperReports open-source reporting library to create quite complex output. If you need more sophisticated reports, you can create an EGL JasperReport Handler.

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

The following list shows common uses for a JasperReport Handler:
  • Responding to specific, predefined events while JasperReports fills the report
  • Providing functions that you explicitly invoke from the XML design file
  • Storing data to be retrieved for subreports

For a complete list of the events that the JasperReport Handler can respond to, see "Predefined EGL JasperReport Handler functions." For information about the generated output from the JasperReport Handler, refer to the EGL Generation Guide.

Responding to events

EGL has a number of predefined function names that correspond to events that can occur when JasperReports fills a report. Such events include entering or leaving a page, beginning or ending a line, and so on. 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 invokes that function automatically.

One of the events that EGL recognizes is the initialization of a user-defined group. You can use the <group> tag in the XML design source file 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 JasperReport Handler.

Creating explicitly invoked functions

You cannot perform any complex (multi-line) Java™ coding within the JasperReports XML source file itself. However, by writing EGL code in the JasperReport Handler, you can create functions that the JasperReports engine can access at run time. You do not have to tie these functions to any specific event or invoke them 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 the report filling process, the engine can invoke the methods of that class. Those methods are the functions you created.

The JasperReport Handler has full access to other EGL resources, such as Record parts, system functions, and libraries.

Storing and retrieving data

Perform the following actions to pass data to a subreport:
  1. Use the built-in handler function addReportData() to store data for later use by a subreport.
  2. Inside the <subreport> tag of the design file, set up a <dataSourceExpression> tag. Within the <dataSourceExpression> tag, invoke the built-in report handler function getDataSource(). This function 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 information and examples, refer to the EGL Programmer's Guide.