Contents


The BIRT ODA extension point

Extend BIRT's data-retrieval capabilities

Comments

The extensibility of the Business Intelligence Reporting Tools (BIRT) is one reason it is a powerful reporting platform. Built on top of Eclipse, BIRT uses the Eclipse plug-in framework to enhance and extend its capabilities. Several different extension points are defined in BIRT. The more prominent extension points include:

  • Open Data Access (ODA) framework for retrieving data
  • Report item extension point for adding new report items to BIRT's palette
  • Emitter framework for expanding BIRT's output capabilities
  • Function script library for extending BIRT's helper methods in BIRT script and in BIRT expressions
  • Aggregation extension point, which allows users to aggregate values of a data set

In previous articles I covered the aggregation and the emitter frameworks (see Related topics for links). This article focuses on one of the other heavily used extension points, the Eclipse Data Tools Platform (DTP) ODA framework. ODA is a BIRT framework that you can use to extend BIRT's data-retrieval capabilities. Knowing this framework allows system integrators to extend BIRT beyond the realm of strictly database reporting. By writing different emitters, BIRT extends to report on flat files, Plain Old Java™ Objects, indexed data stores used for high-speed search applications such as Apache Solr and Lucene search, and to work directly with IBM® Maximo® data application programming interfaces (APIs), and big data sources such as Apache Hadoop and other MapReduce-based storages.

Understand the data extraction task

In this example, you use the BIRT Report Engine API data extraction task to retrieve data. You use the data extraction task to extract data from a previously run BIRT report by retrieving the data from BIRT's report document file. The task requires the name of a report document and the name of a table with a data set binding. This task allows an application to use a report document as a temporary cache that contains all the bindings, expressions, and aggregations. You can then apply sorts during the retrieval process.

By writing an ODA that can retrieve data from a report document file, you can write reports against existing reports, opening a whole new set of possibilities for the open source BIRT, such as run-once data sets that you can reuse for multiple reports.

ODA architecture in BIRT

Writing ODA plug-ins for BIRT can be a complicated matter. There are two types of plug-ins to write: a runtime data plug-in and a design-time user interface (UI) plug-in. Let's consider the runtime plug-in first. Like many other BIRT extension points, the ODA extension classes use an observer-based design pattern. But what is different about the ODA architecture is that several of the observed calls are actually factory calls, requiring the observer to create new objects that are themselves observers. BIRT's internal data engine serves as the observed object, and the developer is responsible for creating the observer. Using the plug-in and manifest Extensible Markup Language (XML) files, the plug-in registers itself as an observer with the data engine.

At a high level, a few basic types of factories create observers. The factories must generate observers for data source connections, data set queries, parameters, and result sets (see Figure 1).

Figure 1. High-level diagram of the observer/observed/factory patterns that are used with BIRT ODA
Image showing a high-level diagram of the observer/observed/factory patterns used with BIRT ODA
Image showing a high-level diagram of the observer/observed/factory patterns used with BIRT ODA

Create a new runtime plug-in project

To create a runtime plug-in project, follow these steps:

  1. In Eclipse, click File > New > Other.
  2. On the Select a wizard page, expand Plug-in Development, and then select Plug-in Project (see Figure 2). Click Next.
    Figure 2. Select the plug-in project type
    Image showing where to select the plug-in project type
    Image showing where to select the plug-in project type
  3. On the Plug-in Project page, in Project name, type com.digiassn.blogspot.birt.oda.reportDocument (see Figure 3), and then click Next.
    Figure 3. Name the project
    Image showing where to name the project
    Image showing where to name the project
  4. On the Content page, fill out the properties as shown in Figure 4. Make note of the ID, then click Next.
    Figure 4. Assign properties to the project
    Image showing where to assign properties to the project
    Image showing where to assign properties to the project
  5. On the Templates page, in the Available Templates box, select ODA Data Source Runtime Driver (see Figure 5). Click Next.
    Figure 5. Assign a template to the plug-in
    Image showing how to assign a template to the plug-in
    Image showing how to assign a template to the plug-in
  6. On the next page, you set the specific plug-in information. Set the properties for the data source to 1 to use for the report document file name and 0 for the data set. Click Finish.

The ODA Data Source Runtime Driver wizard creates all the observer classes that are needed to write the plug-in.

Configure the plug-in

If you followed all of the steps in the wizard, you already set most of the configuration items. The remaining items to work with are the driverClass and the properties.

To configure the plug-in, follow these steps:

  1. Open the plugin.xml file to open the manifest editor, which is shown in Figure 6.
    Figure 6. Configure the plugin.xml file in the manifest editor
    Image showing how to configure the plugin.xml file in the                             manifest editor
    Image showing how to configure the plugin.xml file in the manifest editor
  2. At the bottom of the editor, click the Extensions tab (see Figure 7).
    Figure 7. The manifest editor Extensions tab
    Image showing the manifest editor Extensions tab
    Image showing the manifest editor Extensions tab
  3. In the All Extensions box, expand org.eclipse.datatools.connectivity.oda.dataSource until you see the (properties) section, which you use to pass in data source parameters. For this ODA, it passes in a report document file name. Rename this item from filename to ReportDocument, as shown in Figure 8.
    Figure 8. Rename the property for your plug-in
    Image showing how to rename the property for your plug-in
    Image showing how to rename the property for your plug-in

    (View a larger version of Figure 8.)

  4. Click the dataSource leaf node in the editor to open the properties for the ODA, and verify that the driverClass property is set. (Clicking the hyperlink opens the Driver class.)

Class structure of the runtime driver

The Driver class is the root observer for the ODA. It serves as a factory object that creates the Connection object. If you are using the wizard, the Connection object most of the boilerplate code is already written, but you complete the implementations of these methods. However, the Connection object has a few methods for you to modify. The open method is one of the methods observed that you must override. It is responsible for opening the data connection to the data source. For a Java Database Connectivity (JDBC) database connection, open would open a connection to the database. However, the report document ODA in this example uses the BIRT Report Engine API to open the report document file that is reported on. The Connection object also serves as a factory for IQuery objects through the newQuery method.

The IQuery method follows this same pattern of being both an observer and a factory. The observer method that you must overwrite is the prepare() method, which is responsible for preparing the IQuery method for execution. For a database query, you use a Structured Query Language query. The report document ODA, contains the name of the data set that is stored inside the report document, which is supplied by the design plug-in and stored in the report design for execution. The second method to overwrite is the factory method executeQuery(), which returns an IResultSet object.

Continuing the observer/factory pattern that other objects use, the IResultSet object is responsible for iterating over the results from a query and retrieving the column values from both a numeric index and a named column. You use the next() method to iterate over each row in the result set. The method returns true if there are remaining rows and false if there are no other rows to return. In the report document ODA, this method calls the BIRT Data Extraction Task's next() method. You must write each of the get column methods and get data type methods. A getMetaData() method returns the metadata of the column types. BIRT uses this metadata object to track the types and uses that information as a map to call the IResultSet-appropriate getType(columnNumber) or getType(columnName) method. Depending on the data source you retrieve, you can override the close() method in the IResultSet, as well. For a database, this override closes the JDBC ResultSet object. For the report document ODA, this method closes the Data Extraction Task's result set iterator and sets all objects to null.

That roughly describes all the objects that are used in the runtime plug-in. The complete source for the plug-in is available in Download.

Design time UI plug-in

The design time UI plug-in is not required, but it is helpful. If you don't create a design time UI plug-in, BIRT provides prompts for the properties that are defined in the plugin.xml and manifest files.

To create the design time UI plug-in, follow these steps:

  1. Create a new plug-in project, as you did earlier, and then click Next.
  2. Give the project a name, identifying it as a UI plug-in (see Figure 9), and then click Next.
    Figure 9. Name the UI plug-in project
    Image showing how to name the UI plug-in project
    Image showing how to name the UI plug-in project
  3. On the Content wizard page, select the This plug-in makes contributions to the UI check box; otherwise, the wizard option for ODA UI plug-ins is not available. Click Next.
  4. On the Templates wizard page, in the Available Templates box, select ODA Data Source Designer, as shown in Figure 10. Click Next.
    Figure 10. Assign the ODA Data Source Designer template to the plug-in
    Image showing how to assign the ODA Data Source Designer template to the plug-in
    Image showing how to assign the ODA Data Source Designer template to the plug-in
  5. On the ODA Data Source Designer wizard page that is shown in Figure 11, verify that the IDs for the ODA runtime driver plug-in, data source element, driver class, and the data set element ID match what was set in the runtime project. If you want to change these items after the wizard is complete, you can modify the values through the manifest editor or set the variables for the IDs in the plugin.properties file.

    Note: Pay attention to that little tidbit about the plugin.properties file: When I first started ODA development, I wasted time looking for it.

    Figure 11. Review the properties in the ODA Data Source Designer
    Image showing how to review the properties in the ODA Data Source Designer
    Image showing how to review the properties in the ODA Data Source Designer

Creating the pages for the data source and data set editors is a simple matter of registering property pages in the manifest editor, and then creating Standard Widget Toolkit (SWT) composites. Each page extends the DataSourceEditorPage, DataSourceWizardPage, or DataSetWizardPage, depending on what type of page it is. DataSourceWizard pages are the property pages that are used during the first execution of a new data source in BIRT. Likewise, the DataSetWizardPage is the first page that is used in data set creation. The DataSourceWizardPage creates a custom properties composite from the createPageCustomControl() method. The composite that is created calls the DataSourceWizardPage.setPageComplete() method to move to the next wizard page. It also calls the DataSourceWizardPage.setDataSourceProperties() method with the appropriate properties set. Remember that editing a data source editor when you click a data source in the BIRT editor does not call this same set of classes: It calls a separately defined property page. The definition for both can be seen in the newDataSourceWizard and the designer data source connection properties in the manifest editor. In the example code, the RptDocPropertyPage.java file for editing an existing data source calls the same CustomPropertiesPage that the new data source wizard does.

I described a mostly straightforward Eclipse view development. You might want to explore the no cost WindowBuilder Pro from Instantiations/Google (see Related topics for a link). The SWT designer goes a long way in easing the development of the layouts of views.

Conclusion

This article walked you through the process of creating two plug-in projects—one for design time and one for runtime. These plug-ins are fairly complex, but by referencing the example project, you can extend BIRT's data-retrieval capabilities. In addition, the plug-in shows you how to use the BIRT engines data extraction task to extract data from existing BIRT report document files.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Big data and analytics
ArticleID=847475
ArticleTitle=The BIRT ODA extension point
publish-date=11272012