Sample Custom Data Source Types
The WAR file installer includes several sample data source types in the <js‑install>/samples/customDataSource directory. These samples are not intended for production use. Use and modify these samples to understand how to set up JasperReports Server to connect to an existing JasperReports data source. You can build and deploy the examples after you have deployed JasperReports Server. The following samples are available:
| • | Custom Bean Data Source type |
| • | Webscraper Data Source type |
| • | Hibernate Data Source type |
Installing the Sample Custom Data Source Types
The sample directory includes:
| • | readme.txt: Text file describing how to build the examples. |
| • | build.xml: The Ant build file. |
| • | src: Java source directory. |
| • | webapp: A directory containing other files required by the examples, such as JSPs and Spring configuration files, which are copied directly to the JasperReports Server web application directory. |
| • | reports: A directory containing example JRXML files that use the sample custom data source types. |
Prerequisites
The <js‑install>/samples/customDataSource directory includes an Ant script that compiles the Java code for the samples and places all the required files in the correct locations in JasperReports Server. To run the Ant script, you need the correct versions of the Java Development Kit and Apache Ant.
Java Development Kit:
The examples are provided as Java source files. To work with the examples, you must install the Java Development Kit (JDK). Ensure that the JAVA_HOME environment variable points to a full JDK installation. The samples are supported only with JDK 1.6.
Apache Ant:
Ant is installed as part of the JasperReports Server installation process. Run Ant using the following command:
| Linux: | <js-install>/apache-ant/bin/ant <ant-arguments> |
| Windows: | <js-install>apache-antbinant.bat <ant-arguments> |
If you cannot find Ant on your system, you can download it from http://ant.apache.org. The bundled Apache Ant is version 1.9.4; this version or higher is recommended.
Installation Procedure
To install the samples in your JasperReports Server web application:
| 1. | At the command line, change directories to the custom data source sample directory (<js‑install>/samples/customDataSource). |
| 2. | Edit build.xml and set the webAppDir property to the root of the JasperReports Server web application. |
| 3. | Run the Ant command (as described in Prerequisites) with no arguments; this executes the default target, which is named deploy. The deploy target initiates these actions: |
| • | Compiles the Java source files under the <js‑install>/samples/customDataSource/src directory. |
| • | Deploys the compiled Java class files to the web application. |
| • | Deploys files under the webapp directory to the web application. |
| 4. | Restart the application server. |
The example custom data source types are now available from the New Data Source page in JasperReports Server.
To test the samples and create or view reports:
| 1. | Log on to JasperReports Server as an administrator. |
| 3. | Open the New Data Source page (for example, by selecting Create > Data Source for the main menu), enter the required values for the data source type you selected, and save the data source. See the JasperReports Server Administrator Guide for more information about creating data sources. |
| 4. | To test a sample, upload the associated report from the <js‑install>/samples/customDataSource/reports directory and view the report. |
Custom Bean Data Source Type
My Custom Data Source shows how to create a data source type for a custom bean JasperReports data source. It includes the following:
| • | A sample custom bean JasperReports data source implemented as a collection of Java beans declared in the source code. |
| • | The Java code required to set up and tear down a connection from JasperReports Server to the JasperReports data source. |
| • | The Spring bean definition file for the custom data source type (<js‑install>/samples/customDataSource/webapp/WEB-INF/applicationContext‑sampleCDS.xml). |
| • | An example report that uses this data source type (<js‑install>/samples/customDataSource/reports/simpleCDS.jrxml). |
Webscraper Custom Data Source Type
An implementation of the webscraper custom data source type fetches a web page, decodes its HTML, and extracts selected data that is turned into field values in the data source. The Spring bean definition file for this custom data source type is located in:
<js‑install>/samples/customDataSource/webapp/WEB-INF/applicationContext-webscraperDS.xml
The webscraper data source type definition includes these elements:
| • | URL: An HTTP URL that refers to the HTML page containing the desired content. |
| • | DOM path: An XPath expression that locates HTML elements to be turned into rows in the data source. |
| • | Field paths: XPath expressions for each field defined in the JRXML. JasperReports Server uses these paths to locate the field value in each row selected by the DOM path. |
The data source takes two parameters: the URL of the web page and the XPath that determines how elements in the HTML page become rows in the data source. The parameters can either be specified by a data source definition in the repository or by a query string in the JRXML. The <js-install>/samples/reports/webscrapertest.jrxml report has no query. Instead, it relies on an instance of the custom data source that you must create in the repository. Set the URL and DOM Path according the website you are trying to access.
When a data source of this type is used in a report, dashboard, or Ad Hoc view, JasperReports Server creates a JasperReports data source by:
| • | Using the URL to issue a GET request for an HTML page. |
| • | Using the DOM path to select XML elements from the converted response. |
| • | Creating a new data source row for each selected element. |
| • | Determining the context for each field based on its field path. |
|  | Web sites are frequently redesigned and the URLs used by any website are subject to change. This can affect your reports. |
In order to use the webscraper data source, you must first register the webscraper query executer factory. One way to do this is as follows:
| 1. | Open the file <js-install>/WEB-INF/classes/jasperreports.properties for editing. |
| 2. | Add the following at the end of the file: |
# registering query executer for webscraperQEtest.jrxml examplenet.sf.jasperreports.query.executer.factory.webscraper=example.cds.WebScraperQueryExecuterFactory[/code] |
| 4. | Restart your application server. |
For more information about registering query executors, see the Report Query section in the JasperReports Library Ultimate Guide.
Hibernate Custom Data Source Type
The Hibernate custom data source type implementation supports Hibernate Query Language (HQL) queries in report units in JasperReports Server. The Spring bean definition file and related Java code for the Hibernate custom data source example are in the following locations in the <js‑install>/samples directory:
| • | <js‑install>/samples/customDataSource/webapp/WEB-INF/applicationContext-hibernateDS.xml – Spring bean XML to configure the Hibernate data source |
| • | <js‑install>/samples/customDataSource/src/example/cds/HibernateDataSourceService.java – implementation of ReportDataSourceService for the data source |
| • | <js‑install>/samples/customDataSource/src/example/cds/HibernateSessionFactoryFinder.java – a helper class used to locate a SessionFactory instance for HibernateDataSourceService |
The implementation works with the JasperReports Library's support for HQL queries to create a data source. The library will use the JRHibernateQueryExecuter to run an HQL query in a report unit, and this query executer needs a Hibernate Session object. The Hibernate custom data source will create the session from a Hibernate SessionFactory configured as a Spring bean in JasperReports Server.
The Hibernate data source configuration on the data source menu in JasperReports Server includes the following element:
| • | Session Factory Bean Name: A SessionFactory created with a named Spring bean of class SessionFactory, HibernateDaoSupport, or one of their subclasses. |
Using the Hibernate Data Source Type Example
The sample Hibernate test report contains an HQL query on the JasperReports Server repository, which uses Hibernate internally. After you have installed the samples using ant as described in Installing the Sample Custom Data Source Types , you can configure a Hibernate data source and load the test report as follows:
| 1. | Create a new Hibernate data source: |
| a. | Create a data source and select Hibernate data source for the type. |
| b. | Enter sessionFactory for the name of the SessionFactory bean – this is the id of the repository's Hibernate SessionFactory. |
| c. | Save the data source and give it a name when prompted. |
| 2. | Upload and configure the sample report: |
| a. | Navigate to the repository location where you want to save the report. |
| b. | Right-click and select Add Resource > JasperReport. The Add JasperReport page is displayed. |
| c. | On the Set Up page, enter a name for the report unit. |
| d. | Select Upload a Local File, click Browse, select <js‑install>/samples/reports/hqlTest.jrxml, and click OK. |
| e. | On the Data Source page, click Select data source from repository and browse to the data source created in the previous step. |
| f. | Click Submit to save the report. |
Click on the new report, which should show a list of resources in the repository.
Recommended Comments
There are no comments to display.