Exporter Input - API Overview
Once generated, a JasperPrint object may be
exported to various output formats such as PDF, HTML, XML, CSV, RTF, Excel, MSWord, PPTX, etc.
The JasperReports library includes a builtin exporter class for each output format enumerated here.
An exporter should be able to handle a wide range of report sources, along with their specific export configuration settings.
In order to perform the export, exporters require some specific input data:
- a single JasperPrint or a list
of JasperPrint objects to be exported at a time; these objects may:
- be in-memory objects
- come from the network through an input stream
- be loaded from files on disk
- a set of export configuration settings to be applied either globally or per each report in the list
Exporter builtin implementations acquire input data based on methods inherited from their
JRAbstractExporter super class. When extending the
JRAbstractExporter class, one can reuse the
public void setExporterInput(ExporterInput exporterInput)
method to deal with the report sources and export configuration settings.
As shown in the method signature, all we need is an ExporterInput object.
This object must implement the
public List<ExporterInputItem> getItems()
method in order to retrieve a list of
ExporterInputItem objects. Each
ExporterInputItem in the list contains a single
JasperPrint object along with its related export
configuration settings. Methods in the ExporterInputItem interface are:
public JasperPrint getJasperPrint() - return the JasperPrint objectpublic ReportExportConfiguration getConfiguration() - return export configuration settings to be applied for the
JasperPrint object
Global configuration settings per exporter can be configured using the
public void setConfiguration(C configuration)
method in the JRAbstractExporter class. This method accepts an
ExporterConfiguration object that contain common export settings available for the
exporter itself; they do not depend on particular reports and will be applied globally during the export. An example of global setting is the use of custom
color palette in the Excel output. This is a global setting for the Excel app itself, rather than a report setting, so it should be set globally per export.
Another way to provide configuration settings globally is to use the overloaded
public void setConfiguration(RC configuration)
method in the JRAbstractExporter class. It requires a
ReportExportConfiguration object. This object contains common report-specific
export settings and will be applied during the report per each report in the list.
Builtin implementations
Below is a list of the builtin implementations for the exporter input APIs:
- ExporterInput interface:
- SimpleExporterInput class
- ExporterInputItem interface:
- SimpleExporterInputItem class
- ExporterConfiguration interface:
- SimpleCsvExporterConfiguration class - global setting for the CSV export
- SimpleCsvMetadataExporterConfiguration class - global setting for the CSV metadata export
- SimpleDocxExporterConfiguration class - global setting for the DOCX export
- SimpleGraphics2DExporterConfiguration - global setting for the Graphics2D export
- SimpleHtmlExporterConfiguration class - global setting for the HTML export
- SimpleJsonExporterConfiguration class - global setting for the JSON export
- SimpleOdsExporterConfiguration class - global setting for the ODS export
- SimpleOdtExporterConfiguration class - global setting for the ODT export
- SimplePdfExporterConfiguration class - global setting for the PDF export
- SimplePptxExporterConfiguration class - global setting for the PPTX export
- SimplePrintServiceExporterConfiguration class - global setting for the PrintService export
- SimpleRtfExporterConfiguration class - global setting for the RTF export
- SimpleTextExporterConfiguration class - global setting for the Text export
- SimpleXlsExporterConfiguration class - global setting for the XLS export
- SimpleXlsMetadataExporterConfiguration class - global setting for the XLS metadata export
- SimpleXlsxExporterConfiguration class - global setting for the XLSX export
- ReportExportConfiguration interface:
- SimpleCsvReportConfiguration class - report setting for the CSV export
- SimpleCsvMetadataReportConfiguration class - report setting for the CSV metadata export
- SimpleDocxReportConfiguration class - report setting for the DOCX export
- SimpleGraphics2DReportConfiguration class - report setting for the Graphics2D export
- SimpleHtmlReportConfiguration class - report setting for the HTML export
- SimpleJsonReportConfiguration class - report setting for the JSON export
- SimpleOdsReportConfiguration class - report setting for the ODS export
- SimpleOdtReportConfiguration class - report setting for the ODT export
- SimplePdfReportConfiguration class - report setting for the PDF export
- SimplePptxReportConfiguration class - report setting for the PPTX export
- SimplePrintServiceReportConfiguration class - report setting for the PrintService export
- SimpleRtfReportConfiguration class - report setting for the RTF export
- SimpleTextReportConfiguration class - report setting for the Text export
- SimpleXlsReportConfiguration class - report setting for the XLS export
- SimpleXlsMetadataReportConfiguration class - report setting for the XLS metadata export
- SimpleXlsxReportConfiguration class - report setting for the XLSX export
Batch Mode Export
The first thing an exporter needs to know is whether it is acting on a single JasperPrint
report or on a list with several JasperPrint objects.
Exporting multiple reports to a single resulting document is called batch mode exporting.
Not all exporters can work in batch mode, but those that do first look into the exporter input data to see whether a list of several
JasperPrint objects has been
supplied to them. If so, the exporter loops through this list of reports and produces a single document from them.
If the exporters act on a single report, then they check whether a single JasperPrint object is supplied to
the exporter input data to be exported. As already shown, this object may be loaded from an input stream, an URL,
a file object, or a file name. If no JasperPrint object is supplied,
then the exporter throws an exception telling that no input source was set for the export process.
Batch Mode Bookmarks
When several JasperPrint documents must be concatenated in the same PDF file by
batch export, you can introduce PDF bookmarks in the resulting PDF document to mark
the beginning of each individual document that was part of the initial document list.
These bookmarks have the same name as the original JasperPrint document as
specified by the jasperPrint.getName() property. However, users can turn on and off
the creation of those bookmarks by using the following
export configuration setting. The exporter does not create such bookmarks by default.
Code Samples
This sample illustrates how to deal with exporter input settings when multiple reports are exported in batch mode.
Looking into the src/BatchExportApp.java source file one can see that, first of all, 3 reports are filled to generate
JasperPrint objects:
Let's see now the batch export to the PDF output:
jasperPrintList = new ArrayList();
jasperPrintList.add((JasperPrint)JRLoader.loadObjectFromFile("build/reports/Report1.jrprint"));
jasperPrintList.add((JasperPrint)JRLoader.loadObjectFromFile("build/reports/Report2.jrprint"));
jasperPrintList.add((JasperPrint)JRLoader.loadObjectFromFile("build/reports/Report3.jrprint"));
JRPdfExporter exporter = new JRPdfExporter();
exporter.setExporterInput(SimpleExporterInput.getInstance(jasperPrintList));
exporter.setExporterOutput(new SimpleOutputStreamExporterOutput("build/reports/BatchExportReport.pdf"));
SimplePdfExporterConfiguration configuration = new SimplePdfExporterConfiguration();
configuration.setCreatingBatchModeBookmarks(true);
exporter.setConfiguration(configuration);
exporter.exportReport();
System.err.println("PDF creation time : " + (System.currentTimeMillis() - start));
}]]>
One can see that a list of JasperPrint objects is
loaded from previously created *.jrprint files. The list is used to populate the exporter input data, using the
SimpleExporterInput builtin implementation:
:
exporter.setExporterInput(SimpleExporterInput.getInstance(jasperPrintList));
Based on the list of JasperPrint objects, the
SimpleExporterInput will create and save
a list of corresponding ExporterInputItem objects.
Next, a global configuration setting is supplied to the exporter, using the
SimplePdfExporterConfiguration implementation.
This will instruct the exporter to take into account the batch export mode when creating bookmarks.
Another example is the batch export to Excel 2007 (XLSX) output format:
jasperPrintList = new ArrayList();
jasperPrintList.add((JasperPrint)JRLoader.loadObjectFromFile("build/reports/Report1.jrprint"));
jasperPrintList.add((JasperPrint)JRLoader.loadObjectFromFile("build/reports/Report2.jrprint"));
jasperPrintList.add((JasperPrint)JRLoader.loadObjectFromFile("build/reports/Report3.jrprint"));
JRXlsxExporter exporter = new JRXlsxExporter();
exporter.setExporterInput(SimpleExporterInput.getInstance(jasperPrintList));
exporter.setExporterOutput(new SimpleOutputStreamExporterOutput("build/reports/BatchExportReport.xlsx"));
SimpleXlsxReportConfiguration configuration = new SimpleXlsxReportConfiguration();
configuration.setOnePagePerSheet(false);
exporter.setConfiguration(configuration);
exporter.exportReport();
System.err.println("XLSX creation time : " + (System.currentTimeMillis() - start));
}]]>
The main difference here is the global use of the
SimpleXlsxReportConfiguration class, the
builtin implementation of the ReportExportConfiguration
interface fot the XLSX output format:
This configuration setting may differ from report to report, but when it's set on the exporter like above, it means
that the same setting will be applied to al reports in the list. To have different settings per each report, we need to set a
ReportExportConfiguration to each
ExporterInputItem in the list.
Running the Sample
Running the sample requires the Apache Ant library. Make sure that ant is already installed on your system (version 1.5 or later).
In a command prompt/terminal window set the current folder to demo/samples/batchexport within the JasperReports source project and run the > ant test view command.
It will generate all supported document types containing the sample report in the demo/samples/batchexport/build/reports directory.
Then the report will open in the JasperReports internal viewer.