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​

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

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.

To support Unicode characters in PDF exports, you must replace the default encoding and font settings. The encoding Cp1252 supports only Windows Latin-1 characters, so you need to use Jasper encoding Identity-H for horizontal Unicode characters.

The embedded font Helvetica does not contain glyphs for all characters. Specify a compatible font available in the server’s 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 fonts are embedded in the PDF.

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.

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.

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 each text field in your report with the following properties to ensure proper Unicode support:

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

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.

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 workaround addresses cases where the server falls back to default settings without Unicode support.

Further Reading​