Creating a Custom Data Source

Creating a Custom Data Source Type

This section describes how to create a custom data source type to support an existing JasperReports data source in JasperReports Server.

Files Used by a Custom Data Source Implementation

Type

Path (relative to web application directory)

Java classes

WEB-INF/lib or WEB-INF/classes

Spring bean definition

WEB-INF/applicationContext-<name>.xml

where <name> is unique

Message catalog

WEB-INF/bundles/<cat_name>.properties

where <cat_name>is unique

Query language configuration (optional)

WEB-INF/flows/queryBeans.xml

Java Implementation

Implementing the ReportDataSourceService Interface

A custom data source definition requires an implementation of the ReportDataSourceService interface, which sets up and tears down data source connections in JasperReports Server. ReportDataSourceService relies on:

•

void setReportParameterValues(Map parameterValues): called before running a report; it creates resources needed by JasperReports Library to obtain a JRDataSource, and adds them to the parameter map.

•

void closeConnection(): cleans up any resources allocated in setReportParameterValues().

Defining Custom Data Source Properties

A custom data source definition can define properties that help users configure each data source instance differently, in the same way that a JDBC data source has properties for JDBC driver class, URL, user name, and password. While implementing your ReportDataSourceService, Jaspersoft recommends that you consider which properties you’ll need.

There are two kinds of properties:

•

Editable properties that must be string values. When you use the New Data Source dialog to create an instance of your custom data source definition, you can enter values for the editable properties using text fields. These values are persisted when you save the data source.

•

Hidden properties that can be of any type. These property’s values are determined by the Spring configuration file: they are not persisted, nor are they visible in the New Data Source dialog. Use them to give your ReportDataSourceService implementation access to a Spring bean instance.

For an example of both types of properties, see the custom bean data source definition in the XML example in Defining the Custom Data Source in Spring.

These property values are set by the custom data source framework after it instantiates your ReportDataSourceService implementation. You need property setters and getters corresponding to each property name; for example, if you defined a property with the name foo, you need getFoo() and setFoo() methods.

Implementing Optional Query Executer Interfaces

If you want to use the value of the queryString in the JRXML to obtain your data source, you must create implementations of the JRQueryExecuter and JRQueryExecuterFactory interfaces.

Optional Query Executer Interfaces
Interface	Method to Implement	Notes
JRQueryExecuterFactory	JRQueryExecuter createQueryExecuter(JRDataset dataset, Map parameters)	Returns a `JRQueryExecuter` for the given dataset and parameter map.
JRQueryExecuter	JRDataSource createDatasource()	Returns the actual data source based on the parameter map passed to the JRQueryExecuterFactory; most likely, you will create a JRDataSource implementation suitable for your data source.
	close()	Called when the report filling process is done with the data source.
	cancelQuery()	Called to clean up resources if the report filling process is interrupted.
CustomDataSourceValidator	validatePropertyValues(CustomReportDataSource ds, Errors errors)	Use this to provide validation in New Data Source dialog. It checks parameters and calls errors.rejectValue() with the appropriate property name and error code (defined in a message catalog; for more information, refer to Creating the Message Catalog).

Implementing Optional Domain Support

To use your custom data source in Domains, you must implement CustomDomainMetaData.

Optional Domain MetaData Interfaces
Interface	Method to Implement	Notes
CustomDomainMetaData	getFieldMapping()	Mapping between names in the data source and names to show in the Domain, as key value pairs.
	getJRFieldList()	return list of JRFieldName (name, type, description) for custom data source (basically list of columns)
	getQueryLanguage()	query language specified in the query executor you are using
	getQueryText()	query text used by the custom data source.

Creating the Message Catalog

The message catalog contains messages displayed in the New Data Source dialog when creating and editing custom data source instances. The various types of messages are shown in the following table, along with message naming conventions:

Messages about Instances of Custom Data Sources
Message Type	Naming Convention
Name of the custom data source type	Cdsname.name (where cdsname is the value of the name property of the custom data source).
Name of the custom data source property	Cdsname.properties.propname (where propname is the name of the property that the user must define when creating a custom data source).
Validation messages	The CustomDataSourceValidator implementation will call errors.rejectValue() for errors detected in property values for the custom data source. The second argument to errors.rejectValue() must match one of the messages defined in this catalog.

For example, the webscraper message catalog contains the following:

Defining the Custom Data Source in Spring

To configure your data source, you must add a definition to the Spring bean definition file. You can do this in one of two ways:

•

Using an instance of CustomDataSourceDefinition

•

Using a data adapter

Using CustomDataSourceDefinition

This class has the following properties:

Properties of CustomDataSourceDefinition Class
Name	Required	Value
factory	Yes	A fixed value of ref="customDataSourceFactory" This bean manages all the custom data sources.
name	Yes	A unique name that identifies this data source to the custom data source framework. It is also used as a prefix for all messages in the message catalog. Choose the name that is not used by other custom data sources.
serviceClassName	Yes	The class name for your ReportDataSourceService implementation.
validator	—	An instance of your CustomDataSourceValidator implementation.
property Definitions	—	Information describing each property used by the data source implementation, structured as a list of maps.

The propertyDefinitions property is a list of maps, each one describing a property of the custom data source implementation. It includes these entry keys:

Entry Keys for propertyDefinitions Property
Name	Required	Value
name	Yes	Name of property that matches a Java Bean property in the ReportDataSourceService implementation; it is also used in message catalog keys.
default	—	A default value for the property.
hidden	—	If a property has the hidden entry key set to true, then its value is fixed to that of the default entry key. Such properties are not visible in the New Data Source dialog, nor are they persisted. This is handy for making Spring beans accessible to ReportDataSourceService implementations.

The following XML defines a CustomDataSourceDefinition bean for the custom bean data source example:

Using a Data Adapter

As of JasperReports Server 6.0, you can create a custom data source based on a data adapter in JasperReports Library. In this case, your query executer gets the custom data source properties from the data adapter.

To do this, you must first create an instance of your class in your custom data source definition Java code, implementing any additional properties you want:

public class MyCustomDataSourceDefinition extends DataAdapterDefinition {...}[/code]

Then you must create a bean for the data source in your XML file, using the class you defined in your Java file. In addition, you must specify the correct data adapter implementation in your dataAdapterClassName property. For example, the following XML defines a bean for the Mongo DB Query example:

<bean id="mongoDBQueryDataSource" class="example.cdspro.MongoDbDataSourceDefinition">  <property name="factory" ref="customDataSourceServiceFactory"/>  <property name="name" value="mongoDBQueryDataSource"/>  <property name="dataAdapterClassName" value="com.jaspersoft.mongodb.adapter.MongoDbDataAdapterImpl"/></bean>[/code]

Specifying the Message Catalog

Defining the Custom Data Source in Spring:

For the value property, substitute the location of your message catalog file, omitting the .properties extension. Note that if you also supply localized versions of the message catalog that follow the Java conventions for naming resource bundles, users with other locales automatically see the localized strings when creating a new data source of this type.

Adding the Custom Query Language to the UI

To make the query language for your custom data source definition appear in the UI, you must edit the file described in this section. Query languages can be selected from a drop down list when defining query resources such as query-based input controls. The server matches the name of the query language to your data source to use its custom query executor class.

Edit the file <js-webapp>/WEB-INF/applicationContext-rest-services.xml and locate the queryLanguagesCe list. Add the name of your query language to the list, for example:

    <util:list id="queryLanguagesCe">        <value>sql</value>        <value>hql</value>        <value>domain</value>        <value>HiveQL</value>        <value>MongoDbQuery</value>         <value>cql</value>        <value>MyQueryLanguage</value>    </util:list>[/code]

The name must be a language supported by your query executor. After saving the file, restart JasperReports Server.

If the custom data source is not listed as an available data source type, the custom data source is not properly installed.

Sign In