Birt 3.7 Migration Guide

< To: BIRT Project

BIRT POJO Runtime

To simplify application deployment, BIRT 3.7 features a new POJO based runtime. The new Runtime consists of a set of jars that can simply be added to the classpath of your application. While this affects the Runtime of BIRT the designer will continue to use the same OSGi based approach as previous versions of BIRT. The new Runtime is available for download on the BIRT web site and is structured as illustrated in the following diagram.

Engines

The Runtime contains the ReportEngine which can be used to run and render reports using the Report Engine API (RE API), and the DesignEngine which can be used to create report, library and template designs using the Design Engine API (DE API). The Runtime also contains the Chart Engine which can be used to build and display charts outside of a BIRT report or to manipulate charts within a design using the Chart Engine API (CE API).

genReport Command Line

The ReportEngine directory also contains a bat file (genReport.bat) or shell script (genReport.sh) to run reports from the command line using the Report Engine API. To use the command line file, extract the ReportEngine directory to a local file location (eg c:\birt3.7). To run a report you must set the environment variable BIRT_HOME first. The shell/bat file uses this to locate the jars.

set BIRT_HOME=c:\birt3.7
cd c:\birt3.7\ReportEngine
genReport samples/Hello_World.rptdesign

This will produce Hello_World.html in the samples directory. Use the following to get more parameter options.

genReport --help runrender
genReport --help run
genReport --help render

BIRT Viewer

In addition, the Runtime contains a Java EE AJAX based viewer that uses the Report Engine API to run and render reports and supports pagination, table of contents, and exporting to all supported formats. This viewer is available as a WAR (BIRT.war) or in exploded format (WebViewerExample). Many of the features of the viewer can be customized by modifying JSP fragments and JavaScript files located in the webcontent directory. See below for deployment instructions for the new Viewer.

Connection Profiles

If your reports use connection profiles supplied by the Data Tools Platform project (DTP), you will need to add a system or environment property that specifies a DTP workspace location. The genReport bat or shell script files show an example of setting this variable. If you are deploying these reports to the BIRT Viewer you will need to add the system property or set the environment variable in your application server. More details on this variable are available in the New and Noteworthy for DTP version 1.9

For Tomcat, you can add lines to catalina.bat that are similar to:

SET java.io.tmpdir=C:\apps\apache-tomcat-5.5.20\tmpdir

SET org.eclipse.datatools_workspacepath=%java.io.tmpdir%\workspace_dtp

mkdir %java.io.tmpdir%

mkdir %org.eclipse.datatools_workspacepath%

Font Config

If you are modifying your font locations using the fontsConfig.xml files located in the org.eclipse.birt.report.engine.fonts_version plugin see this bug.

JDBC Drivers

Adding a JDBC driver to the BIRT designer has not changed, but in the new runtime the driver jar(s) can be copied to <BIRT folder>/WEB-INF/lib.

For example, in GlassFish 3.1 this will be in glassfish/domains/domain1/applications/birt/WEB-INF/lib .

Custom Extension Point Implementations

If you have developed plugins that implement BIRT extension points these should continue to work if you add them to the classpath. For example, if you have developed an ODA data source extension to access data, or if you have developed an emitter simply add the jar for the exported plugin to your application classpath. If you are using the viewer, just copy your exported plugin to the viewer/WEB-INF/lib directory. If your plugin contains jar files that are used by your plugin you will need to extract these files from the exported plugin and put them in the WEB-INF/lib directory of the viewer as well.

BIRT POJO Viewer Deployment

The Viewer can be deployed as a standard Java EE based web application. Specific instruction are provided below.

BIRT POJO Viewer Websphere Deployment
BIRT POJO Viewer WebLogic Deployment
BIRT POJO Viewer JBOSS Deployment
BIRT POJO Viewer Tomcat Deployment

BIRT 3.7 API Changes

If you have existing code (RE, DE or CE API) that you plan on migrating to BIRT 3.7, no changes should be required, but it is advised to remove the setBirtHome method from your EngineConfig instance. Add all jars in the ReportEngine/lib directory to your classpath or to your buildpath if you are using Eclipse to build your Java application.

BIRT RE API code
config = new EngineConfig( ); 
config.setBIRTHome("pathtoruntime");
Should be changed to:
config = new EngineConfig( ); 

BIRT DE API code
config = new DeisgnConfig( );
config.setBIRTHome("pathtoruntime");
Should be changed to:
config = new DesignConfig( );

If you are using the Chart Engine API
PlatformConfig pf = new PlatformConfig();
pf.setBIRTHome("pathtoruntime");
Should be changed to:
PlatformConfig pf = new PlatformConfig();