JasperReports with Arabic

JasperReports is a great reporting library that can produce high quality pixel-perfect reports. Unfortunately, creating reports in Arabic language can be bit tricky if you need to produce a high quality report, especially in PDF format.
This article is actually a remake of a previous article I made on my blog long ago, but here I add more updates, in addition to discussing how to produce Arabic reports using Jasper report API.

So, What is the problem?

When trying to create PDF reports in Arabic, the most common problems I met were :

• Empty Pages: You create your report on JasperSoft Studio, you select a nice font that supports Arabic like Arial, it runs greate in the preview. Then you try producing a PDF file and get a blank page.

• No Hindi numerals:
  
  The numerals used in English language - like 1,2,3, .. - that we all use and love are called "Arabic numerals". However Arabic and some other eastern languages use other numerals called "Hindi numerals" : (١, ٢, ٣ , ...) - It is a bit confusing, I Know 😅 ! -. While many organizations do tolerate using Arabic numerals in their Arabic reports, others simply don't, and they may consider it a hard requirement for audit reasons. And generally, using numerals of a different language makes the report looks more sloppy and less professional.

• "It works on my machine" scenario

You solve the above problems on your machine, and the report work fine, just for them to appear again either during runtime, or on other developers machines. Whether you are generating the reports in your application, Jasper Server or Jasper Reports API, the runtime environment will need some configuration.

So, let's fix these one-by-one!

Problem 1: Empty Pages PDF Reports

This is not a problem specific to Arabic itself, but using a non-latin language makes it more common. The reason is simple:

                                  The font you used is not available at runtime!  

This may seem confusing at first, especially when you run the report on JasperSoft Studio itself. I mean it was running just fine with the java preview, right ?!

Well, for PDF generation, the font must be available in the java runtime classpath. If you are not familiar with java, a classpath is basically collection of locations for additional resources and libraries that your program need while running. Typically it can be a directory or a java archive (Jar).

The confusion actually comes from the fonts list in Jasper studio.

If look at it, you will find a separator line between some fonts at the top. Fonts above the line are in the classpath of JasperSoft studio - which is a java application itself -, therefore, they can be used for PDF generation. Other fonts are the fonts available on your system, these will work in the java preview, or when exporting to formats like docx or xlsx on the same machine.

In addition to the PDF problem, relying on system fonts can break the report generation on other systems if they don't have the same fonts. For example if a developer works on a windows machine, and used the font Arial which comes pre-installed with windows, the report won't run as expected on a linux machine, because they don't have Arial installed.

The simple solution is to use a font already existing in the classpath. JasperReports actually provides a library with some default fonts called jasperreports fonts, these are the ones you find by default above the separator line in the font list. While some of these fonts supports Arabic like Dejavu Sans, none of them looks great. Official documents in Arabic usually use Arial, or maybe Times New Roman, and users will usually consider Dejavu Sans visually inferior to them. But if your users are Ok with it, just use the default fonts, it will save even more effort on configuring the runtime because the default fonts are usually included in your report server. If your application generates the report then you will just need to adds the fonts dependency.

<dependency>
    <groupId>net.sf.jasperreports</groupId>
    <artifactId>jasperreports-fonts</artifactId>
    <version>${version.jasperreports}</version>
</dependency>

Ok, but what if we need a more professionally looking report ? You will need to add your fonts to the classpath.

Luckily, this is a simple process, JasperSoft Studio already provides a tool for quickly doing this :

• First, you will need to get your font files, usually TTF.
• From the main menu open Window -> Preferences -> JasperSoft Studio -> Fonts -> Add
• This will open a dialog for adding the font where you provide the font file for each mode : Normal, Bold, Italic. You should at least provide a file for Normal, the rest are extra.
• A critical part here will be checking Embed this font in PDF document and setting PDF encoding to Identity-H.
• Press finish

After finishing, your font should now appear above the separator line in the font list, indicating it is now "installed" by JasperSoft Studio. Now, if you used this font for your text elements, they should now appear in the PDF file!

The good news is: You now have a PDf report that is not empty, bad news is : It probably won't work elsewhere!

This is because you installed the font to the IDE only, but you need to make your font accessible to other runtimes as well. We will discuss this later with problem 3.

Problem 2: No Hindi numerals

Congradulations! You now have a readable PDF report!

But your prefectionist eye quickly catches something unsettling : All numbers and dates are in English :)

As discussed before, many organizations will have no problem with that, but others will have higher standards, assuming you are from the later, let's try to fix this. The fastest fix will be to change the report default locale to Arabic, and it is fairly simple to do it:

• Select your report in the overview tab, or just click on an empty space outside the design
• In Properties pane select Advanced tab -> Misc -> The button on right of Edit Properties
• This will open the report properties window. Search for net.sf.jasperreports.default.locale and select one of the Arabic locale's.

If you can't change the locale for some reason, the other option will be using a FormatFactory.
FormatFactory is an interface in jasper reports that defines methods for doing a custom formatting on numeral fields and dates. This should be used if the default pattern-based formatting is not enough. In our case we use jasperreports-arabic library, which provides simple utils for supporting Arabic in jasper reports. The library should be available on maven central and the github repository, after downloading the jar file you should :

• Copy it to your JasperSoft Studio project, then right-click -> Build Path -> Add to Build Path. This will add the library to the project classpath and make it available for reports.
• Select your report in the overview tab, or just click on an empty space outside the design
• In Properties your will find Format Factory field, press the the button next to it.
• This will open a dialog for selecting classes, search with keyword Hindi, the class HindiNumeralsFormatFactory should appear in the results. Select it and press OK.

Regardless of the method, if you run your report now, you will notice that numbers and dates are shown in arabic with hindi numerals.

But wait a second! It seems that there are still english numbers in the title of this report!
Well, that's because changing the locale and FormatFactory works only on TextFields whose expression result is either numeric (int, long, double , ..) or java.util.Date. The title here is actually a string which has a number inside it.

If the string is static, you may actually just replace the Arabic numerals with hindi ones manually, but more often the string is dynamic and is being fetched from some database. So, what can we do?

To fix that problems, we need to process the string first to replace all Arabic numerals with Hindi numerals. Luckily jasperreports-arabic already provides a utility method for that : io.github.deathwaiting.jasperreports.arabic.HindiNumeralsUtils.toHindiNumerals(). Apply the method to the string in the expression editor, then try running the report.

After using the method in the Expression editor and running, you can see that the title now is rendered with Hindi Numerals.

You will find that this method is commonly used through out the report, so, to avoid using the fully qualified name of the class, you can import the class to the report instead :

• In Properties your will find Imports field, press the the button next to it.
• In the dialog, Add the class io.github.deathwaiting.jasperreports.arabic.HindiNumeralsUtils.
• Now you can use HindiNumeralsUtils.toHindiNumerals() directly.

Problem 3: "It works on my machine!"

"It works on my machine!" is a famous quote, said by many many programmers, young and old, regardless of the technology or the era. We don't want to say it :).

In the last sections, we solved the problems of missing fonts that led to blank PDF's, and we solved the problem of Hindi numerals mainly by using a third party library. In both cases we basically added a new dependency to our report, and for the report to work, those dependencies should be available and in the classpath of other environments that will run the report. So, the focus of this section will be about how to provide the used dependencies in :

• Your reports project. So JasperSoft Studio can run the report on other machines.
• Your report server. We will talk about Jasper report API and Jasper Server.
• Your java application. In case the reports are generated by the application directly.

So, lets start by the first step.

Exporting fonts

If you are not familiar with java, jar stands for Java Archive, which are basically just zip archives containing java classes and other resources. Jar files are the main way to package libraries and applications in the java ecosystem, and even the java virtual machine can run applications packaged as jar directly.
To be able to run the fonts you "installed" on JasperStudio on other environments, you will need to export them as jar files, then import those jar files in other environments. That's the main idea of this section.

To export the fonts:

• From the main menu open Window -> Preferences -> JasperSoft Studio -> Fonts
• Select the font you want to export from the list, then press Export, and select the location of the jar

That's it 🙂. We will then use those font jars in other environments. But each environment will need different method.

Preparing your reports project

First, let me tell you some well-known "Secret": Tibco didn't actually build JasperSoft Studio from the ground up!

JasperSoft Studio is actually a plugin on the well known java IDE eclipse. This makes sense, as jasperreports is basically a java library. But more importantly, because JasperSoft Studio is essentially a java IDE, you get other features out of the box: like project dependencies management, git repositories support, navigation for jar files, class search , etc.

What this has to do with the topic? Well, basically, the reports projects you create on JasperSoft Studio are nothing but java projects, and those can have jar files saved into them, and can be configured to add those jars to the classpath, your font jars are not an exception.

In more simple terms, you copy your font jars into the report project, right-click -> Build Path -> Add to Build Path. And by just doing this, these fonts will be added to the project itself, not just JaserSoft Studio. If the same project is opened on another machine, you should find these fonts automatically added to the top of the font list! Your team members don't need to install them from TTF files again. This also means if your team works on a shared report repository, you can share certain fonts to be used by the team to standardize the looks of your reports.

The same goes for third-party libraries like jasperreports-arabic. Just copy the jar and add it to the build bath and share it on the repository, and it will be available to the team.

This is actually a crucial step to unify the development environment for the whole team.

Preparing Jasper Reports API

If you are using Jasper report API as your report server, then the good news is you don't need to do much as long as your reports repository, along with the jars, is provided as the report root directory for the server.

Jasper Report API will add all the jar files inside the report root directory and its sub-directories to the classpath. This means all your font jars and third-party libraries will be loaded on startup and be available for the reports. But be aware of adding multiple versions of the same library/font, as only one version will be loaded, better to set a central directory for all jars to avoid duplication.

Preparing Jasper Server

Jasper Server on the other hand has to be configured manually to add each jar file and make it available to the reports. But the good news is, JasperSoft Studio has a very good integration with Jasper Server. If you connect to the server using the studio, you can copy paste the jar files as resources for each report.

The good point her, is that each report can probably have its own version of the jar file if needed - AFAIK, didn't try it before -. Bad news is, you will get a lot of duplicated jar files.

A good solution will be to make a central directory for the common jar files, and add a link to the jar in each report, this will give access to the reports to use the same jar. In JasperSoft Studio this can be done by:
in Repository explorer pane -> copy the jar file -> right click on the report unit -> paste as link.
You will notice that an icon for the jar file appeared under the report unit.

Preparing your application

I won't go in details here, because there are many build tools in the java ecosystem and each project have its own thing. But if you are a java developer, you will know what to do with your jar files :). In the end you just need to add them to your project somehow.

That's will be the end of this tutorial, I hope it helps you out with your next project to make outstanding reports 🙂 !
While this may look dull for us developers, but a good looking report can impress your end users and give a first impression of a high quality system for your potential clients, and of course : first impressions last .... hopefully 🙂.

Lastly, please feel free to add your thoughts and suggestions on the topic, Peace!