See: Description
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.
|
JsonExporter.PrintBookmarkMixin | |
JsonExporterContext |
A context that represents information about an HTML export process.
|
ResetableExporterFilter | |
XmlResourceHandler |
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.
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.
ExporterOutput
setting to see whether it needs to
output the text content it produces to:
java.lang.StringBuffer
objectjava.io.Writer
objectjava.io.OutputStream
objectjava.io.File
objectjava.lang.String
file name
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.
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:
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.
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
JRPropertiesUtil
). 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
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.
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.
<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:
Copyright © 2016. All rights reserved.