Developer's notes for SPR 772
Marnix Bindels, Mar 12 2007

Implementation of this SPR was taken as the opportunity to do away with the
swing based reporting in favour of JasperReports based reporting. Three reports
have been implementen PropAllSQL, PropSummarySQL and ObsAllSQL. What follows are
some notes on the JR technolgy, the reports themselves and their integration in
the ISOC System.

Technology

JasperReports (JR) can be downloaded at jasperforge.org and other sourceforge
like resources. For this 1st implementation version 1.3.1 has been used. The
reports can be designed easily using the iReports GUI. The iReports GUI works
under Linux, but has some peculiarities (and bugs). Most notably: when editing a
static or database text field by double clicking on it, the text is not visible.
You will be editing it though! And many more things like these.

For the jasperforge forums and stuff, a login isoc_dev/dev4isoc has been setup.
A similar account is setup for reporting the iReports bugs.


Report Implementation

The reports query the database directly. So they are based on an SQL query
behind it. Bear this in mind when changing the tables. The query editor in
iReport is a pain in copy-and-paste but the automatic field retrieval is kind of
cool.

The subreport feature has been used extensively. In the main report you
reference a subreport, pass some parameters to it and the subreport will run its
own query to construct the next few pages. Subreports are constructed without
margins so that they can be placed anywhere on the page.

Sometimes a report does not print, JR runs into an infinite loop until memeroy
runs out. Even though all subreports have been tested and work in isolation.
Just increase the band size and subreportelement in the main report until it
starts working again... (I know... it's a pain) 

To print separate sections on new pages, introduce a new group-by band (on some
"empty" expression) and stick a break element (floating!) near the bottom of the
band. When the band is printed, it will start a new page for the section coming
after it.

I have been able to use our classes to format Ra and Dec, so interfacing to our
code is pretty easy.



JR Integration

Only ISOC-core uses the reporting upto now.

ReportDescriptor - interface

The user interface component deals with one instance of class implementing the
ReportDescriptor interface. It is supposed to give enough information to present
some information to the GUI user on what's going to be reported and perhaps some
user controlled layout parameters on one hand. On the other hand it should be
suffuciently equipped to get JR going in actually procducing the report.
Currently it's things like a description, the Report file and boolean switches
the user may toggle to condense the reports. The descriptor typically knows what
kind of objects to accept as a key and how to transfor such objects into a
(number of) parameter(s) to limit the SQL query.

JRControlDialog

The main user interface. It takes a ReportDescriptor, adapts the GUI contents to
what it finds in the descriptor and when the user clicks go, it produces a
JR.Print using the FillManager which is then given to an Exporter.

Form the application point of view, the app collects a descriptor, a list of
keys that matches the descriptor  and a database connection. With those, the
JRControlDialog can be setup and the reporting is handled in a standard way
after that. Using a SwingWorker, each member of the key list is used to produce
a Print and export: it's either printed or exported as PDF. The dialog shows a
progressbar wich indicates the index in the key list. The cancel button can be
used to stop the printing.

JRPortefolio 

This class is a placeholder for the descriptors of the three implemented
reports. Use the static public members when configuring the JRControlDialog.

Maven

We chose to pre-compile the XML (jrxml) files into serialized reports. It loads
a bit faster before reporting. The maven target compileJasperReports picks up
resources/reports and builds .jasper files in classes/reports. It has been made
a preGoal of the jar target, so they will be built in time when building a dist.

I had some trouble with the XML reader: the target compileJapserReports would
work fine, but when called in the preGoal phase of jar:jar no suitable XML
parser could be found to cover the dynamic validation feature. By turning  off
xmlvalidation in the JR ant task, this problem was circumvented.