Package net.sf.jasperreports.engine.export

Class JRGraphics2DExporter

java.lang.Object
net.sf.jasperreports.engine.JRAbstractExporter<Graphics2DReportConfiguration,Graphics2DExporterConfiguration,Graphics2DExporterOutput,JRGraphics2DExporterContext>
net.sf.jasperreports.engine.export.JRGraphics2DExporter
All Implemented Interfaces:
Exporter<ExporterInput,Graphics2DReportConfiguration,Graphics2DExporterConfiguration,Graphics2DExporterOutput>
public class JRGraphics2DExporter extends JRAbstractExporter<Graphics2DReportConfiguration,Graphics2DExporterConfiguration,Graphics2DExporterOutput,JRGraphics2DExporterContext>
Exports a JasperReports document to a Graphics2D object.

JasperReports relies on AWT for text measurements and all sorts of layout calculations during report filling, so documents created using AWT will certainly look perfect when rendered with AWT on a java.awt.Graphics2D context. For this reason, the JRGraphics2DExporter is the perfect exporter. The output it produces is considered to be the reference in terms of layout capabilities and element styling.

Generally speaking, the document quality produced by all the other exporters is only an approximation of the perfect output that the Graphics2D exporter can produce. As its name indicates, this exporter is special because it does not produce files or send character or binary data to an output stream. Instead, its only target for rendering the content of a page is a java.awt.Graphics2D object. This exporter is also special because it can export only one page at a time.

This exporter is used by the built-in Swing viewer to render the content of each page, and it is also used when printing the documents. The documents are printed page by page, and the exporter is invoked to draw each document page on the graphic context associated with the selected printer job.

Because we are relying on the same code (same exporter) when viewing the documents using the built-in viewer and when printing them, JasperReports is a perfect WYSIWYG tool. The document quality on paper is the same as on the screen.

In terms of exporter input, note that this exporter does not work in batch mode. If a java.util.List of JasperPrint documents is supplied to it through a SimpleExporterInput instance, the exporter considers only the first one for exporting and ignores all the others.

Furthermore, this exporter can export only a single page at a time. The index of the page to be exported can be set using either the getStartPageIndex() exporter configuration setting or the getPageIndex(). Note that if present, getPageIndex() overrides the value of getStartPageIndex(). Therefore, this exporter actually exports only the first page from the specified page range, no matter how the page range is specified.

As already mentioned, this exporter needs a target java.awt.Graphics2D object onto which to render the specified page. This Graphics2D object can be set using the special exporter output setting getGraphics2D(). If this setting is not present, the exporter will throw an exception signaling to the caller program that no output target was specified for the export process.

By default, the exporter renders the content of the page at normal proportions. However, it can also render it at different proportions if needed. For instance, when used inside the Swing viewer, the Graphics2D exporter must render the page using the user-defined zoom ratio. To set the zoom ratio for the exporter, supply a java.lang.Float value ranging from 0 to 1 as the value for the getZoomRatio() export configuration setting.

The Graphics2D exporter is also used when printing directly from Java. The Java Print Service exporter relies on the Graphics2D exporter and delegates to it all the rendering that needs to be performed on the printer's graphic context. Some of the existing JVM implementations have problems related to the huge size of the printer spool jobs that are created even for small documents. To avoid this, a bug fix was introduced in the Graphics2D exporter to minimize the impact of this problem and reduce the size of print spool jobs, while preserving document quality when printing. However, the bug fix itself is not perfect, and users might experience problems when printing bidirectional writing texts such as Arabic and Hebrew.

This is why the special isMinimizePrinterJobSize() export configuration setting was introduced, along with a configuration property called net.sf.jasperreports.export.graphics2d.min.job.size, to allow users to turn on and off this rendering optimization, depending on their actual needs. The configuration property value is used only in the absence of the export configuration setting.

Author:
Teodor Danciu (teodord@users.sourceforge.net)
See Also: