net.sf.jasperreports.export.package-info Maven / Gradle / Ivy
Show all versions of jasperreports Show documentation
/*
* 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 exporter input, exporter output and exporter configurations
*
*
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 {@link net.sf.jasperreports.export.Exporter#exportReport() 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 {@link net.sf.jasperreports.engine.JRAbstractExporter#setExporterInput(ExporterInput) setExporterInput(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
* {@link net.sf.jasperreports.engine.JRAbstractExporter#setExporterOutput(ExporterOutput) 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.
*
* Export Configuration Settings
* Other export configuration settings can be communicated to exporters using the
* public void {@link net.sf.jasperreports.engine.JRAbstractExporter#setConfiguration(ExporterConfiguration) setConfiguration(C configuration)}
and
* public void {@link net.sf.jasperreports.engine.JRAbstractExporter#setConfiguration(ReportExportConfiguration) setConfiguration(RC configuration)}
* {@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
*
*
*
* Related Documentation
* JasperReports Tutorial
*
* @see net.sf.jasperreports.engine.JasperPrint
* @see net.sf.jasperreports.engine.JRAbstractExporter
*/
package net.sf.jasperreports.export;