MyEclipse Logo

MyEclipse Reports - Working with MyEclipse JDBC Data Sources


Table of Contents

  1. Introduction
  2. MyEclipse JDBC Data Source Basics
  3. Creating a MyEclipse JDBC Data Source
  4. Editing a MyEclipse JDBC Data Source
  5. MyEclipse JDBC Data Source Validation and Synchronization
  6. Feedback

1. Introduction

The data used to create MyEclipse reports can be retrieved from a number of physical sources such as relational databases, web-services, XML files or even flat files. To minimize the complexity that would result if the MyEclipse report engine and report designer were required to understand and implement the interface for interacting with all of these very different data providers, MyEclipse Reports uses a programmatic abstraction known as a "data source". A data source insulates the MyEclipse report engine and report design tools from the implementation details of connecting with the physical provider of data for a report. In this tutorial we will introduce the basic concepts and tools for working with a special type of data source known as the MyEclipse JDBC data source.

For an overview of the MyEclipse Reports tools and development features, see the MyEclipse Reports Overview document.

Suggested Audience

This tutorial assumes the reader is familiar with the MyEclipse Database Explorer features. To get a better feel for the full scope of MyEclipse, please check out our product documentation.

System Requirements

This tutorial was created using MyEclipse 6.0.1 Professional Edition. If you are using a more recent version of MyEclipse, most of the images and instructions should be backward compatible.

MyEclipse Reports requires MyEclipse 6.0.1 or above. It is a Professional level feature and is only available to MyEclipse Pro subscribers.

2. MyEclipse JDBC Data Source Basics

The MyEclipse Database Explorer consists of a rich set of relational database browsing and development tools. The Database Explorer interacts with relational database systems using the respective JDBC drivers for each specific relational database, e.g. Oracle, MS SQL Server, MySQL, DB2, etc. MyEclipse Reports is designed to allow use of the Database Explorer's configured JDBC drivers using a special data source known as a MyEclipse JDBC Data Source.

The MyEclipse JDBC Data Source is extremely convenient in that it allows you to reuse existing Database Explorer JDBC drivers and avoid repeating a very similar database driver configuration process in MyEclipse Report that you have already performed in the MyEclipse Database Explorer. It doesn't take much experience working with databases to understand that correctly setting up a JDBC driver can be an error prone process. Thus, by reusing working Database Explorer drivers as data sources in MyEclipse Reports you are assured of a hassle-free driver setup experience when creating a MyEclipse report.

A MyEclipse JDBC Data Source can be used by multiple reports. If you do plan to reuse a data source in multiple report projects, you can create that data source in a library and reuse that data source from the library. The advantage of this approach is that updates to the MyEclipse JDBC data source in the library are subsequently available to all reports that use the library through a sophisticated report-data source synchronization process.

When you create a report design, you use the data explorer, as shown in Figure 3-1, to create and manage data sources. The MyEclipse Report Designer supports using as many data sources as necessary for the report design. The data sources can be of different types, however, MyEclipse supports the use of the MyEclipse JDBC data source which is closely coupled with a corresponding MyEclipse JDBC driver.

3. Creating a MyEclipse JDBC Data Source

  1. Switch to the Report Design perspective, Windows > Open Perspective > MyEclipse Report Design
    The Data Explorer view should be available in the top-left region of the workbench. If this view is not visible open it using Windows > Show Views > Other > MyEclipse Report Design > Data Explorer

      
    Figure 3-1, Data Explorer view

  2. Launch the Report Designer by either creating a report or opening an existing report.
  3. In the Data Explorer view right-click Data Sources, then choose New Data Source from the context menu, See Figure 3-2.


    Figure 3-2, New Data Source action

    This will launch the New Data Source wizard as shown below.


    Figure 3-3, Select Data source type

  4. Select the MyEclipse JDBC Data Source
    Enter "MyEclipse Derby DS" in Data Source Name field
  5. Click Next> to view all of the configured Database Explorer JDBC drivers

     
    Figure 3-4, Select a driver

  6. In the Driver field select the "MyEclipse Derby" driver and click Finish.
    If you wish to create a new MyEclipse JDBC driver, select the "Create new driver..." link. You may also edit existing drivers using the "Edit driver..." link.

    Note: In order to provide seamless MyEclipse Reports integration, only drivers which have their passwords saved may be selected. To learn more about MyEclipse drivers, please see the     Database Explorer Tutorial.

The newly created MyEclipse Derby DS data source should be present in the Data Explorer View.


Figure 3-5, MyEclipse Derby DS data source

During the process of creaing the new MyEclipse JDBC data source, the Database Explorer JDBC driver properties (connection URL, driver class name, username and password) are copied into the report file. Additionally the Database Explorer JDBC driver's JAR files are copied into the folder: <projectName>/WebRoot/Web-INF/report-engine/platform/plugins/org.eclipse.birt.report.data.oda.jdbc_<version>/drivers. These JAR files will be deployable along with your report's web project.

4. Editing a MyEclipse JDBC Data Source

During the life-cycle of a MyEclipse JDBC data source you may have a need to rename the data source or change the associated MyEclipse JDBC driver bound to the data source.

4.1 Renaming a Data Source

To rename a data source, right-click the data source in the data explorer and choose Rename from the context menu. The name that you use must be unique to this report.

4.2 Changing the Database Explorer JDBC driver bound to a Data Source

To change the associated MyEclipse driver:

  1. Select the Data Explorer view.
  2. Expand Data Sources, then right click the data source you wish to modify and choose edit from the context menu as shown below.


    Figure 4-1, Edit Data Source

  3. Use the Driver combo to view and select a new MyEclipse driver. Click OK to commit these changes to your report.


    Figure 4-2, MyEclipse JDBC Data Source Editor

If you change the associated MyEclipse driver, driver JAR(s) from this new driver will be copied into your project.

Because the MyEclipse JDBC data source is coupled to a MyEclipse JDBC driver, the data source's JDBC properties cannot be directly edited in the data source. To change these properties, you must edit them in the associated Database Explorer driver.

5. MyEclipse JDBC Data Source Validation and Synchronization

When you modify a Database Explorer JDBC driver that is bound to a MyEclipse JDBC data source its new state is different from that maintained by the MyEclipse JDBC data source. This state results in a stale JDBC data source and can result in unexpected report results. MyEclipse Reports provides a JDBC data source validation and synchronization tools to detect stale JDBC data sources and resynchronize them with their Database Explorer JDBC drivers.

5.1 JDBC Data Source Synchronization

  1. When you modify a Database Explorer JDBC driver, MyEclipse Reports automatically initiates a validation phase to identify all stale JDBC data source.  When stale JDBC data sources are identified the Data Source Synchronization tool is launched. See Figure 5-1 below.

  2. The Synchronization dialog displays a list of the reports, libraries and templates in your workspace that are bound to the modified JDBC driver. Select the stale MyEclipse Report elements that you wish to update with the new state of the JDBC driver.

  3. Click OK to begin the resynchronization process for the selected report elements.


    Figure 5-1, JDBC Data Source Synchronization Dialog

5.2 Problems View and Warning Markers

During the validation process MyEclipse JDBC data sources are compared with the state of their corresponding Database Explorer JDBC drivers. If there is a mismatch between any of the JDBC properties or the driver JAR files, the report is marked with a Warning icon. This warning can be seen in the Problems view. The report will also be marked with a warning if it references an unsynchronized data source in a library.


Figure 5-2, Properties view with stale JDBC data source warning

5.3 Manual JDBC Data Source Resynchronization

A stale JDBC Data Source situation can persist after the synchronization opportunity described in Section 5.1. There are several reasons that this can happen. For example, the data source validator can not detect stale data sources in a project that is closed and hence these resources will not be available in the Synchronization dialog view. In such cases it is possible to manually synchronize the JDBC data source.

  1. In the Data Explorer select the stale JDBC data source and choose Edit from its context menu
    This will open the Data Source Editor, See Figure 5-3 below.

  2. In the left column select MyEclipse JDBC Data Source. Then click the Synchronize Driver button to resynchronize its state to that of its JDBC driver.


Figure 5-3, Manual Synchronization

Note-1a: Since your report's data source is connected to a MyEclipse JDBC driver, when you preview the results in the Report Designer Preview page, the JDBC properties from the associated Database Explorer JDBC driver will be used to establish the database connection, irrespective of the JDBC properties that may be stored in your report file. At runtime, the JDBC properties in your report will be used.

Note-1b: However, if you provide custom data source property bindings, these bound properties will take precedence over the Database Explorer JDBC driver properties even for the Preview operation. Thus if incorrect property values are specified an unsuccessful database connection might result.


Figure 5-4, Edit Property Binding

6. Feedback

We would like to hear from you! If you liked this tutorial, has some suggestions or even some corrections for us please let us know. We track all user feedback about our learning material in our Documentation Forum.  Please be sure to let us know which piece of MyEclipse material you are commenting on so we can quickly pinpoint any issues that arise.