Contents


Integrate the BIRT Viewer with Java and Java EE web applications

Comments

Examining the problem

A famous thermoelectric power company in Italy required a custom web application to automate the collection and archiving of the production data and budget of its plants across various locations. One part of the application was to generate reports that are based on the data that is submitted in the backend. The Business Intelligence and Reporting Tools - BIRT was suggested as the technology for report generation. For the custom web application, it was decided to use Struts2 framework.

The reports were developed by using BIRT designer. An easiest option was to use the BIRT runtime (org.eclipse.birt.runtime version 3.7.1) API to render the reports. This option required integrating the BIRT run time with the custom web application by using Maven (through use of Maven dependencies for JAR files of BIRT run time). With the BIRT runtime integrated, the reports might be rendered through custom code that is written by using BIRT runtime API classes and interfaces.

Apart from rendering the report, the client also needed to export the report in different formats, such as PDF or Excel. The BIRT runtime download contains a sample BIRT report Viewer web application that renders reports in various formats by using its in-built servlet. In addition to rendering the reports in various formats, this sample viewer also provides other useful features:

  • Navigation through a large report by page and from a table of contents
  • Running and generating reports in formats like HTML or PDF
  • Exporting the report data in formats like CSV, TSV, and PSV
  • Printing the report locally or at the server
  • Testing and rerunning of the reports with other parameters

Considering all these useful features, we preferred to reuse the sample BIRT viewer viewer application instead of writing custom code for viewing and downloading reports by using BIRT runtime API. This reuse saved time and effort for generating a custom BIRT report viewer.

Considering possible solutions

The sample BIRT viewer (that comes in bundle with BIRT runtime download) is itself a web application that is composed of the BIRT Engine and Java API. You might use it with the custom web application in the following ways:

  • Maintain an extra web application for the BIRT viewer, that the custom web application can invoke to render reports. In this case, whenever the user needs to view a report, the custom web application invokes the BIRT-viewer web application (running separately on the server). The custom app passes the name of the report to render, along with other parameters required to run the report. This method assumes that the reports are maintained in the BIRT-viewer web application and not inside the custom web application.
  • Integrate the sample BIRT viewer application in the custom web application and maintain a single application instead, having the core features along with the responsibilities of rendering reports.

Finding the preferred solution

The first solution in Considering possible solutions required the creation and maintenance of multiple applications:

  • The custom web application
  • A supplementary web application (the BIRT Viewer web application), whose main goal was only to print some reports

The client did not accept the proposal of maintaining two web applications on their server: the custom web application and another for the sole purpose of rendering reports. So, we were left with integrating the sample BIRT viewer application with the custom web application and thus maintaining a single web application at the server.

Integrating the BIRT Viewer with a custom Java Platform, Enterprise Edition web application

Steps to follow for Maven type projects

  1. Add the dependencies in Listing 1 in your pom.xml
    Listing1: Maven dependency - BIRT runtime
    <dependency>
            <groupId>org.eclipse.birt.runtime</groupId>
            <artifactId>org.eclipse.birt.runtime</artifactId>
            <version>4.2.0</version>
        </dependency>
        <dependency>
            <groupId>axis</groupId>
            <artifactId>axis</artifactId>
            <version>1.4</version>
        </dependency>
  2. Save the viewservlets.jar file (see programfiles.zip in Downloadable resources) in your local folder structure.
  3. Go inside the maven project folder (that contains the pom.xml). Run the following command (assuming that Maven is configured).
    mvn install:install-file -Dfile=[location_where_you_saved]\viewservlets.jar
        -DgroupId=org.eclipse.birt.example -DartifactId=viewer-servlet -Dversion=4.2.0
        -Dpackaging=jar

    Note: If Maven is not configured, run the command from [location where Maven is downloaded]\apache-maven-3.0.4\bin

  4. Add the code in Listing 2 to your pom.xml:
    Listing 2. Maven Dependency - BIRT example
    <dependency>
      <groupId>org.eclipse.birt.example</groupId>
      <artifactId>viewer-servlet</artifactId>
      <version>4.2.0</version>
    </dependency>

Steps to follow for non-Maven type projects

  1. Download the BIRT runtime (version 4.2.0) from the BIRT website.
  2. Add the following JAR files into your WEB-INF/lib folder from [where_you_extracted birt-runtime-4_2_0.zip]/ WebViewerExample/WEB-INF/lib:
      axis-ant.jar
      axis.jar
      com.ibm.icu_4.4.2.v20110823.jar
      com.lowagie.text_2.1.7.v201004222200.jar
      commons-cli-1.0.jar
      commons-discovery-0.2.jar
      derby.jar
      flute.jar
      javax.wsdl_1.5.1.v201012040544.jar
      javax.xml.stream_1.0.1.v201004272200.jar
      jaxrpc.jar
      js.jar
      org.apache.batik.bridge_1.6.0.v201011041432.jar
      org.apache.batik.css_1.6.0.v201011041432.jar
      org.apache.batik.dom.svg_1.6.0.v201011041432.jar
      org.apache.batik.dom_1.6.0.v201011041432.jar
      org.apache.batik.ext.awt_1.6.0.v201011041432.jar
      org.apache.batik.parser_1.6.0.v201011041432.jar
      org.apache.batik.pdf_1.6.0.v201105071520.jar
      org.apache.batik.svggen_1.6.0.v201011041432.jar
      org.apache.batik.transcoder_1.6.0.v201011041432.jar
      org.apache.batik.util.gui_1.6.0.v201011041432.jar
      org.apache.batik.util_1.6.0.v201011041432.jar
      org.apache.batik.xml_1.6.0.v201011041432.jar
      org.apache.commons.codec_1.3.0.v201101211617.jar
      org.apache.commons.logging_1.0.4.v201101211617.jar
      org.apache.xerces_2.9.0.v201101211617.jar
      org.apache.xml.resolver_1.2.0.v201005080400.jar
      org.apache.xml.serializer_2.7.1.v201005080400.jar
      org.eclipse.birt.runtime_4.2.0.v20120613-1143.jar
      org.eclipse.core.contenttype_3.4.200.v20120523-2004.jar
      org.eclipse.core.expressions_3.4.400.v20120523-2004.jar
      org.eclipse.core.filesystem_1.3.200.v20120522-2012.jar
      org.eclipse.core.jobs_3.5.200.v20120521-2346.jar
      org.eclipse.core.resources_3.8.0.v20120522-2034.jar
      org.eclipse.core.runtime_3.8.0.v20120521-2346.jar
      org.eclipse.datatools.connectivity.apache.derby.dbdefinition_1.0.2.v201107221459.jar
      org.eclipse.datatools.connectivity.apache.derby_1.0.102.v201107221459.jar
      org.eclipse.datatools.connectivity.console.profile_1.0.10.v201109250955.jar
      org.eclipse.datatools.connectivity.db.generic_1.0.1.v201107221459.jar
      org.eclipse.datatools.connectivity.dbdefinition.genericJDBC_1.0.1.v201107221459.jar
      org.eclipse.datatools.connectivity.oda.consumer_3.2.5.v201109151100.jar
      org.eclipse.datatools.connectivity.oda.design_3.3.5.v201204241156.jar
      org.eclipse.datatools.connectivity.oda.flatfile_3.1.2.v201206121559.jar
      org.eclipse.datatools.connectivity.oda.profile_3.2.7.v201203291105.jar
      org.eclipse.datatools.connectivity.oda_3.3.3.v201110130935.jar
      org.eclipse.datatools.connectivity.sqm.core_1.2.5.v201205240353.jar
      org.eclipse.datatools.connectivity_1.2.5.v201206130431.jar
      org.eclipse.datatools.enablement.hsqldb.dbdefinition_1.0.0.v201107221502.jar
      org.eclipse.datatools.enablement.hsqldb_1.0.0.v201107221502.jar
      org.eclipse.datatools.enablement.ibm.db2.luw.dbdefinition_1.0.4.v201107221502.jar
      org.eclipse.datatools.enablement.ibm.db2.luw_1.0.2.v201107221502.jar
      org.eclipse.datatools.enablement.ibm.informix.dbdefinition_1.0.4.v201107221502.jar
      org.eclipse.datatools.enablement.ibm.informix_1.0.1.v201107221502.jar
      org.eclipse.datatools.enablement.msft.sqlserver.dbdefinition_1.0.1.v201201240505.jar
      org.eclipse.datatools.enablement.msft.sqlserver_1.0.1.v201107221504.jar
      org.eclipse.datatools.enablement.mysql.dbdefinition_1.0.4.v201109022331.jar
      org.eclipse.datatools.enablement.mysql_1.0.3.v201205252211.jar
      org.eclipse.datatools.enablement.oda.ws_1.2.4.v201203221631.jar
      org.eclipse.datatools.enablement.oda.xml_1.2.3.v201112061438.jar
      org.eclipse.datatools.enablement.oracle.dbdefinition_1.0.103.v201206010214.jar
      org.eclipse.datatools.enablement.oracle_1.0.0.v201107221506.jar
      org.eclipse.datatools.enablement.postgresql.dbdefinition_1.0.2.v201110070445.jar
      org.eclipse.datatools.enablement.postgresql_1.1.1.v201205252207.jar
      org.eclipse.datatools.modelbase.dbdefinition_1.0.2.v201107221519.jar
      org.eclipse.datatools.modelbase.derby_1.0.0.v201107221519.jar
      org.eclipse.datatools.modelbase.sql.query_1.1.3.v201206060918.jar
      org.eclipse.datatools.modelbase.sql_1.0.5.v201110151330.jar
      org.eclipse.emf.common_2.8.0.v20120606-0717.jar
      org.eclipse.emf.ecore.change_2.8.0.v20120606-0717.jar
      org.eclipse.emf.ecore.xmi_2.8.0.v20120606-0717.jar
      org.eclipse.emf.ecore_2.8.0.v20120606-0717.jar
      org.eclipse.emf_2.6.0.v20120608-0554.jar
      org.eclipse.equinox.app_1.3.100.v20120522-1841.jar
      org.eclipse.equinox.common_3.6.100.v20120522-1841.jar
      org.eclipse.equinox.preferences_3.5.0.v20120522-1841.jar
      org.eclipse.equinox.registry_3.5.200.v20120522-1841.jar
      org.eclipse.osgi.services_3.3.100.v20120522-1822.jar
      org.eclipse.osgi_3.8.0.v20120529-1548.jar
      org.eclipse.update.configurator_3.3.200.v20120523-1752.jar
      org.w3c.css.sac_1.3.0.v200805290154.jar
      org.w3c.dom.smil_1.0.0.v200806040011.jar
      org.w3c.dom.svg_1.1.0.v201011041433.jar
      saaj.jar
      Tidy.jar
      viewservlets.jar

Steps common to Maven and non-Maven type projects

  1. Create these directories under the web application folder:
    1. logs
    2. report
    3. report/images
    4. scriptlib
  2. Under the WEB-INF folder, create a tlds folder.
  3. Under WEB-INF folder, put birt.tld (see programfiles.zip in Downloadable resources).
  4. Put the server-config.wsdd and viewer.properties files (see programfiles.zip in Downloadable resources) under the WEB-INF folder.
  5. Put the webcontent folder (see webcontent.zip in Downloadable resources) under the web application folder.
  6. Put your report design files (.rptdesign) files under the report folder.
  7. After all the folders are created properly and the different files are put in place, the WebContent folder resembles the list in Figure 1:
    Figure 1. Directory listing
    Screen capture of the WebContent folder, subfolders, and files
    Screen capture of the WebContent folder, subfolders, and files
  8. Add the code in Listing 3 to your web.xml file.
    Listing 3. Entries in Web.xml 1
    <!-- Report resources directory for preview. Defaults to ${birt home} -->
    
      <context-param>
        <param-name>BIRT_VIEWER_WORKING_FOLDER</param-name>
        <param-value>report</param-value>
      </context-param>
    
      <!-- Flag whether the report resources can be accessed only under the working folder. Defaults to true -->
      <context-param>
        <param-name>WORKING_FOLDER_ACCESS_ONLY</param-name>
        <param-value>true</param-value>
      </context-param>
    
      <!-- Settings for how to deal with the url report path. For example, "http://host/repo/test.rptdesign".
           Following values are supported: 
           <all> - All paths.
           <domain> - Only the paths with host matches current domain. 
           The comparison is literal, "127.0.0.1" and "localhost" are 
           considered as different hosts. <none> - URL paths are not supported. 
           Defaults to "domain". -->
      <context-param>
        <param-name>URL_REPORT_PATH_POLICY</param-name>
        <param-value>domain</param-value>
      </context-param>
    
      <!-- Defines the BIRT viewer configuration file -->
      <context-param>
        <param-name>BIRT_VIEWER_CONFIG_FILE</param-name>
        <param-value>WEB-INF/viewer.properties</param-value>
      </context-param>
    
      <!-- Flag whether to allow server-side printing. Possible values are "ON" and "OFF". Defaults to "ON". -->
      <context-param>
        <param-name>BIRT_VIEWER_PRINT_SERVERSIDE</param-name>
        <param-value>ON</param-value>
      </context-param>
    
      <!-- Flag whether to force browser-optimized HTML output. Defaults to true -->
      <context-param>
        <param-name>HTML_ENABLE_AGENTSTYLE_ENGINE</param-name>
        <param-value>true</param-value>
      </context-param>
    
      <!-- Filename generator class/factory to use for the exported reports. -->
      <context-param>
        <param-name>BIRT_FILENAME_GENERATOR_CLASS</param-name>
        <param-value>org.eclipse.birt.report.utility.filename.DefaultFilenameGenerator</param-value>
      </context-param>
    
      <!-- Viewer Filter used to set the request character encoding to UTF-8. -->
      <filter>
        <filter-name>ViewerFilter</filter-name>
        <filter-class>org.eclipse.birt.report.filter.ViewerFilter</filter-class>
      </filter>
      <filter-mapping>
        <filter-name>ViewerFilter</filter-name>
        <servlet-name>ViewerServlet</servlet-name>
      </filter-mapping>
      <filter-mapping>
        <filter-name>ViewerFilter</filter-name>
        <servlet-name>EngineServlet</servlet-name>
      </filter-mapping>
    
      <!-- Viewer Servlet Context Listener -->
      <listener>
        <listener-class>org.eclipse.birt.report.listener.ViewerServletContextListener</listener-class>
      </listener>
    
      <!-- Viewer HttpSession Listener -->
      <listener>
        <listener-class>org.eclipse.birt.report.listener.ViewerHttpSessionListener</listener-class>
      </listener>
      <!-- Viewer Servlet, Supports SOAP -->
      <servlet>
        <servlet-name>ViewerServlet</servlet-name>
        <servlet-class>org.eclipse.birt.report.servlet.ViewerServlet</servlet-class>
      </servlet>
    
      <!-- Engine Servlet -->
      <servlet>
        <servlet-name>EngineServlet</servlet-name>
        <servlet-class>org.eclipse.birt.report.servlet.BirtEngineServlet</servlet-class>
      </servlet>
    
      <servlet-mapping>
        <servlet-name>ViewerServlet</servlet-name>
        <url-pattern>/frameset</url-pattern>
      </servlet-mapping>
    
      <servlet-mapping>
        <servlet-name>ViewerServlet</servlet-name>
        <url-pattern>/run</url-pattern>
      </servlet-mapping>
    
      <servlet-mapping>
        <servlet-name>EngineServlet</servlet-name>
        <url-pattern>/preview</url-pattern>
      </servlet-mapping>
    
      <servlet-mapping>
        <servlet-name>EngineServlet</servlet-name>
        <url-pattern>/download</url-pattern>
      </servlet-mapping>
    
      <servlet-mapping>
        <servlet-name>EngineServlet</servlet-name>
        <url-pattern>/parameter</url-pattern>
      </servlet-mapping>
    
      <servlet-mapping>
        <servlet-name>EngineServlet</servlet-name>
        <url-pattern>/document</url-pattern>
      </servlet-mapping>
    
      <servlet-mapping>
        <servlet-name>EngineServlet</servlet-name>
        <url-pattern>/output</url-pattern>
      </servlet-mapping>
    
      <servlet-mapping>
        <servlet-name>EngineServlet</servlet-name>
        <url-pattern>/extract</url-pattern>
      </servlet-mapping>
    
      <!-- For Web module version higher than 2.3 -->
      <!--
      <jsp-config>
        <taglib>
          <taglib-uri>/birt.tld</taglib-uri>
          <taglib-location>/WEB-INF/tlds/birt.tld</taglib-location>
        </taglib>
      </jsp-config>
      -->
    
    <!-- For Web module version 2.3 -->
      <taglib>
        <taglib-uri>
          /birt.tld
        </taglib-uri>
    		<taglib-location>
          /WEB-INF/tlds/birt.tld
        </taglib-location>
      </taglib>
  9. Build and deploy your application.
  10. View the report with the following URLs:
    • To view the report in the BIRT viewer

      http://[host]:[port]/[/[context name]/frameset?__report=[your report].rptdesign

    • To view the full report in PDF or HTML format

      http://[host]:[port]/[context name]/run?__report=[report name].rptdesign&__format=[pdf/html]

All the files and folder contents as attached in the document (viewservlets.jar, birt.tld, viewer.properties, server-config.wsdd, and webcontent.zip) are from the BIRT runtime 4.2.0 download. Find the webcontent.zip and programfiles.zip files in Downloadable resources.

Conclusion

In this article, you learned how to integrate the sample BIRT viewer (that is provided with the BIRT runtime download) with a Java/Java EE-based dynamic web project. This integration facilitates the reuse of the viewer (thus saving time in developing a custom viewer for reports) and helps in incorporating other useful features that it provides (see Examining the problem).


Downloadable resources


Related topics

  • Download the BIRT run time 4.2.0 from Eclipse downloads. The entries in the web.xml suggested in Listing 3 are from the web.xml file that is in the WebViewerExample\WEB-INF folder of BIRT run time 4.2.0.
  • Visit the standard Maven repository site for more about the dependency entries in pom.xml as suggested in Listing 1.
  • Learn about the Maven install command at Apache Maven project.
  • Get the details on Business Intelligence and Reporting Tools (BIRT) at Eclipse BIRT Project.

Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Data and analytics
ArticleID=981207
ArticleTitle=Integrate the BIRT Viewer with Java and Java EE web applications
publish-date=09022014