# Package net.sf.jasperreports.extensions

Provides support for extension points.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  ExtensionsRegistry | A registry of JasperReports extensions.
  ExtensionsRegistryFactory | A factory of `ExtensionsRegistry` instance.

- Class Summary
  Class | Description
  --- | ---
  DefaultExtensionsRegistry | The default `extension registry` implementation.
  DefaultExtensionsRegistryFactory |
  ExtensionsEnvironment | A class that provides means of setting and accessing `ExtensionsRegistry` instances.
  ListExtensionRegistry<Type> | An extension registry that contains a list of extensions.
  ListExtensionsRegistry | An extension registry that contains several lists of extensions.
  SingletonExtensionRegistry<Type> | An extension registry that contains a single extension.
  SpringExtensionsRegistry | An `extension registry` which works by looking for beans of a specific extension type in a Spring beans factory.
  SpringExtensionsRegistryFactory | A `ExtensionsRegistryFactory` which works by loading a Spring beans XML file and using beans of specific types as extensions.

## Package net.sf.jasperreports.extensions Description

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:

`ExtensionsRegistry createRegistry(String registryId, JRPropertiesMap properties);`

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 font extensions mechanism.

### Related Documentation

JasperReports Tutorial

© 2001-2010 Jaspersoft Corporation www.jaspersoft.com