Creating a Custom Data Source

If you have an existing JRDataSource implementation used with JasperReports Library that you'd like to use in JasperReports Server, you need to implement the supporting classes and configure the server. You need to create or edit the following files:

Files Used by a Custom Data Source Implementation

Type

Path (relative to web app directory)

Description

Java classes

WEB-INF/lib or WEB-INF/classes

The logic of your JasperReports data source, the supporting interfaces, and any optional classes compiled into JAR files.

Spring bean definition

WEB-INF/applicationContext-<name>.xml

The configuration of the data source within the server's web application.

Message catalog

WEB-INF/bundles/<name>.properties

also <name>_<locale>.properties

Strings such as the name of the data source type in the New Data Source dialog, names for visible properties, and any validation messages. You can translate the strings for other locales in multiple files.

Query language
configuration (optional)

WEB-INF/applicationContext-[pro-]remote-services.xml or

WEB-INF/applicationContext-custom.xml and WEB-INF/js.spring.properties

If your JR data source is created using a query executer and you want the query language to be available in the UI, such as input control dialogs

These files work together to make your custom data source type available in the user interface and to instantiate your custom JRDataSource, as described in the following sections.

Writing Java Classes

As seen in Custom Data Source Architecture, you must provide additional classes so that the server can instantiate your custom JRDataSource when needed with the requested parameters. This is the purpose of the ReportDataSourceService interface that you must implement. For code samples, see Custom Data Source Examples.

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. It defines the following methods:

The ReportDataSourceService Interface
Interface	Method to Implement	Description
ReportDataSourceService	void setReportParameterValues(Map parameterValues)	Called before running a report; it creates resources needed by JasperReports Library to instantiate a JRDataSource, and adds them to the parameter map.
	void closeConnection()	Cleans up any resources allocated in setReportParameterValues().
	Property setters and getters	A getter and setter method corresponding to each parameter name, including hidden properties; for example, if you defined a property with the name user, you need getUser() and setUser() methods.

Defining Custom Data Source Properties

A custom data source definition can have properties so that users may 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. Ultimately, it is your JRDataSource that determines what properties are needed.

There are two kinds of properties:

•

Editable properties that must be string values. When a user launches the New Data Source dialog to create an instance of your custom data source definition, the editable properties have text fields for user input. These values are persisted in the repository when you save the data source.

•

Hidden properties that can be of any type. You set these property values in the Spring configuration file to be passed to your ReportDataSourceService implementation. Therefore, they do not appear in the New Data Source dialog, nor do they need to be persisted in the repository. Use hidden properties if you want to give your ReportDataSourceService implementation access to a Spring bean instance.

These properties are defined in two places that must work together:

•

Your ReportDataSourceService implementation must have getters and setters for each property, and your code can use the values for any type of processing. For source code examples, see Hibernate Custom Data Source.

•

The Spring beans need the list of properties to set up the New Data Source dialog, save the user values in the repository, and later instantiate your ReportDataSourceService when needed to fill a report. For examples of both editable and hidden properties, see the XML example in Defining the Custom Data Source in Spring.

Implementing the Optional Validator Interface

A validator verifies property values entered by the user and rejects bad values with an optional message. The validators are applied to the editable properties that are returned from the New Data Source dialog, before a data source is being stored in the repository.

You can implement any level of validation that you need, such as:

•

Null check (presence or absence of value)

•

Type validation (string or number)

•

Syntax validation (format or contents of a string)

•

Range validation (value of a number)

Property values may include references to attributes, whose values are not determined until the data source is instantiated when running a report. An attribute has the following syntax: {attribute('attrName')} or {attribute('attrName','[user|Tenant|Server]')}. Your validator code should recognize these patterns in property value strings and allow or skip validation of the attribute reference.

To create a validator, implement the CustomDataSourceValidator interface as follows:

Optional Validator Interface
Interface	Method to Implement	Description
CustomDataSourceValidator	validatePropertyValues(CustomReportDataSource ds, Errors errors)	Your code checks parameters and calls errors.rejectValue() with the appropriate property name and error code (see Defining the Message Catalog).

For a source code example of the CustomDataSourceValidator implementation, see Webscraper Custom Data Source.

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	Description
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.
	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.

Query Executers must be registered with the JasperReports Library before use. For instructions and source code examples, see Webscraper Custom Data Source.

Implementing Optional Domain Support

To use your custom data source in Domains and Ad Hoc views, you must implement the CustomDomainMetaData interface.

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

For source code examples, see the links to Java files in Custom Data Source Pro and Pre-installed Data Source Types.

Defining the Custom Data Source in Spring

To configure your data source, you must add a Spring bean that references the customDataSourceFactory so that it will be visible to the server at run time. To do this, create a new file in the web application:

.../WEB-INF/applicationContext-<name>.xml

Within this file, there are two ways to configure your data source:

•

If you implemented the ReportDataSourceService interface, use the CustomDataSourceDefinition class.

•

If your data source extends DataAdapterDefinition, you can configure your data source as 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. See the table below.

The propertyDefinitions property is a list of maps, each one describing a property of the custom data source implementation. Each map 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; 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

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:

      [/code]

Defining the Message Catalog

The message catalog contains labels and 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 in its Spring definition.
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	<cdsname>.<propname>.<error> where <propname> is the name of the property that is invalid, and <error> is the type of error. 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.
Query language	query.language.<qlname>.label where <qlname> is the name of the query language. Define this property if you implement the optional query language and want to give your query language a different name, or want to have localized names for it in a bundle.

For example, the webscraper message catalog contains the following:

If you use your JasperReports Server in multiple languages, you can provide multiple copies of the message catalog, with translated strings (known as a message bundle). Each file name contains the locale to which it applies, according to the Java convention, for example cdstest_fr.properties. By convention, all message catalogs or bundles are stored in:

.../WEB-INF/bundles

To configure your message catalog, add a bean definition such as the following to the Spring definition file that you created in Defining the Custom Data Source in Spring:

For the value property, specify the path and name of your message catalog file, omitting the .properties extension.

Adding the Custom Query Language to the UI

If you implemented the optional Query Executer, you must add it to the Spring configuration to make the query language for your custom data source definition appear in the UI. 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.

If you are using a commercial edition of JasperReports Server, edit the file .../WEB-INF/applicationContext-pro-remote-services.xml and locate the queryLanguagesPro bean. Add the name of your query language to the list, for example:

    <bean id="queryLanguagesPro" parent="queryLanguagesCe"          class="org.springframework.beans.factory.config.ListFactoryBean">        <property name="sourceList">            <list merge="true">                <value>sl</value>                <value>MyQueryLanguage</value>            </list>        </property>    </bean>[/code]

If you are using the community edition of JasperReports Server, edit the file .../WEB-INF/applicationContext-remote-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.

Alternatively, you can add your query executor as a separate bean without modifying the existing Spring configuration. In that case you would:

•

Create a bean similar to queryLanguagesPro above, but that extends queryLanguagesPro if you are using a commercial edition. Save this bean with id=customQueryLanguage in a file named .../WEB-INF/applicationContext-customQueryLang.xml. Of course, you can use your own names for the id and file name.

•

Edit the file .../WEB-INF/js.spring.properties and modify the following line:

    bean.queryLanguages=queryLanguagesPro[/code]

so that it references the id of your new bean, for example:

    bean.queryLanguages=customQueryLanguage[/code]

After editing and saving the files, restart JasperReports Server.

Installing a Custom Data Source Type

To install your custom data source type in JasperReports Server, add all the files it requires to the server web application directory. For the correct locations, refer to Files Used by a Custom Data Source Implementation.

After adding the files and making the configuration changes specified in the previous sections, restart JasperReports Server.

Using a Custom Data Source Type

When you create a new data source type in JasperReports Server, it appears in the list of available types in the New Data Source dialog. If the custom data source is not listed as an available data source type, the custom data source is not properly installed.

When the new type is selected, JasperReports Server displays the fields and labels for the visible properties you configured. Users may enter values directly, or they may use attribute syntax to specify user, organization, or system attribute values. The server resolves any attribute values before passing the values to your ReportDataSourceService at run time.

When the form is submitted, the property values are validated with your optional CustomDataSourceValidator implementation and appropriate validation messages are displayed. Once the data source is validated, you can save it to the repository. The data source can now be used in a JRXML report. When you run a JRXML report, Domain, Ad Hoc view, or dashboard that uses this data source, the saved property values are used by your ReportDataSourceService implementation to instantiate your JRDataSource which then provides the data to run the report.

Open topic with navigation

Sign In