JBoss.orgCommunity Documentation

Birt Plugin Integration Reference Guide

Anastasiya Bogachuk

Olga Chikvina

Version: 1.0.0.GA

Copyright © 2008, 2009 JBoss, a division of Red Hat

August 2008

PDF version

1. Introduction
1.1. What is BIRT?
1.2. JBoss BIRT Integration Functionality Overview
1.3. Other Relevant Resources on the Topic
2. Adding BIRT Functionality to Standard Seam Web Project
2.1. Creating Seam Web Project with Birt Facet
2.2. Integration with Seam
3. Hibernate ODA Data Source
4. BIRT Reports Deployment

Chapter 1. Introduction

1.1. What is BIRT?
1.2. JBoss BIRT Integration Functionality Overview
1.3. Other Relevant Resources on the Topic

BIRT plugin is an Eclipse-based open source reporting system for web applications based on Java and J2EE. BIRT consists of two main components: a report designer based on Eclipse, and a runtime component that can be added to your app server. BIRT also offers a charting engine that lets you add charts to your own Web application.

With the help of BIRT you can generate a great number of reports to be used in your application:

You can find more detailed information on the BIRT plugin, its report types and anatomy on the BIRT Homepage.

To understand the basic BIRT concepts and to know how to create a basic BIRT report, refer to the Eclipse BIRT Tutorials. What extensions JBoss Tools provides for Eclipse BIRT you'll find out in the next sections.

This reference guide describes the one module of the JBoss Tools project which performs the integration with BIRT. The integration includes the following functionalities:

To enable JBoss Tools integration with BIRT you are intended to have the next:

Note:

Versions of BIRT framework and BIRT WTP integration should be no less than RC4 in order to the BIRT facet works correctly.

All JBoss Developer Studio/JBoss Tools release documentation you can find athttp://docs.jboss.org/tools in the corresponding release directory.

The latest documentation builds are available at http://download.jboss.org/jbosstools/nightly-docs.

Chapter 2. Adding BIRT Functionality to Standard Seam Web Project

updated
2.1. Creating Seam Web Project with Birt Facet
2.2. Integration with Seam

In this chapter you'll know how to create a Seam web project with BIRT capabilities included.

You are supposed to have Seam runtime and JBoss Application Server downloaded and extracted somewhere on you hard drive.

Tip:

We usedJBoss Seam 2.0.1 GA and JBoss Application Server 4.2.2 GA in examples of this guide.

First, open Seam perspective by going to Window > Open Perspective > Other > Seam. To create a new Seam Web project follow to File > New > Seam Web Project (or File > New > Other > Seam > Seam Web Project if you are not in the Seam perspective).

On the first wizard page enter the project name, then specify the target runtime and target server. In the Configuration section click Modify to configure the project facets.

Creating Seam Web Project

Figure 2.1. Creating Seam Web Project


Choose the 2.0 version of the Seam facet and enable the Birt Reporting Runtime Component facet.

Adding the Birt Reporting Runtime Component Facet

Figure 2.2. Adding the Birt Reporting Runtime Component Facet


Or you can just choose the JBoss BIRT Integration Web Project configuration.

Choosing the JBoss BIRT Integration Web Project Configuration

Figure 2.3. Choosing the JBoss BIRT Integration Web Project Configuration


Next three pages are filled out with defaults, just leave them through by pressing Next. On the Seam Facet page you should specify the Seam runtime and Connection profile.

Configuring the Seam Facet settings

Figure 2.4. Configuring the Seam Facet settings


Hit Finish to create the project with Birt functionality enabled.

The JBoss BIRT Integration feature contains the BIRT tag that allows the user to add a BIRT report to an .xhtml file:

<p:birt xmlns:ui="http://java.sun.com/jsf/facelets" 
            xmlns:s="http://jboss.com/products/seam/taglib" 
            xmlns:p="http://jboss.com/products/seam/birt" 
            designType="run" 
            format="pdf" 
            designName="test.rptdesign" 
            title="JBoss Birt Test">
        
</p:birt>

Let's look how it works.

Create in the Web Content folder three .xhtml pages with the following content:

Now start the application server by clicking the Start option in the context menu of the server in the JBoss Server View (if the view isn't open go to Window > Show View > Other > JBoss Server View). Try the tests out by accessing http://localhost:8080/hellobirt/birttests.seam in your web browser.

Welcome Page in the Browser

Figure 2.5. Welcome Page in the Browser


Now if you click Test Birt you should see the following .pdf file:

After Clicking Test Birt

Figure 2.6. After Clicking Test Birt


After clicking Test Birt 1 the next page is displayed:

After Clicking Test Birt 1

Figure 2.7. After Clicking Test Birt 1


Put the test param as Sample Parameter value, specify the maximum possible Customer Number as 1001, for instance, and then press Ok. You'll see the following BIRT report:

BIRT Report in the Browser Window

Figure 2.8. BIRT Report in the Browser Window


The BIRT tag recognizes most of the parameters described on the BIRT Report Viewer Parameters page. The attributes of the BIRT tag don't contain the "__" prefix.

The param tag describes report parameters (see the listing for the testbirt.xhtml above). It supports the following attributes:

  • name - the parameter name (required)

  • value - the parameter value (required)

  • isnull - specifies that a report parameter has a null value (optional)

  • islocale - specifies whether the parameter is localized (optional)

These tags are defined in the org.jboss.birt.core/resources/jboss-seam-birt.jar library that contains source.

It is also possible to embed a BIRT report in some Seam .xhtml page. See how it may be done:

Example: 

<!DOCTYPE composition PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
                                                        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<ui:composition xmlns="http://www.w3.org/1999/xhtml" 
		                 xmlns:s="http://jboss.com/products/seam/taglib" 
		                 xmlns:ui="http://java.sun.com/jsf/facelets" 
		                 xmlns:f="http://java.sun.com/jsf/core" 
		                 xmlns:h="http://java.sun.com/jsf/html" 
		                 xmlns:rich="http://richfaces.org/rich" 
		                 xmlns:b="http://jboss.com/products/seam/birt" 
		                 template="layout/template.xhtml">
        <ui:define name="body">
                <h:messages globalOnly="true" styleClass="message" id="globalMessages"/>
                     <rich:panel>
                         <f:facet name="header">Products</f:facet>
                         <b:birt designType="embed" designName="ProductCatalog.rptdesign" 
                                         embeddable="true" masterpage="false"/>
                             <div style="clear:both"/>
                     </rich:panel>
                     <div class="actionButtons">
                         <s:button view="/ProductsEdit.xhtml" id="edit" value="Edit"/>
                         
                         <s:button view="/#{empty productsFrom ? 'ProductsList' : productsFrom}.xhtml" 
                                             id="done" value="Done"/>
                     </div>
        </ui:define>
</ui:composition>

See the result in a Browser:

Embedding BIRT Report in Seam xhtml Page

Figure 2.9. Embedding BIRT Report in Seam xhtml Page


Chapter 3. Hibernate ODA Data Source

updated

The JBoss BIRT Integration feature includes the Hibernate ODA Data Source completely integrated with Hibernate Tools. You can use it in the way you use any of BIRT ODA drivers. Let's perform simple actions that demonstrate it.

First, run the Seam Generate Entities action (You can access it from File > New > Seam Generate Entities in the Seam perspective. More details on the Seam Generate Entities read in our Seam Dev Tools Reference guide). This action will create a Hibernate Console configuration.

Tip:

Before performing Seam Generate Entities, you should have a connection profile adjusted and connected to a database. How to do this see in the CRUD Database Application chapter of the Seam Dev Tools Reference guide.

Next add a new BIRT report. To do that navigate to File > New > Other > Business Intelligence and Reporting Tools > Report. In the New Report wizard enter the report name, for instance testHibernateOda.rptdesign, then click Finish.

Creating a New BIRT Report

Figure 3.1. Creating a New BIRT Report


Now switch to the Report Design perspective.

In the Data Explorer View right-click the Data Source node and choose New Data Source.

Creating a New Data Source

Figure 3.2. Creating a New Data Source


In the wizard select Hibernate Data Source and give it a proper name, HbDataSource for instance. Hit Next.

Creating Hibernate Data Source

Figure 3.3. Creating Hibernate Data Source


On the next wizard page leave everything as it is, just press the Test Connection button to verify the connection is successful.

Hibernate Data Source Profile

Figure 3.4. Hibernate Data Source Profile


Click Ok and then Finish to complete.

Now let's add a Hibernate ODA dataset. To do that you should bring up the New Data Set wizard. In the Data Explorer View right-click the Data Set node and select New Data Set.

Creating a New Data Set

Figure 3.5. Creating a New Data Set


In the Data Set Name section specify the name. Let's it be HbDataSet.

Creating a Hibernate ODA Data Set

Figure 3.6. Creating a Hibernate ODA Data Set


Next you'll be prompted to define the query for this data set. To validate the entered query you can press the Test query button. All the HQL features like syntax highlighting, content assist, formatting, Drag and Drop, etc., are available to you here.

Testing Query

Figure 3.7. Testing Query


Next the output columns will be displayed. It's possible to edit them here.

HQL Features - Output Columns Section

Figure 3.8. HQL Features - Output Columns Section


To preview the results of the defined query click the Preview Results item.

HQL Features - Preview Results Section

Figure 3.9. HQL Features - Preview Results Section


So far you have the Hibernate data source and data set defined. Now you can create a BIRT report using this data source and data set.

Tip:

If you don't know how to do this we suggest that you refer to the Eclipse BIRT Tutorial.

Creating a BIRT Report using Created Data Source and Data Set

Figure 3.10. Creating a BIRT Report using Created Data Source and Data Set


If you switch to the Preview tab, it will run your report and show the output.

BIRT Report -Preview Tab

Figure 3.11. BIRT Report -Preview Tab


You can also use parameters within the Hibernate ODA driver.

Using Parameters within the Hibernate ODA Driver

Figure 3.12. Using Parameters within the Hibernate ODA Driver


Adding New Parameter

Figure 3.13. Adding New Parameter


Again, to preview the results switch to the Preview Results item.

Previewing the Results

Figure 3.14. Previewing the Results


Chapter 4. BIRT Reports Deployment

updated

When everything is configured correctly you will be able to view/render the designed reports in your Seam (or any other) Web application.

You can deploy a report by adding an action button to the Seam's CRUD .xhtml file.

Adding Action Button to the Seam file

Figure 4.1. Adding Action Button to the Seam file


As you can see on the figure you should have the testHibernateOda.xhtml file. It's content should be the following:

<p:birt xmlns:ui="http://java.sun.com/jsf/facelets"
            xmlns:s="http://jboss.com/products/seam/taglib"
            xmlns:p="http://jboss.com/products/seam/birt"
            designType="run"
            format="pdf"
            designName="testHibernateOda.rptdesign"
            title="JBoss Birt Test">
      
</p:birt>

Next run the Seam page with embedded report on the server by right-clicking the file and going to Run > Run on Server.

Opening Employees.xhtml Page

Figure 4.2. Opening Employees.xhtml Page


After clicking the BIRT PDF Report button, you should see the following report:

Birt PDF Report

Figure 4.3. Birt PDF Report


Thus, a Seam project that includes the BIRT facet can be deployed as any project. If you define the Hibernate ODA driver, the JBoss BIRT engine will use JNDI URL that has to be bind to either Hibernate Session Factory or Hibernate Entity Manager Factory. If you don't specify the JNDI URL property, our engine will try the following JNDI URLs:

  • java:/<project_name>

  • java:/<project_name>EntityManagerFactory

When creating a Seam EAR project, Hibernate Entity Manager Factory is bound to java:/{projectName}EntityManagerFactory. All you need to do is using the Hibernate Configuration created automatically. You can use default values for the Hibernate Configuration and JNDI URL within the BIRT Hibernate Data Source.

When using a Seam WAR project, neither HSF nor HEMF aren't binded to JNDI by default. You has to do this manually. For instance, HSF can be bound to JNDI by adding the following property to the persistence.xml file:

<property name="hibernate.session_factory_name" value="java:/projectname"/>

And you can use java:/projectname as the JNDI URL property when creating a BIRT Hibernate Data Source.

Note:

If you want to test this feature using PDE Runtime, you need to add osgi.dev=bin to the WebContent/WEB-INF/platform/configuration/config.ini file.

In conclusion, the main goal of this document is to get you know with a full featureset that JBoss BIRT Tools provide. Thus if you have some questions, comments or suggestions on the topic, please feel free to ask in the JBoss Tools Forum. You can also influence on how you want to see JBoss Tools docs in future leaving your vote on our page here.