Package net.sf.jasperreports.components

Contains classes for built-in components.

In addition to the standard report elements, such as text fields, images, charts, subreports and crosstabs JasperReports has an increasing number of core components that can be used to add content to generated reports. Some of them are used for greatly simplifying the creation of complex layouts, others are used to embed highly specialized visualization packages, such as barcodes and other types of graphics, or to generate report interactivity, like the Header Toolbar component.

The purpose of this feature is to allow users to extend the functionality of the JasperReports engine by plugging-in custom-made visual components that would take data as input and produce content that is embedded into the resulting documents. Custom made components can be anything from simple barcodes to tables, and professional charting packages.

The custom component support is relying on two other major features of the JasperReports library: extension support and generic elements and you need to be familiar with them before delving into custom components.

A custom component is a custom report element that has a defined structure and produces some output in generated reports, just like usual report elements do. Just like a normal chart element in a report template will produce an image element in the generated document, or just like a crosstab element present in the report template will produce a series of frames and text fields that makes up a tabular structure in the generated documents, generic custom components declared in a report template could generate any combination of simple elements and generic elements as the output of their built-in calculation and layout logic.

Custom components are supposed to come in bundles. A component bundle is a package comprising of one or several components that share the same XML namespace and schema. For example, a chart component bundle can contain multiple chart components, one for each type of chart (pie chart component, bar chart component and so on).

Custom Components Use Cases Examples

In the following use case example, we consider a JasperReports user that wants to replace the JFreeChart library (bundled with JasperReports by default for the built-in charting support) with some other charting package.

Following are the few steps required to achieve it:

  • A new component bundle is developed. The bundle can contain several components, that is, one per chart type.
  • An XML schema for the chart components is designed.
  • The schema uses a namespace reserved for the chart component implementation.
  • A Java object model is designed for the chart components.
  • Chart components can (optionally) use report subdatasets to produce data.
  • The component implementation produces JRPrintImage instances when the report is filled. The images can use a custom image renderer (Renderable) implementation.
  • The developed component code is bundled into a JAR and placed on the application's classpath.
  • Report designers can now embed custom charts into JRXMLs.

Custom Component Implementation Overview

A typical implementation of a custom component would involve the following:
  • A jasperreports_extension.properties resource which registers an extension factory that reads a Spring beans file.
    The Spring beans file that includes one or more beans of type ComponentsBundle. Most of the time the default implementation DefaultComponentsBundle is used.
  • A component bundle includes:
  • A set of component types retrieved via ComponentsBundle.getComponentTypes() method
  • One or more component managers, ComponentManager implementations, usually instances of DefaultComponentManager. A component manager is an entry point through which the handlers for a single component type can be accessed. It contains:
    • A component compiler (ComponentCompiler implementation) that handles a component instance during report compile. It contains methods to collect report expressions from a component instance, to validate such a component and to create a component object that is included in the compiled report.
    • A component converter (ComponentDesignConverter implementation) which onverts a component element into a print element that represents a preview of the component.
    • A factory of component fill instances, ComponentFillFactory implementation.
    • Such a factory would produce custom FillComponent instances. A fill component object is responsible for managing a component at fill time. A typical implementation would evaluate a set of expressions and use the results to create a print element to be included in the generated report.
  • If the component needs to generate an output elements that do not fall into the types built into JasperReports (such as texts/images), the component can produce generic print elements.
    To handle such generic elements at export time, custom generic element handler implementations need to be written
  • If the component implementation generates charts, or, more generically, if it needs to collect data from several records in the report dataset or from subdatasets, the component object model will contain classes derived from abstract JasperReports element dataset classes. These classes offer the infrastructure required to collect data from report datasets.
    More specifically, the following classes would be extended by the component implementation:

    • When implementing custom components, the most helpful information can be found in the form of JasperReports API Javadoc and samples. The following samples found in the /demo/samples folder of the JasperReports project distribution package show custom components:

    • Barbecue: A sample that illustrates the use of the Barbecue component built into JasperReports.
    • Barcode4j: A sample that displays barcodes using the Barcode4j component built into JasperReports.
    • xchartcomponent: A chart component implementation that outputs axis charts generated by the XChart library (http://knowm.org/open-source/xchart/).