Fonts & Internationalization

A PDF file can describe text in two ways. It can name one of the fourteen standard fonts (Helvetica, Times, Courier and a few others), which every viewer is expected to supply, or it can carry a font program inside the file, usually a subset that holds only the glyphs the document uses. The first way gives small files but only the Latin characters of the standard encodings, and different viewers may draw the glyphs slightly differently. The second way gives an identical result everywhere and is the only way to print Greek, Cyrillic, or any character outside the old Latin encodings. It is also required by the archival standard, see PDF Standards & Conformance, and the file-level mechanics (font dictionaries, subsets, ToUnicode maps) are described in PDF File Structure. The same topic from the iText side is in Fonts & Unicode.

For a PDF produced by JasperReports the decision is made per text element through three values: the font program to use, the PDF encoding, and whether to embed. The jasperreports-pdf module delegates the drawing to the OpenPDF library, so these three values are what the exporter hands to OpenPDF. A TrueType font written with the encoding Identity-H and embedded is the combination that works for any Unicode text; this is what the DejaVu families in jasperreports-fonts declare, and it is what the run below shows.

A text element selects its font with a few attributes. In v7 JRXML they are written directly on the <element kind="textField"> or <element kind="staticText"> element, or inherited from a style.

Inheritance works as for every other attribute: an element inherits from its style, and the style from the default style (default="true") declared in the report. A report with no default style and no explicit font uses the property net.sf.jasperreports.default.font.name, whose value in the shipped defaults of 7.0.8 is SansSerif.

The legacy route is worth recognizing because older tutorials and templates are full of it. Before font extensions existed, a template declared a named reportFont element, and each text element carried pdfFontName, pdfEncoding and isPdfEmbedded, sometimes pointing at a font file on disk or at an Acrobat Asian font pack for Chinese, Japanese or Korean text. Those books and posts are outdated on three counts. The reportFont element is gone from the v7 format in favour of styles. The boolean attribute is now pdfEmbedded. And the official sample documentation says that the pdfEncoding and pdfEmbedded attributes on the element are deprecated in favour of the same two settings inside the font family of an extension, which is the route the rest of this page follows. (The old attributes were also run against 7.0.8: an element with pdfFontName pointing at a TrueType file on the classpath, pdfEncoding="Identity-H" and pdfEmbedded="true" still produced an embedded font, so old templates keep working once converted to v7 syntax. It is a compatibility path, not one to copy.)

The reference for all of this is the fonts sample.

A font extension is the way to make fonts part of the application instead of part of the machine. It is a classpath resource set made of three things: the TrueType files, an XML file describing font families, and a jasperreports_extension.properties file at the root of the classpath that registers the XML. The engine finds every jasperreports_extension.properties on the classpath, so a font extension can be a separate jar, or just resources of the application.

The jasperreports-fonts artifact is the extension that JasperReports itself ships. It contains the DejaVu fonts, in the families DejaVu Sans, DejaVu Sans Condensed, DejaVu Serif, DejaVu Serif Condensed and DejaVu Sans Mono (read from the XML file of the 7.0.8 jar), together with the logical names SansSerif, Serif and Monospaced, which are declared only to give the HTML exporter a CSS font stack, and its registration file. Adding the dependency is enough to make fontName="DejaVu Sans" work in any template:

Its registration file, read from the 7.0.8 jar, is two lines:

The first line names the factory class that turns font-family XML files into registry entries. The second says "here is one XML file", and its last segment (dejavu) is only a unique name, so each extension uses a different one. A family declared there looks like this (the DejaVu Sans entry of the jar, shortened):

Each part has a job:

Fonts that the application owns follow the same recipe. The Bookshelf company font (here the four DejaVu Serif files from the same jar stand in for it, so the example runs without a licence question) is registered in three files:

The TrueType files go in src/main/resources/fonts/ttf/. In the run, a template using fontName="Bookshelf Serif" produced a PDF whose font list contained an embedded DejaVuSerif subset, so the extension was found with nothing but the classpath. Two practical points follow from how the registration works. The resource names in the XML are classpath resource names, with no leading slash. And because every extension uses the same file name, jasperreports_extension.properties, a build that merges several jars into one (a shaded jar, for example) must merge those files instead of keeping one of them, or the other extensions silently disappear; a Spring Boot executable jar keeps its dependency jars nested and does not have this problem.

The official walkthrough, including a second extension based on the open-source Lobster Two font and a tool that prints the fonts.xml of all installed extensions, is in the fonts sample (section "Font Extensions").

Always check the licence of a font before bundling it in a deployable. The DejaVu fonts are distributed under a permissive free licence, which is why JasperReports can bundle them. A corporate or purchased font usually has terms about embedding in documents and about redistribution inside an application, and the answer is in its licence file, not in this page.

When a template does not say, the engine falls back on properties. The relevant ones and their values in the shipped default.jasperreports.properties of 7.0.8 (read from the jar) are:

A property can be set on a SimpleJasperReportsContext, in a jasperreports.properties file on the classpath, or on a report or element as a property, and the reference page lists where each applies: net.sf.jasperreports.default.pdf.embedded and net.sf.jasperreports.awt.ignore.missing.font.

The defaults are the reason a template written with the logical font SansSerif produces a PDF that is not self-contained. Three runs against 7.0.8 show the consequences (the text was extracted back from the PDF with PDFBox):

The last row is worth understanding: the embedding flag asks for a font file to be embedded, but Helvetica is a standard font with no file behind it, so the flag changes nothing for it. default.pdf.embedded=true helps only when the font that reaches the exporter is a real TrueType file. The robust rule is to avoid the logical font names in templates meant for PDF, give every text element (usually through the default style) a family from an extension, and set the encoding and the embedding in that family.

The old route of choosing a different single-byte encoding is still possible: an element with pdfFontName="Helvetica" and pdfEncoding="Cp1253" printed the Greek text correctly in the run, without embedding. That depends on the viewer having a suitable Greek font to substitute and on the text being limited to that one code page, so it is no substitute for embedding, and it does not help once a document mixes scripts.

A template that names a font nobody provides fails by default. With net.sf.jasperreports.awt.ignore.missing.font at its default of false, filling the report raised a JRFontNotFoundException, with the message that the font is not available to the JVM, and logged a warning with a pointer to the Javadoc of that exception. With the property set to true the fill continues, a warning is logged, the missing font is replaced by Helvetica, and the PDF contained a non-embedded Helvetica and none of the Greek text. Both outcomes were observed in the run. The failing behaviour is the better one for a service: it turns a silent font substitution into an error that shows up in the first test, and true is a choice for a report that must be produced whatever happens.

The same reasoning is why fonts should come from an extension on any machine that is not a developer laptop. A font that is only "installed" is a property of the machine, and a build server, a Kubernetes node image and a developer’s Mac have different fonts. Two points apply to containers:

An integration test that fills and exports every template with the production classpath, and then checks the PDF for embedded fonts the way the next section does, catches both problems before deployment. How to run such tests is covered in Testing & Performance.

Report text is Unicode inside the engine, and the PDF can carry any of it as long as a font with the glyphs is embedded. Three rules cover most cases:

Output formats that are text (CSV, HTML, XML) have their own encoding, set at export time with net.sf.jasperreports.export.character.encoding, which defaults to UTF-8. It does not apply to PDF, where the font encoding is the one discussed above. The unicode sample shows a template with Greek, Cyrillic, Chinese, Arabic and Hebrew text written as \uXXXX escapes in expressions, which is also a way to keep a JRXML pure ASCII.

JasperReports separates the text that changes with the language from the layout. The texts live in java.util.ResourceBundle files, the template refers to them by key, and the engine chooses the right file from the locale of the fill. The mechanism has four parts.