Implementation and Usage of Chart Customizer Classes for Customizing JFreeCharts in JasperReports

In the previous article I introduced the topic of customizing JFreeCharts in JasperReports by giving an overview of customizing possibilities for JFreeCharts in JasperReports (and resp. iReport Designer / Jaspersoft Studio). The most flexible and powerful way of customizing JFreeCharts can be achieved by using chart customizer classes.

In this post I’ll give a short tutorial on the implementation and usage of customizer classes for customizing JFreeCharts. All details discussed in this article are related to JFreeCharts, so they can be applied both in the community edition as well in the professional or enterprise editions of JasperReports, iReport Designer and Jaspersoft Studio.

What is a Chart Customizer Class?

Chart customizer classes are Java classes that can be used to implement changes in the appearance of charts. Compared to chart properties or chart themes, customizer classes can leverage the full functionality of the JFreeCharts library. For example by using chart customizer classes you can change the line style for a series from solid to dashed; change the style for bars to custom gradients or even striped patterns; display a zero-line, marker-lines or marker-regions; read all design information from a database, etc. All these aforementioned customizations are not possible by setting chart properties or creating a chart theme, but they can only be achieved by implementing a chart customizer class.

Implementation of a Chart Customizer Class

For the implementation of a chart customizer class the interface JRChartCustomizer needs to be implemented. This interface defines a customize method, which takes a JFreeChart and a JasperReports chart object as parameters. Inside the customize method we can access all settings defined for a chart and apply our custom changes to them. During report execution JasperReports automatically calls this customize method for our chart and applies the implemented instructions.

Following example shows the implementation of a chart customizer class for displaying minor ticks on the y-axis of a JFreeChart. Neither the chart properties panel, nor chart themes offer a possibility for enabling minor ticks, so displaying minor ticks requires the implementation of a chart customizer class.

import net.sf.jasperreports.engine.JRChart;import net.sf.jasperreports.engine.JRChartCustomizer;import org.jfree.chart.JFreeChart;import org.jfree.chart.axis.ValueAxis;import org.jfree.chart.plot.XYPlot;public class XYMinorTicksCustomizer implements JRChartCustomizer{	public void customize(JFreeChart chart, JRChart jasperChart){		XYPlot plot = chart.getXYPlot();		ValueAxis rangeAxis = plot.getRangeAxis();		rangeAxis.setMinorTickCount(4);		rangeAxis.setMinorTickMarkOutsideLength(1.0f);		rangeAxis.setMinorTickMarksVisible(true);		rangeAxis.setTickMarkOutsideLength(2.5f);	}}

The number of minor ticks is set using the setMinorTickCount method. The first minor tick always overlaps with the lower major tick, so by setting the value for the minor tick count to ’4′ we get 3 minor ticks between two major ticks. The length for the major and minor ticks can be adjusted by setting the values accordingly using the methods setTickMarkOutsideLength and setMinorTickMarkOutsideLength. By setting a new length for the ticks the minor ticks appear smaller than the major ticks. The visibility of the minor ticks can be adjusted by the method setMinorTickMarksVisible.

By applying the customizer class to a chart, we get the following result (notice the minor ticks on the y-axis):

http://blog.itransparent.de/wp-content/uploads/2013/10/XYMinorTicksChart1-300x176.png

Using Chart Customizer Classes in a Report

Before we can use a chart customizer class in a report, first we need to compile its code and export it to a JAR file.

In the iReport Designer this JAR file needs to be added to the classpath. For adding a JAR to iReport’s classpath, go to Tools / Options / iReport / Classpath, click on ‘Add’ and select your JAR file. I’d advise to always set the tick in the ‘Reloadable’ column for the chart customizer JAR file. By making it reloadable, changes in the JAR file will appear automatically in iReport without the need of restarting the iReport Designer. This simplifies the development and debugging of chart customizer classes when using an external IDE.In Jaspersoft Studio the chart customizer class can be managed and developed in the same project as the reports. This simplifies the development and debugging of custom code used by reports, since there is no longer any need for an external IDE – everything can be developed using Eclipse. If an already existing chart customizer should be used in a Jaspersoft Studio project, then the JAR containing the customizer class needs to be added to the build path of the given project.The chart customizer class is a property of every JFreeChart, so every chart in a report can have its own customizer class. Of course the same customizer class can be applied for several charts in several reports. A chart can be bound to a customizer class by setting the “Customizer Class” property of the selected JFreeChart. The customizer class is referenced by its package name followed by the name of the class which contains the implementation of the customization. Following image displays the setting of the customizer class value for a JFreeChart in the iReport Designer.

http://blog.itransparent.de/wp-content/uploads/2013/10/set_chart_customizer-300x201.png

If report containing a chart which are manipulated by a customizer class needs to be deployed to the JasperReports Server, the customizer class implementation needs to be included to the classpath of the given report unit. To achieve this the JAR file containing the customizer class needs to be added as a resource to the report unit. To add a resource to a report unit in iReport Designer, right-click on the subfolder ‘Resources’ of the report unit and select JAR file from the context menu. Next a window will appear where you can set the ID, name and source path for the JAR resource (as depicted in the image below). The ID and the name of the resource can be different from the filename of the uploaded JAR. In Jaspersoft Studio the JAR file can be added by right-clicking on the folder of the report unit, selecting ‘New’ and ‘JAR’ from the context menu and adding the values for ID, name and the source path.

http://blog.itransparent.de/wp-content/uploads/2013/10/add_jar_as_resource-300x168.png

Conclusion

In this article I gave a short introduction on the implementation and usage of chart customizer classes for customizing JFreeCharts in JasperReports, iReport Designer, Jaspersoft Studio and JasperReports Server. The example customizer class which adds minor ticks to the y-axis of a chart can be downloaded as a Jaspersoft Studio project at the following link: ChartCustomizerBlog.zip

The next post will give a more extensive overview on the customizing possibilities for JFreeCharts in JasperReports.