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 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 | 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). |
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 JRField Name (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 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 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 | 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:
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 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 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] |
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/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.
Recommended Comments
There are no comments to display.