Deployment of Reports with BIRT

Exclusive offer: get 50% off this eBook here
Practical Data Analysis and Reporting with BIRT

Practical Data Analysis and Reporting with BIRT — Save 50%

Use the open-source Eclipse-based Business Intelligence and Reporting Tools system to design and create reports quickly

$23.99    $12.00
by John Ward | January 2009 | Java Open Source

Deployment answers the need to have the generated reports reach the relevant user.In this article by John Ward, we are going to look at two different Deployment options available. We will look at the BIRT Viewer for J2EE that comes with the BIRT Runtime and is embedded into the BIRT Eclipse IDE, and we are also going to look at a basic Java application that implements the Report Engine API to run reports. We will also cover the command-line tools that come with the BIRT Runtime for executing reports.

Everything in this article uses utilities from the BIRT Runtime installation package, available from the BIRT homepage at http://www.eclipse.org/birt.

BIRT Viewer

The BIRT Viewer is a J2EE application that is designed to demonstrate how to implement the Report Engine API to execute reports in an online web application. For most basic uses—such as for small to medium size Intranet applications—this is an appropriate approach. The point to keep in mind about the BIRT Web Viewer is that it is an example application. It can be used as a baseline for more sophisticated web applications that will implement the BIRT Report Engine API.

Installation of the BIRT Viewer is documented at a number of places. The Eclipse BIRT website has some great tutorials at:

http://www.eclipse.org/birt/phoenix/deploy/viewerSetup.php

http://wiki.eclipse.org/BIRT/FAQ/Deployment

This is also documented on my website in a series of articles introducing people to BIRT:

http://digiassn.blogspot.com/2005/10/birt-report-server-pt-2.html

I won't go into the details about installing Apache Tomcat as this is covered in depth in other locations, but I will cover how to install the Viewer in a Tomcat environment. For the most part these instructions can be used in other J2EE containers, such as WebSphere. In some cases a WAR package is used instead. I prefer Tomcat because it is a widely used open-source J2EE environment.

Under the BIRT Runtime package is a folder containing an example Web Viewer application. The Web Viewer is a useful application as you require basic report viewing capabilities, such as parameter passing, pagination, and export capabilities to formats such as Word, Excel, RTF, and CSV.

Deployment of Reports with BIRT

For this example, I have Apache Tomcat 5.5 installed into a folder at C:apache-tomcat-5.5.25. To install the Web Viewer, I simply need to copy the WebViewerExample folder from the BIRT Runtime to the web application folder at C:apache-tomcat-5.5.25webapps.

Deployment of Reports with BIRT

Accessing the BIRT Web Viewer is as simple as calling the WebViewerExample Context.

Deployment of Reports with BIRT

When copying the WebViewerExample folder, you can rename this folder to anything you want. Obviously WebViewerExample is not a good name for an online web application. So in the following screenshot, I renamed the WebViewerExample folder to birtViewer, and am accessing the BIRT Web Viewer test report.

Deployment of Reports with BIRT

Installing Reports into the Web Viewer

Once the BIRT Viewer is set up, Deploying reports is as simple as copying the report design files, Libraries, or report documents into the application's Context, and calling it with the appropriate URL parameters.

For example, we will install the reports from the Classic Cars – With Library folder into the BIRT Web Viewer at birtViewer. In order for these reports to work, all dependent Libraries need to be installed with the reports. In the case of the example application, we currently have the report folder set to the Root of the web application folder.

Deployment of Reports with BIRT

Accessing Reports in the Web Viewer

Accessing reports is as simple as passing the correct parameters to the Web Viewer. In the BIRT Web Viewer, there are seven servlets that you can call to run reports, which are as follows:

  • frameset
  • run
  • preview
  • download
  • parameter
  • document
  • output

Out of these, you will only need frameset and run as the other servlets are for Engine-related purposes, such as the preview for the Eclipse designer, the parameter Dialog, and the download of report documents.

Out of the these two servlets, frameset is the one that is typically used for user interaction with reports, as it provides the pagination options, parameter Dialogs, table of contents viewing, and export and print Dialogs. The run servlet only provides report output.

Deployment of Reports with BIRT

There are a few URL parameters for the BIRT Web Viewer, such as:

  • __format : which is the output format, either HTML or PDF.
  • __isnull: which sets a Report Parameter to null, parameter name as a value.
  • __locale: which is the reports locale.
  • __report: which is the report design file to run.
  • __document: which is the report document file to open.

Any remaining URL parameter will be treated as a Report Parameter. In the following image, I am running the Employee_Sales_Percentage.rptdesign file with the startDate and endDate parameters set.

Deployment of Reports with BIRT

 

Practical Data Analysis and Reporting with BIRT Use the open-source Eclipse-based Business Intelligence and Reporting Tools system to design and create reports quickly
Published: February 2008
eBook Price: $23.99
Book Price: $39.99
See more
Select your format and quantity:

To Schedule this file to run, I go to the Control Panel|Scheduled Tasks, and create a new Scheduled Task. I set the command to run as C:birt_runtimebirt-runtime-2_1_0ReportEnginerunReport.bat. I set up the appropriate time, and set the directory to start in as C:birt_runtimebirt-runtime-2_1_0ReportEngine. I also set this to run as a dedicated report user. The following figure illustrates the values I use under Scheduler.

Deployment of Reports with BIRT

Now, I can schedule BIRT reports to run without needing Apache. This cuts down on system overhead. There are a few caveats to take into consideration. If your BIRT report hits a database, the appropriate drivers will need to be included in the ReportEngineplugins folders. For example, if the report uses JDBC to connect, the JDBC drivers will need to be installed under the ReportEnginepluginsorg.eclipse.birt.report.data.oda.jdbc_<version> folder. Also, you will need to copy the iText.jar file (as indicated in the BIRT Runtime installation instructions) to the appropriate plug-ins directory.

From this exercise, I learned a few interesting things. I was unaware that Java classes could be invoked from the command line. For example, if I set an environment variable called BIRTClassPath like the following:

SET BIRTCLASSPATH=%BIRT_HOME%ReportEnginelibcommons-cli-1.0.jar;%BIRT_
HOME%ReportEnginelibcommons-codec-1.3.jar;%BIRT_HOME%ReportEngine
libcom.ibm.icu_3.4.4.1.jar;%BIRT_HOME%ReportEnginelibcoreapi.jar;
%BIRT_HOME%ReportEnginelibdteapi.jar;%BIRT_HOME%ReportEngine
libengineapi.jar;%BIRT_HOME%ReportEnginelibjs.jar;%BIRT_HOME%
ReportEnginelibmodelapi.jar;%BIRT_HOME%ReportEngineflute.jar;%BIRT_
HOME%ReportEnginelibsac.jar;

I can run the following command from the DOS prompt and get the parameters that the ReportEngine class is expecting:

java -cp "%BIRTCLASSPATH%" org.eclipse.birt.report.engine.api.ReportRunner
org.eclipse.birt.report.engine.impl.ReportRunner
--mode/-m [ run | render | runrender] the default is runrender
\For runrender mode: we should add it in the end<design file>
--format/-f [ HTML | PDF ]
--output/-o <target file>
--htmlType/-t < HTML | ReportletNoCSS >
--locale /-l<locale>
--parameter/-p <parameterName=parameterValue>
--file/-F <parameter file>
--encoding/-e <target encoding>
\locale: default is English
\Parameters in command line will override parameters in parameter file
\Parameter name can't include characters such as ' ', '=', ':'
\For RUN mode: we should add it in the end<design file>
--output/-o <target file>
--locale /-l<locale>
--parameter/-p <parameterName=parameterValue>
--file/-F <parameter file>
\locale: default is English
\Parameters in command line will override parameters in parameter file
\Parameter name can't include characters such as ' ', '=', ':'
\For RENDER mode: we should add it in the end<design file>
--output/-o <target file>
t --page/-p <pageNumber>
--locale /-l<locale>
\locale: default is English

For me, this is a major break from the paradigm of "compile and run" software in other languages.

Report Engine API

Embedding the Report Engine API into your application requires a little knowledge of the inner workings of BIRT. The API is outside of the scope of this article, but we will get a brief view of how to do a simple report executor application.

The requirements for this application to work are that you have Java 1.4 or higher set up, and have the BIRT Runtime set up and visible in your Classpath. I am also using Apache Commons CLI to handle the command-line options. The following does not take into account the parameters; it simply demonstrates how to instantiate the Report Engine API.

package com.birt_book;
import java.util.HashMap;
import org.apache.commons.cli.CommandLine;
import org.apache.commons.cli.CommandLineParser;
import org.apache.commons.cli.HelpFormatter;
import org.apache.commons.cli.Options;
import org.apache.commons.cli.PosixParser;
import org.eclipse.birt.core.exception.BirtException;
import org.eclipse.birt.core.framework.Platform;
import org.eclipse.birt.core.framework.PlatformConfig;
import org.eclipse.birt.report.engine.api.EngineConfig;
import org.eclipse.birt.report.engine.api.EngineConstants;
import org.eclipse.birt.report.engine.api.EngineException;
import org.eclipse.birt.report.engine.api.HTMLRenderContext;
import org.eclipse.birt.report.engine.api.HTMLRenderOption;
import org.eclipse.birt.report.engine.api.IReportEngine;
import org.eclipse.birt.report.engine.api.IReportEngineFactory;
import org.eclipse.birt.report.engine.api.IReportRunnable;
import org.eclipse.birt.report.engine.api.IRunAndRenderTask;
public class ReportExecutor {
private static String BIRT_HOME =
 "C:/BIRT_RUNTIME_2_2/birt-runtime-2_2_0/ReportEngine";
private static String IMAGE_PATH = "C:/BIRT_RUNTIME_2_2/images";
private String reportLocation;
private String reportOutputLocation;
/**
* setupCLIParameters
*
* This will setup the arguments
* @return
*/
public Options setupCLIParameters()
{
Options options = new Options();
options.addOption("i", "input", true, "The report file to execute");
options.addOption("o", "output", true, "The name of the output file");
return options;
}
/**
* parseCommandLineOptions
*
* Given the arguments passed into main, this method will use the
* Apache Commons CLI
* to parse those options and return
* a CommandLine object with the options
*
* @param args
* @return CommandLine
*/
public CommandLine parseCommandLineOptions(String []args)
{
//First, parse the command line options using Apache Commons CLI
CommandLineParser parser = new PosixParser();
Options options = setupCLIParameters();
CommandLine line = null;
HelpFormatter formatter = new HelpFormatter();
//Try to parse the command line options, exit the app if there is an error
try {
//Get the options
line = parser.parse(options, args);
catch (Exception e) {
System.err.println("Parsing failed. Reason: " + e.getMessage());
formatter.printHelp("ReportExecutor", options);
System.exit(-1);
}
return line;
}
/**
* startupPlatform
*
* This will startup the Eclipse platform and load any plugins
*/
private void startupPlatform()
{
//Initialize the Eclipse platform, plug-ins, and Report Engine
PlatformConfig platformConfig = new PlatformConfig();
platformConfig.setBIRTHome(BIRT_HOME);
try {
Platform.startup(platformConfig);
catch (BirtException e) {
e.printStackTrace();
//We cannot start the platform, exit
System.exit(-1);
}
}
/**
* createReportEngine
*
* This will create a report engine to use
* @return
*/
private IReportEngine createReportEngine()
{
//Create a new report engine factory
IReportEngineFactory factory = (IReportEngineFactory) Platform.
createFactoryObject(IReportEngineFactory.
EXTENSION_REPORT_ENGINE_FACTORY);
//create a new report engine
EngineConfig engineConfig = new EngineConfig();
engineConfig.
setBIRTHome("C:/BIRT_RUNTIME_2_2/birt-runtime-2_2_0/ReportEngine");
//will replace with configuration file
return factory.createReportEngine(engineConfig);
}
/**
* Executes a report with no parameters, only requires report name to execute
* @param reportName
* @return
*/
public void executeReportNoParams(String reportName, String outputFile,
IReportEngine engine)
{
try {
//Create the report runnable and runandrender task
IReportRunnable runnable = engine.openReportDesign(reportName);
IRunAndRenderTask task = engine.createRunAndRenderTask(runnable);
//Set Render context to handle url and image locations
HTMLRenderContext renderContext = new HTMLRenderContext();
renderContext.setImageDirectory(IMAGE_PATH);
HashMap contextMap = new HashMap();
contextMap.put( EngineConstants.APPCONTEXT_HTML_RENDER_CONTEXT,
renderContext );
task.setAppContext( contextMap );
//Set rendering options - such as file or stream output,
//Output format, whether it is embeddable, etc
HTMLRenderOption options = new HTMLRenderOption();
options.setOutputFileName(outputFile);
options.setOutputFormat("html");
task.setRenderOption(options);
//Run the report and close
task.run();
task.close();
catch (EngineException e) {
e.printStackTrace();
System.exit(-1);
}
}
/**
* executeReport
*
* This method will execute the report and save the the output file
* @param reportInput
* @param reportOutput
*/
public void executeReport(String reportInput, String reportOutput)
{
//Start up the platform
startupPlatform();
//Create a Report Engine
IReportEngine engine = createReportEngine();
//Create a run and render task, and execute report
executeReportNoParams(reportInput, reportOutput, engine);
//Shutdown platform
Platform.shutdown();
}
/**
* @param args
*/
public static void main(String[] args) {
ReportExecutor re = new ReportExecutor();
//Get command line options
CommandLine cl = re.parseCommandLineOptions(args);
//Get the input file and output file
String reportInputFile = cl.getOptionValue("i");
String reportOutputFile = cl.getOptionValue("o");
//Execute the report
re.executeReport(reportInputFile, reportOutputFile);
}
}

Outputting to Different Formats

The BIRT platform supports a plug-in structure based on Eclipse. One of the BIRT Plug-in extension points is the Emitter extension point. Emitters are plug-ins that handle the rendering of reports to different formats.

Out of the box, BIRT comes with several different Emitters. BIRT can output to the following formats with the default Emitters:

  • HTML
  • PDF
  • Microsoft Word
  • Microsoft Excel
  • RTF
  • Microsoft PowerPoint
  • Adobe PostScript

In the BIRT Web Designer, the different output formats are available under the File|View Report menu.

When using the BIRT Web Viewer, you can specify different report formats by using the __format URL parameter. If you specified __format=pdf it would output in the Adobe PDF format, or for __format=xls, it would output in the Microsoft Excel format.

In addition to the URL parameter, there is also an Export dialog available in the frameset servlet.

Deployment of Reports with BIRT

Summary

Although brief, this article gave some examples of how to Deploy BIRT reports. The main options are to use the BIRT Example Web Viewer, to use the example command-line tools, or to embed the BIRT Engine API into your own custom web application.

Practical Data Analysis and Reporting with BIRT Use the open-source Eclipse-based Business Intelligence and Reporting Tools system to design and create reports quickly
Published: February 2008
eBook Price: $23.99
Book Price: $39.99
See more
Select your format and quantity:

About the Author :


John Ward

John Ward is a consultant for Innovent Solutions, specializing in BIRT and e-commerce search and navigation solutions. Prior to that, John was an Assistant Vice President for Citibank, North America, managing the training MIS group and overseeing development of new technology-based training initiatives. John actively works with and tests BIRT—an open-source reporting platform built on Eclipse—including development work based on BIRT reports and the BIRT APIs.

John also maintains The Digital Voice blog at http://digiassn.blogspot.com

Books From Packt

EJB 3 Developer Guide
EJB 3 Developer Guide

Learning Nagios 3.0
Learning Nagios 3.0

Drupal Multimedia
Drupal Multimedia

Service Oriented Architecture with Java
Service Oriented Architecture with Java

Java EE 5 Development using GlassFish Application Server
Java EE 5 Development using GlassFish Application Server

Drupal 6 Themes
Drupal 6 Themes

Learning Ext JS
Learning Ext JS

Alfresco Developer Guide
Alfresco Developer Guide

 

 

 

 

Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software