Chapter 3. Installing Other BIRT Packages

Beyond the BIRT Report Designer packages, BIRT provides a number of other separate packages as downloadable archive files on the Eclipse web site. Some of these packages are stand-alone modules, others require an existing Eclipse or BIRT environment, and still others provide additional functionality to report developers and application developers. This chapter describes the steps required to install the BIRT packages shown in the following list:

• Chart Engine

• Data Tools Platform (DTP) Integration

• Demo Database

• Report Engine

• Samples

• Source Code

• Web Tools Integration

Installing Chart Engine

Chart Engine supports adding charting capabilities to a Java application. An application can use Chart Engine without using the BIRT reporting functionality or Report Engine. Chart Engine integrates into an existing Eclipse platform on Microsoft Windows, UNIX, or Linux. You can also install Chart Engine on an existing J2EE application server. To use Chart Engine, you use its public API, org.eclipse.birt.chart.

Both BIRT Report Designer and BIRT RCP Report Designer include all the components of Chart Engine. If you are using a BIRT report designer, you do not need to install BIRT Chart Engine separately.

How to install BIRT Chart Engine

On the BIRT web site, perform the following operations:

1 Navigate to BIRT Downloads for build 2.6.0.

For more information about how to navigate to the BIRT web site and BIRT Downloads for build 2.6.0, see Chapter 2, “Installing a BIRT Report Designer.”

2 In the Chart Engine section, choose the Chart Engine archive file:

birt-charts-2_6_0.zip

3 In File Downloads, choose Open.

4 Extract the archive file to a location of your choice.

5 Start Eclipse from the command line with the -clean option to remove cached information.

The archive extraction process creates the following subdirectories in the extraction directory:

• ChartRuntime

This directory contains the plug-ins and libraries that an Eclipse platform requires to run, render, and edit charts.

• ChartSDK

This directory contains the plug-ins and libraries from the ChartRuntime directory plus the SDK that you need to create your own charting applications. It also includes examples, source code, and a Web Tools Platform (WTP) extension to support charts in web applications.

• DeploymentRuntime

This directory contains the libraries that you need to run your charting application in a non-Eclipse environment such as on an application server.

The Chart Engine download file also includes extensive Frequently Asked Questions (FAQ) and examples illustrating how to use Chart Engine. After extracting the archive, you can find the FAQ at the following location:

<CHART_ENGINE>/DeploymentRuntime/ChartEngine/docs/Charts_FAQ.doc

The examples are in a JAR file located at:

<CHART_ENGINE>/ChartSDK/eclipse/plugins
   /org.eclipse.birt.chart.examples_<version>.jar

Installing BIRT Data Tools Platform Integration

This package includes the minimal set of Data Tools Platform (DTP) plug-ins that BIRT Report Designer requires. If you install the BIRT Report Designer package in an existing Eclipse installation, you can install this BIRT DTP Integration package instead of the full DTP platform.

How to install BIRT DTP Integration

On the BIRT web site, perform the following operations:

1 Navigate to BIRT Downloads for build 2.6.0.

2 In the BIRT DTP Integration section, choose the BIRT DTP Integration archive file:

birt-dtp-integration-2_6_0.zip

3 On Eclipse downloads, choose your closest download site.

4 Extract the archive file to the directory that contains your Eclipse directory.

Extracting creates the DTP features and plug-ins in the eclipsefeatures and eclipseplugins directories.

5 Start Eclipse from the command line with the -clean option.

To test the BIRT DTP Integration package, open the Report Design perspective in Eclipse, as described in the following procedure.

How to test the BIRT DTP Integration installation

1 Start Eclipse.

2 From the Eclipse main menu, choose Open Perspective→Report Design. If Report Design does not appear in the Open Perspective window, choose Other. From the list of perspectives, choose Report Design.

Eclipse displays the BIRT Report Designer perspective.

Installing BIRT Demo Database

The BIRT Demo Database package provides the Classic Models database that this book uses for example procedures. The database is provided in the following formats:

• Apache Derby

• MySQL

BIRT Report Designer and BIRT RCP Report Designer include this database in Apache Derby format, as the Classic Models Inc. sample database data source. Install BIRT Demo Database if you want to use the native drivers to access this data source.

How to install BIRT Demo Database

On the BIRT web site, perform the following operations:

1 Navigate to BIRT Downloads for build 2.6.0.

2 In the Demo Database section, choose the Demo Database archive file:

birt-database-2_6_0.zip

3 In File Download, choose Open.

4 Extract the archive file to a location of your choice.

Extracting creates a directory, ClassicModels, that contains the BIRT Demo Database in Apache Derby and MySQL formats.

To test the BIRT Demo Database, first connect to the database with the native database client tool or a Java application.

How to access BIRT Demo Database using a database client tool

Perform one of the following sets of tasks, based on your preferred database:

• Apache Derby database

Connect to the database in the derby subdirectory of ClassicModels.

• MySQL

1 Navigate to the mysql subdirectory of ClassicModels.

2 Create a database to use or edit create_classicmodels.sql to uncomment the lines that create and select the classicmodels database.

3 Use the mysql command line interface to run create_classicmodels.sql.

4 Review load_classicmodels.sql to determine if you can use the script on your platform without editing. Use the mysql command line interface to run load_classicmodels.sql.

Next, connect to the database from BIRT Report Designer or BIRT RCP Report Designer.

How to access BIRT Demo Database from a BIRT report designer

Connect to the database using BIRT Report Designer or BIRT RCP Report Designer.

1 To access the Classic Models database in Apache Derby or MySQL format, first add the driver JAR files to a BIRT report designer installation.

2 In any report design, create a data source on the database. In the same report design, create a data set on the data source.

Installing Report Engine

Report Engine supports adding reporting capabilities to a Java application. BIRT Report Engine integrates into an existing Eclipse platform on Microsoft Windows, UNIX, or Linux. You can also install report engine components on an existing J2EE application server. To support quick deployment of reporting functionality to an application server, Report Engine includes a web archive (.war) file.

How to install BIRT Report Engine

On the BIRT web site, perform the following operations:

1 Navigate to BIRT Downloads for build 2.6.0.

2 In the Report Engine section, choose the Report Engine archive file:

birt-runtime-2_6_0.zip

3 In File Download, choose Open.

4 Extract the archive file to a suitable directory.

5 Create a system variable, BIRT_HOME.

Set the value of BIRT_HOME to the BIRT Report Engine installation directory. For example, if you extracted the BIRT Report Engine to C:, the value of BIRT_HOME is:

C:irt-runtime-2_6_0

To test the installation, run the Report Engine report generation command line example. This example uses a batch (.bat) file on a Windows system and a shell script (.sh) file on a UNIX or Linux system. This file takes the parameters shown in Table 3-1.

Table 3-1 Parameters for the genReport script

How to test the BIRT Report Engine installation

1 From the command line, navigate to the directory where you installed BIRT Report Engine.

2 Navigate to the ReportEngine subdirectory.

3 To run the genReport script, run the appropriate file for your operating system:

• On a Windows platform, run genReport.bat.

• On a UNIX or Linux platform, run genReport.sh.

Enclose the value for a command line parameter in quotes. For example, the following Windows platform command uses the value, Hello, for the parameter, sample, to generate an HTML file from the report design, test.rptdesign:

genReport -p "sample=Hello"
   "C:irt-runtime-2_6_0WebViewerExample est.rptdesign"

genReport generates the required output file.

4 Open the output file. In this example, the file is C:irt-runtime-2_6_0WebViewerExample est.html.

For more information about setting up the BIRT Report Engine, see Chapter 4, “Deploying a BIRT Report to an Application Server.”

Installing BIRT Samples

BIRT Samples provides examples of a BIRT report item extension and of charting applications. The report item extension integrates into BIRT Report Designer and BIRT Report Engine.

How to install BIRT Samples

On the BIRT web site, perform the following operations:

1 Navigate to BIRT Downloads for build 2.6.0.

2 In the Samples section, choose the Samples archive file:

birt-samples-plugins-2_6_0.zip

3 In File Download, choose Open.

4 Extract the archive file to the directory that contains your Eclipse directory.

Installing BIRT Source Code

This package includes the source code for all BIRT plug-ins. You can examine this code to see how BIRT generates reports from designs. You can also import this source code into a workspace to build a custom BIRT installation.

How to install BIRT Source Code

1 Navigate to BIRT Downloads for build 2.6.0.

2 In the BIRT Source Code section, choose the BIRT Source Code archive file:

birt-source-2_6_0.zip

3 In File Download, choose Open.

4 Extract the archive file to a new workspace directory.

Extracting creates the build files and BIRT features and plugins directories in that workspace directory.

To test the BIRT Source Code package, import the source code projects into your workspace.

How to test the BIRT Source Code installation

1 Start Eclipse.

2 Set the Java preferences for BIRT.

1 From the Eclipse window menu, choose Window→Preferences.

2 Expand Java, select Compiler. Make the following selections:

• Set Compiler Compliance Level to 1.6.

• Deselect Use default compliance settings.

• Set Generated .class files compatibility to 1.6.

• Set Source compatibility to 1.6.

3 Choose OK.

3 From the Eclipse window menu, choose File→Import.

4 In Import—Select, expand General and select Existing Projects into Workspace. Choose Next.

5 In Import—Import Projects, select Select root directory, then type or browse to your workspace directory.

The BIRT features and plug-ins appear in Projects.

6 Choose Finish.

Eclipse builds the BIRT projects.

If the projects do not build correctly, check that you installed the prerequisites for BIRT Report Designer, as described in Chapter 1, “Introducing BIRT Report Designers.” If you have not installed the BIRT Report Designer Full Eclipse Install, download this package and extract any JAR files that the build requires. Add any libraries that Eclipse does not find to the build paths of specific projects to resolve other build errors.

Installing BIRT Web Tools Integration

This package includes the minimal set of BIRT plug-ins that the Eclipse Web Tools Platform (WTP) requires to build a BIRT web project using the BIRT Web Project Wizard. This package also includes the source code for these plug-ins.

How to install BIRT Web Tools Integration

On the BIRT web site, perform the following operations:

1 Navigate to BIRT Downloads for build 2.6.0.

2 In the BIRT Web Tools Integration section, choose the BIRT Web Tools Integration archive file:

birt-wtp-integration-sdk-2_6_0.zip

3 In File Download, choose Open.

4 Extract the archive file to the directory that contains your Eclipse directory.

Extracting creates the BIRT features and plug-ins in the eclipsefeatures and eclipseplugins directories.

To test the BIRT Web Tools Integration package, create a BIRT web project in Eclipse.

How to test the BIRT Web Tools Integration installation

1 Start Eclipse.

2 From the Eclipse window menu, choose File→New→Project.

3 In New Project—Select a wizard, expand Web, select Dynamic Web Project. Choose Next.

4 In New Project—Dynamic Web Project, make the choices that you need for your BIRT web project, then choose Finish.

If you do not have the Java EE perspective open, Eclipse displays the following message:

This kind of project is associated with the Java EE perspective. Do you want to open this perspective now?

Choose Yes.