Skip to main content

Unicode Support (Special Characters)

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.

Prerequisites​

Before configuring Unicode support in JasperReports for ADITO, it's important to understand the limitations of the default export configuration.

Understand the Default JasperReports Configuration​

These defaults typically appear across the report definition, the Designer, and the server-side PDF export:

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

All settings in report text fields are deprecated, but the exporter may still use them if no valid font extension is available.

To support Unicode characters in PDF exports, you must replace the default encoding and font settings. The encoding Cp1252 covers only Windows Latin-1 characters, so it is not sufficient for many language-specific or non-Latin characters. Use Jasper encoding Identity-H for horizontal Unicode text.

The default PDF font Helvetica does not contain glyphs for all characters. Use a compatible font that is available in the server classpath at runtime, typically via a font extension.

Although font embedding is inherited via the font extension, Jasper documentation recommends explicitly enabling it to ensure the font is included in the exported PDF.

Deprecated Settings​

The Unicode-specific settings via jasperreports.properties and equivalent Designer settings mentioned in earlier articles are no longer necessary and should not be used.
The reason is that the server does not reliably apply these settings to every report field, and this approach effectively limits PDF export to a single font.

Step-by-Step Configuration Guide​

Step 1: Create a Font Extension​

Use the JasperReports Designer to create a new font extension for ADITO. Refer to Font Extension

This article guides you through creating a font extension and addresses common issues with faulty font extension generation.

If an older or bundled extension is already present, do not assume it is valid. Re-check the generated font.xml before using it in production.

Step 2: Validate Your Font Configuration​

Verify that your font.xml inside the font extension JAR does not contain any <![CDATA[...]]> elements and that the <pdfEmbedded> value is set to true. If CDATA sections exist or embedding is disabled, edit the file manually.

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

Step 3: Apply Font Settings to Report Fields​

Configure every affected text field in your report with the following properties to ensure proper Unicode support:

Property (Designer)ValueRequired
Font NameName from the font extension, for example DejaVu Sans✅
PDF EncodingIdentity-H✅
PDF Font NameLeave empty✅
PDF Embeddedtrue✅
note

Do not leave PDF Font Name at <Default> when configuring the field explicitly. Leave the field empty so Jasper does not fall back to the default PDF font.

If the font extension is configured correctly, it also controls the correct bold and italic variants for PDF export.

Step 4: Deploy the Font Extension on the Server​

Place the font extension .jar file in the following directory on the ADITO server (or each pod in ADITO Cloud):

$ADITOHOME\lib\server\ext

Use a meaningful file name, for example, custom-font-dejavusans.jar. Restart the server or system to load the extension into the classpath.

note

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

Step 5: Test the Output​

Generate a test report containing 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 and Workarounds​

Common Issues​

  • Ensure the font extension was created correctly. Remove any <![CDATA[...]]> entries from font.xml inside the extension JAR.
  • Ensure <pdfEmbedded> is set to true in the extension.
  • Ensure the extension JAR is deployed on the target ADITO server or on every relevant pod in ADITO Cloud.
  • Ensure the report field uses the exact font family name exposed by the extension.

Fallback Fix​

  • If a specific field still causes issues even though a font extension is present, try the deprecated field properties as a targeted workaround:

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

    This can help in cases where the server still falls back to default settings without Unicode support for individual fields.

Further Reading​