Jaspersoft Studio Expression Editor: how to extend it and contribute your own functions : part 2

Overview:

If you haven't already, please read the introduction to the new Expression Editor in the first part of this tutorial. In this page, we will cover some of the internal workings of the Functions Library. We will explain how it is implemented and how a developer can extend it in order to contribute his own functions in the environment.

Implementation Details

Since their introduction, the expression functions APIs have been refactored. When first introduced they were a standalone project and were added to the Jaspersoft Studio distribution as jars. About that, we previously created a tutorial that is right now deprecated and outdated.

Starting from the JasperReports version 5.1.2 they were moved to the JasperReports library. The main classes are part of the core library but the additional ones are contributed as separate jar produced from the jasperreports/demo/functions folder.

All implementation details and additional examples are good covered in the official JasperReports documentation, therefore give a look at the following reference page before proceed. It will help you in having a good understanding of what we will cover in the next section.

Creating a Functions Library skeleton

In order to make the developer's life more easy, we created a dedicated wizard in Jaspersoft Studio which has the purpose of preparing the base skeleton for having a new functions library ready to use.

There are some requirements in order to proceed:

• be sure to have in your JasperReport project Build-Path the "JasperReports Library".

   

  

   

• be sure to have a Source Folder in your JasperReports project. If you don't have it create a new one, and if necessary unlock the Java Capabilities from the Jaspersoft Studio preferences.

   

  

   

  

After having verified these few requirements, you can proceed by invoking the wizard File > New > Other... > Jaspersoft Studio > Functions Library.

In the first page you will have to enter some basic information:

1. the Library Name should be a class-name like identifier and it will be used to generate the class file containing your functions;
2. the Source folder is the chosen Build-Path entry;
3. the Package is the Java package where most of the generated output files will be placed;
4. the Category Label will be the text shown in the Expression Editor categories list;
5. the Category Description is an additional details regarding the category
6. the Category Class is automatically suggested based on the chosen label;
7. the automatic creation of sample methods and an example report;

The second (optional) page allows the user to define more additional categories to which the library functions will belong to.

After completing the wizard (click on Finish button) you will end-up having the skeleton that is useful to start implementing your own functions. The sample methods serve only as a quick and simple example. Again, for all the details please refer to the official JasperReports documentation as exposed in the above section.

If you double click on a text-field in order to bring-up the expression editor you can see how the sample functions are presented.

Additional information

When using the wizard to create the initial skeleton for your functions library, the bundle file "jasperreports_messages.properties" is created on the same level of the class containing the methods (Functions class). However it is possible to customize the bundle location to be used for the translations of the parameter and function names and descriptions. 

In order to do so you will need to specify at class level the FunctionMessagesBundle annotation. See the example below:

This can be useful also in order to prevent possible collisions caused by different Function/Category classes in different jars but in the same packages.

Also using the default package (this is a discouraged practice) can lead to similar issues. The key/value pairs will not be correctly retrieved and you will end up having an entry in the Error Log view similar to the one shown in the following screenshot:

As said, specifying a different bundle location will help to overcome this problem. The value for the FunctionMessagesBundle annotation must be the basename of the resource, including the package.

This code line @FunctionMessagesBundle("com.test.another.jasperreports_messages") will specify to use the jaspereports_messages.properties file located in the com.test.another package.

Conclusions

As you can see the creation of new functions library was made more easy introducing this wizard. All the foundation files will be ready just after one simple step. Moreover having the ability to edit Java classes and properties files directly inside your Jaspersoft Studio installation, allows you to quickly test your functions. You can develop without the need to generate every time the jar package to be included on the Build-Path. You can modify your library and proceed with internationalization support, test and once all is done export the jar file using the dedicated standard wizard.