Package net.sf.jasperreports.extensions

Provides support for extension points.

Extension Support

The JasperReports functionality can be extended in various ways, but is usually done by implementing public interfaces that the library already exposes.

The best example is with report data sources. Report data sources are instances of the JRDataSource interface. In cases where reporting data is available in a custom format which is not understood by the built-in data source implementations that the JasperReports library comes with, the parent application needs to implement that JRDataSource and thus teach the reporting engine how to iterate through that custom data and how to get the values of the fields corresponding to each virtual record in that virtual data table. By implementing the data source interface that JasperReports exposes, the parent application as thus extended the library's functionality.

This is the case with other public interfaces that the library exposes, including, but not limited to custom components, query executers, hyperlink producers, chart themes, font bundles, etc.

In order to simplify the way JasperReports can be extended and the way those extensions are deployed, or made available to a given JasperReports deployment, built-in support for extensions was introduced in the library and then various features of the library where made extension-friendly and thus transformed into extension points.

The extension support of JasperReports allows people to implement the various interfaces that the library exposes through predefined extension points and to put together all those implementation classes in single JAR, which can be then added to the classpath of the application where JasperReports runs, making them all available to that JasperReports running instance. The only requirement for the construction of the JAR file is the presence of a jasperreports_extension.properties file in its root package. This properties file is used for describing the content of the JAR.

Basically, at runtime, the JasperReports engine will read this file and try to understand what extensions where provided within the JAR, making them available to all interested extension points.

Extension registry

JasperReports looks for available extensions by loading all the jasperreports_extension.properties files that it can find in the default package.

Note that many such files can be found, because although they are all having the same name and being in the default Java package, they can actually sit in different JAR files that are present in the application's classpath.

This special properties file should contain properties in the following format:

 
 net.sf.jasperreports.extension.registry.factory.<registry_id>=<extension_registry_factory_class>
Each such property gives the name of an extension registry factory class and also names the extension registry (through the property's suffix). Some extension registry factories make use of this suffix. For example, they could use this name of the extension registry to look for other properties in the same file, properties that would help configure the extension registry factory itself.

The extension registry factory should be an implementation of the ExtensionsRegistryFactory interface. It produces instances of the ExtensionsRegistry interface, based on the registry_id value (the suffix mentioned above) and the properties read from the current jasperreports_extension.properties file. The signature of the single method that this factory interface exposes is as follows:

createRegistry(String, JRPropertiesMap)

The extension registry obtained from the factory is able to return a list of actual extension point implementations based on extension point class type.

For example, in JasperReports, query executers can be added as extensions in the form of query executer bundles. The predefined query executer extension point in JasperReports is represented by the QueryExecuterFactoryBundle interface, from which query executer implementation are retrieved based on the query language name. The extension registry implementation is expected to return a list of query executer factory bundles in this case.

Another example of an extension point in JasperReports are the chart themes. They are also expected to come in bundles, based on their name, so the associated extension point interface for them is the ChartThemeBundle interface. In this case, the extension registry implementation is expected to return a list of chart theme bundle instances.

A third example of an extension point is represented by the hyperlink producers. The associated extension point interface is the JRHyperlinkProducerFactory interface and thus the extension registry implementation should return a list of those.

Spring Extension Registry Factory

JasperReports is shipped with a convenience implementation of the ExtensionsRegistryFactory interface that can be used to load extensions from a Spring bean XML file.

This convenience extension registry factory implementation is the SpringExtensionsRegistryFactory class and works by loading a Spring beans XML file and using beans of specific types as extensions.

The factory requires a property named net.sf.jasperreports.extension.<registry_id>.spring.beans.resource to be present in the properties map passed to the

createRegistry(String, JRPropertiesMap)

method. The value of this property must resolve to a resource name which is loaded from the context class loader, and parsed as a Spring beans XML file.

Once the Spring beans XML file is loaded, this factory creates a SpringExtensionsRegistry instance which will use the bean factory. This Spring-based extension registry factory is used by the built-in chart themes extensions mechanism.

Related Documentation

JasperReports Tutorial