# Package net.sf.jasperreports.engine.export

Provides utility classes for exporting reports to various popular formats such as PDF, HTML, RTF, CSV, Excel, DOCX, PPTX, ODT, ODS, XML, Text, etc.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  ExporterFilter |
  ExporterFilterFactory | A factory of `ExporterFilter` instances.
  ExporterNature |
  GenericElementCsvHandler | A generic print element CSV export handler.
  GenericElementGraphics2DHandler | A generic print element Graphics2D export handler.
  GenericElementHandler | A generic print element export handler.
  GenericElementHandlerBundle | A bundle of `generic element handlers` that share the same namespace.
  GenericElementHtmlHandler | A generic print element HTML export handler.
  GenericElementJExcelApiHandler | Deprecated To be removed.
  GenericElementJExcelApiMetadataHandler | Deprecated To be removed.
  GenericElementJsonHandler | A generic print element JSON export handler.
  GenericElementPdfHandler | A generic print element PDF export handler.
  GenericElementRtfHandler | A generic print element RTF export handler.
  GenericElementTransformer | A generic print element transformer.
  GenericElementTransformerContext | A context in which an element tranformation takes place.
  GenericElementXlsHandler | A generic print element XLS export handler.
  GenericElementXlsMetadataHandler | A generic print element XLS export handler.
  GenericElementXmlHandler | A generic print element XML export handler.
  HtmlResourceHandler |
  HyperlinkURLResolver |
  JExcelApiExporterContext | Deprecated To be removed.
  JRCsvExporterContext | A context that represents information about a CSV export process.
  JRExporterContext | A context that represents information about an export process.
  JRExportProgressMonitor |
  JRGraphics2DExporterContext | A context that represents information about an Graphics2D export process.
  JRHtmlExporter.StringProvider |
  JRHtmlExporterConfiguration | Deprecated To be removed.
  JRHtmlExporterContext | A context that represents information about an HTML export process.
  JRHtmlReportConfiguration | Deprecated To be removed.
  JRHyperlinkProducer | A simple hyperlink generator that can be used to handle custom hyperlink types.
  JRHyperlinkTargetProducer | A simple hyperlink target generator that can be used to handle custom hyperlink targets.
  JRPdfExporterContext | A context that represents information about an PDF export process.
  JRRtfExporterContext | A context that represents information about an RTF export process.
  JRTextExporterContext | A context that represents information about a text export process.
  JRXlsExporterContext | A context that represents information about an XLS export process.
  JRXmlExporterContext | A context that represents information about an XML export process.
  JsonExporterContext | A context that represents information about an HTML export process.
  ResetableExporterFilter |

- Class Summary
  Class | Description
  --- | ---
  AbstractExporterNature |
  AbstractHtmlExporter<RC extends HtmlReportConfiguration,C extends HtmlExporterConfiguration> |
  AbstractPdfTextRenderer |
  AbstractTextRenderer |
  AwtTextRenderer |
  Cut | Utility class used by grid exporters to create a grid for page layout.
  CutsInfo | Utility class used by grid exporters to create a grid for page layout.
  DefaultElementHandlerBundle | The default `GenericElementHandlerBundle` implementation.
  DefaultExporterFilterFactory | Default exporter filter factory.
  DefaultHyperlinkProducerFactory | Extension-based hyperlink producer factory implementation.
  DefaultHyperlinkTargetProducerFactory | Extension-based hyperlink target producer factory implementation.
  ElementGridCell |
  ElementKeyExporterFilter | An exporter filter that excludes elements based on their keys.
  ElementKeyExporterFilterFactory | Factory of `ElementKeyExporterFilter` instances.
  ElementReplacementGridCell |
  EmptyGridCell |
  ExporterFilterContainer | An exporter filter that consists of several exporter filter, and filters elements through each of them.
  ExporterFilterFactoryUtil | A `ExporterFilterFactory` utility class.
  FileHtmlResourceHandler |
  FlashHtmlHandler | A HTML export handler for generic print elements produced by `FlashPrintElement`.
  FlashPrintElement | Utility class that creates generic print elements of Flash type.
  GenericElementHandlerEnviroment | A class that provides access to `generic element handlers`.
  GenericElementReportTransformer | A utility class that applies `GenericElementTransformers` to a filled report.
  GenericElementReportTransformer.TransformerContext |
  GenericElementsFilterDecorator |
  Grid |
  GridCellSize |
  GridCellStyle |
  GridRow |
  HtmlExporter |
  HtmlExporterHyperlinkProducerAdapter | An adapter of `JRHtmlExporterContext` as `JRHyperlinkProducer`.
  HtmlFont |
  HtmlFontUtil |
  HyperlinkUtil |
  JExcelApiExporter | Deprecated To be removed.
  JExcelApiExporterNature | Deprecated To be removed.
  JExcelApiExporterParameter | Deprecated To be removed.
  JExcelApiLocalHyperlinkInfo | Deprecated To be removed.
  JExcelApiMetadataExporter | Deprecated Replaced by `JRXlsMetadataExporter`.
  JRAbstractCsvExporter<RC extends CsvReportConfiguration,C extends CsvExporterConfiguration,E extends JRExporterContext> | Exports a JasperReports document to CSV format.
  JRCsvExporter | Exports a JasperReports document to CSV format.
  JRCsvExporterNature |
  JRCsvExporterParameter | Deprecated Replaced by `CsvExporterConfiguration`.
  JRCsvMetadataExporter | Exports a JasperReports document to CSV format based on the metadata provided.
  JRCsvMetadataExporterParameter | Deprecated Replaced by `CsvMetadataExporterConfiguration`.
  JRExporterGridCell |
  JRGraphics2DExporter | Exports a JasperReports document to a `Graphics2D` object.
  JRGraphics2DExporterParameter | Deprecated Replaced by `Graphics2DExporterConfiguration` and `Graphics2DExporterOutput`.
  JRGridLayout | Utility class used by grid exporters to create a grid for page layout.
  JRGridLayout.BoxKey |
  JRHtmlExporter | Deprecated Replaced by `HtmlExporter`.
  JRHtmlExporterHelper | Deprecated To be removed.
  JRHtmlExporterNature | Deprecated To be removed.
  JRHtmlExporterParameter | Deprecated Replaced by `ExporterInput`, `HtmlExporterConfiguration` and `HtmlExporterOutput`.
  JRHyperlinkProducerFactory | An abstract factory of `hyperlink producers`.
  JRHyperlinkProducerMapFactory | Map-based hyperlink producer factory implementation.
  JRHyperlinkTargetProducerFactory | An abstract factory of `hyperlink target producers`.
  JRHyperlinkTargetProducerMapFactory | Map-based hyperlink target producer factory implementation.
  JROriginExporterFilter |
  JROriginExporterFilterFactory | Factory of `JROriginExporterFilter` instances.
  JRPdfExporter | Exports a JasperReports document to PDF format.
  JRPdfExporter.Bookmark |
  JRPdfExporter.BookmarkStack |
  JRPdfExporterParameter | Deprecated Replaced by `PdfExporterConfiguration`.
  JRPdfExporterTagHelper | Provides support for tagged PDF documents.
  JRPrintServiceExporter | Prints a JasperReports document using the Java Print Service API.
  JRPrintServiceExporterParameter | Deprecated Replaced by `PrintServiceExporterConfiguration`.
  JRRtfExporter | Exports a JasperReports document to RTF format.
  JRTextExporter | Exports filled reports in plain text format.
  JRTextExporterParameter | Deprecated Replaced by `TextExporterConfiguration`.
  JRXhtmlExporter | Deprecated Replaced by `HtmlExporter`.
  JRXlsAbstractExporter<RC extends XlsReportConfiguration,C extends XlsExporterConfiguration,E extends JRExporterContext> | Superclass for the Excel exporters.
  JRXlsAbstractExporter.SheetInfo |
  JRXlsAbstractExporter.TextAlignHolder |
  JRXlsAbstractExporterNature |
  JRXlsAbstractExporterParameter | Deprecated Replaced by `XlsExporterConfiguration`.
  JRXlsAbstractMetadataExporter<RC extends XlsMetadataReportConfiguration,C extends XlsMetadataExporterConfiguration,E extends JRExporterContext> |
  JRXlsAbstractMetadataExporterParameter | Deprecated Replaced by `XlsMetadataExporterConfiguration`.
  JRXlsExporter | Exports a JasperReports document to XLS format.
  JRXlsExporterNature |
  JRXlsExporterParameter | Deprecated Replaced by `XlsExporterConfiguration`.
  JRXlsMetadataExporter |
  JRXlsMetadataExporterNature |
  JRXml4SwfExporter | This is a modified version of the JRXmlExporter class, which produces an XML document that is used by the Flash viewer.
  JRXmlExporter | Exports a JasperReports document to an XML file that contains the same data as a `JasperPrint` object, but in XML format, instead of a serialized class.
  JRXmlExporterParameter | Deprecated Replaced by `XmlExporterOutput`.
  JsonExporter |
  LengthUtil |
  MapHtmlResourceHandler |
  MatcherExporterFilter |
  MatcherExporterFilterFactory | Factory of `MatcherExporterFilter` instances.
  MatcherExportFilterMapping |
  MatcherExportFilterMappingExtensionsRegistryFactory |
  OccupiedGridCell |
  PdfTextRenderer |
  PrintElementIndex |
  SimplePdfTextRenderer |
  XlsRowLevelInfo |

## Package net.sf.jasperreports.engine.export Description

Provides utility classes for exporting reports to various popular formats such as PDF, HTML, RTF, CSV, Excel, DOCX, PPTX, ODT, ODS, XML, Text, etc.

### Exporting Reports

In some application environments, it is useful to transform the JasperReports-generated documents from the proprietary format into other, more popular formats like PDF, HTML, RTF, or XLSX. This way, users can view those reports without having to install special viewers on their systems, which is especially important in the case of documents sent over a network.

There is a facade class in JasperReports for this type of functionality: `JasperExportManager`; it can be used to obtain PDF, HTML, or XML content for the documents produced by the report-filling process. Exporting means taking a `JasperPrint` object, which represents a JasperReports document, and transforming it into a different format. The main reason to export reports into other formats is to allow more people to view those reports. HTML reports can be viewed by anybody these days, since at least one browser is available on any system. Viewing JasperReports documents in their proprietary form would require the installation of special software on the target platform (at least a Java applet, if not more).

With time, more and more output formats will be supported by the JasperReports library. For the moment, the various exporter implementations shipped with the library produce Graphics2D, PDF, HTML, RTF, CSV, Excel, DOCX, PPTX, ODT, ODS, XML, pure text and JSON output.

The `JasperExportManager` class offers easy access for only the PDF, HTML, and XML implementations, as these have historically been the most common formats or required the least export configuration.

Here's how you can export your report to HTML format using the facade export manager class:

     JasperExportManager.exportReportToHtmlFile(myReport);

To avoid excessive utility methods, this class was originally written such that the default settings only offer easy access to the most common export formats. When new exporters were added to the library, the export manager class was not extended, and users were encouraged to use the exporter classes directly. Only by doing that could they fully customize the behavior of that particular exporter using specific exporter parameters.

JasperReports tries to expose its exporting functionality in a flexible way and allow users to fully customize how documents are exported, as well as extend the existing functionality if needed. All document exporting in JasperReports is done through a very simple interface called `Exporter`. Every document format that JasperReports currently supports has an implementation of this interface. When a report must be exported, an instance of the desired exporter implementation is created and configured before the export method is called to launch the actual export process on that exporter.

### Exporter Input

All the input data the exporter might need is supplied by the so-called exporter input before the exporting process is started. This is because the exporting process is always invoked by calling the `exportReport()` method of the `Exporter` interface, and this method does not receive any parameters when called.

The input data for an exporter comes in the form of one or more `JasperPrint` objects that must be exported to some other document format, along with other optional export settings. These `JasperPrint` objects may be already in memory, come from the network through an input stream, or reside in files on disk.

An exporter should be able to handle such a wide range of document sources. In fact, all the exporter implementations that are shipped inside the library already do this. They all extend the `JRAbstractExporter` class, which holds all the logic for dealing with the source documents that need to be exported inside its defined `setExporterInput(ExporterInput exporterInput)` method.

As shown in the method signature, all we need is an `ExporterInput` instance that holds the necessary input data. This object must implement the `public List<ExporterInputItem> getItems()` method in order to obtain a list of `ExporterInputItem` objects. Each `ExporterInputItem` object in the list contains a single `JasperPrint` object along with its related export configuration settings.

### Exporter Output

There are at least three types of exporters, depending on the type of output they produce:

- Exporters that export to text- or character-based file formats (HTML, RTF, CSV, TXT, XML ... exporters)
- Exporters that export to binary file formats (PDF, XLS ... exporters)
- Exporters that export directly to graphic devices (Graphics2D and Java Print Service exporters)

The first two categories of exporters reuse generic exporter settings for configuring their output. A text- or character-oriented exporter first looks into its `ExporterOutput` setting to see whether it needs to output the text content it produces to:

- a supplied `java.lang.StringBuffer` object
- a supplied `java.io.Writer` object
- a supplied `java.io.OutputStream` object
- a `java.io.File` object
- a file with a given `java.lang.String` file name

If none of these OUT parameters have been set, then the exporter throws an exception to inform the caller.

A binary exporter uses similar logic to find the output destination for the binary content it produces. It checks generic exporter output settings in this exact order: `java.io.OutputStream`, `java.io.File`, or file with a given `java.lang.String` file name.

Special exporters that do not produce character or binary output but rather render the document directly on a target device have special export settings to configure their output.

Output settings for all built-in exporters can be set using the `public void setExporterOutput(O exporterOutput)` method inherited from their `JRAbstractExporter` parent class. The `exporterOutput` argument must be an instance of `ExporterOutput` interface.

### Other Export Configuration Settings

Other export configuration settings can be communicated to exporters using the `public void setConfiguration(C configuration)` and `public void setConfiguration(RC configuration)` inherited from the `JRAbstractExporter` parent class. The first method accepts an `ExporterConfiguration` argument and applies settings per exporter. The second one accepts a `ReportExportConfiguration` and applies settings per each exported report in a batch export.

Below are some examples of report configuration settings available in the `ReportExportConfiguration` class:

- the start page index - specifies the 0-based index for the first page in a page range to be exported
- the end page index - specifies the 0-based index for the last page in a page range to be exported
- the page index - specifies the 0-based index for a single page to be exported. If present, this setting overrides both the first page index and the end page index
- the x offset - to move the page content horizontally, when it doesn't always fit with the printer page margins
- the y offset - to move the page content vertically, when it doesn't always fit with the printer page margins
- etc

### Batch Mode Export

The first thing an exporter needs to know is whether it is acting on a single `JasperPrint` document or a list with several such generated documents. Exporting multiple `JasperPrint` objects 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 supplied exporter input values to see whether a `java.util.List` of `JasperPrint` object has been supplied to them. If so, the exporter loops through this list of documents and produces a single document from them.

If the exporters act on a single document, then they check whether an in-memory `JasperPrint` value is supplied to the exporter input data. If no such value is found for this setting, then the input for the exporter is a single `JasperPrint` document to be loaded from an input stream, an URL, a file object, or a file name. If the exporter does not find any of these settings, then it throws an exception telling the caller that no input source was set for the export process.

### Exporter Filters

When exporting a report to any format, it is possible to filter the elements from the generated report by skipping elements that do meet a certain condition. This allows report designers to control what gets exported to each format. In many cases, it's not desirable to export all report sections and elements to all output formats; for instance, some visual report elements should only be displayed in output formats that are meant for on-screen viewing and not in other data-centric output formats.

JasperReports comes with two built-in filter implementations that cover the most frequent use cases. It also defines a set of interfaces that can be used to introduce other filter implementations. Custom export filter can be written by users to support specific filtering mechanisms.

When exporting a report, a filter can be explicitly specified using an export parameter, or a filter can be implicitly created based on the properties/export hints present in the report.

To explicitly specify an export filter, the exporter configuration setting `public ExporterFilter getExporterFilter()` (method in the `ReportExportConfiguration` class) should be used to pass a filter object, which would be an instance of a class that implements the `ExporterFilter` interface. The filter object can be of one the built-in export filter types, or of a custom filter implementation type.

When no value is found for the export filter setting, the exporter will use a default filter factory to instantiate a filter that will be used for the export. The default filter factory class is set via a property named `net.sf.jasperreports.engine.export.default.filter.factory`.

The built-in default filter factory implementation calls all registered filter factories and allows each of them to apply filters on the exporter report. If any of the filters decides to exclude an element, the element will be excluded from the export process. In most cases the built-in default filter factory provides the desired behavior. However users can choose to change it by setting another value for the default filter factory property. To allow a custom export filter implementation to be used by the implicit export filter mechanism, one needs to register an export filter factory class with JasperReports. To do so, a property named `net.sf.jasperreports.engine.export.filter.factory.<factory_name>` has to be included in the `jasperreports.properties` file (or set at runtime via `JRProperties`). The factory name is an arbitrary suffix, and the property value should be the name of a class that implements `ExporterFilterFactory`. The engine uses the class name to instantiate an export filter factory, therefore the factory class needs to have an accessible no-argument constructor.

Each registered filter factory has the chance of producing a filter every time a report export occurs. The filter factory receives an object that contains information about the current export process, including the exporter report and a property prefix that corresponds to the exporter, and decides based on this information whether it applies to the current export or not. This would usually involve consulting custom properties of the exporter report to determine whether the report contains properties that indicate some filtering criteria. The recommended practice is to make the filter factory recognize properties that have a specific suffix appended to the exporter property prefix. For instance, the element key filter factory recognizes properties that have `exclude.key` appended after the exporter property prefix.

If the exporter factory decides that it applies to the current report, it needs to return a non null exporter filter, which is an instance of a class that implements `ExporterFilter`. This filter will be applied to each element in the generated report and will be able to trigger the exclusion elements that match a given criteria.

Each exporter uses a different property prefix such that different filter criteria can be set for each exporter. The built-in exporters use property prefixes of the form `net.sf.jasperreports.export.<output_format>`. Below are the property prefixes for the built-in output formats:

- `Java Print/Graphics2D` - `net.sf.jasperreports.export.graphics2d`
- `PDF` - `net.sf.jasperreports.export.pdf`
- `RTF` - `net.sf.jasperreports.export.rtf`
- `XML` - `net.sf.jasperreports.export.xml`
- `HTML` - `net.sf.jasperreports.export.html`
- `Excel` - `net.sf.jasperreports.export.xls`
- `DOCX` - `net.sf.jasperreports.export.docx`
- `PPTX` - `net.sf.jasperreports.export.pptx`
- `ODT` - `net.sf.jasperreports.export.odt`
- `ODS` - `net.sf.jasperreports.export.ods`
- `CSV` - `net.sf.jasperreports.export.csv`
- `Text` - `net.sf.jasperreports.export.txt`

In case no filter instance is passed at export time, the exporter searches for some configuration properties with a given prefix, both at report level (exporter hints) and globally, in order to decide if a default exporter filter instance should be created on-the-fly and used internally, when exporting the current document.

If created, this default exporter filter will filter out content from the exported document based on element origin information. Elements present in JasperReports generated documents keep information about their origin. The origin of an element is defined by its parent section in the initial report template, and optionally the name of the group and/or subreport that the element originated from.

This built-in filter implementations also exclude from export elements that match a given element key.

Element keys are set at report design time and are propagated into generated reports. Each element in a filled report has the same key as the element from the report template that generated it.

To trigger an element key filter, the report designer needs to define one or more report properties that start with `<exporter_property_prefix>.exclude.key`. Each such property matches a single element key which is to be excluded by the filter. The element key is given by the property value, or if no value is set for the property, by the property suffix.

### Monitoring Export Progress

Some applications need to display a progress bar to show the user how much has been already processed from the supplied document and how much remains to be exported.

All exporters can inform the caller program of their progress through a simple interface called `JRExportProgressMonitor`. To monitor the exporter's progress, implement this interface and supply an instance of its export progress monitor class as the value for the `getProgressMonitor()` report exporter configuration setting, which is recognized by almost all built-in exporters.

The interface has only one method, `afterPageExport()`, which gets called by the exporter on the monitor object after exporting each page from the supplied document.

The monitor object can keep track of the number of pages already exported and the total number of pages to be exported by checking the number of pages in the source `JasperPrint` object.

### Grid Exporters

The main goal of the JasperReports library is to produce high-quality, pixel-perfect documents for printing. The documents it produces can have rich content, and all the elements on a given page are positioned and sized absolutely. The library tries to keep the same document quality throughout all supported export formats, but there are some limitations for each of these formats. All existing exporters fall into one of two categories, depending on the way the content of the documents they produce can be structured:

- exporters that target document formats that support free-form page content (Graphics2D, PDF, RTF, XML exporters).
- exporters that target document formats that only support relative positioning of elements on a page or a grid-based layout (HTML, Excel, CSV exporters).

Exporters from this second category are also known as grid exporters because the layout of the documents they produce is formed by a grid. For instance, the HTML exporter will generate a `<table>` element for each page and try to put each element on that page inside a `<td>` tag. Likewise, the XLS exporter must put each element inside a sheet cell.

These grid exporters have an obvious limitation: a built-in algorithm for transforming an absolutely positioned page layout into a grid-based layout. This algorithm analyzes each page and tries to build a virtual table in which to place elements so that the overall layout of the document remains intact. However, since a table cell can contain only a single element, elements that overlap in the initial absolutely positioned layout will not display correctly in a grid-based layout. In fact, when two elements overlap, the element behind will not even appear in the grid-based layout.

When the report templates are very complex or agglomerated, passing from absolute positioning to grid or table layout produces very complex tables with many unused rows and columns, in order to make up for the empty space between elements or their special alignment. Here are a few very simple guidelines for obtaining optimized HTML, XLS, or CSV documents when using the built-in JasperReports grid exporters:

1. Minimize the number of rows and columns in the grid-oriented formats (the number of "cuts"). To do this, align your report elements as often as you can, both on the horizontal and the vertical axes, and eliminate the space between elements.
2. Make sure report elements will not overlap when the report is generated. If two elements share a region, they cannot share the same cell in the resulting grid structure. Overlapping elements might lead to unexpected results.

### Related Documentation

JasperReports Tutorial

See Also:
  `JasperExportManager`, `JasperPrint`, `JRAbstractExporter`, `Exporter`, `ExporterConfiguration`, `ExporterInput`, `ExporterInputItem`, `ExporterOutput`, `ReportExportConfiguration`

© 2001-2010 Jaspersoft Corporation www.jaspersoft.com