Deploying BIRT

The Business Intelligence and Reporting Tools (BIRT) project is an open source, Eclipse-based reporting framework that enables the creation and deployment of complex report designs. Development with BIRT can usually be thought of as a two-step process: the creation of the report designs within the Eclipse BIRT Report Designer, followed by the deployment of the designs and framework to an application for dissemination.

Some of the most common questions in the BIRT News Group are about deploying BIRT. The reason for this is not the complexity of deploying, but the many deployment options. In this article, we will delve into the options and discover what is available to the BIRT developer.

BIRT Deployment

BIRT is comprised of several components, but it is most often associated with the Eclipse IDE platform as a set of plugins for use during design time. Although this is valid, BIRT also offers three public APIs and a J2EE servlet-based viewer that can be used outside of Eclipse.

The APIs are the Design Engine API (DE API), the Report Engine API (RE API), and the Chart Engine API (CE API). The DE API is responsible for creating and modifying the XML report design format. This API is what the Eclipse BIRT Report Designer uses to create the report design (rptdesign), library (rptlibrary), and template (rpttemplate) files. The RE API is responsible for consuming these files and producing the report output. The Report Designer Preview and Web Viewer servlet use this API to generate reports. The CE API can be used to create and render charts standalone or through the DE and RE APIs.

The BIRT Web Viewer is a web application, comprised of servlets and JSPs, that encapsulates the RE API to generate reports. In addition to generating reports, it supports HTML pagination, PDF, Table of Contents (TOC) functionality, and export to CSV.

Because the RE API is the main API responsible for generating the reports, this article will focus on the available options for its deployment. Some of the most common deployment options are listed below:

Deploy the BIRT Viewer to a J2EE application server.

Create a servlet that wraps the RE API and deploy it to a J2EE application server.

Add the BIRT plugins to an existing Eclipse Rich Client Platform (RCP) application and use the BIRT Web Viewer plugin for generating and viewing reports.

Wrap the RE API in an existing RCP application.

Wrap the RE API in an existing Java application.

Wrapping the RE API within an existing Java application is described on the BIRT site. See Report Engine API for more details.

The remaining scenarios are described below, with source code provided for each.

Deploying the BIRT Viewer Servlet

This form of deployment is the most common and, in most cases, tends to be the easiest. Before describing how to deploy the Viewer, an introduction to the Viewer architecture is in order.

BIRT Viewer

One of the most significant changes for BIRT 2.0 is the addition of an Ajax-based Viewer. Prior to 2.0, the servlet that executed BIRT reports would run a report and display it in either PDF or HTML. The HTML results were presented as one long page, which made viewing large reports difficult.

To address this, the BIRT engine has been enhanced to support a two-phase report generation process. The first phase, called Generation, takes the report design (.rptdesign) and generates a report document (.rptdocument), which holds the report data and design. The second phase is the Presentation phase, in which the report document is rendered in HTML, paginated HTML, or PDF. The Viewer servlet wraps the engine functionality and exposes the newer functions to the end user. This architecture also allows the engine to support Table of Contents (TOC) functionality and CSV exporting, without rerunning the report. Figure 1 shows the BIRT Viewer in action.

Figure 1. BIRT Viewer

The new viewer adds page navigation, TOC, parameter entry, export, and print controls to the toolbar.

The Viewer servlet implements two mappings. The first is "/run" which combines the Generation and Presentation phases into one operation. This mapping should be used when generating PDF documents, or when additional functions such as Page Navigation, TOC, Export to CSV, etc., are not needed. The second is "/frameset" which was added to facilitate the new Viewer functions, and divides the Generation and Presentation phases.

BIRT Viewer Deployment

Deploying the BIRT Viewer will depend on the Application Server you are using. The BIRT Viewer is available in the WebViewerExample directory of the Report Engine download. This directory contains the entire web application, with the exception of iText.jar file (used for PDF Generation). After adding iText as described on the BIRT website, the application can be placed in a war file and deployed as a normal web application. Deployment to Tomcat can be achieved by copying the entire WebViewerExample directory to the Tomcat webapps directory.