Jump to content
  • This documentation is an older version of JasperReports Server Ultimate Guide. View the latest documentation.

    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


    Path (relative to web application directory)

    Java classes

    WEB-INF/lib or WEB-INF/classes

    Spring bean definition


    where <name> is unique

    Message catalog


    where <cat_name>is unique

    Query language configuration (optional)


    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


    Method to Implement



    JRQueryExecuter createQueryExecuter(JRDataset dataset, Map parameters)

    Returns a JRQueryExecuter for the given dataset and parameter map.


    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.


    Called when the report filling process is done with the data source.


    Called to clean up resources if the report filling process is interrupted.


    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


    Method to Implement




    Mapping between names in the data source and names to show in the Domain, as key value pairs.

    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






    A fixed value of ref="customDataSourceFactory"

    This bean manages all the custom data sources.



    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.



    The class name for your ReportDataSourceService implementation.


    An instance of your CustomDataSourceValidator implementation.


    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 of property that matches a Java Bean property in the ReportDataSourceService implementation; it is also used in message catalog keys.


    A default value for the property.


    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.

    User Feedback

    Recommended Comments

    There are no comments to display.

    This is now closed for further comments

  • Create New...