A custom data source consists of Java code, a message catalog, and a Spring bean definition file that configures all the parts of the implementation with JasperReports Server. This section describes the implementation of a custom data source.
Files Used by a Custom Data Source Implementation
Type
Path (relative to web application directory)
Description
Spring bean definition
WEB-INF/applicationContext-<name>.xml
where <name> uniquely identifies your custom data source
Defines Spring beans needed to configure the data source. Choose a unique name starting with applicationContext- and ending with .xml
Message catalog
WEB-INF/bundles/<cat_name>.properties
where <cat_name> uniquely identifies your custom data source
Defines messages used by the data source implementation (this path is referenced in the Spring bean definition file).
Implementation classes
WEB-INF/lib or WEB-INF/classes
Any Java code required by the implementation.
UI configuration
WEB-INF/flows/queryBeans.xml
Add the query language for your custom data source to the UI.
Implementing the ReportDataSourceService Interface
A custom data source requires an implementation of the ReportDataSourceService interface, which sets up and tears down data source connections in JasperReports Server. It 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 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 JasperReports Server data source wizard to create an instance of your custom data source, 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 data source wizard. 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 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 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 the JasperReports Server data source creation wizard. 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). |
Creating the Message Catalog
The message catalog contains messages displayed by JasperReports Server’s data source wizard 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 an instance of CustomDataSourceDefinition to the Spring bean definition file. 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 | A class name for your ReportDataSourceService implementation. |
| validator | — | An instance of your CustomDataSourceValidator implementation. |
| property | — | 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 be editable in the JasperReports Server data source wizard, 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:
Defining Custom Data Source Properties
A custom data source 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 JasperReports Server data source wizard to create an instance of your custom data source, 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 data source wizard. 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.
Configuring the Message Catalog
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, substitute the location of your message catalog file, omitting the .properties extension. Setting the addMessageCatalog property precludes the need to edit the messageSource bean definition in applicationContext.xml. 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 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/flows/queryBeans.xml and locate the queryLanguages property in the editQueryAction bean. Add the name of your query language to the list, for example:
<bean id="editQueryAction" class="com.jaspersoft.jasperserver.war.action.EditQueryAction"> ... <property name="queryLanguages"> <list> <value>sql</value> <value>hql</value> <value>domain</value> <value>sl</value> <value>HiveQL</value> <value>MongoDbQuery</value> <value>MyQueryLanguage</value> </list> </property> ...</bean>[/code] |
The name must be a language supported by your query executor. After saving the file, restart JasperReports Server.
Installing a Custom Data Source
To install your custom data source 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 section, restart JasperReports Server.
When you create a new data source in JasperReports Server, the new custom data source type appears in the list of available data source types. If the new type is selected, JasperReports Server displays a form containing the list of properties you configured.
When the form is submitted, the parameter values are validated with your CustomDataSourceValidator implementation and appropriate validation messages are displayed. Once the data source is validated, save it to the repository. The data source can now be used in a report or analysis connection.
When defining <queryString> in JRXML, use a language setting that your custom data source supports.
When you add a report to the repository, you can define a local data source or you can select one of the data sources in the repository. In either case, you can use a data source based on your custom data source implementation. In the case of a data source in the repository, you must create it before adding the report. If, during the creation of your data source, the custom data source is not listed as an available data source type, the custom data source is not properly installed.
Recommended Comments
There are no comments to display.