Birt Reporting Plugin

  • Tags: report, charts, charting
  • Latest: 4.3.0.3
  • Last Updated: 02 September 2013
  • Grails version: 2.0 > *
11 votes
Dependency:
compile ":birt-report:4.3.0.3"
Custom repositories:
mavenRepo "http://www.it-jw.com/maven/"

 Documentation  Source  Issues

Summary

Makes it easy to integrate the Birt reporting engine (runtime component) into your Grails application. Currently BIRT 4.3.0 is used.

Installation

To use the plugin put the following into your BuildConfig.groovy:
grails.project.dependency.resolution = {
    plugins {
        compile ":birt-report:4.3.0.2"
    }
    repositories {
        . . .
        mavenRepo "http://www.it-jw.com/maven"
        . . .
    }
}

Description

The birt-report plugin allows to embed reports created using the BIRT Report Engine into your Grails application.

Using the plugin

Generating Reports

To generate a report you need to do the following

// generate html output and send it to the browser
    def show() {
        String reportName = params.remove('id')
        String reportExt = 'pdf'
        params.remove('action')
        params.remove('controller')
        params.remove('name')
        def options = birtReportService.getRenderOption(request, 'html')
        def result=birtReportService.runAndRender(reportName, params, options)
        response.contentType = 'text/html'
        response.outputStream << result.toByteArray()
        return false
    }
    // generate pdf for download
    def downloadAsPDF() {
        String reportName = params.remove('id')
        String reportExt = 'pdf'
        params.remove('action')
        params.remove('controller')
        params.remove('name')
        def options = birtReportService.getRenderOption(request, 'pdf')
        def result=birtReportService.runAndRender(reportName, params, options)
        response.setHeader("Content-disposition", "attachment; filename=" +reportName + "."+reportExt);
        response.contentType = 'application/pdf'
        response.outputStream << result.toByteArray()
        return false
    }

Localization of reports

The localization of BIRT reports is described at the BIRT help and the BIRT FAQ; a tutorial can be found at Dummies Mind. Once the report and its property-files are deployed the report should be rendered using the locale provided by grails (based on the accept-language header of the request). This locale can be overwritten by appending the url parameter lang (see the Grails userguide).

This mechanism works well if you have a request. If the service is used without a request (e.g. in a quartz job) it falls back to the locale of the host system which might not be what you want. Therefore the run, render, and runAndRender methods offer the possibility to overwrite the locale by providing a java.util.Locale object as an optional parameter. This way the locale used in the report can be specified explicitly.

BirtReportService interface

The following methods are provided wich require the following parameters:

  • listReports : returns a list of the available reports found in the reportHome directory
  • getReportProperties : returns the standard and custom properties of a specific report
    • reportName - name of the report (without extension), the file name will be derived of it
    • userProps - list of user properties to be read from the report
  • getReportProperties : same as getReportProperties but reads from an input stream
    • reportName - name of the report
    • inputStream - the input stream holding the report file content
    • userProps - list of user properties to be read from the report
  • getReportParams : returns a complete list of the report parameters
    • reportName - name of the report (without extension), the file name will be derived of it
  • getReportParams : same as getReportParams but reads from an input stream
    • reportName - name of the report
    • inputStream - the input stream holding the report file content
  • getReportParamNames : returns a list of the report parameter names
    • reportName - name of the report (without extension), the file name will be derived of it
  • getReportParamNames : same as getReportParamNames but reads from an input stream
    • reportName - name of the report (without extension), the file name will be derived of it
    • inputStream - the input stream holding the report file content
  • getRenderOption : creates a render option which can be used with runAndRender or render
    • format - format of the output to be generated (html, pdf, xls, doc, ppt)
  • getRenderOption : creates a render option which can be used with runAndRender or render
    • request - the request (this is used to determine the context path)
    • format - format of the output to be generated (html, pdf, xls, doc, ppt)
  • getRenderOption : creates a render option which can be used with runAndRender or render
    • request - the request (this is used to determine the context path)
    • format - format of the output to be generated (html, pdf, xls, doc, ppt)
    • genSVG - enable/disable the use of SVG graphics for chart generation
  • runAndRender : run and render a document using the given report parameters and render options
    • reportName - name of the report (without extension), the file name will be derived of it
    • parameters - parameters to be passed to the report engine running the report
    • renderOptions - options specifying the output format
    • locale - a java.util.Locale object describing the locale the report is render to. If omitted or null the locale provided by grails is used
  • runAndRender : same as runAndRender but reads from an input stream
    • reportName - name of the report
    • inputStream - the input stream holding the report file content
    • parameters - parameters to be passed to the report engine running the report
    • renderOptions - options specifying the output format
    • locale - a java.util.Locale object describing the locale the report is render to. If omitted or null the locale provided by grails is used
  • run : run a given report generating a report document (containing the data)
    • reportName - name of the report (without extension), the file name will be derived of it
    • parameters - parameters to be passed to the report engine running the report
    • reportDocumentName - name of the report document
    • locale - a java.util.Locale object describing the locale the report is render to. If omitted or null the locale provided by grails is used
  • run : same as run but reads from an input stream
    • reportName - name of the report
    • inputStream - the input stream holding the report file content
    • parameters - parameters to be passed to the report engine running the report
    • reportDocumentName - name of the report document
    • locale - a java.util.Locale object describing the locale the report is render to. If omitted or null the locale provided by grails is used
  • render : render a report document into a specific output format
    • reportDocumentName - name of the report document
    • parameters - parameters to be passed to the report engine running the report
    • renderOptions - options specifying the output format
    • locale - a java.util.Locale object describing the locale the report is render to. If omitted or null the locale provided by grails is used

Configuring the plugin

The plugin supports configuration via the default Grails configuration file Config.groovy . You can also use the per-environment configuration feature.

Currently supported options:

  • birt.reportHome - the location where report files are stored. This can be absolute or relative; in the latter case it is relative to the web app root directory.
  • birt.imageUrl - the location where temporary images for HTML pages are stored. Since images need to be accessible via the web app the path is always relative to the web app root directory.
  • birt.generateAbsoluteBaseURL - enables the generation of absolute URLs if the URLs are taken from a HTTPServletRequest
  • birt.baseUrl - the base URL to use for links if they are used within the report (e.g. drill-down). The baseUrl should be absolut, ie. starts with http: or you should set birt.generateAbsoluteBaseURL = true . The Format should be controllerName / actionName . The action get the name of the report via params.id .
  • birt.useGrailsDatasource - a boolean enabling the use of the grails datasource as the report datasource (default is false). This can be modified on case by case basis by setting the property useGrailsDatasource of the service to true or false .
  • birt.cacheSize - size of the memory cache to use for report generation (in mega bytes)
A simple example:
birt {
    reportHome = "Reports" // will be in the webapp directory during development
    imageUrl = "images/report" // this is a subdirectory of the images dir in the webapp directory, where BIRT stores the chart-images.
}

Troubleshooting

  • Using Tomcat on linux without having a X-Server running you have to set an option in catalina.sh
    JAVA_OPTS="${JAVA_OPTS} -Djava.awt.headless=true "
  • If you run into out-of-memory issues you can try to increase the PermGen Space. For Suns JVM you may use
    -XX:MaxPermSize=80m
  • if you deploy on linux - you need to set writable permission on the birt engine directory

Running an example

An example can be found at http://www.it-jw.com/grails/birt-report-test_0.5.zip (it is just 287kB). This example uses a quartz job to read and cache report descriptions (e.g. to do context or parameter dependent report listing) and provides a simple way to upload report documents and associated files (like images). If you use a grails version other than 2.2.3 you need to run:

grails upgrade
Now you are ready to run the example. The ReportScanJob will fire 10 secs after the app start and will populate the database. After that you can get a list of available reports (initially there is a helloWorld report) and run them.

Releases

Version 4.3.0.3 - 02-sep-2013

Fixed a bug which prevented the extraction of report parameters if the report content comes from an input stream

Version 4.3.0.2 - 11-Aug-2013

Fixed dependency problems

Version 4.3.0.0 - 8-Aug-2013

Upgraded BIRT engine to version 4.3.0

Added service function using an input stream for the report design instead of deriving the file name and location

Version 3.7.2.0 - 4-Jul-2012

Added birt runtime jar which is now bundled with the plugin.

Version 3.7.0.1 - 15-Sep-2011

Added the ability to localize the generated reports based on the grails localization mechanism

Version 3.7.0.0 - 14-Aug-2011

Updated the BIRT version used to v3.7.0. This release does not need a special handling anymore as all OSGI plugins are bundled into a single jar not having plugin.xml descriptors anymore

Version 2.6.1.0 - 26-Oct-2010

Updated the BIRT version used to 2.6.1. The version number of the plugin will stay in sync with the BIRT version number.

Version 1.1 - 18-Sep-2010

Updated the BIRT version used to 2.6.0

Version 1.0 - 28-Jun-2010

Fixed download location

Version 0.8 - 19-Oct-2009

Skipped some versions in the changelog :-( therefore a wrap-up:

  • splitted runAndRender into run and render method to allow reuse of compiled report documents to generate different output formats from the same data
  • added the use of the grails datasource as the report data soruce (THX to Niels Stargardt for pointing this out)
  • added the possibility to create renderOptions without a request to enable batch generation of reports, in this case the birt.baseUrl setting becomes important if links are use in the report documents
  • fixed a bug while detecting absolute pathes on Windows (THX to Jean-Francois Dube for spotting this)
  • fixed the download location of the BIRT runtime for the plugin installation
  • added some javadoc to the service
Version 0.5 - 04-Aug-2009

Minor update due to missing compile time dependencies

Version 0.4 - 04-Aug-2009

Update of BIRT to version 2.5.0 following the Galileo release

Version 0.2 - 29-Mar-2009

First release to Grails repositories