Class Summary
Class	Description
ERJRFetchSpecificationReportTask	A background task class that creates a JasperReports report in the context of a WebObjects application.
ERJRFoundationDataSource	Takes an an NSArray of `NSKeyValueCodingAdditions` (think keypaths) objects
ERJRReportTaskFromEO
ERJRUtilities	8/24/2010: All methods related to on the fly compilation of jrxml templates have been removed since this does not make sense

Package er.jasperreports Description

ERJasperReports

Overview

ERJasperReports is a framework wrapper around the JasperReports library and its dependent libraries. You can learn

Installation and Setup

Include the ERJasperReports framework in your classpath.

Quick Start Guide

Designing Reports

Place your jasper report xml templates (those having the .jrxml extensions) into your application, or framework Resources folder. Edit the jasper xml design template in place by hand, or by using the convenient iReport application, which can be downloaded from SourceForge. Compile your jrxml design template while you work which will result in a binary template with the file extensions .jasper in the same directory as the jrxml design template. Image resources may also be placed in the same Resources directory and referenced by relative path in the report template. At runtime they will be found by the jasper report engine.

You will need the iReport application version that corresponds to the version of JasperReports that is included in this framework to ensure template compatability. Check the current JasperReports version by looking at the name of the JasperReports jar in the built framework or in the Libraries directory of the source project. It is also possible to use a newer version of iReport and to set the JasperReports version compatability in the iReport application preferences.

Important: Use keyPaths that are relative to the detail object as Field names, however since JasperReports will not allow us to use the period character in Field names, we use an underscore character instead. If you already use underscore in your object attributes, you can define your own JasperReports keyPath separator using the property er.jasperreports.keyPathSeparator. For example if Movie (from the ERMoviesLogic Movies EOModel) is the detail object of a report, then to make a field that represents the Studio's name, we would simply define a Field in the jasper design template as "studio_name" which during report generation is the equivalent of executing movie.valueForKeyPath("studio.name")

You can implement the report generation and download logic in your application to test your report while you are designing it. You can leave your WebObjects app running while you simply switch between the browser to test the report and iReport application to make changes and compile your changes. Remember that the JasperReports engine works directly with the compiled .jasper file, not your .jrxml design template, so make sure you compile using the convenient toolbar button (the one with the hammer icon) after making changes to validate your changes and to regenerate the .jasper compiled template.

Report Generation Logic

ERJasperReports needs three things to generate a report:

The compiled .jasper binary template file in your Resources folder
A JRDataSource concrete implementation that defines the report detail objects.
Optionally a HashMap<String,Object> object containing miscellaneous report parameters that you want to use in your report logic.

Report generation time is proportional to the number of detail objects in the data source. So in general we must always plan for reports to be generated in a background task. ERJasperReports provides a convenient java.util.concurrent.Callable class that does the report generation and returns a pdf java.io.File result

However you can implement your own background tasks with similar logic as ERJRFetchSpecificationReportTask if you wish

Here is an example of business logic that creates a report task ready for execution in a background thread:


        /**
         * @return a Callable task that creates and returns a StudioRevenueReport PDF file
         */
        public static Callable<File> createStudioRevenueReportTask() {
                // SortOrderings
                // Sort by studio name alphabetical sort
                ERXSortOrderings sortOrderings = Movie.STUDIO.dot(_Studio.NAME).ascs();
                
                // Then sort by Movie Title
                sortOrderings = sortOrderings.then(Movie.TITLE.asc());
                
                // EOQualifier, null for this demo
                EOQualifier qualifier = null;
                
                ERXFetchSpecification<Movie> fs = 
                        new ERXFetchSpecification<Movie>(Movie.ENTITY_NAME, qualifier, sortOrderings);
                
                String reportDescription = "A report that subtotals revenue by Studio"
                        + " and lists the Movie revenue detail for each Studio";
                
                HashMap<String, Object> parameters = new HashMap<String, Object>();
                parameters.put("reportDescription", reportDescription);
                parameters.put("userName", "WOWODC Demo");
                
                ERJRFetchSpecificationReportTask reportTask = 
                        new ERJRFetchSpecificationReportTask(fs, "StudioRevenueReport.jasper", parameters);
                
                return reportTask;
        }

Properties

The properties below allow you to change the behaviour of ERJasperReports:

er.jasperreports.keyPathSeparator: Defaults to underscore character. Since the standard WebObjects keypath separator character ( . ) is invalid for jasper report field name definitions we must use a different character when specifying datasource fields as keypaths in the report template.
er.jasperreports.currentRow.fieldName: Defaults to "_currentRow". Sometimes we want might want a reference to the current row, perhaps to pass to a custom function in a scriptlet. This functionality allows us to specify a jasper template field name that returns the current row object itself rather than an attribute of the current row.

Getting More Information

Get your hands on the 90 minutes "Integrating JasperReports with WebObjects&guot; presentation from WOWODC 2010 in Montreal. The presentation will be available beginning October 2010 from http://www.wocommunity.org

An example application, ERJasperReportsExample, will be committed to Wonder during September 2010 which will give you everything you need to understand how to make your own reports