DEV Community: ahmed galal

JasperReports with Arabic

ahmed galal — Sat, 28 Sep 2024 17:21:49 +0000

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!

JasperReports in microservices

ahmed galal — Tue, 24 Sep 2024 21:01:12 +0000

Introduction

Microservices has almost became the defacto architecture in many current projects, and while you may agree or disagree with the need for microservices, the reality is it is a very common architecture now, especially in modern enterprise applications.
And in many such applications we are usually faced with the need for providing reports to the user, these can be mainly web-based reports like the ones shown in dashboards, or they can be pixel-perfect reports, i.e reports that are expected to be printed by users; bank statements, invoices, salary slips, are all examples of such reports. While using paper-based reports seems obsolete, in many enterprises and government workflows, it is a hard requirement.

The web-based reports are already done via the frontend technology of the application, which will generate some html for showing the data in the end. The web-based reports aims to be interactive, with reactive design for different screen sizes, and it is mainly optimized to run on browsers.
But in the case of printable reports, we usually aim to provide them as PDF files, and they are designed to be printed on certain paper size like A4. The design objectives are different, and so are the optimizations and required features, for example there is usually the need for page breaks, page header and footers with sections like page numbers, page background images, etc.
This means the tools and design priorities and optimizations are different, and usually conflicting. While we can try to generate the report as a simple html page and let the user print it, it is not that simple, and the results are usually sub-optimal, and because browser print functionality handle basic cases, any more complex requirement can lead to a road block.

So, the best option is usually to generate pixel-perfect reports with tools dedicated for that, and there are many tools already available; Birt, Pentaho, Jasper Reports, Crystal reports are all example of such tools. Some tools provides SDK's and libraries that you can use in your application directly, others rely on a dedicated report server for generating the reports. Like everything in technology, each option comes with its pros and cons, but when it comes to printable reports, I believe Jasper reports are on the top of the list.

Why Jasper reports?

Jasper reports is one of the oldest and most-mature report generation libraries in the java eco-system, having several great features such as :

Opensource

It seems at first that money shouldn't be a problem for enterprises, yet, for teams working in enterprises, opensource solutions are usually on the top of the list, while the money can be available for paid solutions, another main factor is ... bearucracy 🙂.
To use a properitary solution, you need to go through a bearucratic limbo in a big organizations, depending on the organization , the process may take months of back-and-forth meetings and procedures, and for technical teamleaders to start such a quest, there have to be some good reasons.
On the otherhand opensource solutions can be used on day 1, as long as the license allows it, this means quick and cheap adoption.
Jasper reports is mainly a java library , which is opensource, therefore, teams can start using it at once, or at least try it in some pilot project. The same goes for the community version of other jasper reports tools like their report designer : Jasper studio, and their report server.

Actively developed

A usual problem with opensource projects is developers abandoning the project. With lack of motivated developers or resources, development can halt after sometime. This can be a problem in enterprise applications because they usually have long lifetime, so, you need tools with long lifetime as well. It is not rare to have a system working for a decade in a big organization, because the business it serves actually doesn't change that much through out the decade.
Jasper reports ecosystem is developed by Tibco, a well-know company, and for more than a decade now, the project has bee active and kicking. Tibco profit model here is to provide opensource version of their tools, while providing additional premium features for a price, which seems to work fine for them till now.

Mature and Feature rich

Jasper reports is almost 2 decades old, so, we can consider it a mature library 🙂. It already provides a variaty of features covering many use cases. Bugs are rare - for me at least -, and it is well optimized.
Reports can have a variaty of datasources, from database queries, to xml and json files. The library supports generating charts, sub-reports, can use custom fonts, and can generate reports as PDF, docx, xlsx, and other formats.
The tooling is also mature. Their WYSIWYG report designer is more than a decade old and is based on eclipse IDE, it is feature rich and simple to use, and it can even have additional features using eclipse plugins like managing git repositories for reports.

Challenges using jasper reports in microservices

So, where is the problem? If we need to use Jasper reports in our microservice application we will just use the library in our services or add the report server to the cluster, right?

Well, it is not always that simple:

Being a java library means it is accessible mainly by applications written in java or other JVM languages. If you have the services built using .Net for example, this option is out.
It is a heavy weight library, adding a lot of dependencies and like 50 MB - IIRC - to the application jar file. Adding a heavy library like that to generate a report or two in a single service is usually an overkill, especially if one of the dependencies may mess with something else.
Generating reports on the microservice itself can be problematic if the reports are complex. If your service has many users who generate reports, then the report generation can eat from the overall performance.
In many cases, the solution is to simply use Jasper report server to handle the report generation for all services, it is battle-proven solution, and will work with any technology via its REST API. The problem is, Jasper report server is not microservices friendly.
Jasper report server is an entire report management system, it comes with its own web report designer, its own dashboard for managing reports, users, access management, database connections, etc. It was meant to run as a standalone central monotlithic solution. It needs its own database to run all this, and needs manual configuration to add the reports to the server.
It was made in the era of the monolith, not microservices. So, if the system needs a lighweight scalable report server just to generate arbitrary reports and nothing else, Jasper report server was not built for that.

Tibco has realized that as well, and therefore they introduced JasperReports IO, a jasper report server that mainly provides a REST API for generating reports.
Unfortunately it is not opensource 🙂.

So, we are now in square one, if we have microservices and need a lightweight opensource report server, what should we use?

I met the same problem with a recent project. We had a simple dotnet service and we needed a good reporting opensource solution. While dotnet had reporting solutions, most were not opensource, and I was familiar with jasper reports, as I already worked with it for several years to produce high quality pixel-perfect reports in Arabic.
The application was deployed as a docker image, so, it made sense to deploy a report server to handle the reports generation in the same cluster.
But even for such a simple scenario, JasperReport server was an overkill. I just needed a lightweight REST API that takes the report as url, generate it and return it back.

As JasperReport IO was licensed, and its features seemed to be an overkill as well, my developer brain decided it is time to just do it myself 🙂.

Introducing Jasper report API !

While this may seem like a shameless promotion ..... well, it is 😅, but there isn't really much to promote here anyway.

Using Jasper reports API

This is a service that provides a simple API for generating arbitrary reports. Reports design files - jasper's JRXML files - are placed in a directory accessible to the service, and to generate a PDF report we call it like this

http://localhost:8080/report/emp-report.pdf

If we need a docx version of it we call

http://localhost:8080/report/emp-report.docx

Current supported extensions are : pdf, docx, xlsx,html, csv

Report parameters can be provided as Query parameters, similar to JasperReports server.

http://localhost:8080/report/emp-report.pdf?dep_id=1&month=11

The service is just a simple spring boot 3 application, so, it can have all the spring boot goodies: Spring security, spring data, optimized docker images, support for distributed tracing, metrics, logging.

The service will run the reports against the configured datasource for the spring application, so, it currently works against a single database only, and while it can be authenticated using spring security, there is no internal access management for each report, that's out of the scope of simple report service.

Fiddling with the API

The easiest way is to run the service as a docker image. This command will run the service with security disabled, and mounts the reports directory at ./test-reports. In this example, the service connects to a postgres database to run the reports against it.

docker run -it --tty --rm\
 -v ./test-reports:/var/reports\
 -e SPRING_PROFILES_ACTIVE=security-off\
 -e SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/postgres\
 -e SPRING_DATASOURCE_USERNAME=postgres\
 -e SPRING_DATASOURCE_PASSWORD=postgres\
 -p 8080:8080\
  ahmedgalalfathy/jasper-reports-api:0.1

After that you can generate a report by calling

http://localhost:8080/report/<report name>.<extension>

If you need some ready examples to fiddle with, feel free to clone the examples repository. It comes with a complete testing environment with sample reports and database.

If you ran into some problems using this, or have anything in your mind about it , your feedback is very welcomed 👍.

If you found that useful, give it a thumb up and a star in github, so I can put it in my CV before the next great global depression.

Thanks for reading all this and have a great day!