JFreeReport Documentation
Introduction
JFreeReport is a successful embedded reporting engine. By providing a high degree of flexibility and minimal requirements for the execution environment, JFreeReport can be integrated into most programs with little effort.
The original design of the library itself was driven by the need to easily print Swing-TableModels. During the last four years, the original design of JFreeReport got transformed into a complete report generator system. It is important to note, that the original design did not include or anticipate the features implemented today.
The initial narrow focus on simple printing resulted in severe architectural problems of JFreeReport. The most notable limitations are certainly the missing support of subreports and the restriction of a band's height to a single page.
The aim of the new version, called JFreeReport 0.9.1, is to solve all the problems, to lift all the restrictions and to bring JFreeReport's architecture into a clean and well-defined state. The main aim of the development is to remove all 'historical remainings', to cut down on the unnecessarily complex processes and to create a simple, cleanly structured library. The known advantages of the old system, however, should remain intact and should be extended if possible.
The development aims can be broken down into the following steps:
- Strict separation of data processing ("the reporting") and layouting ("content creation")
- Preserve the unmatched flexibility of the report processing. JFreeReport allows to reconfigure the report definition while the report is being processed. (As far as I know, no other reporting engine allows that.) With this feature, one is able to create even irregular structures, as long as the rules for that can be implemented as Java-Function.
- Maintain JFreeReport's great extensibility at all levels of the library's architecture (OutputFormats, Functions, Report types, data sources, GUI, etc)
- create an simple, well structured codebase, which can be understood by everyone.
- Keep the system dependencies and requirements minimal, maximize the scalability.
Naturally, deep changes to the engine influence all other programs, which use JFreeReport. It is unavoidable that the changed API will be incompatible to any previously released version. As even minor API changes will break programs anyway, our development will follow that path with full-force, happily refactoring or removing all ugly code. Once the JFreeReport 0.9 release is feature complete, the API will be driven to stability. At that point, only show-stoppers, complex features or bug-fixes will cause non-backward-compatible changes. Once JFreeReport reaches 1.0, the API will be frozen for long-term maintenance. At that point, JFreeReport's code will maintain backward compatibility at all costs.
Reports which use the API to create the report definition from scratch, will not be compatible with the new release. There will be no easy upgrade-path for these reports, as most classes referenced by that legacy code will be gone and the reporting logic will be changed radically. Applications, which use the XML definitions will enjoy an easier upgrade-path. A compatibility layer will be provided, which takes care of most of the gory details of transforming old report definitions into the new format. Of course, report definitions kept in the old format will not be able to use exciting new features.
The compatibility layer consists of an XML-parser for the old report definitions and several LayoutController implementations to emulate the old behaviour of the engine. This allows to execute the old reports without explicitly porting them to the new system. For user defined functions, custom mapping rules have to be defined and/or implemented by the user.
More details on how the project 'JFreeReport' is now organized
Historical Note: The classical report process
The Layout oriented Reporting Process
JFreeReport 0.9 uses a completely different reporting approach. Instead of using the data as the control factor for the report process, JFreeReport concentrates on the layout that should be generated. In the new model, JFreeReport iterates over the layout (the report definition). The data processing is controlled by embedded data control commands, which control the iteration over the data sources.
By concentrating on the desired output format, now it is relatively easy to create reports, which are no longer bounds to the classical nested grouping structures. Groups are controlled by the defined data commands, and therefore it is possible to create parallel or even irregular grouping structures.
Each processing step of the layout processing forms an atomic unit. A layout processing step represents a simple work unit, for instance 'open element', 'process content', 'close element'. This fine grained state generation makes sure that the limitations of the previous versions of JFreeReport will no longer cause trouble when using these states for the report processing recovery which is needed for the paginated reports.
JFreeReport 0.8 already had the unique feature of being able to reconfigure the report processing at runtime. Combining this feature with the new layout driven report generation, functions are now able to affect every single aspect of the report processing.
With JFreeReport 0.9, we are now able to go even further. The actual implementation on how certain elements should be processed is now controlled by small classes. New report elements and/or new, possibly complex behaviour (Pivot-tables, for instance) can be added to the engine by implementing and registering custom LayoutController classes.
A strict separation of all subsystems and all the state machines involved ensures, that the reporting engine has a simple and small core.
The layouting and content generation subsystem has been fully decoupled from the JFreeReport core. The report engine generates the input events for the 'input-feed's of LibLayout. Neither does JFreeReport know the internals of Liblayout nor is LibLayout a JFreeReport specific extension. The layouting engine has been explicitly designed as an independent library. That separation reduces the tight coupling between both libraries and increases the flexibility of the entire system.