All Downloads are FREE. Search and download functionalities are using the official Maven repository.

net.sf.jasperreports.engine.export.package-info Maven / Gradle / Ivy

Go to download

Free Java Reporting Library

There is a newer version: 6.21.2
Show newest version
/*
 * JasperReports - Free Java Reporting Library.
 * Copyright (C) 2001 - 2019 TIBCO Software Inc. All rights reserved.
 * http://www.jaspersoft.com
 *
 * Unless you have purchased a commercial license agreement from Jaspersoft,
 * the following license terms apply:
 *
 * This program is part of JasperReports.
 *
 * JasperReports is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * JasperReports is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with JasperReports. If not, see .
 */
/**
 * 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: 
 * {@link net.sf.jasperreports.engine.JasperExportManager 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 {@link net.sf.jasperreports.engine.JasperPrint 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 {@link net.sf.jasperreports.engine.JasperExportManager 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 {@link net.sf.jasperreports.export.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 
 * {@link net.sf.jasperreports.export.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 
 * {@link net.sf.jasperreports.engine.JasperPrint} 
 * objects that must be exported to some other document format, along with other optional 
 * export settings. These 
 * {@link net.sf.jasperreports.engine.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 {@link net.sf.jasperreports.engine.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 {@link net.sf.jasperreports.export.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 {@link net.sf.jasperreports.export.ExporterInputItem} objects. Each 
 * {@link net.sf.jasperreports.export.ExporterInputItem} object in the list contains a single 
 * {@link net.sf.jasperreports.engine.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 
 * {@link net.sf.jasperreports.export.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 
 * {@link net.sf.jasperreports.engine.JRAbstractExporter} parent class. The exporterOutput 
 * argument must be an instance of {@link net.sf.jasperreports.export.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 
 * {@link net.sf.jasperreports.engine.JRAbstractExporter} parent class. The first method accepts 
 * an {@link net.sf.jasperreports.export.ExporterConfiguration} argument and applies settings per exporter. 
 * The second one accepts a {@link net.sf.jasperreports.export.ReportExportConfiguration} and applies 
 * settings per each exported report in a batch export.
 * 

 * Below are some examples of report configuration settings available in the 
 * {@link net.sf.jasperreports.export.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 
 * {@link net.sf.jasperreports.engine.JasperPrint} document or a list with several such generated documents. Exporting 
 * multiple {@link net.sf.jasperreports.engine.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 {@link net.sf.jasperreports.engine.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 {@link net.sf.jasperreports.engine.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 {@link net.sf.jasperreports.engine.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 
 * {@link net.sf.jasperreports.export.ReportExportConfiguration}  
 * class) should be used to pass a filter object, which would be an instance of a class that 
 * implements the {@link net.sf.jasperreports.engine.export.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 
 * {@link net.sf.jasperreports.engine.JRAbstractExporter#PROPERTY_DEFAULT_FILTER_FACTORY 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 {@link net.sf.jasperreports.engine.export.DefaultExporterFilterFactory#PROPERTY_EXPORTER_FILTER_FACTORY_PREFIX net.sf.jasperreports.engine.export.filter.factory.<factory_name>} has 
 * to be included in the jasperreports.properties file (or set at runtime via 
 * {@link net.sf.jasperreports.engine.JRPropertiesUtil JRPropertiesUtil}). The factory name is an arbitrary suffix, and the property value should 
 * be the name of a class that implements 
 * {@link net.sf.jasperreports.engine.export.ExporterFilterFactory 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 
 * {@link net.sf.jasperreports.engine.export.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 {@link net.sf.jasperreports.engine.export.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 
 * {@link net.sf.jasperreports.engine.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. 
 * 
  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.
    3. 
 * 

 * 
Related Documentation

 * JasperReports Tutorial
 * 
 * @see net.sf.jasperreports.engine.JasperExportManager
 * @see net.sf.jasperreports.engine.JasperPrint
 * @see net.sf.jasperreports.engine.JRAbstractExporter
 * @see net.sf.jasperreports.export.Exporter
 * @see net.sf.jasperreports.export.ExporterConfiguration
 * @see net.sf.jasperreports.export.ExporterInput
 * @see net.sf.jasperreports.export.ExporterInputItem
 * @see net.sf.jasperreports.export.ExporterOutput
 * @see net.sf.jasperreports.export.ReportExportConfiguration
 */
package net.sf.jasperreports.engine.export;




© 2015 - 2024 Weber Informatics LLC | Privacy Policy