Build your customized jar for JasperReports Server

In this wiki page we'll explain 2 different approaches to customize JasperReports Server.

Plug in your customized logic: create your own classes , pack them in a jar and add it to JasperReports Server. Then configure the xml applicationContext files to use your customized logic. This is the best approach, but in some case this is not possible (we'll see when)
Building a patch using Maven: Customize existent class(es) and rebuild JasperReports server patched jar(s)

Plug in your customized logic

Search xml files for the class configuration

JasperReports Server leverages the Spring MVC framework to give you all the flexibility to change the implementation of key feature...
As example if you want to change the behavior of any class the first check you have to perform is:
search the class name in all the .xml files in jasperserver app. If you are using Tomcat the folder should be: [TOMCAT_ROOT]/webapps/jasperserver/WEB-INF

I personally use Notepad++ in Windows to perform this kind of search:

Search -> Find in files...
Find what: then add the class you whish to customize
Filters: *.xml
Directory: [TOMCAT_ROOT]/webapps/jasperserver/WEB-INF
and click Find All

Let's say we want to customize the FTPUtil class.

We search for it
Here the results, we found the configuration!

If you get hits of this in the applicationContext*.xml then you are in good shape.

You can just create your own class and configure it in the xml. Remember to add your new jar (with the class inside) in the lib folder of JasperReports Server

If you don't find a proper result here have a look at Building a Patch Using Maven of this wiki article.

Create your Customized class

If you want just to customize part of the logic a Best Practice is to extend the original jaspersoft class so you can know for sure what is the logic you added (as well it will be easier to update in later versions).
After you created your class you can build it and export it as jar.
Use your favourite IDE, as example Eclipse or IntelliJ. Just configure a new project and add in the build path the required jars from JasperReports Server.
In a hurry? just add all jars from these locations:

[TOMCAT_ROOT]/webapps/jasperserver/WEB-INF/lib
[TOMCAT_ROOT]/lib

Now you can replace the name in the applicationContext*.xml with your class qualified name com.jaspersoft.my.customization.MyClass
Add your jar to this folder

[TOMCAT_ROOT]/webapps/jasperserver/WEB-INF/lib

restart tomcat and test it out.

Building a Patch Using Maven

But what if the class you want to customize is not defined in an xml file but just referenced from the source code itself?
Then the process is a bit trickier but no worries: we'll get there together.

A sample of this usecase is if you want to customize one of our web services. The Job Webservice as example.
Let's say we want to modify the way we produce email notification. Browsing the source we realize the class we whish to customize is ReportJobMailNotification , so let's search for it in xml...

The only result regard something with a similar name, but not our class.
PersistentReportJobMailNotification.hbm.xml

We can say that this class is not defined in any xml file then. What to do now? We'll have to patch the existent class, and create a patched version of the jar that contains it. Then replace the original jar with our patched version.
Easy right? We'll do this using Maven.

If you are not confident with Maven , google "learn maven" and become a guru first!
Just kidding, I am no expert neither, I can't thank our Build team enough for their guidance and help.
So if you don't feel confident with Maven, this is totally fine for now.

Pre-requisites

Maven installed (version 3.0.4 minimum). You can check your version with command mvn -version
Access to JasperReports Server Artifactory
For Pro version only: access to Support Portal with your company credential, download the Maven Repository from Downloads > JasperReports Server > Source

Easy sample

Find the jar containing the class you want to patch

Browse our Artifactory website. Go to the section Archive Search Here you can search for a class and it will tell you in which repo/jar it is (super handy!).
This process applies also if you need to change classes inside multiple jars, but your customized classes are not dependent one from the other. I'll cover this use case later. So let's say we want to patch this class: ReportJobMailNotification

Search it:

It's included in this jar: jasperserver-api-engine-x.x.x.jar (replace x with version you are going to patch).
So what we want is to create a patched version of this jar, to replace it in JasperReports Server lib folder. Let's do it!

Create a maven patch project

We'll use maven for this so let's create a simple maven project (find it attached)
Unzip it where you prefer.
Let's have a look at the structure:

src: here the source file with your modification. Only the ones that you are modifying
target: empty - it will be filled by the building process by maven
pom.xml : this file contain all the configuration - here we define what we want to patch and how.

The pom.xml

The most important properties to understand are:

groupId, artifactId, version : we can find these info in artifactory website, just click in the "Show in Tree" button that appears when you hover on the Artifact Path (for the version you're interested in, e.g. 6.0.1):
Then you should see this:
Notice that we have groupId, artifactId and version in 2 place at the beginning: as property of the main project and inside the dependencies. Just the version is different! This is telling maven that we are using the original jar as dependency, and our own should be tagged with the version 6.0.1-MySample
repositories: these repos will be used by maven to resolve dependencies defined in our project. Dependencies are defined by our maven project, and in cascading order from the project we are using as dependency (jasperserver-api-engine) ... and so on. Just use the repos I defined in the samples, this should be enough in most of usecases
artifactItem: If you scroll to the end of pom.xml you'll find the other important piece of configuration. Here we define which files we want to filter from the original jar. So basically we have to define the classes we are going to customize :)

That's it! Now we can..

Build the project using maven

So first of all make sure you have it installed. Open a command line (cmd in windows) and type:

mvn -version

If this command works we can proceed to the next step. Go to the directory where you extracted the repository and type:

cd [YOUR_PATH]sample1_jasperserver-api-engine
mvn package --batch-mode > output-log.txt

When the process finishes, open the target folder. You should see the jar patched with your versionName at the end (MySample) and ready to be copied in [TOMCAT_ROOT]/webapps/jasperserver/WEB-INF/lib . Remember to remove the original one!

Advanced Sample

In this sample we cover how to build 2 projects patching JasperReports Server jars, when the projects have cross referecenses
We'll use the Easy sample as starting point so if you didn't completed that please do so first :)
Earlier we customized the class ReportJobMailNotification.
Now let's say we want to change the class PersistentReportJobMailNotification . If our change is independent from the change we made in the class ReportJobMailNotification we can use the same approach as earlier.
Otherwise we'll need something more complex because we'll have to reference our customized jar instead of the original one (in the jaspersoft repositories).
Download the complex sample to check the new configuration

The pom.xml – what changes

The pom.xml of jasperserver-api-engine-impl contain a little difference compared to the jasperserver-api-engine project.

the definition of the dependency on the original jar contains an exclusion for the jar we customized. Dependency on jasperserver-api-engine-impl , exclude jasperserver-api-engine-impl .
If you are wondering why the dependency on jasperserver-api-engine-impl should bring in the jasperserver-api-engine project the answer is: maven. The cool thing about Maven is that it will resolve all the dependency in cascade.
Now that we excluded the original jasperserver-api-engine jar we have to add an additional dependency on the customized jar (we'll find it in the target folder of the jasperserver-api-engine project after the build).

Multiple Projects Build

In the last sample we created a new project. Having 2 projects introduced some questionable configurations:

All the pom.xml contain the same list of dependencies. What if we have a lot of projects and we decide to add another repository? Would be great to have this list centralized
Having 2 project with this structure means we have to build the projects separately, with 2 commands, even in a certain order as they have dependencies one on the other.
The version is specified in all the pom.xml, but in our case they all refer to the same project, and version.

Luckily there is another approach that can solve all these limitations. Let's centralize some stuff in a new root project! (download the 3rd sample from this wiki attachment). Now the structure of folders look a bit different. There is a generic pom.xml in the root folder. Let's have a look at it

The pom.xml

This centralized pom.xml contains:

an artifact id for the central project
the version for the project (removed from internal project's pom.xml)
the list of modules (projects)
the maven-compiler-plugin (removed from internal project's pom.xml)
the list of repositories (removed from internal project's pom.xml)

Build the project using maven

The build of a single project is easier. You just need to run one command in the root folder (where the main pom.xml is - in this tutorial we call it Sample3 folder for sample sake)
browse the directory where you extracted the repositories

cd [YOUR_PATH]Sample3
mvn install -B > output-log.txt

When the process finish open the target folder of the different projects, you should see the jar patched, with your versionName at the end (MySample) and ready to be copied to [TOMCAT_ROOT]/webapps/jasperserver/WEB-INF/lib. Remember to remove the original one!
Reapeat this action for all the projects

JasperReports Server PRO patched jar Build

The last sample is about building the source code of the Professional version of JasperReports Server. In order to do that you need a Professional license and access to the Support Portal.
Other than that the process is very similar. We added an additional project in the sample , patching the jasperserver-api-externalAuth project

Download the Maven Repository for Professional version

Login to the Support Portal with your credential. If you have troubles ask your sales representative.
Go In downloads Section , then Jasper Reports Server
Jump to Source section
Download the JasperReports Server Maven Repository
Unzip it somewhere in your local drive. We'll reference to this path as [LOCAL_JRS_REPO] from now on.

In the centralized pom there is a new repository, the only difference with the previous ones is that is defined with a local path:

<!-- local -->
<repository>
    <id>localrepository</id>
    <url>file://C:/Jaspersoft/Source/jasperreports-server-6.0.1-repo/repository</url>
</repository>

Additional Info

Batch Mode and output.txt

In all the command describe in this page you find a property --batch-mode or -B . Both stands for Batch Mode. Batch mode is useful when you want to export the result of the maven build to a file. It produce a less noisy logging, easier to read.
The command >output.txt will redirect the output to a file. This is not mandatorory and you can remove this. If you remove the outputFile you can also remove the batch mode described in the above bullet.
Without the batchMode and output file definition the previous commands will look like:
```
mvn install
mvn package
```