Skip to main content

Unicode Support in JasperReports

Overview​

This guide explains how to configure JasperReports within the ADITO platform to fully support Unicode character sets in PDF exports. It covers the limitations of the default setup, how to create and validate a custom font extension, and what to configure in both the server and report designer.

Problem Analysis​

The issue with displaying country-specific characters is due to problems and a faulty configuration of the PDF exporter.
By default, the server, the designer, and the reports themselves include encodings and fonts that do not support Unicode character sets.

Default Export Configuration​

Property (Designer)Value
PDF EncodingCp1252
PDF Font NameHelvetica
PDF Embeddedfalse
note

All settings in the text fields of the reports are deprecated but are still picked up by the exporter if a proper font extension is not available.

Encoding Configuration​

The encoding Cp1252 does not support all characters and is identical to Windows Latin-1.
To use Unicode (UTF-8), Jasper encoding Identity-H (for horizontal Unicode characters) must be used.

note

This setting is inherited directly from the extension when using a font extension and does not need to be explicitly set in the designer or report fields.

Font Configuration​

The embedded font Helvetica is a default font shipped with Jasper and does not contain glyphs for all characters.
A different font can be specified for PDF export than the one given in Font Name.
The specified font must be compatible with iText and available in the server’s classpath at runtime.
Currently, no correct font extension is configured on the server. (The extension for OpenSans mentioned in the previous contribution is faulty and should not be used.)

note

This setting is also inherited automatically from the extension when using a font extension and does not need to be set explicitly.
The extension also ensures correct selection of the embedded bold and italic variants.

Font Embedding​

This setting ensures that the font used is embedded in the PDF.
If it is deactivated, the system displaying the text must provide the font itself (via OS or PDF viewer).

note

Although this setting is inherited via the font extension, Jasper documentation recommends explicitly enabling it.

Deprecated Settings​

The Unicode-specific settings via jasperreport.properties and equivalent designer settings mentioned in the previous article are no longer necessary and should not be used.
The reason is that the server does not adopt these settings for certain fields in the report, and the configuration alone only allows a single font for PDF export.

Unicode Configuration​

1. Creating a Font Extension​

A knowledge base article for creating a font extension for ADITO already exists:
Jasper – Fonts are incorrectly formatted during export

This article explains the steps necessary to create a font extension using the designer.
It also covers the problem of faulty font extension generation and what can be done to fix it.

It is important to check whether the font extension has been correctly created.
To do this, check in the JAR whether <![CDATA[...]]> entries still exist in the font.xml and whether the value for <pdfEmbedded> is set to true.
If this problem exists, the values must be adjusted manually so that no CDATA elements are present.

2. Validating the Font Configuration​

Invalid font.xml Example​

<fontFamily name="Verdana">
       <normal><![CDATA[fonts/verdana.ttf]]></normal>
       <bold><![CDATA[fonts/verdanab.ttf]]></bold>
       <italic><![CDATA[fonts/verdanai.ttf]]></italic>
       <boldItalic><![CDATA[fonts/verdanaz.ttf]]></boldItalic>
       <pdfEmbedded><![CDATA[false]]></pdfEmbedded>
</fontFamily>

Figure: Invalid font.xml with CDATA sections and PDF embedding disabled

Correct font.xml Example​

<fontFamily name="Verdana">
       <normal>fonts/verdana.ttf</normal>
       <bold>fonts/verdanab.ttf</bold>
       <italic>fonts/verdanai.ttf</italic>
       <boldItalic>fonts/verdanaz.ttf</boldItalic>
       <pdfEmbedded>true</pdfEmbedded>
</fontFamily>

Figure: Correct font.xml without CDATA and with PDF embedding enabled

3. Configuring the Report Template​

The settings must be applied in all affected components.
This means that in the report, each text field must be configured with the appropriate properties.

Property (Designer)ValueRequired
Font NameDejaVu Sans [Name of the font used from the extension]
PDF EncodingIdentity-H✅
PDF Font Name✅
PDF Embeddedtrue

4. Deploying the Font Extension to the Server​

The used font extension must be configured on the ADITO server. In ADITO Cloud, it must be available in each pod.
To load the font extension correctly from the server, place the .jar file in:

$ADITOHOME\lib\server\ext

Note: Use a meaningful file name for your font extension, e.g., custom-font-dejavusans.jar

The server or system must then be restarted once so that the extension is loaded into the classpath.

note

The official font extension from Jaspersoft was used and installed for testing:
JasperReports Font Extension

Verifying the Configuration​

After deployment, generate a test report using known Unicode characters (e.g., €, Ω, α, 中).
Open the resulting PDF on a system without the custom font installed. If characters display correctly, the font was embedded successfully.

Troubleshooting​

Common Issues​

  • Check whether the font extension was created correctly.
    If <![CDATA[...]]> entries still exist in font.xml inside the extension JAR, these must be removed.

Fallback Fix​

  • If a specific field causes issues, try using the deprecated properties:

    • Set PDF Encoding to Identity-H
    • Leave PDF Font Name empty (not <Default>)

    This works around issues where the server might fall back to default settings without Unicode support.

Further Reading​