Package net.sf.jasperreports.pdf

Class JRPdfExporter

java.lang.Object
net.sf.jasperreports.engine.JRAbstractExporter<PdfReportConfiguration,PdfExporterConfiguration,OutputStreamExporterOutput,JRPdfExporterContext>
net.sf.jasperreports.pdf.JRPdfExporter
All Implemented Interfaces:
Exporter<ExporterInput,PdfReportConfiguration,PdfExporterConfiguration,OutputStreamExporterOutput>
public class JRPdfExporter extends JRAbstractExporter<PdfReportConfiguration,PdfExporterConfiguration,OutputStreamExporterOutput,JRPdfExporterContext>
Exports a JasperReports document to PDF format. It has binary output type and exports the document to a free-form layout.

As its name indicates, PDF is a very precise and complex document format that ensures documents will look and print the same on all platforms. This is why the PDF exporter implemented by the JRPdfExporter class in JasperReports is one of the best exporters. The output it produces is almost of the same quality as that produced by the JRGraphics2DExporter, which is always the reference.

The JRPdfExporter implementation uses OpenPDF, which is a specialized PDF-generating library. PDF is a binary document format that allows absolute positioning of the elements inside a page, so the existing PDF exporter does not have the limitations of a grid exporter.

It also works very well in batch mode because it allows concatenation of multiple documents within the same PDF file, even if the files have different page sizes.

Font Mappings

Exporting to PDF requires mapping the fonts using three attributes: pdfFontName, pdfEncoding and isPdfEmbedded. Even though these three attributes are still supported in JRXML and the API, we recommend making the PDF font mappings at export time using font extensions.

When exporting documents to PDF, for each combination of the three fontName, isBold, and isItalic font attributes, there must be an equivalent combination of the PDF-related font attributes pdfFontName, pdfEncoding and isPdfEmbedded.

Equivalent combination means one that causes the text elements to be rendered exactly the same (or at least as closely as possible) in PDF and the built-in Graphics2D exporter, which is the reference.

In some cases, there is no font file available to use with the pdfFontName attribute in order to render bold and italic text exactly like the Graphics2D exporter renders it in AWT. Those fonts might only have a normal style variant and no variants for bold and italic. In such cases, the PDF exporter (the OpenPDF library, to be more precise) is able to simulate those styles by applying transformations to the normal font glyphs. The JRPdfExporter internally acquires the needed PDF font based on the font extension mechanism (see the getFont(Map, Locale, boolean) method.

Batch Mode Bookmarks

When several JasperPrint documents must be concatenated in the same PDF file by batch export, one can introduce PDF bookmarks in the resulting PDF document to mark the beginning of each individual document that was part of the initial document list.

These bookmarks have the same name as the original JasperPrint document as specified by the jasperPrint.getName() property. However, users can turn on and off the creation of those bookmarks by turning on or off the isCreatingBatchModeBookmarks() exporter configuration setting. The exporter does not create such bookmarks by default.

Encrypted PDF

In some cases, users might want to encrypt the PDF documents generated by JasperReports so that only authorized viewers can have access to those documents. There are five exporter configuration settings for this (see PdfExporterConfiguration):

PDF Version and Compression

Some applications require marking the generated files with a particular PDF specifications version. Related export configuration settings are the following (see PdfExporterConfiguration): Since version 1.5, the PDF format supports compression. By default, the PDF exporter in JasperReports does not create compressed PDF documents, but this feature can be turned on using the isCompressed() exporter configuration setting. Note that because compressed PDFs are available only since PDF version 1.5, the PDF version of the resulting document is set to 1.5 automatically if compression is turned on.

Word Wrap and Line Break Policy

By default, the PDF exporter does not guarantee that text with the same style properties will be rendered exactly as it is using AWT. The word wrap and line break policy is slightly different, and in some cases it might cause portions of text to disappear at the end of longer text paragraphs.

To make sure this does not happen, one can configure the PDF exporter to use the AWT word wrap and line break policy by setting the isForceLineBreakPolicy() exporter configuration setting to true. Note that this feature is not turned on by default, because it affects the exporter performance. This default behavior that applies in the absence of the mentioned export parameter can be controlled using the net.sf.jasperreports.export.pdf.force.linebreak.policy configuration property

JavaScript Actions

The PDF specifications provide a means for the automation of various processes, such as the automatic printing of the document when it is opened. PDF viewer applications are able to execute Acrobat JavaScript code that is embedded in the PDF and associated with different events.

JasperReports only allows inserting Acrobat JavaScript code. This code gets executed when the PDF document is opened in the viewer. This can be achieved using the getPdfJavaScript() configuration setting, which retrieve the Acrobat JavaScript source code. Note that Acrobat JavaScript is a programming language based on JavaScript. More details about this can be found in the OpenPDF documentation.

Metadata Information

PDF documents can store metadata information such as the author of the document, its title, and keywords. JasperReports exposes this feature of PDF through special exporter configuration settings available in the PdfExporterConfiguration class. They are all listed following:

Rendering SVG Using Shapes

The isForceSvgShapes() flag is used to force the rendering of SVG images using shapes on the PDF Graphics2D context. This allows fonts to be rendered as shapes, thus avoiding any font mapping issues that might cause Unicode text to not show up properly; however, it has the disadvantage of producing larger PDF files.

By default, the flag is set to true, mainly due to backward-compatibility reasons. To reduce PDF file size for documents containing SVG images such as charts, this flag should be set to false. However, in such a case, the accuracy of the text content rendered by the SVG element in PDF depends on the correct PDF font information being available in the SVG implementation itself.

In JasperReports, SVG elements are rendered using Renderable implementations, which are most likely subclasses of the AbstractRenderToImageDataRenderer class. SVG renderer implementations should be concerned only with implementing the

public void render(JasperReportsContext jasperReportsContext, Graphics2D grx, Rectangle2D rectangle)

method, which should contain all the code required for rendering the SVG on a Graphics2D context. Correct PDF font information means that the java.awt.Font objects used to draw text on the Graphics2D context should have PDF-related text attributes embedded so that when rendered on a PDF Graphics2D context, the exporter can make use of them. Embedding PDF-related text attributes into the SVG means using the following text attributes when creating java.awt.Font to render text in the SVG renderer implementation:

The built-in chart component in JasperReports hides this complexity of dealing with fonts in a SVG renderer by exposing to the end user the usual three PDF-specific font attributes (pdfFontName, pdfEncoding, and isPdfEmbedded) to be set along with the normal font attributes every time a font setting is made for the chart title, subtitle, chart legend, or axis. This feature can be controlled system-wide using the net.sf.jasperreports.export.pdf.force.svg.shapes configuration property. The isForceSvgShapes() export configuration setting overrides the configuration property value, if present.

Section 508 Compliance

PDF files can contain hidden tags that describe the structure of the document. Some of the tags are used by the automated reader tool that reads PDF documents aloud to people with disabilities.

The PDF tags feature of JasperReports allows adding hidden PDF tags to the files generated by the JasperReports PDF exporter. The resulting files comply with the requirements of the Section 508 of the U.S. Rehabilitation Act (http://www.section508.gov/).

Producing Tagged PDF Files

By default, the JasperReports exporter does not put any hidden structural tags inside its generated PDF files. In order to turn on the creation of hidden structural tags, any of the following can be used:

Setting the PDF File Language

When a full accessibility check is requested from Acrobat Professional, among the things it determines is whether the PDF file or the various pieces of content inside it have a language set. JasperReports allows setting the language for the entire content by doing any one of the following:

Alternate Text for Images

In tagged PDF files, image elements can be described in alternate text that is read by the automated reader. The text is specified using the hyperlinkTooltipExpression property of the image element in JRXML.

For more information about tagged PDF documents in JasperReports, please consult the JRPdfExporterTagHelper class.

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