Purpose of this Document

This document briefly describes some basic facts about the Carte report engine, its architecture and intended use. Topics such as the use of XSL and CSS standards to format documents are also discussed. You are encouraged to read this paper if you are looking for a Java-based report engine, or are interested in the use of standards to print reports.

Main Features

Carte is a partial rewrite of an old Java report engine that the author started several years ago. The legacy engine had a non-standard format to specify the document rendering, something shared with most report engines. Later, the design was revised to allow the use of arbitrary XML formats to specify the formatting of the report document, and the result is Carte.

Carte has the following features:

• Uses arbitrary XML-based formats as the basis to specify document formatting. At present, the production of PDF reports is limited to XHTML-based input templates.
• It is possible to plug in alternative template engines. At present, only its own template engine is supported, but is enough for most uses.
• It is possible to plug in alternative chart packages. At present, only part of the jCharts package is supported.
• Text (including all the XML variants) and PDF outputs are supported today, but adding other target formats is possible by implementing a few interfaces.
• The Cascade Style Sheets (CSS) standard is used to specify the format of the documents, in contrast to other report engines that define their own proprietary formats. At present, Carte is the only report engine that the author knows to be able to do this.
• You can use your favorite CSS file as the default for rendering. By default, uses a CSS adapted from the Firefox browser.
• It is possible to generate XHTML and PDF reports from the same template. (However, if speed is an essential issue, it is often better to use a separate XHTML-optimized template. This is mostly a cut and paste matter, however.)
• Carte's native data formatting uses JCLF's DataFormatter objects, that allow to define an extended C-language style formatting. Useful, for example, when printing floating point numbers or dates.
• Can combine reports from many different data sources in the same document. JDBC-based data sources are tandard, and any other data source just has to implement a simple interface.
• Reports are preparsed, allowing for efficient use in a Servlet environment.

Standards-based Document Formatting

As mentioned, Carte chose the path of using document formatting standards, as opposed to the usual proprietary formats that other report engines use. Then, we reach a point where we find two possible standard solutions: CSS and XSL.

While there are some discussions comparing XSL and CSS around the Net, most fail to realise that XSL is a family of recommendations, and many people seem to think that XSL is only XSLT. It makes no sense to compare CSS and XSLT, as one specifies formatting, and the other does XML transformation. However, as XSLT is frequently used to transform an XML document into XHTML, it is sometimes taken as a way to "render" XML.

CSS must be compared to XSL:FO, the Formatting Objects part of XSL. An XSL:FO sheet can take an XML document as input, and produce the desired output, for example PDF. For example, Apache FOP is an open source XSL:FO-based print formatter. XSL:FO, however, has problems:

1. It is enough complicated to require a tool to write the style sheet. One could say that CSS is closer to humans than to the machines, while the opposite happens with XSL:FO.
2. In practice, you have to write somewhat different XSL sheets for different output formats. An XSL:FO sheet for a PDF output can be extremely different from an XSL:FO to render the same content into another format.
3. With both CSS and XSL:FO, the final rendering of the document depends strongly on the software used for it. The difference being that with XSL:FO it is easier to come up with templates that will not work correctly (or not work at all) with other software than the one used to write the sheet. In some cases, to print your document you are bound to the tool that also produced the XSL.
4. XSL:FO implementations have a large memory footprint, and each document rendering operation requires many expensive XPath operations.

The first problem is important as there are no open source XSL:FO GUI builders, and the commercial ones are very expensive and, what is still worse, not very useful. The second problem, combined with the first can make things really difficult.

One example that can be also of help when comparing CSS and XSL:FO is to examine the CSS and XSL sheets used to format an XHTML document. If you use Mozilla Firefox, you can find an html.cs file in the res subdirectory of the main Firefox folder (generally Program Files\Mozilla Firefox). Other browsers (MS Internet Explorer not included) also have their own CSS file. It is harder to find the equivalent XSL:FO sheet, but there is one at the Antenna House web site.

CSS is used extensively by web page designers, and is easy to understand. So it was the styling language chosen for Carte.

Transforming an XML Document into a Report

Any XML format can potentially be used as input for Carte, generally XHTML, but in addition to the formatting you need a way to define how to merge the data with the format. This is done with the use of XML namespaces, and the Carte elements and attributes are responsible for that. All the source XML document must be inside a report element with a namespace definition, for example <xte:report xte:version="0.1" xmlns:xte="http://www.informatica.info/projects/carte/xte">, and then its contents annotated with the Carte elements.

For example, to data-enable an HTML table you just have to use the Carte namespace prefix, in our example "xte", and the tag would look like <xte:table xte:dataspec="mydatasource">. Analogously, a report chart comes from changing the img element into something like <xte:img xte:type="barchart" xte:dataspec="mydatasource">.

Getting Started

If you are in a hurry, you can obtain a very simple XHTML template to print a table from an SQL query using the ReportUtil convenience class. If you want a report optimized for text (just for XHTML pages) you have to run:

java info.informatica.report.ReportUtil --driver=<jdbc-driver> --datasrc=<data-source>
  --name=<name> "<SQL query>"

where "name" is the name that you want to give to your SQL query in the report. And, if you want a report that can generate both text and PDF, run:

java info.informatica.report.ReportUtil --driver=<jdbc-driver> --datasrc=<data-source>
  --name=<name> --blocktype=table "<SQL query>"

In any case, you can then store your template in a file somewhere, and run this to print the report:

java info.informatica.report.Report --driver=<jdbc-driver> --datasrc=<data-source>
  --name=<name> --templatepath=<path to template> "<SQL query>"

The result is poor, but gives you a starting point. You may want to give your own format to the generated XHTML template to get a better view.

Market Niche

Carte still lacks several functionalities present in other report engines, like a wide variety of charts. However, works well enough to be in production at several sites. The main points for Carte adoption are:

Roadmap

Future work is going to concentrate in the following areas, several of which are partly implemented:

• More documentation.
• Add more charts.
• Improve PDF formatting.
• Conditional report compilation, and runtime conditionals.
• Plug in XSLT support.
• Add FreeMarker and Javascript template support.
• Web-based editor of report templates.
• Improve CSS computation speed by caching.
• Improve tolerance against bad templates.
• Support for directly printed reports.
• Integration with content management system.

If you want to contribute to the development of Carte, please contact the author.