<?xml version="1.0" encoding="UTF-8"?>

<sample>

  <name>batchexport</name>
  <title>Batch Export Sample</title>
  <description>Shows how multiple reports could be concatenated during export.</description>

  <mainFeature ref="batchexport"/>
  
  <!-- batchexport -->
  
  <feature name="batchexport" title="Exporting Multiple Reports into a Single Output File (Batch Export)">
    <description>
Several reports can be exported together to form a single resulting document.
    </description>
    <since>0.6.0</since>
    <documentedBy>
      <author>
    	<name>Sanda Zaharia</name>
    	<email>shertage@users.sourceforge.net</email>
      </author>
    </documentedBy>
    <content>
<b>Exporter Input - API Overview</b>
<br/>
<br/>
Once generated, a <api href="net/sf/jasperreports/engine/JasperPrint.html">JasperPrint</api> 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:
<ol>
<li>a single <api href="net/sf/jasperreports/engine/JasperPrint.html">JasperPrint</api> or a list 
of <api href="net/sf/jasperreports/engine/JasperPrint.html">JasperPrint</api> objects to be exported at a time; these objects may:
<ul>
<li>be in-memory objects</li>
<li>come from the network through an input stream</li>
<li>be loaded from files on disk</li>
</ul>
</li>
<li>a set of export configuration settings to be applied either globally or per each report in the list</li>
</ol>
<br/>
Exporter builtin implementations acquire input data based on methods inherited from their  
<api href="net/sf/jasperreports/engine/JRAbstractExporter.html">JRAbstractExporter</api> super class. When extending the 
<api href="net/sf/jasperreports/engine/JRAbstractExporter.html">JRAbstractExporter</api> class, one can reuse the 
<ul> 
<li><code>public void setExporterInput(ExporterInput exporterInput)</code></li>
</ul>
method to deal with the report sources and export configuration settings.
<br/>
As shown in the method signature, all we need is an <api href="net/sf/jasperreports/export/ExporterInput.html">ExporterInput</api> object. 
This object must implement the 
<ul> 
<li><code>public List&lt;ExporterInputItem&gt; getItems()</code></li> 
</ul>
method in order to retrieve a list of 
<api href="net/sf/jasperreports/export/ExporterInputItem.html">ExporterInputItem</api> objects. Each 
<api href="net/sf/jasperreports/export/ExporterInputItem.html">ExporterInputItem</api> in the list contains a single 
<api href="net/sf/jasperreports/engine/JasperPrint.html">JasperPrint</api> object along with its related export 
configuration settings. Methods in the <api href="net/sf/jasperreports/export/ExporterInputItem.html">ExporterInputItem</api> interface are:
<ul>
<li><code>public JasperPrint getJasperPrint()</code> - return the <api href="net/sf/jasperreports/engine/JasperPrint.html">JasperPrint</api> object</li>
<li><code>public ReportExportConfiguration getConfiguration()</code> - return export configuration settings to be applied for the 
<api href="net/sf/jasperreports/engine/JasperPrint.html">JasperPrint</api> object</li>
</ul>
Global configuration settings per exporter can be configured using the 
<ul> 
<li><code>public void setConfiguration(C configuration)</code></li>
</ul>
method in the <api href="net/sf/jasperreports/engine/JRAbstractExporter.html">JRAbstractExporter</api> class. This method accepts an 
<api href="net/sf/jasperreports/export/ExporterConfiguration.html">ExporterConfiguration</api> 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.    
<br/>
<br/>
Another way to provide configuration settings globally is to use the overloaded 
<ul> 
<li><code>public void setConfiguration(RC configuration)</code></li>
</ul>
method in the <api href="net/sf/jasperreports/engine/JRAbstractExporter.html">JRAbstractExporter</api> class. It requires a 
<api href="net/sf/jasperreports/export/ReportExportConfiguration.html">ReportExportConfiguration</api> object. This object contains common report-specific 
export settings and will be applied during the report per each report in the list. 
<br/>
<br/>
<b>Builtin implementations</b>
<br/>
<br/>
Below is a list of the builtin implementations for the exporter input APIs:
<ol>
<li><api href="net/sf/jasperreports/export/ExporterInput.html">ExporterInput</api> interface:
<ul>
<li><api href="net/sf/jasperreports/export/SimpleExporterInput.html">SimpleExporterInput</api> class</li>
</ul>
<br/>
<br/>
</li>
<li><api href="net/sf/jasperreports/export/ExporterInputItem.html">ExporterInputItem</api> interface:
<ul>
<li><api href="net/sf/jasperreports/export/SimpleExporterInputItem.html">SimpleExporterInputItem</api> class</li>
</ul>
<br/>
<br/>
</li>
<li><api href="net/sf/jasperreports/export/ExporterConfiguration.html">ExporterConfiguration</api> interface:
<ul>
<li><api href="net/sf/jasperreports/export/SimpleCsvExporterConfiguration.html">SimpleCsvExporterConfiguration</api> class - global setting for the CSV export</li>
<li><api href="net/sf/jasperreports/export/SimpleCsvMetadataExporterConfiguration.html">SimpleCsvMetadataExporterConfiguration</api> class - global setting for the CSV metadata export</li>
<li><api href="net/sf/jasperreports/export/SimpleDocxExporterConfiguration.html">SimpleDocxExporterConfiguration</api> class - global setting for the DOCX export</li>
<li><api href="net/sf/jasperreports/export/SimpleGraphics2DExporterConfiguration.html">SimpleGraphics2DExporterConfiguration</api> - global setting for the Graphics2D export</li>
<li><api href="net/sf/jasperreports/export/SimpleHtmlExporterConfiguration.html">SimpleHtmlExporterConfiguration</api> class - global setting for the HTML export</li>
<li><api href="net/sf/jasperreports/export/SimpleJsonExporterConfiguration.html">SimpleJsonExporterConfiguration</api> class - global setting for the JSON export</li>
<li><api href="net/sf/jasperreports/export/SimpleOdsExporterConfiguration.html">SimpleOdsExporterConfiguration</api> class - global setting for the ODS export</li>
<li><api href="net/sf/jasperreports/export/SimpleOdtExporterConfiguration.html">SimpleOdtExporterConfiguration</api> class - global setting for the ODT export</li>
<li><api href="net/sf/jasperreports/export/SimplePdfExporterConfiguration.html">SimplePdfExporterConfiguration</api> class - global setting for the PDF export</li>
<li><api href="net/sf/jasperreports/export/SimplePptxExporterConfiguration.html">SimplePptxExporterConfiguration</api> class - global setting for the PPTX export</li>
<li><api href="net/sf/jasperreports/export/SimplePrintServiceExporterConfiguration.html">SimplePrintServiceExporterConfiguration</api> class - global setting for the PrintService export</li>
<li><api href="net/sf/jasperreports/export/SimpleRtfExporterConfiguration.html">SimpleRtfExporterConfiguration</api> class - global setting for the RTF export</li>
<li><api href="net/sf/jasperreports/export/SimpleTextExporterConfiguration.html">SimpleTextExporterConfiguration</api> class - global setting for the Text export</li>
<li><api href="net/sf/jasperreports/export/SimpleXlsExporterConfiguration.html">SimpleXlsExporterConfiguration</api> class - global setting for the XLS export</li>
<li><api href="net/sf/jasperreports/export/SimpleXlsMetadataExporterConfiguration.html">SimpleXlsMetadataExporterConfiguration</api> class - global setting for the XLS metadata export</li>
<li><api href="net/sf/jasperreports/export/SimpleXlsxExporterConfiguration.html">SimpleXlsxExporterConfiguration</api> class - global setting for the XLSX export</li>
</ul>
<br/>
<br/>
</li>
<li><api href="net/sf/jasperreports/export/ReportExportConfiguration.html">ReportExportConfiguration</api> interface:
<ul>
<li><api href="net/sf/jasperreports/export/SimpleCsvExporterConfiguration.html">SimpleCsvReportConfiguration</api> class - report setting for the CSV export</li>
<li><api href="net/sf/jasperreports/export/SimpleCsvMetadataReportConfiguration.html">SimpleCsvMetadataReportConfiguration</api> class - report setting for the CSV metadata export</li>
<li><api href="net/sf/jasperreports/export/SimpleDocxReportConfiguration.html">SimpleDocxReportConfiguration</api> class - report setting for the DOCX export</li>
<li><api href="net/sf/jasperreports/export/SimpleGraphics2DReportConfiguration.html">SimpleGraphics2DReportConfiguration</api> class - report setting for the Graphics2D export</li>
<li><api href="net/sf/jasperreports/export/SimpleHtmlReportConfiguration.html">SimpleHtmlReportConfiguration</api> class - report setting for the HTML export</li>
<li><api href="net/sf/jasperreports/export/SimpleJsonReportConfiguration.html">SimpleJsonReportConfiguration</api> class - report setting for the JSON export</li>
<li><api href="net/sf/jasperreports/export/SimpleOdsReportConfiguration.html">SimpleOdsReportConfiguration</api> class - report setting for the ODS export</li>
<li><api href="net/sf/jasperreports/export/SimpleOdtReportConfiguration.html">SimpleOdtReportConfiguration</api> class - report setting for the ODT export</li>
<li><api href="net/sf/jasperreports/export/SimplePdfReportConfiguration.html">SimplePdfReportConfiguration</api> class - report setting for the PDF export</li>
<li><api href="net/sf/jasperreports/export/SimplePptxReportConfiguration.html">SimplePptxReportConfiguration</api> class - report setting for the PPTX export</li>
<li><api href="net/sf/jasperreports/export/SimplePrintServiceReportConfiguration.html">SimplePrintServiceReportConfiguration</api> class - report setting for the PrintService export</li>
<li><api href="net/sf/jasperreports/export/SimpleRtfReportConfiguration.html">SimpleRtfReportConfiguration</api> class - report setting for the RTF export</li>
<li><api href="net/sf/jasperreports/export/SimpleTextReportConfiguration.html">SimpleTextReportConfiguration</api> class - report setting for the Text export</li>
<li><api href="net/sf/jasperreports/export/SimpleXlsReportConfiguration.html">SimpleXlsReportConfiguration</api> class - report setting for the XLS export</li>
<li><api href="net/sf/jasperreports/export/SimpleXlsMetadataReportConfiguration.html">SimpleXlsMetadataReportConfiguration</api> class - report setting for the XLS metadata export</li>
<li><api href="net/sf/jasperreports/export/SimpleXlsxReportConfiguration.html">SimpleXlsxReportConfiguration</api> class - report setting for the XLSX export</li>
</ul>
</li>
</ol>
<b>Batch Mode Export</b>
<br/>
<br/>
The first thing an exporter needs to know is whether it is acting on a single <api href="net/sf/jasperreports/engine/JasperPrint.html">JasperPrint</api> 
report or on a list with several JasperPrint objects. 
<br/>
Exporting multiple reports to a single resulting document is called batch mode exporting. 
<br/>
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 
<api href="net/sf/jasperreports/engine/JasperPrint.html">JasperPrint</api> objects has been 
supplied to them. If so, the exporter loops through this list of reports and produces a single document from them.
<br/> 
If the exporters act on a single report, then they check whether a single <api href="net/sf/jasperreports/engine/JasperPrint.html">JasperPrint</api> 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 <api href="net/sf/jasperreports/engine/JasperPrint.html">JasperPrint</api> object is supplied, 
then the exporter throws an exception telling that no input source was set for the export process.
<br/>
<br/>
<b>Batch Mode Bookmarks</b>
<br/>
<br/>
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. 
<br/>
These bookmarks have the same name as the original JasperPrint document as 
specified by the <code>jasperPrint.getName()</code> property. However, users can turn on and off 
the creation of those bookmarks by using the following
<pre><![CDATA[
  SimplePdfExporterConfiguration configuration = new SimplePdfExporterConfiguration();
  configuration.setCreatingBatchModeBookmarks(true);  //or false, if needed
  exporter.setConfiguration(configuration);]]></pre>
export configuration setting. The exporter does not create such bookmarks by default. 
<br/>
<br/>
<b>Code Samples</b>
<br/>
<br/>
This sample illustrates how to deal with exporter input settings when multiple reports are exported in batch mode.
<br/>
Looking into the <code>src/BatchExportApp.java</code> source file one can see that, first of all, 3 reports are filled to generate 
<api href="net/sf/jasperreports/engine/JasperPrint.html">JasperPrint</api> objects:
<pre><![CDATA[
public void fill() throws JRException
{
  long start = System.currentTimeMillis();
  
  //first JasperPrint object is generated and saved as .jrprint object in the build/reports directory
  JasperFillManager.fillReportToFile(
    "build/reports/Report1.jasper",
    null, 
    new JREmptyDataSource(2)
    );
    
  //second JasperPrint object is generated and saved as .jrprint object in the build/reports directory
  JasperFillManager.fillReportToFile(
    "build/reports/Report2.jasper",
    null, 
    new JREmptyDataSource(2)
    );
    
  //third JasperPrint object is generated and saved as .jrprint object in the build/reports directory
  JasperFillManager.fillReportToFile(
    "build/reports/Report3.jasper",
    null, 
    new JREmptyDataSource(2)
    );
    
  System.err.println("Filling time : " + (System.currentTimeMillis() - start));
}]]></pre>
Let's see now the batch export to the PDF output: 
<pre><![CDATA[
public void pdf() throws JRException
{
  long start = System.currentTimeMillis();
  
  List<JasperPrint> jasperPrintList = new ArrayList<JasperPrint>();
  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));
}]]></pre>
One can see that a list of <api href="net/sf/jasperreports/engine/JasperPrint.html">JasperPrint</api> objects is
loaded from previously created <code>*.jrprint</code> files. The list is used to populate the exporter input data, using the 
<api href="net/sf/jasperreports/export/SimpleExporterInput.html">SimpleExporterInput</api> builtin implementation:
:
<br/>
<br/>
<code>exporter.setExporterInput(SimpleExporterInput.getInstance(jasperPrintList));</code>
<br/>
<br/>
Based on the list of <api href="net/sf/jasperreports/engine/JasperPrint.html">JasperPrint</api> objects, the 
<api href="net/sf/jasperreports/export/SimpleExporterInput.html">SimpleExporterInput</api> will create and save 
a list of corresponding <api href="net/sf/jasperreports/export/ExporterInputItem.html">ExporterInputItem</api> objects.
<br/> 
<br/> 
Next, a global configuration setting is supplied to the exporter, using the 
<api href="net/sf/jasperreports/export/SimplePdfExporterConfiguration.html">SimplePdfExporterConfiguration</api> implementation. 
This will instruct the exporter to take into account the batch export mode when creating  bookmarks.
<pre><![CDATA[
  SimplePdfExporterConfiguration configuration = new SimplePdfExporterConfiguration();
  configuration.setCreatingBatchModeBookmarks(true);
  exporter.setConfiguration(configuration);]]></pre>
Another example is the batch export to Excel 2007 (XLSX) output format:
<pre><![CDATA[
public void xlsx() throws JRException
{
  long start = System.currentTimeMillis();
  List<JasperPrint> jasperPrintList = new ArrayList<JasperPrint>();
  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));
}]]></pre>
The main difference here is the global use of the 
<api href="net/sf/jasperreports/export/SimpleXlsxReportConfiguration.html">SimpleXlsxReportConfiguration</api> class, the 
builtin implementation of the <api href="net/sf/jasperreports/export/ReportExportConfiguration.html">ReportExportConfiguration</api> 
interface fot the XLSX output format:
<pre><![CDATA[
  SimpleXlsxReportConfiguration configuration = new SimpleXlsxReportConfiguration();
  configuration.setOnePagePerSheet(false);
  exporter.setConfiguration(configuration);]]></pre>
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 
<api href="net/sf/jasperreports/export/ReportExportConfiguration.html">ReportExportConfiguration</api> to each 
<api href="net/sf/jasperreports/export/ExporterInputItem.html">ExporterInputItem</api> in the list.
<br/>
<br/>
<b>Running the Sample</b>
<br/>
<br/>
Running the sample requires the <a href="http://ant.apache.org/">Apache Ant</a> library. Make sure that <code>ant</code> is already installed on your system (version 1.5 or later).
<br/>
In a command prompt/terminal window set the current folder to <code>demo/samples/batchexport</code> within the JasperReports source project and run the <code>&gt; ant test view</code> command.
<br/>
It will generate all supported document types containing the sample report in the <code>demo/samples/batchexport/build/reports</code> directory. 
<br/>
Then the report will open in the JasperReports internal viewer.
    </content>
  </feature>

</sample>
