ONJava.com -- The Independent Source for Enterprise Java
oreilly.comSafari Books Online.Conferences.


AddThis Social Bookmark Button

Deploying BIRT
Pages: 1, 2, 3, 4

Creating A Servlet

If you do not wish to use the BIRT Viewer, wrapping the RE API in a servlet is possible. The major drawback to deploying BIRT in this fashion is that native functions supplied by the BIRT Viewer are not available without the developer coding them into the servlet. These functions include TOC, paginated HTML, and export to CSV. This approach is generally used when the developer has a specific need, such as direct generation to PDF, and does not want the other functions available in the viewer.

Creating a servlet to run the BIRT RE API is very simple. To illustrate, we will deploy an example servlet that generates an HTML Report. This example uses Tomcat, and the servlet is placed in the webapps directory. See the sample code (in the Resources section) for the complete example.

  1. Create a WebReport/WEB-INF/lib directory underneath the Tomcat webapps directory.
  2. Copy all the jars in the birt-runtime-2_1_0/ReportEngine/lib directory from the Report Engine download into your WebReport/WEB-INF/lib directory.
  3. Next, create a directory named platform in your WEB-INF folder.
  4. Copy the birt-runtime-2_1_0/Report Engine/plugins and birt-runtime-2_1_0/ReportEngine/configuration directories to the platform directory you just created. In this example the context is WebReport, so the folder structure is /webapps/WebReport/platform/plugins and webapps/WebReport/platform/configuration.
  5. Additionally, create directories below WebReport for image location and report location.

When completed, your directory structure should look like Figure 2.

Web Structure when deploying BIRT Engine as a servlet
Figure 2. Folder structure when deploying BIRT Engine as a servlet

This example application consist of three files that are archived into webreport.jar. If you are using Eclipse to build the servlet, make sure to add all the jars from the birt-runtime-2_1_0/ReportEngine/lib directory to your build path. You will also need servlet.jar from the Tomcat Eclipse plugin in your build path. Either build or copy webreport.jar from the example and place it in your WEB-INF/lib directory.

  • BirtConfig.properties: Configuration properties for the Engine.
  • BirtEngine.java: Class used to initialize the Report Engine.
  • WebReport.java: The servlet that handles report generation on a GET command.


The BirtConfig.properties file contains only two entries.


The logDirectory specifies where the Report Engine will log entries. The logLevel sets the level for logging.


The BirtEngine.java class is a singleton and is used to create one instance of the Report Engine for the servlet. It has a synchronized method for retrieving the instance, or creating and configuring it if it doesn't exist.

The BIRT Report Engine uses OSGi to load Eclipse plugins. These plugins provide functions for connecting to data sources and emitting PDF/HTML. The following lines instruct the Report Engine to look in the webapps/WebReport/WEB-INF/platform directory when starting Eclipse plugins using OSGi.

IPlatformContext context = 
               new PlatformServletContext( sc );
config.setPlatformContext( context );

The rest of the code within this class is responsible for starting the platform and creating the report engine.

public static synchronized IReportEngine getBirtEngine(ServletContext sc) {
  if (birtEngine == null) 
                //Start up the OSGi framework
                Platform.startup( config );
        catch ( BirtException e )
                e.printStackTrace( );

        IReportEngineFactory factory = 
                (IReportEngineFactory) Platform.
        birtEngine = 
                  factory.createReportEngine( config );
        return birtEngine;


The WebReport.java class contains the servlet to process requests for report generation.

The servlet's init method calls the BirtEngine.initBirtConfig() method to read the BIRT configuration file discussed earlier.

public void init() throws ServletException {

The destroy method of the servlet shuts down the Report Engine and platform. This should only be called when the servlet is shutting down.

public void destroy() {
      //call engine and platform shutdown 

In this example we only support GET commands. The servlet doGet method retrieves the Report Engine using the singleton described above and executes the report specified as ReportName in the URL. One of the key lines in this function is:


This particular option instructs the Report Engine to render the report to the servlet Output stream. The rest of the code in the doGet method sets up the proper directories, loads the engine, opens, and executes the report.

public void doGet(HttpServletRequest req,
            HttpServletResponse resp)
                        throws ServletException, IOException {


    //get report name and launch the engine             
    String reportName = 
    ServletContext sc = 
    this.birtReportEngine = 

    //setup image directory     
    HTMLRenderContext renderContext = 
                       new HTMLRenderContext();

    HashMap< String, HTMLRenderContext > contextMap 
           = new HashMap< String, HTMLRenderContext >();

                renderContext );

    IReportRunnable design;

            //Open report design
        design = birtReportEngine.
               "/reports")+"/"+reportName );
        //create task to run and render report   
        IRunAndRenderTask task = 
              createRunAndRenderTask( design );
        task.setAppContext( contextMap );
        //set output options            
        HTMLRenderOption options = 
           new HTMLRenderOption();

        //run report
    }catch (Exception e){
        throw new ServletException( e );

Copy the testWebReport.rptdesign from the example source code to the webapps/WebReport/Reports directory. Copy the web.xml from the example source code to the webapps/WebReport/WEB-INF directory. Launch a browser and enter the URL to the WebReport application. For example, http://localhost:8080/WebReport/run?ReportName=testWebReport.rptdesign.

Pages: 1, 2, 3, 4

Next Pagearrow