This thread got me thinking about filtering on multiple fields in a MongoDB query. The author of the original question attempted to use the $and operator which was introduced in MongoDB 2.0. But that’s not needed for simple queries that filter on multiple fields. I created a simple report to show the idea.

Filtering on multiple fields at once in MongoDB

The report is available here if you want to play with it. Here’s the sample data I used:

db.shiraz.save( { "ServiceType" : "sms", "ServiceHealthState" : "ok", "DocumentID" : "11" } )
db.shiraz.save( { "ServiceType" : "sms", "ServiceHealthState" : "ok", "DocumentID" : "12" } )
db.shiraz.save( { "ServiceType" : "sms", "ServiceHealthState" : "ko", "DocumentID" : "13" } )
db.shiraz.save( { "ServiceType" : "jms", "ServiceHealthState" : "critical", "DocumentID" : "21" } )
db.shiraz.save( { "ServiceType" : "jms", "ServiceHealthState" : "critical", "DocumentID" : "22" } )

If you haven’t used (or heard of!) the Jaspersoft connector for MongoDB, then start with this article.

Standard Answer

Normally JasperReports Server is installed in a corporate environment. You already have an email server, and configuring scheduled reports to get sent out using this email server is simple. The settings are well documented in “JasperReports-Server-Install-Guide.pdf”.

Make-my-life-easy Answer

But what about a simple evaluation situation? You don’t have a corporate email server or you don’t have simple access to it. Shouldn’t it be easy to configure JasperReports Server to use GMail or some other publicly available email server? Yes. It’s possible, and it’s easy. But it’s sometimes hard to track down all of the little details as these email threads can attest:

• What are the setting values in order to use Gmail
• jasperserver 3.7 mail schedule using gmail smtp
• From variable isn’t working?
• how can send reports by emails ??

If you read through all of those threads and read GMail support information, you can indeed find all of the information that you need. But for those that don’t want to wade through the threads, here are the complete details for setting up JasperReports Server to send out email using GMail.

First, edit …/WEB-INF/js.quartz.properties. Use these settings:

report.scheduler.web.deployment.uri=http://localhost/jasperserver-pro
report.scheduler.mail.sender.host=smtp.gmail.com
report.scheduler.mail.sender.username=me@gmail.com
report.scheduler.mail.sender.password=mypassword
report.scheduler.mail.sender.from=me@gmail.com
report.scheduler.mail.sender.protocol=smtp
report.scheduler.mail.sender.port=587

Of course you’ll need to set your own information appropriately. But the GMail server and port need to be as I have indicated.

Second, edit …/WEB-INF/applicationContext-report-scheduling.xml

original version:

<property name="javaMailProperties">
    <props>
        <prop key="mail.smtp.auth">false</prop>
    </props>
</property>

modified version:

<property name="javaMailProperties">
    <props>
        <prop key="mail.smtp.auth">true</prop>  <!--as indicated in JasperReports-Server-Install-Guide.pdf)-->
        <prop key="mail.smtp.starttls.enable">true</prop>  <!--not indicated in JasperReports-Server-Install-Guide.pdf-->
    </props>
</property>

Restart your application, and that’s it. Two quick changes are all that are needed. You should be able to get reports emailed out to your users in under 5 minutes.

Questions

As noted in one of the email threads listed above, the value that you set for ”report.scheduler.mail.sender.from” seems to get ignored. I suppose that’s probably a GMail security issue. They don’t allow you to use me@gmail.com to authenticate but then claim that the email came from you@gmail.com. That’s just speculation; maybe someone can comment and confirm. When you are using a corporate email server under your own control it should be possible to set that value to, for example, no-reply@mydomain.com.

Improvements

Perhaps JasperReports Server should be smart enough to figure out that authentication ought to be used based on the fact that you provide a password in js.quartz.properties. I’m not sure if that really would work or not. Ideally we should come up with a mechanism to set javaMailProperties in the properties file. Maybe mail.smtp.starttls.enable ought to be in the documentation. If you want to see any of these changes, then log a bug on the tracker.

Error Reference

If you don’t configure applicationContext-report-scheduling.xml correctly, then you will get an error. I have included the error that I got below in case it helps folks with the same error to track down the solution.

2011-09-27 23:18:55,301 ERROR ReportExecutionJob,quartzScheduler_Worker-0:309 - The job error notification was not completed. An error occurred while sending it.
org.springframework.mail.MailSendException; nested exception details (1) are:
Failed message 1:
com.sun.mail.smtp.SMTPSendFailedException: 530 5.7.0 Must issue a STARTTLS command first. bw6sm18434073qab.16
        at com.sun.mail.smtp.SMTPTransport.issueSendCommand(SMTPTransport.java:1388)
        at com.sun.mail.smtp.SMTPTransport.mailFrom(SMTPTransport.java:959)
        at com.sun.mail.smtp.SMTPTransport.sendMessage(SMTPTransport.java:583)
        at org.springframework.mail.javamail.JavaMailSenderImpl.doSend(JavaMailSenderImpl.java:403)
        at org.springframework.mail.javamail.JavaMailSenderImpl.send(JavaMailSenderImpl.java:342)
        at org.springframework.mail.javamail.JavaMailSenderImpl.send(JavaMailSenderImpl.java:338)
        at com.jaspersoft.jasperserver.api.engine.scheduling.quartz.ReportExecutionJob.sendMailNotification(ReportExecutionJob.java:1264)
        at com.jaspersoft.jasperserver.api.engine.scheduling.quartz.ReportExecutionJob.executeAndSendReport(ReportExecutionJob.java:446)
        at com.jaspersoft.jasperserver.api.engine.scheduling.quartz.ReportExecutionJob.execute(ReportExecutionJob.java:232)
        at org.quartz.core.JobRunShell.run(JobRunShell.java:195)
        at org.quartz.simpl.SimpleThreadPool$WorkerThread.run(SimpleThreadPool.java:520)

Background

You need some software before you can make use of these ideas:

• MongoDB
• iReport or JasperReports Server
• Jaspersoft MongoDB connector

You should probably start by reading my previous articles before reading this one:

• Simple MongoDB reporting
• More MongoDB reporting

Date queries in MongoDB reports

This idea actually applies to all types of Java objects, not just Dates. But most data types likes Strings and simple numbers get converted magically to what you probably want. Dates are probably the most common object that is too complex to be handled by this automatic conversion process.

Let’s take what is perhaps the simplest possible example. I want a query that will return only the documents for which a specified field, status_date, is later than some date. It’s a simple JSON-style query in the MongoDbQuery language of the Jaspersoft MongoDB connector:

{
  'collectionName' : 'active_users',
  'findQuery' : { 'status_date' : {'$gte':$P{StartDate}} }
}

It’s easy enough to understand even if it’s a bit verbose with curly braces in curly braces in curly braces. My report has a java.util.Date parameter which gets passed into the query. In earlier versions of the connector—as pointed out by one astute reader—there was no way to do this. Attempts to embed syntax like this into the query resulted in JSON parsing exceptions: { ‘status_date’ : {‘$gte’: new ISODate(’2011-09-15T00:00:00.000Z’)’ } }

Sample Data

In case you’re relatively new to MongoDB, like me, it can smooth your path to testing to have a sample data set and sample report that are known to work well together. You can insert a these few documents on the MongoDB shell and then use the sample report listed below to get something that ought to work with minimal effort. Then you’re ready to start writing your own reports.

The first document is listed on many lines to make it easier to parse it by eye to see what’s in it. The second two documents are compressed onto a single line. The final “find” command is useful to confirm that the earlier inserts worked as expected.

db.active_users.save(
{
"status_date" : ISODate("2011-09-01T07:48:58Z"),
"id" : "123",
"events" : {
"ACHIEVEMENT_Minor" : 1,
"ACHIEVEMENT_Major" : 1,
"ACHIEVEMENT_Ultimate" : 0
},
"install_source" : {
"detail" : "campaign - Free iPad",
"vt1" : "email",
"vt2" : "facebook"
},
"rev" : {
"net_total" : 700
}
}
)
db.active_users.save({"status_date" : ISODate("2011-09-09T22:17:27Z"),"id" : "456","events" : {"ACHIEVEMENT_Minor" : 1,},"install_source" : {"detail" : "campaign - Free iPad","vt1" : "email","vt2" : "facebook"},"rev" : {"net_total" : 450}})
d = new Date()
db.active_users.save({"status_date" : d,"id" : "789","events" : {"ACHIEVEMENT_Minor" : 1,},"install_source" : {"detail" : "campaign - Like us on Facebook","vt1" : "email","vt2" : "facebook"},"rev" : {"net_total" : 222}})
db.active_users.find()

Sample Report

Reminder

The idea for this article (and for this new feature to the Jaspersoft MongoDB Connector) came from a reader comment. Please let me know when you run into questions, but for general questions about the MongoDB connector please post to the JasperReports Server forum instead of posting a comment here. That’s a better location for asking and answering questions.

Before you can do interesting reporting, you need to do simple reporting. You have to walk before you can run. Please start with the article Simple Reporting on MongoDB. That article explains where to get the MongoDB connector for iReport and JasperReports Server. When you have completed that, then read this article more advanced and more interesting reporting techniques.

Simple Filters

Let’s start with a simple hard-coded filter.

{
  'collectionName' : 'accounts',
  'findQuery' : { 'name' : 'M & Y Takemura Communications, Ltd'  }
}

Filtering on a single value makes sense when that value is a complex document. There could be lots of information in that document to create a report. To make this truly interesting though, we need this query to be parameterized. So our first truly realistic sample query is the following:

{
  'collectionName' : 'accounts',
  'findQuery' : { 'name' : '$P{CUSTOMER_NAME}'  }
}

Field Selection and Dot Notation

Documents in MongoDB can be big. The queries above will return every field in the document. When this is not appropriate, it’s easy to create a query to return only the fields that you need.

Imagine the case where we have lots of users and we want a report showing which users had logged certain events. There could be lots and lots of events, but there’s only one particular event that I care about in this report. Rather than return the complete document for each user we instead return only the fields we care about.

{
  'collectionName': 'active_users',
  'findFields' : { 'id':1, 'date':1, 'events.ACHIEVEMENT_Minor':1 }
}

Enter this query into iReport’s query field, and then iReport is able to execute the query and return only the fields we’re interested in.

The query editor makes it easy to test query syntax and to see query results

We could then combine this with a filter if we only want certain users returned.

{
  'collectionName': 'active_users',
  'findFields' : { 'id':1, 'date':1, 'events.ACHIEVEMENT_Minor':1 },
  'findQuery' : { 'events.ACHIEVEMENT_Major' : 1 }
}

Joins!

Joins? MongoDB doesn’t support joins. In general your data should be modeled so that you don’t need joins. If you need them, then perhaps you should be using a traditional RDBMS instead of MongoDB. But what about simple joins that are required in some types of reports? Subreports can be used in JasperReports to effectively join two collections together.

Imagine a collection that stores summary data by country and a collection that stores customers. I want to query the country collection to find my top countries for some time period and then query my customers collection to find the top customers in the those countries.

It’s simple in JasperReports. We create a query in the top level report to return the countries that I want. Then for each country I run a subreport that returns the customers from that country.  Here’s a simple version.

Parent query:

{ ‘collectionName’:'countries’ }

The subreport query finds all accounts that are in that country and whose name starts with “B”. (It’s a silly example. Why would I want companies that start with “B”? But I wanted to show the syntax for Regular Expressions in queries.)

{
	'collectionName':'accounts',
	'findFields':{'name':1,'phone_office':1,'billing_address_city':1,'billing_address_street':1,'billing_address_country':1},
	'sort':{'billing_address_city':1,'name':1},
	'findQueryRegEx':{'billing_address_country':'/$P{AccountCountry}/','name':'/^B /'}
}

The above set of two queries gives me exactly what I want. It has the drawback of running “N + 1″ queries. By that I mean that runs the subreport query once for each country. In some cases that could be bad. In these cases it could be even better to use the “IN” syntax so that I only need to run each query once.

I can use the same parent query. But rather than pass the countries one at a time to the subreport we can pass the complete list of countries as a Collection. Then the subreport can run a single query to get all of the accounts that I want. The working reports are attached below, but here’s the query to show the idea.

{
	'collectionName':'accounts',
	'findFields':{'name':1,'phone_office':1,'billing_address_city':1,'billing_address_street':1,'billing_address_country':1},
	'sort':{'billing_address_country':1,'billing_address_city':1,'name':1},
	'findQuery':{ 'billing_address_country': {'$in':$P{AccountCountryCollection}} }
}

Summary

MongoDB has more flexibility than most of today’s Big Data databases in its query syntax. That’s one thing that made it attractive as a reporting target for Jaspersoft. Hopefully this article gives a good idea of some of the possibilities that exist for reporting directly against a MongoDB data source.

Sample reports using all of the above queries are available here.

Big Data databases are being adopted with rapidly increasing frequency. Opinions on NoSQL and Hadoop are being generated nearly as quickly as the data going into these databases. This article doesn’t contribute a viewpoint on any of that.

I’m assuming that you already have data in MongoDB. You probably had a great reason for using MongoDB, and reporting on that data was probably not a top consideration. But now that the data is there, what options exist for reporting and analysis?

Option 1: Dump it to a traditional RDBMS

This technique is not exciting or sexy, but it’s ideal in many cases. Create ETL jobs to get the data out of MongoDB and into PostgreSQL, MySQL, Vertica, Teradata, Netezza, or whatever good old relational database you prefer. From there you have a plethora of tools at your disposal for slicing and dicing the data or for designing reports. Having acknowledged the utility of this technique for many requirements… I will proceed to ignore it.

Option 2: Connect your BI solution directly to MongoDB

You’ve got a lot of data in MongoDB. That’s why it’s called “Mongo” after all; that’s why the whole field is referred to as “Big Data”. So there are plenty of downsides to pulling all of the data back out and putting it somewhere else.

If requirements are simple enough, you can code it up yourself. Write some PHP scripts to create reports. The MongoDB PHP driver makes it easy enough to connect and get data.

If your requirements are a bit more extensive, then the build-it-yourself method has important drawbacks. A simple tabular report can be created quickly. But what happens when your users like it and then say, “Great, now can I get the same thing in PDF?” Or soon they’ll ask for charting. Or you’ll find you need to implement security on who can see which reports. There are plenty of benefits to using standard reporting and analysis tools for solving problems like these. The biggest barrier to this is that most Big Data databases (including MongoDB) are not accessible via standard methods like JDBC. That means traditional Business Intelligence (BI) tools can’t get directly to Big Data data sources.

Jaspersoft has addressed this problem for a number of Big Data databases including MongoDB. It offers connectors to a variety of datasources. Read the marketing fluff. See the connectors.

OK, that’s enough background. The rest of the article below this point is a hands-on guide to creating reports in iReport against a MongoDB data source.

Prerequisites

• iReport installed
• MongoDB installed
• MongoDB connector downloaded

First Report

The installation of the connector is simple. It’s covered in the documentation included with the connector. After installing the plugin and restarting iReport, you’re ready to define your connection. The connection needs to know the host, port, and database that you’ll be connecting to. This is expressed in a JDBC-like url shown below.

Simple JDBC-like connection URL

Now you’re ready to create your first report. Choose File -> New to launch the report wizard. Choose the Coffee template (well… choose any template besides the blank ones). Then click “Launch Report Wizard”. When you reach the step of the wizard that requires a Query in the MongoDbQuery language you have reached your first real test. MongoDB doesn’t have a query language. What should you enter here?

For your first report, use the simplest possible query:

{ ‘collectionName’ : ‘myCollection’ }

Simple MongoDB Query

Click “Next”. iReport then runs your query. It connects to MongoDB, reads each document from the specified collection, finds each field and its datatype, and presents these fields to you. Documents in MongoDB do not necessarily have the same fields. The list of fields presented is the union of all fields found for each document.

The available fields are automatically discovered. Choose the ones you want.

If you’re dealing with a very large collection, then you perhaps don’t want to wait for iReport to read through every record. You can tell it to read only the first 100 documents like this:

{ ‘collectionName’ : ‘myCollection’,
‘rowsToProcess’ : 100 }

Note: the field ‘rowsToProcess’ is read only by iReport’s Fields Provider. That means when you run the report it will still process all documents from the collection.

Finish the report wizard and then preview the report. You have just created a report against a MongoDB database without having to first dump the data into MySQL. Woo hoo!

Your first report showing data from MongoDB should be working now!

Useful Reports

Creating the first report was easy. But let’s face it: a report that includes every record from a collection is not really interesting. It’s bound to be a humongous report. Let’s add filters to get genuinely useful reports.

Continue to my article Cool Reporting on MongoDB for some advanced techniques.

You can download the report from this article (and all of the reports from the second article) here.

Recently someone asked my if it was possible to create Ad Hoc reports in JasperReports Server (JRS) using a Hibernate data source. I was quick to say yes. I have heard of projects at Jaspersoft where that was done, and in general one of the great strengths of Jaspersoft is that custom data sources are easy to implement. (Sidenote: that flexibility is one reason that lots of big data datasources were so easy to implement.) But when I investigated the precise steps around how to setup Ad Hoc reporting with Hibernate, I found that things were not well documented. I will log bugs and enhancement requests to create new samples and document existing samples better. But for an immediate solution I thought it would be useful to document this for future reference.

JasperReports and Hibernate

Can JasperReports (JR) work with Hibernate? This one is almost too easy. Yes. Not only can it work with hibernate, but there’s even a sample that ships with JR showing it in action. Here’s how to get it:

• Head to JasperForge.org, then to the JR project, then click “Download JasperReports Now“, then sign-in or join jasperforge, then get re-directed to the downloads hosted on sourceforge.net, then choose the 4.0.1 JR release to correspond to the current [as of 1 July 2011] JasperReports Server 4.1 release (not a typo: JRS 4.1 uses JR 4.0.1).
• Or click here.

Then choose jasperreports-4.0.1-project.tar.gz or jasperreports-4.0.1-project.zip.

Download either of the "project" files to get the JR binaries and source and, most importantly, the samples.

After unzipping the archive you’ll find the sample database and the sample hibernate example:

.../jasperreports-4.0.1/demo/hsqldb
.../jasperreports-4.0.1/demo/samples/hibernate

To start the sample database you can simply run “ant” in the directory “hsqldb”.
To execute the sample reports you can simply run “ant” in the directory “hibernate”. You’ll to open a command line to do this. It will look something like this:

Run "ant" to launch the sample database.

Then you’ll find the generated reports here:

.../jasperreports-4.0.1/demo/samples/hibernate/build/reports

There are lots more details to investigate. You can see the sample HQL queries in the .jrxml files. You can see the hibernate cfg files and hbm files, etc. But to just get it working, it takes only those two commands. Here’s the sample HQL query from one of the provided reports:

select address as address, document.id as documentId, document.total as documentTotal
from Address as address join address.documents as document
where city not in ($P{CityFilter})
order by address.city, address.lastName, address.firstName, address.id

iReport and Hibernate

Having seen that JasperReports works with Hibernate, the next practical step is to start creating your own reports. The best place to do this is in iReport. (Coming soon: the best place to do this will be Jaspersoft Studio!)

Open the iReport Preferences window to the tab “Query Executers” and you can see that “hql” is supported as a query language by default. This is a nice start. But to be able to execute a query you need your Hibernate classes and configuration files in iReport’s classpath. To set the classpath go to the menu Tools → Options… (on Mac: ⌘,). I wanted to open and execute the reports that came with the JR sample shown above, so I went to the tab “Classpath” and added this directory:

…/jasperreports-4.0.1/demo/samples/hibernate/build/classes

Next define a Hibernate connection, and you’re all set. The connection has only a single parameter to set; for this sample be sure to use Hibernate Annotations. Click the button “Test” to make sure all is well. Make a puzzled expression when it prompts you for a password and just click OK (isn’t the login info included in the file hibernate.cfg.xml?). Make a questioning noise when it prompts you for a password again (Huh? What possible reason could it have for prompting twice?) and click OK again without entering a password. Smile when the connection is successful.

A Hibernate connection has only one parameter.

Now you can open and run the reports from the hibernate sample project. I started with “HibernateQueryReport.jrxml”. As a convenience to the user, it would be nice if the three parameters in this report had default values. They don’t. As a convenience to the reader, I have suggested reasonable values below.

ReportTitle: My Hibernate Report

CityFilter: Lexington,Indianapolis,Jackson

OrderClause: id

Make a derisive snort when iReport prompts again for the password. Just click OK. Roll your eyes when iReport prompts yet again for a password. (Surely someone should log a bug in the iReport tracker for this. I haven’t.) And voilà: a report using HQL has been automatically translated into SQL and executed against the sample Hypersonic database. This is great! Those JR guys didn’t shirk their duties either: it’s not just a trivial query populating a tabular report. This is a reasonably interesting HQL query including parameters, and the report even has a subreport. Here is a snippet from the generated report using the parameter values indicated above:

Preview of the generated HQL report

JasperReports Server and Hibernate

Now that we can build reports, let’s deploy them.

Deploy the Hibernate Data Source

JasperReports Server (JRS) does not ship with built-in support for Hibernate like it does for JDBC SQL data sources. Creating a custom data source isn’t too hard, but it’s not trivial either. Fortunately, we don’t have to create the datasource ourselves. JRS ships with sample custom data sources to show you the way.

The precise location of the samples folder will depend on where you installed JRS, of course, but in my case the folder is here:

.../jasperreports-server-4.1-bin/samples/customDataSource

So how do you install these sample data sources? Fortunately, there’s a readme.txt with instructions. Unfortunately, it hasn’t been turned over to the documentation team for proofreading (sorry, Bob). It reads “JasperServer” where it should indicate “JasperReports Server”. Jaspersoft changes product names pretty often, so this is forgivable in a readme that was written long ago. It has things like “you will have Ant installed already”. That future tense is awkward. “Ant may be run with the following command” Passive voice would have been disliked by a doc writer (he he). “The example reports for this data source read a web page …” Subject verb agreement. Etc.

But ignoring style considerations, the readme file contains quite a bit of useful information which can be distilled from 76 lines into two critical steps for us in our task of enabling Hibernate reports:

1. Edit build.xml to set the webAppDir property
2. Run ant with no arguments

Edit build.xml to set the webAppDir property
original: <property name="webAppDir" value="c:/download/apache-tomcat-5.5.12/webapps/jasperserver-pro"/>
modified: <property name="webAppDir" value="/usr/local/tomcat/webapps/jasperserver-pro"/>
Your modified version will be slightly different. Be sure that it points to the location where JRS is deployed.

This copies 20 files into your existing JRS deployment. Since we only care about the Hibernate at the moment, let’s look at the 7 files relevant to this data source. (The web scraper sample is pretty cool. Maybe I’ll write about that another time.) These are the files:

WEB-INF/applicationContext-hibernateDS.xml
bundles/hibernateds.properties
classes/hibernate.cfg.xml
classes/example/cds/BasicHib.class
classes/example/cds/basichib.hbm.xml
classes/example/cds/HibernateDataSourceService.class
classes/example/cds/HibernateSessionFactoryFinder.class

The applicationContext file makes sense if you’re familiar with Spring. If you aren’t, don’t worry. It just defines the bean hibernateDataSource, and you don’t need to worry about it. The properties file defines some text strings that show up in the JRS GUI.

The files in the directory “classes” are the interesting ones. These define our Hibernate data model. Presumably you have your own version of these or you wouldn’t be reading this article. But let’s test with the sample version before you swap in your own version of these.

Create a Hibernate Connection (to the JRS Repository)

Start JasperReports Server (JRS). Or restart it if it was running. It must restart to pickup the new configuration files. Create a new data source. Notice that you now have three new data source types.

Three new data sources in JRS

Now that the data source “Hibernate Data Source” has been installed, you can create a data source pointing to your particular Hibernate sources. First, we can test a special case. The JRS Repository uses Hibernate to connect the web application to the database. This is what makes it easy to support PostgreSQL, MySQL, Oracle, MS SQL Server, etc. We can use the JRS Repository as the data source for a report.

Right-click on a folder in the JRS repository view and add a data source. It should look like this:

Special case: use the JRS Repository as the data source for a report

To use the JRS Repository as the data source you must set the Session Factory Bean Name value to “sessionFactory“. This is a standard bean that JRS uses for its repository connection. This allows the data source to get data out of the JRS repository, and we count on Hibernate to make sure that the query works regardless of whether the repository is on PostgreSQL or MySQL or Oracle or MS SQL Server etc.

Now that the data source is defined, next you need to upload the report. Find the file “hqlTest.jrxml” here:

.../jasperreports-server-4.1-bin/samples/customDataSource/reports/hqlTest.jrxml

Right-click a folder in the JRS Repository view and add a JasperReport. Use the data source that you just created (it’s called “Hibernate_Sample_Datasource” in the image above.)

Run the Hibernate Report

The sample report report hqlTest.jrxml isn’t a beautiful one. It’s unsorted, and it’s not particularly well formated. But it’s running HQL to get its data. Therefore it’s pretty cool. It could have quite a few practical uses. We could use this to get an interesting list of reports from the repository, and we could add a drill-down link to launch each report. The possibilities are very interesting.

Preview of the sample Hibernate Repository Report

But the task at hand—the reason you’ve labored through this lengthy article—is to run a query against your own Hibernate data model. Let’s move on.

Create a Hibernate Connection (to an arbitrary Hibernate source)

The file “hibernate.cfg.xml” that is currently deployed to your JRS defines a connection to a MySQL database called hibernatesample. To use this connection you could create the database “hibernatesample” and create a table like this:

create table basichib ( EVENT_ID int, name varchar(10), value int );
insert into basichib values ( 1, 'nameA', 1 );
insert into basichib values ( 2, 'nameB', 42 );

Creating a connection to this Hibernate data source is easier than one might expect. Indeed, it took me a few days to realize what I needed to do, since I thought there were probably quite a few steps needed. In fact, the only thing you need to do is create another Hibernate data source and NOT specify anything for the Session Factory Bean Name. It was great to figure this out… but it was also a bit anti-climactic. The data source definition looks like this (it should have no parameters set at all):

General case: Connection to any Hibernate source

Then create a report with an HQL query like this:

from example.cds.BasicHib h

I created the requisite table and report. I found that I had a report which is dead boring from a practical standpoint… but I confess to being wildly excited as I first got data from my database without writing any SQL. On the other hand, you’ll be far more interested in connecting to your existing Hibernate data source. Fear not, the task is finally at home. Read on.

Create a Hibernate Connection (to your own Hibernate source!)

Creating and reporting on sample data lacks a certain level of gravitas. Let’s modify this connection to use your own database. We don’t need to make any connection to the data source defined in JRS. It doesn’t have any properties after all, so there’s nothing to modify. Instead you must copy the relevant Hibernate configuration files into the JRS classpath.

For my article I’ll use the Hypersonic database that ships with the JR samples which is referenced at the start of this article which is by default inaccessible to a JRS instance. I simply need to copy the hibernate configuration files from the JR sample to the deployed JRS to make it accessible.

from: .../jasperreports-4.0.1/demo/samples/hibernate/build/classes
to: .../apache-tomcat-6.0.32/webapps/jasperserver-pro/WEB-INF/classes

In theory, all that’s left is to restart JRS and start deploying reports. Hooray! In fact, I ran into three problems with this idea. Bummer.

First, JRS didn’t have the Hypersonic database driver. This is pretty obvious requirement, so I wasn’t too surprised. I had to copy hsqldb-1.8.0-10.jar into WEB-INF/lib.

Second, it seems that JR had no need for the current session… but the data source in JRS needs this. This wasn’t quite as obvious. But the error message was quite clear. So it wasn’t hard to figure out what was needed. I had to add this additional property to hibernate.cfg.xml:

<property name="current_session_context_class">thread</property>

After these two changes I was able to run the sample reports that came with the JR hibernate sample as canned reports. This was great, and now I’m nearly done. Next, I wanted to use these queries as Ad Hoc topics, so I copied the reports into the repository folder /adhoc/topics.  You can see them here:

Closeup view of the Topics folder

The first topic—the one that was a copy of the report used the repository as a data source—worked immediately. I was able to create a new Ad Hoc report using the drag and drop Ad Hoc interface to get whatever I wanted.

My second test used the sample query listed above: “from example.cds.BasicHib h”. It worked perfectly as well.

My third test used the sample report that shipped with the JR hibernate sample. This one failed. It ran with no errors, but it didn’t return any data. This one was more confusing. In the end I realized that the problem is that the HQL query executer relies on the field description as important metadata. But the Ad Hoc engine assumes that the description is not important, so it ignores this information. Having found this crucial issue, the solution was straightforward. It’s a single line of code that needs to change. But for a JRS user like myself this is not a trivial demand. In the release of JasperReports Server 4.2 this change will be included, so HQL reports should work immediately as topics. Until that’s available, I have made the relevant re-compiled .jar file available. Just replace your existing version of ji-gyroscope-4.1.0.jar with the one attached to this article. Note: my second test worked, and you may find that your HQL reports work just fine as topics right out of the box too. Since the fix will be released quite soon, I won’t bother documenting the circumstances when the failure to pass in the field description matters and when it doesn’t.

After that final tweak I was all set. The report AddressesReport.jrxml was already working in the JRS repository as a canned report. Now it’s working as expected as a Topic. Hooray!

Ad Hoc Editor with sample hibernate source

Summary

This article is surprisingly long. That’s because there are samples in a couple of different places, and there are independent steps involved in getting HQL working in iReport and in JasperReports Server. I wanted to include  extensive details on each stage of the process for future reference. Good luck. Please let me know if you have questions about the setup.

Appendix

For the curious, here is a diff of the code change that was needed:

--- gyroscope/src/main/java/com/jaspersoft/ji/adhoc/strategy/NewClassicDataStrategy.java        (revision 20735)
+++ gyroscope/src/main/java/com/jaspersoft/ji/adhoc/strategy/NewClassicDataStrategy.java        (working copy)
@@ -146,7 +146,7 @@
                                slField.setName(f.getName());
                                slField.setType(f.getType());
                                // pass description through because MDX queries need it
-                               if (lang != null && lang.equalsIgnoreCase("mdx")) {
+                               if (lang != null && (lang.equalsIgnoreCase("mdx") || lang.equalsIgnoreCase("hql"))) {
                                        slField.setProperty(BaseField.PROP_JR_DESCRIPTION, f.getDescription());
                                }
                                // if other props possibly needed by QE are there (e.g. webscraper custom QE sample), pass them through

You can see that the solution was to treat the HQL query executer just like we already treat the MDX query executer.

In a previous article I described some reasons that chart customizers are useful and gave some links to useful resources. (I’ll call that article “Chart Customizers 1″.) If you are not already familiar with chart customizers, then please read Chart Customizers 1 before reading this one. If you are already familiar with them, then please skim Chart Customizers 1 before reading this one.

Overview

“Chart Customizers 1″ explained what chart customizers are and provided some code. It was useful for Java developers. It made all changes as hard-coded settings, so the samples were not immediately useful for anyone without further coding.

“Chart Customizers 2″ (this article) provides a useful chart customizer and describes why it’s useful. You can immediately use it to solve some common problems (no coding required!).

If you just want to grab the chart customizer (binary and source) scroll all the way to the bottom.

Using Additional Properties

The concept of “properties” is a key idea that was missing in “Chart Customizers 1″. Using properties lets you set values in the report (in the .jrxml file) rather than hard-coding them as I did in my earlier sample. As one would hope (expect?) it’s simple. The chart customizer extends JRAbstractChartCustomizer. Therefore we can get the chart properties like this:

JRPropertiesMap pm = jasperChart.getPropertiesMap();

Then we can get a particular property like this:

double upperMargin = (pm.getProperty("UpperMargin") == null) ? -1 : Double.parseDouble(pm.getProperty("UpperMargin"));

This is the addition that made it possible for me to extend my chart customizers from being purely proof of concept samples to being useful chart customizers.

Bar Chart Improvements

Integer Tick Marks

Let’s start with some common requests for bar charts. Perhaps the most common request that I have seen is to prevent charts from showing non-integer values on value axis. Here’s an example. The number of times that a person shopped on a particular day is necessarily an integer. I don’t want to see “2.5″ on the chart axis.

The bars are completely accurate. Yet it's annoying to have the non-decimal value displayed.

How easy is it to tell JFreeChart to only use integers? Really easy! Hooray! It has a method called “createIntegerTickUnits()”. By the way, if you’re doing any significant work with JFreeChart then you should buy their Developer Guide. It’s well done.

How easy is it tell iReport and JasperReports to use only this method? Impossible. That’s a big bummer.

Fortunately, we can amend that somewhat pessimistic answer like this:

How easy is it tell iReport and JasperReports to use only integers? Really easy if we use a chart customizer! Hooray! It’s a single line. Since we might not always want this applied, we can surround it by an if statement:

if (useIntegerTickUnits) {
	valueAxis.setStandardTickUnits(NumberAxis.createIntegerTickUnits());
}

Now if I add the property “IntegerTickUnits” with the value “true” to my bar chart I’ll only get integers.

On the chart "Shopping Days" I set this property

If I set the value to “false” (or to anything besides “true”) or if I don’t set the property at all, then I get the standard behavior. If you’re new to JasperReports Server then refer to the Detailed Steps at the end of this article to exactly exactly what you need to do to apply this chart customizer.

The bars look much better when aligned with tick marks (or exactly half way between them)

Category Labels on multiple lines

By default there is no way to tell the chart to use multiple lines to display a category label. Again it’s easy in JFreeChart, so it’s easy in a chart customizer. Now I just have to add the property “MaximumCategoryLabelLines” with the value “2″ to my chart to get what I want.

Who is it that drank more ţuică?

Now its clear that I ate more hot dogs.

Using more space for category labels

JFreeChart is nice enough to truncate long labels for me. But it’s quite restrictive about how large it lets the labels be. A call to setMaximumCategoryLabelWidthRatio let’s me allot more space for the labels. Here’s an alternative solution to the previous problem where labels are cut off.

Who is it that ate more hot dogs?

Alternative solution increases the width allowed for the labels

Space between bars

The default amount of space put between the bars within each category is pretty generous. That can be reduced as a percentage of the available space. I added this to the .jrxml (well, iReport adds this to the .jrxml) to completely eliminate the space between bars:

<property name="ItemMargin" value="0.0f"/>

In some charts its more effective to remove the space between bars

Upper Margin

I will not bother showing this property since it’s covered in “Chart Customizers 1″. The only difference now is that in that case I hard-coded the margin to .40. Now I can set that percentage as a property in the chart.

Pie Chart Improvements

My most common annoyance with pie charts was when I put several pie charts onto the same page to show a trend. There is no easy way to specify a color for a named section. It’s easy to specify a color for the first section and a color for the second section. This is often sufficient. But this has the potential to be extremely confusing when two different charts have different items or when they have the same items returned in a different order. The following sample report shows the idea clearly.

Passing in the colors for the sections in a pie chart is the most complex piece in all of my chart customizers. I give a special thank you to Teodor Danciu for the idea and to Luke Shannon for help with some implementation details.

You must create a property on the chart called “Predefined Colors”. The property value is a String containing key:value pairs separated from each other by semi-colons. For example, for a report that I run which shows the databases that JasperReports Server instances use for their repository database I pass this string:

MySQL:#015A84;Oracle:red;PostgreSQL:#0085B0;Microsoft SQL Server:#F8EB33

For most databases I choose a color using RGB values. For Oracle I use the shorthand syntax “red”. These values get converted into colors using a utility class that is built-in to JasperReports: http://jasperreports.sourceforge.net/api/net/sf/jasperreports/engine/type/ColorEnum.html

To see exactly how it’s done, refer to the sample report (Pie_Specified_Series_Colors.jrxml) and to the comments in the chart customizer (PieLabels.java).

These are some of the most common chart tweaks that I have seen. Some are ones that I have needed myself, and others are ones that I have seen requested on JasperForge. Please let me know if you find the chart customer useful, and let me know what other properties you would find useful in a chart customizer.

Detailed Steps to update a report

Here are the steps I followed to apply my new chart customizer to an existing report. This is the report “Customer Overview” that ships with Jaspersoft BI evaluation version. So you can easily apply this chart customizer to that sample before trying it on your own charts.

1. Upload ChartCustomizers2.jar into JasperReports Server. (Use either the web UI or iReport’s JasperReports Server plug-in.)
2. Edit the report to add a link to the resource ChartCustomizers2.jar. (Use either the web UI or iReport’s JasperReports Server plug-in.)
3. Edit the report in iReport to make two changes:
1. Find the property “Customizer Class” and set it to “com.jaspersoft.bizdev.BetterBarLabels” (without the quotes).
2. Find the property “Properties expressions” and add a new property called “IntegerTickUnits” with the value “true” (without the quotes in both cases).
4. Save the report back to JasperReports Server. Run the report.

Sample reports and the Chart Customizer

WordPress seems to lose my attachments with some regularity. So instead of using that I’ll try GoogleDocs for sharing my samples.

• Chart Customizer 2 – This is a .jar file. Just add it to your classpath and you can use it. The .jar also includes the source .java files.
• Pie Chart sample report JRXML
• Pie Chart sample report PDF

Update: Much of the content of this article should still be useful. But I wrote a more recent article with a much more useful chart customizer attached. So please take a look at that article as well.

When charts in reports designed in iReport don’t look the way that you want them to there are a few common next steps that you can take. Here are the most common:

• Silently curse those Jaspersoft developers (what a stupid default display style)
• Silently curse those JFreeChart developers (surely everyone in the world would prefer it differently)
• Loudly curse them (come on guys! hurry up and add my new feature!)
• Search jasperforge.org, figure out that you need a chart customizer or a chart theme, speculate that this sounds too difficult, and then finally decide that you don’t really care so much about whatever it was that you really wanted to change afterall.

In this article I’ll take a look at some of the less-used alternative next steps:

• Refer to the documentation
• Refer to the samples
• Create and use a Chart Customizer

Documentation

The JasperReports Ultimate Guide includes the section “Chart Customizer and Chart Theme”. This is a good starting point. It explains the reason these objects exist: to provide full control over chart customization. And it describes the interface that you must implement and the class you should extend in order to create a chart theme. The iReport Ultimate Guide mentions the existence of chart themes, but it doesn’t provide any additional examples or insight.

The online documentation on jasperforge.org provides additional information. The Sample Reference section includes a page on charts which has a section on chart customizers. It has sample chart customizer code that can hard-code a bar chart to ignore the colors that you have chosen when designing the report and to use only green and orange instead. The customizer has no practical value, but it’s nice to have a working sample as a starting point.

Samples

The page mentioned above refers the reader to a resource that should already have been consulted… the samples that ship with JasperReports. If you have only installed JasperServer or iReport, then you’ll need to download JasperReports directly. It includes this folder containing over 50 samples:

…/jasperreports-3.7.4/demo/samples

In the subfolder “charts” you’ll find the aforementioned BarChartCustomizer.java to generate green and orange bars along with reports that use this chart customizer. In the folder “chartthemes” you’ll find sample code for chart themes.

The other sample that everyone has easy access to is the set of chart customizers that ships with JasperServer Professional. Use iReport to browse the JasperServer repository and download the file DemoChartLabels.jar. It contains both the binaries used by the server as well as the source java files.

The highlighted file, DemoChartLabels.jar, may be downloaded using the JasperServer Plugin in iReport

Chart Customizer Samples

I’m not a Java developer. I will not be able to create an impressive chart customizer to amaze your friends and family. But I know enough Java to create some very basic chart customizers. I have set my sights slightly higher than just creating alternating green and orange bars in a bar chart. But not much higher.

Pie Chart Labels

The problem:

I want a pie chart with no labels on it. It sounds funny right? But it’s pretty common. It came up in this thread on jasperforge.org. I have wanted it in the past. Most recently, Jaspersoft partner OpenBI asked me about it. Here’s a simple example.

Pie Chart with the Default Look

The solution:

I need a way to tell the chart not to display labels. iReport (and JasperReports) does not provide a way to do this. The underlying chart engine is JFreeChart. The JFreeChart API provides a mechanism avoid displaying labels. I found the answer on stackoverflow.com. The good news is that it’s a single line of code. Where do I put this code? In a chart customizer! It’s simple enough once you have the idea. Here is the complete code for the chart customizer:

/**
  * OK, it's not really the COMPLETE code. I removed the imports and comments.
  * But those are included in the attachments.
  */
public class PieLabels implements JRChartCustomizer {
  public void customize(JFreeChart chart, JRChart jasperChart) {
    Plot plot = chart.getPlot();
    if (plot instanceof PiePlot) {
      PiePlot piePlot = (PiePlot)plot;
      piePlot.setLabelGenerator(null);
    }
  }
}

Next, I compiled this class into the very small file DemoChartCustomizers.jar. Finally, I need to tell the report to use the chart customizer. Select the chart and set the property “Customizer Class”.

Set the Customizer Class property

Remember to add the JAR file to iReport’s classpath.

Set the iReport Classpath

The final result is shown below. It’s modest, but it’s certainly nicer than the original.

Pie Chart with the Customized Look

Bar Chart Labels

The problem:

This one has annoyed me for years. But I never quite got around to attempting to fix it. I went with option number two from my list above: I’ve been silently cursing those JFreeChart developers. JFreeChart’s default way of arranging labels on bar charts puts them above the bars. But its default way of rendering the chart doesn’t leave enough room above the tallest bar to display the label. This old thread discusses the problem. The project leader of JFreeChart, David Gilbert, writes, “Eventually, it would be nice if the renderer could calculate an appropriate range so that the item labels are always visible.” Here’s a typical example of the issue. (This one ships with JasperServer Professional.)

Bar Chart Original Labels

The average sale price for All Customers is 27.54. But what is the average sale price for M. Benigar? It’s significantly higher than the average… but where is its label? This annoys me to no end. Perhaps the problem has already been solved in JFreeChart’s default settings. The thread identifying the problem is more than three years old as I write this article. But as far as I can tell, there have been no changes in this regard.

The solution:

Until JFreeChart cleans this up internally, we have to manually calculate a better margin to allow space for the label to be displayed. I use a somewhat crude calculation: hard-code the margin to 40%. Here is the result.

Bar Chart with Customized Labels

Woo hoo! Now we can see the exact value of the tallest bar.

Summary

iReport gives good control over chart options for dozens of properties. But if you want complete control over the display options, you need to use JasperReport’s chart customizers. This requires Java coding. Sorry. But it’s not much coding. My two chart customizers really have only one functional line each.

Next Steps

You can download my ChartCustomizerSamples to try it yourself. The download file is ChartCustomizerSamples.odt. You need to rename this to ChartCustomizerSamples.zip. (WordPress won’t let me post a .zip file.) The JAR file included inside will let you run the pie chart reports in iReport. It also includes the source code. The reports use the FoodMart sample database that ships with JasperServer.

Additional Note: I have conveniently ignored Chart Themes. In fact, chart themes are newer and better than chart customizers. Chart customizers have been deprecated in favor of chart themes. Hopefully I’ll have time to investigate and write about chart themes someday in the future.

Background

To get reports to display exactly the way that you want them to display you need to ensure that you have exactly the font that you want. Jaspersoft makes this relatively easy through the mechanism of “Font Extensions”. To understand the technical workings of font extensions well, your best resources is the JasperReports Ultimate Guide. If you are working with JasperReports you owe it to yourself to buy a subscription to this resources; it’s great.

I’m not writing about the details of how font extensions work.

In the past creating font extensions was relatively difficult. I wrote about it in this post. It wasn’t really overly difficult if you refer to the documentation and took your time, but it involves creating XML files and is certainly not a point-and-click process. With the release of iReport 3.7 it’s much easier. For details on how to use the wizard to create font extensions, take a look at the iReport Ultimate Guide. It has a whole chapter on “Fonts and Styles”. It’s great.

I’m not trying to replace the content already included in the iReport premium documentation.

So what is the point of this article? This is an example of the complete process of creating a new report, specifying fonts, confirming that the report works well, then deploying the report to a server where the font doesn’t already exist and configuring that server correctly.

Create a report and specify fonts

In the attached report “FontExtensions.jrxml” you can see that I have selected 4 different fonts for the 4 different text fields. The title is set to “DejaVu Serif”. I chose this because it is already installed as a font extension by default in iReport (and JasperServer). How do I know that it’s already installed? You can see the installed fonts from the menu Tools -> Options -> Fonts. You can also tell by looking at the dropdown list of fonts in the property “Font name” for the field. DejaVu Serif is above the line. That means it’s installed. The fonts below the line are on my machine, but they aren’t registered as font extensions, so there could be trouble at deployment time.

Tools -> Options -> Fonts

Dropdown list of available fonts

Next, I want to set the subtitle to Microsoft’s Comic Sans font. (Please note: I forbid you to use this font in your own reports. It’s terrible. Maybe if you’re creating a report on preschool statistics it would be OK. I only chose it for this article because it’s well known and distinctive.) Oh no! This font appears only below the line! (as “Comic Sans MS”)

Family Details

Select a TrueType Font

Don’t worry: installing a font is simple. From the Tools -> Options -> Fonts screen shown above click “Install Font”. On the first step of the wizard browse to the font file. On the second step specify the separate file with the bold version of the font. The final steps of the wizard are described in detail in the iReport Ultimate Guide, so I won’t bother with details here. For our purposes we can skip through these steps with no changes.

Hooray. Now Comic Sans MS appears “above the line” as well as on the window Tools -> Options -> Fonts. It can safely be selected as the font for the subtitle field.

Code2000 PDF Encoding

Next, I created a field for my group header. I included the Japanese characters “日本語” in this field to test support for non-ascii characters. Of course I need to select a font that includes support for these characters. I chose Code2000. It’s not a particularly elegant font visually. But it supports lots and lots of characters. As before, the next step is to install Code2000 as a font extension.

This time be sure to set the PDF Encoding to “Identity-H”. If you forget to set it during the initial run of the wizard, you can edit the font details later as shown in the screenshot here. Embedding the font in the PDF document is not required, but I recommend it. Without that option you are at the mercy of the machine viewing the PDF document to supply the font. With the font embedded you are sure to get what you’re expecting. The file size will be larger, but it’s really not a big difference. The PDF creation process is smart enough to embed only the characters that are required; you don’t get the entire font file embedded into the document.

My final text field is in the detail band. For this field I went with the simple option of using the Java logical font “SansSerif”. This logical font will get translated to some physical font by the JVM when the report gets run. It’s impossible for the report designer to know what font will be selected, so this option is appropriate only when you don’t need a precise font. As a practical matter, one can make a good guess. I see that my JVM on Windows XP is configured to use Arial for its SansSerif font. I see that my JVM on CentOS will use lucidasans. These are common default values, but they are not guaranteed.

Run the report in iReport

Now that the report is created, I’ll run it to confirm that all fonts are working as expected. But to make the details perfectly clear I first deleted my font extensions. Let’s see what this report looks like without the font extensions defined in iReport.

With no font extensions defined the output is somewhat surprising

The good news is that the report looks good without the font extensions. The bad news is that the report looks good without the font extensions. It’s bad news because it can make you think that things are configured correctly. Only the PDF export of the report shows the problems caused by not defining the needed font extensions.

Now I put the font extensions back and re-run the report. The internal preview and HTML were already fine before, so they remain fine. But with the font extensions PDF is working well too.

With the fonts installed the PDF is now good

The sharp-eyed reader may notice that the Japanese characters in the detail band still do not display well. I’m willing to ignore this for now. It happens because my JVM translates SansSerif to Arial, and Arial does not include support for Japanese characters. I could solve the problem by updating my JVM properties to use another font or by modifying my report to use Code2000 or Arial Unicode MS or another font with support for these characters.

Deploy the Report to JasperServer

From iReport use the Repository Navigator to deploy the report to JasperServer. Open a browser, find the report, and woo hoo! Everything is good: the title uses DevaVu Serif, the subtitle uses MS Comic Sans, the group header shows Japanese characters correctly using Code2000, and the detail band shows Japanese characters correctly using some unspecified sans serif font.

HTML Report on JasperServer

Just to be sure, let’s take a look at the report in PDF format. On no! It looks exactly like it did in iReport before we defined the font extensions. Japanese characters are missing and it uses the wrong fonts.

If you have been following along closely, you should already know what is wrong. Although we defined the font extensions in iReport, we have not deployed them to JasperServer. That’s the final step we need before the reports will work exactly as intended.

Export and upload the font extensions

We need to get the font extension from iReport over to JasperServer. In JasperServer 3.5 this required tracking down (or creating) the relevant XML files, properties files, and TTF font files. I wrote about font extensions in JasperServer 3.5 previously. In JasperServer 3.7 it’s a single click to export the extension and only a few more clicks to load it up to JasperServer.

Return to the window Tools -> Options -> Fonts and click the button “Export as extension”. That was easy.

In the Repository Navigator pane right-click a folder and choose Add -> Jar Archive. Then on the report unit add a reference to this JAR file. It is possible to add the JAR Archive directly into the report unit. But it’s better to add the JAR independently so that it may be referenced by many reports. In the screenshot below you can see that MyFontExtensions.jar has already been added, and now I am just adding a reference link from my report unit to this resource.

Add JAR Archive and a reference to the JAR Archive

Success

Now that the font extensions have been loaded up into JasperServer—and the report makes use of it—the report works perfectly. HTML, XLS, OpenOffice.org spreadsheets and text documents, and even PDF are all rendered as intended. Don’t forget that most formats, like the ODS file below, refer to the correct font but do not embed it. So these will not render as intended on client machines lacking the relevant font. But PDF with its font embedding can be counted on to produce a pixel-perfect output.

The same report in ODS with correct fonts

Appendix

One way to be more certain that your reports are well defined is to tell JasperServer to more rigorously enforce fonts. By default JasperServer makes a best guess and substitutes another font in place of one that cannot be found. This is helpful in some respects, but I find that it promotes laziness. I much prefer to set the following option in …/WEB-INF/classes/jasperreports.properties:

# ignore missing fonts in reports
net.sf.jasperreports.awt.ignore.missing.font=false

The default value is true. By setting it to false JasperServer will throw an exception when it cannot find the font that it needs. Here’s what the user sees when running the above report before deploying the font extensions when JasperServer does not ignore missing fonts:

net.sf.jasperreports.engine.util.JRFontNotFoundException: Font 'Comic Sans MS' is not available to the JVM. See the Javadoc for more details.
	at net.sf.jasperreports.engine.util.JRFontUtil.checkAwtFont(JRFontUtil.java:321)
	at net.sf.jasperreports.engine.util.JRStyledText.getAwtAttributedString(JRStyledText.java:226)
	at net.sf.jasperreports.engine.fill.TextMeasurer.measure(TextMeasurer.java:362)
	at net.sf.jasperreports.engine.util.JdkGlyphFixTextMeasurer.measure(JdkGlyphFixTextMeasurer.java:133)
	at net.sf.jasperreports.engine.fill.JRFillTextElement.chopTextElement(JRFillTextElement.java:1008)
	at net.sf.jasperreports.engine.fill.JRFillTextField.prepare(JRFillTextField.java:539)
	at net.sf.jasperreports.engine.fill.JRFillElementContainer.prepareElements(JRFillElementContainer.java:327)
	at net.sf.jasperreports.engine.fill.JRFillBand.fill(JRFillBand.java:402)
	...

Of course you wouldn’t want to let errors like this creep into a production system. But that’s why we have testing. During testing it’s far better to see these errors. Without this error I might not have noticed that a report was rendering without Comic Sans MS. This way I see exactly what the problem is, so I can take steps to fix it.

The Problem

I have written about fonts in JasperServer in the past, but I’m revisiting it now. It’s popular topic because fonts are very important to the look of your reports, but it’s easy to get things setup wrong (or incompletely). Let’s start with the “Sales by Month” report which ships with JasperServer Professional and Enterprise 3.7.

Sales by Month report in Japanese

Let me be the first to say, “Hey! didn’t those Jaspersoft guys improve anything in v3.7? Why doesn’t my chart correctly display the legend characters in Japanese by default!?”

The Solution

The issue—as is common with font issues—turns out to be more subtle than one might expect. First we have the somewhat confusing situation that some Japanese characters display well. It’s only the chart that has a problem. This is because my local Windows XP machine has appropriate Japanese fonts. So things like this render nicely: “キー：  低い値    高い値”. That’s because they get rendered by my browser. But the chart gets created on the server. A bad choice of font must be happening there.

In JasperServer v3.5 the problem was that the report specified Verdana as the font. Verdana doesn’t include glyphs for Japanese characters, so it wasn’t really JasperServer’s fault that it couldn’t render things well. It was the report designer’s fault. In JasperServer v3.7 all of the sample reports have been updated to use Java logical fonts like SansSerif, Monospaced, etc. This means that JasperServer pushes the job of selecting the exact physical font down to the JVM which works with the underlying OS to find an appropriate font.

Aha! this means we have a new culprit to point fingers at: Java. What font is the JVM deciding to use? I’m running JasperServer in the cloud on a CentOS Linux box. What font faces are available? Let’s see:

# fc-list
#

That’s right. No fonts at all are available. That is likely the root of my problem. Are there fonts available to install? Let’s see:

# yum list | grep japanese
fonts-japanese.noarch                    0.20061016-4.el5       base
m17n-db-japanese.noarch                  1.3.3-48.el5           base

There are fonts available. It takes only a few seconds to install them:

# yum install fonts-japanese.noarch

Now I have lots of fonts available:

# fc-list
fxd:style=Bold semicondensed
sys:style=Bold
hlv:style=Bold Italic
Fixed:style=Bold
goth_p:style=Bold
sys:style=Bold Italic
...

Finally, I need to restart Tomcat. Now when I log back into JasperServer I see everything rendered correctly. Woo hoo! The report was good. JasperServer was good. Tomcat was good. Everything was good… except the underlying operating system didn’t have any appropriate fonts.

Sales by Month correctly displaying all Japanese characters

Other Fonts

What about when you want to specify the precise font that you need? That’s a good question. I ignored it in this article. The short answer is that you need to use Font Extensions. I wrote about it previously in my article “Fonts in JasperServer“.

In general the use of Java logical fonts makes things more flexible. That’s what made it the ideal choice for sample reports that ship with JasperServer. But it’s possible that different systems will map the logical fonts to different physical fonts. These fonts may have slightly different metrics, so the results in the report can be slightly unpredictable.

In many reports, you simply don’t care about the minor font metric differences. On one machine a particular value fits on a single line. On another machine it overflows into a second line. So what?

In other reports you have more precise positioning requirements. Your title fits nicely on a single line at design time. But when the report is deployed the final word in the title overflows into a second line. That won’t look impressive. Worse: that field isn’t allowed to expand, so you don’t see the final word anywhere. Bummer. In cases like this you need to specify the precise font that gets used. Of course it therefore becomes your responsibility to make sure that the server has the font that you want to use. For these situations Font Extensions are your savior.