Charts

A chart is a report element with kind="chart" and a chartType. The element has three parts that are worth keeping apart, because they live in different places in the template and are filled at different moments:

When the report is filled, the dataset collects the values, the engine builds a JFreeChart object from them through a chart theme, lets a customizer change it if one is attached, and stores the outcome in the document as an image whose renderer knows how to draw the JFreeChart object. The exporter then draws that image into the PDF. The official sample page describes the same idea: the library integrates charts produced by other libraries, and the chart element simplifies that integration.

Charts live in the optional jasperreports-charts artifact, which brings JFreeChart and the Batik SVG classes as dependencies. The artifact’s own POM for 7.0.8 depends on JFreeChart 1.5.6, so a source that says 1.5.4 is out of date. The engine alone does not know the chart element. In the run, a template with a chart element compiled on a classpath without jasperreports-charts failed with Jackson’s Could not resolve type id 'chart' error and an empty list of known type ids, and nothing in the message names the missing artifact. If a chart template stops loading after a dependency clean-up, this is the cause.

The charts module is added next to the PDF exporter, the fonts and the expression compiler already used by the other pages of this section. The last two entries are described later: jasperreports-chart-customizers holds ready-made customizers and is optional, and XChart is only needed for the last example.

JFreeChart and Batik come in transitively through jasperreports-charts, so they need no declaration, and the customizer and theme examples below compiled against the JFreeChart classes obtained that way.

The data for the report is a list of sales, with a second list of monthly totals for the time series. Each row is a JavaBean. A Java record does not work as a bean data source row: the run failed with Error retrieving field value from bean: category and the cause NoSuchMethodException: Unknown property 'category', because the bean data source looks for getter methods and a record’s accessors are named category() rather than getCategory(). The Sale class below is a plain class with getters.

The template has a group by category, a variable that totals the amount per category, a detail line per sale and four charts in the summary band: a bar chart, a pie chart, a time series fed from a separate dataset, and a spider chart. It is saved as src/main/resources/reports/sales-charts.jrxml. The next sections explain each part. The title and the summary are bands that hold their elements directly in the version 7 format, so the summary has a single height and no nested band: a nested band element was rejected in the run with Unrecognized field "band".

The program compiles the template, passes the second data source as a parameter, fills the report from the sale list and writes the PDF. It sets REPORT_LOCALE explicitly: without it, the time series axis uses the locale of the machine, and in a run on a Spanish-language workstation the month labels came out as ago-2026 and sept-2026.

The result is one page: the title, the twelve sale lines and the four charts in a two by two grid. The bar and pie charts show Fiction as the largest category, and the spider chart draws one polygon for the series Q3 with one axis per category. The template follows the official charts sample, whose reports use the same element kind="chart" syntax.

The chartType attribute selects the kind of chart, and each kind works with one kind of dataset, selected by the kind attribute of the dataset element. The official documentation lists the values below.

Each dataset kind has its own series expressions. The element names below are the ones the official documentation lists. In the sample JRXML files the XY expressions are spelled xvalueExpression and yvalueExpression, with a lowercase v, which differs from the capitalisation in the prose of the sample page.

The pie dataset has a rule of its own. According to the configuration reference, a repeated key is an error unless the property net.sf.jasperreports.chart.pie.ignore.duplicated.key is true, in which case only the last value for the key is considered. A pie fed one slice per sale row, with the category as the key, runs into this as soon as two sales share a category, which is why the example pie is fed from the group total instead.

In the JasperReports 7 JRXML, the title, the subtitle and the legend are not child elements of the chart, as the prose of the sample page still says. They are attributes and expressions on the element itself: titleExpression, subtitleExpression, titleFont, titleColor, titlePosition, showLegend, legendPosition, legendColor, legendBackgroundColor and legendFont. A template that uses a chartLegend child element is rejected when it is loaded. The run reported Unrecognized field "chartLegend" and listed the fifty-three properties that the chart element does know, which is a convenient reference of its own. The position values are the edges: Top, Bottom, Left and Right.

The plot element holds what depends on the kind of chart. The settings common to all plots are backcolor, orientation (Horizontal or Vertical), backgroundAlpha and foregroundAlpha, plus the seriesColor children that set the colour of each series by its position. In version 7 the attribute of a seriesColor is order, not seriesOrder: the run rejected seriesOrder and named color and order as the only two properties. The settings that belong to one kind of chart are:

Narrow charts clip long labels. In the run, the pie labels Children, Fiction and Science wrapped onto two lines inside their label boxes at 250 points wide, and the bar chart abbreviated the category Children to Chil... on the axis. Giving the chart more width, using a shorter label, or setting labelFormat to {0} alone are the usual fixes. A chart drawn at a fixed size does not reflow with the page.

A few axis settings are properties of the chart element rather than attributes: net.sf.jasperreports.chart.range.axis.tick.interval, net.sf.jasperreports.chart.range.axis.tick.count and net.sf.jasperreports.chart.range.axis.integer.unit, and their domain.axis counterparts. The configuration reference gives their scope as the chart. They are set with a property child of the chart element, and the integer-unit flag is for count charts whose axis would otherwise show fractional ticks.

Items of a chart can carry hyperlinks: the pie series takes a sectionHyperlink and the category and XY series take an itemHyperlink, with the same hyperlink type and expressions as other elements. A pie with a sectionHyperlink of type Reference filled and exported in the run; the link annotations in the PDF were not inspected. The hyperlink types, bookmarks and the way they are exported are covered in Hyperlinks, Bookmarks & Books.

The attributes above are those of JRChart, and the plot settings are described in the charts sample.

A chart is drawn into the document by a renderer, and the renderType attribute chooses which one. The official documentation gives three values:

The default is draw, and it can be changed for every chart through the configuration property net.sf.jasperreports.chart.render.type, at global, context or report scope. In the run, a chart with renderType="svg" filled and exported to PDF like the others, with the Batik classes that jasperreports-charts already brings. Which type is sharpest in a given output format was not compared. When a chart looks soft in the PDF, the render type is the first attribute to try. The PDF exporter itself, and how it treats images, is the subject of PDF Exporter Configuration.

A chart theme is the part of the engine that creates the JFreeChart object from the report’s chart definition, and it decides the look of everything the template does not set: fonts, colours, backgrounds, gridlines, shadows. The default theme is the one used in the examples above, and it is why the pie chart in the first run has a drop shadow. A theme is selected for a whole deployment or for a report with the property net.sf.jasperreports.chart.theme, whose default is default, and for one chart with the theme attribute of the element.

A custom theme implements net.sf.jasperreports.charts.ChartTheme, whose only method receives a ChartContext and returns a JFreeChart. The simplest custom theme extends DefaultChartTheme, lets it build the chart, and restyles the result. This one gives the Bookshelf reports a flat white style, a fixed colour per category on pies and a teal colour on bars.

Themes are found through the extensions mechanism. A ChartThemeBundle gives names to one or more themes, and an ExtensionsRegistryFactory provides the bundle to the engine. The factory is registered in a jasperreports_extension.properties file at the root of the classpath, so a jar that holds these classes and that file adds the theme to any application it is dropped into, without any other configuration.

The registration file has one line. The segment after registry.factory. is an identifier chosen by the author of the extension, and it only has to be unique among the registrations.

The template then names the theme, on one element or for the whole report:

Both forms ran. With the report-level property, the bar, pie and time series charts took the theme’s white background and bold title font, and the pie got the four category colours and lost its shadow. The spider chart did not change, because it is a component and not a chart element. Its look is controlled by its own settings and customizer, as described below.

The official documentation also describes two XML-driven theme implementations, one on Spring beans and one on Castor XML mapping, with sample themes named aegean, eye.candy.sixties and default.spring. They belong to the separate artifact jasperreports-chart-themes, which exists on Maven Central at version 7.0.8. It was not run for this page, and its registration steps, which the sample page describes as editing lines of a jasperreports_extension.properties file, should be taken from the sample page itself. For most applications a small ChartTheme subclass like the one above is simpler than either.

The sources are the chart themes sample and the API pages of ChartTheme and ChartThemeBundle.

A customizer changes one chart after the engine has created it. It receives the finished JFreeChart and the chart’s definition, and can call any JFreeChart method on it, which makes it the tool for what neither the template nor the theme exposes: item labels on every bar, a marker line at a target value, a fixed axis range, a different renderer. The official documentation recommends themes over customizers for a look that applies to many charts, and keeps customizers for adjustments that belong to a single chart.

The interface is net.sf.jasperreports.charts.JRChartCustomizer, with one method, and the convenient base class is JRAbstractChartCustomizer, which also gives access to the properties set on the chart element. In 7.0.8 both are in the net.sf.jasperreports.charts package of the charts module, so imports in code written for an earlier version should be checked. For the spider chart component the interface is net.sf.jasperreports.components.charts.ChartCustomizer. This customizer draws the value on top of each bar and takes the bar colour from a property of the chart element.

There are two ways to attach it. The customizerClass attribute names the class and is the shortest form, but it gives the customizer no properties, so getProperty returns null and the code above falls back to its default blue; the run showed blue bars with this form. The more flexible way is a pair of properties on the chart element: net.sf.jasperreports.customizer.class.<name> holds the class, and the properties named net.sf.jasperreports.customizer.<name>.<property> are the ones the customizer reads with getProperty("<property>"). The configuration reference lists both patterns, and the official customizers sample attaches several customizers, each with its own name, to one chart. The red bars in the run came from this form:

The artifact jasperreports-chart-customizers ships ready-made customizers for common adjustments, configured only with properties, so no Java is needed. The official customizers sample uses, among others, net.sf.jasperreports.customizers.axis.RangeAxisCustomizer and DomainAxisCustomizer, a category marker customizer, a legend shape customizer and a step customizer. The range axis one ran as shown, and fixed the value axis of a bar chart from 0 to 3000:

A customizer works on the JFreeChart object that the theme created, so one written against the default theme can break if a different theme changes the plot type or the renderer. Casting the renderer, as the example does, ties the customizer to the chart type it is attached to.

The references are the chart customizers sample and the API pages of JRChartCustomizer and JRAbstractChartCustomizer.

A spider chart, also called a radar chart, draws one axis per category and one polygon per series. It is not a chart element but a component, declared inside element kind="component" with a component kind="spiderChart". According to the official sample it was developed to show how a custom component can be built on JFreeChart. Its structure mirrors the chart element, and is the one that ran in the example above:

The plot attributes that the official sample documents are rotation (Clockwise or Anticlockwise), tableOrder (Row or Column), isWebFilled, startAngle (the default is 90 degrees), headPercent, interiorGap, axisLineColor, axisLineWidth, labelGap, labelColor, backcolor, backgroundAlpha and foregroundAlpha, a labelFont child and a maxValueExpression child that fixes the maximum of every axis. The example sets only maxValueExpression, at 1500d, so that the four categories share one scale. The code follows the spider chart component sample, and the element names are those of the SpiderChartComponent API.

The sample states two limits: tick marks and tick labels are not supported on the axes, and negative values are not supported. A spider chart is a poor fit for a handful of categories, as the four-axis diamond in the example shows, and more useful with six or more.

The 3D chart types, bar3D, stackedBar3D and pie3D, are still accepted by the template in 7.0.8, but they no longer draw a 3D effect. The reason is upstream: JFreeChart removed its 3D charts in version 1.5.0, and JasperReports 7 is built on JFreeChart 1.5.6. The official samples carry a notice that the three types are deprecated and will be removed. In the run, a bar3D chart filled and exported without error and came out as flat bars like those of bar, with no depth. Old templates therefore keep working with a different look. The practical advice is to change bar3D to bar, stackedBar3D to stackedBar and pie3D to pie in templates that are being maintained, so that the deprecation does not become a failure on a later upgrade. Books and tutorials that show 3D charts were written for JFreeChart 1.0, and their screenshots cannot be reproduced with the current version.

The built-in element covers the common charts, and plot settings and customizers cover a lot of what it does not. When a chart needs something beyond that, such as a chart type JFreeChart supports but the element does not, or a library with a different look, the application can draw the chart itself and give the template an image. Two routes are documented in the official samples.

The first route keeps JFreeChart as the drawing engine but bypasses the element. An image element accepts a value of type net.sf.jasperreports.renderers.Renderable, and JCommonDrawableRendererImpl in the charts module wraps a JFreeChart Drawable as one, so the chart draws itself on the graphics context. The official sample does this in a scriptlet. Passing the renderer as a parameter, as below, needs no scriptlet and keeps the chart code in the service.

The second route uses a library that produces a bitmap. XChart builds the chart and BitmapEncoder turns it into a BufferedImage, which the template shows through an image element whose expression class is java.awt.Image.

The returned map is added to the fill parameters, next to the data source. The matching parts of the template declare the two parameters and place the image elements:

Both ran with XChart 4.0.4 and JFreeChart 1.5.6, and both images appeared on the page. The JFreeChart chart drew at the size of its element with JFreeChart’s default fonts, which look large in a small box. The XChart image is a bitmap rendered at the size given to the builder and scaled into the element, so it loses sharpness if it is enlarged. The official XChart sample was written for the 3.x API; XChart 4.0.4 was the latest release on Maven Central on the baseline date, and the example compiled against it with the XYChartBuilder and BitmapEncoder.getBufferedImage calls shown. JFreeChart is published under the LGPL and XChart under the Apache License 2.0; both licences should be confirmed on the project pages before a release.

The approaches compare as follows:

Charts are also possible in the iText-based pages of this section: a chart rendered to an image or an SVG with the same libraries can be placed in a document, as described in iText: Colors, Images & SVG.

The two routes follow the official JFreeChart sample and XChart sample.

A chart in the PDF is graphics. Tagged PDF output is a Professional-edition feature in JasperReports 7.0.8, as the architecture page states, and what the community build produces for a chart for assistive technology was not examined here. The dependable approach in either edition is to put the data the chart shows next to it, as a table or in the text, as the detail lines in the example do. Where a PDF has to conform to an accessibility standard, the chart should be treated as a picture of data that is also available as text.

Older tutorials and books on JasperReports charts were mostly written for versions 1 to 5, and their charts differ from what 7.0.8 does in these points.