So far in this book, we have developed a bunch of reports. While some of these reports were intended to be used for our own purposes, some reports may be intended for use by other people. How do we get these reports to the users who need to run them? That's the question that deployment seeks to answer.
With BIRT, deployment is a large topic. Some people consider the BIRT Viewer that comes with the BIRT Runtime as the deployment endpoint. On the contrary, BIRT deployment is a much larger product due to the fact that the BIRT Report Engine API is available to embed into Java applications.
In this chapter, we are going to look at two of the different deployment options available. We will look at the BIRT Viewer for J2EE that comes with the BIRT Runtime and that is embedded into the BIRT Eclipse IDE. We are also going to look at a basic Java application that implements the Report Engine API to run reports. We are also going to look at the command line tools that come with the BIRT Runtime for executing reports.
Everything in this chapter uses utilities from the BIRT Runtime installation package, available from the BIRT homepage (http://www.eclipse.org/birt).
The BIRT Viewer is a J2EE application that is designed to demonstrate the implementation of 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 thing 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 and http://wiki.eclipse.org/BIRT/FAQ/Deployment.
This is also documented on my website in a series of articles, aimed at introducing people to BIRT (http://digiassn.blogspot.com/2005/10/birt-report-server-pt-2.html).
Let's not go into details about installing Apache Tomcat as this is covered in more depth in other locations, but we 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 as 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 application is a useful application if one requires basic report viewing capabilities such as parameter passing, pagination, and the ability to export to formats such as Word, Excel, RTF, and CSV.
In this example, we have Apache Tomcat 5.5 installed into a folder at C:apache-tomcat-5.5.25. To install the web viewer, we simply need to copy the WebViewerExample folder from the BIRT Runtime to the web application folder at C:apache-tomcat-5.5.25webapps.
Accessing the BIRT web viewer is as simple as calling the WebViewerExample context.
When copying the WebViewerApplication, we can rename this folder to anything of our choice. Obviously, WebViewerApplication is not a good name for an online web application. So, as shown in the following screenshot, let's rename the WebViewerApplication folder to birtViewer, and access the Birt Web Viewer test report. When we click on the View Example link in the preceding screenshot, we can see the report viewer as shown here:
More information on installing the BIRT Web Viewer can be found at http://www.eclipse.org/birt/phoenix/deploy/viewerSetup.php.
Once the BIRT Viewer is set up, deploying reports is as simple as copying the report design files, libraries, or report documents into the applications 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 in the "birtViewer" subfolder. 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.
Accessing reports is as simple as passing the correct parameters to the web viewers. In the BIRT web viewer, there are following seven servlets that we can call to run reports:
framesetrunpreviewdownloadparameterdocumentoutput
Out of these, we will need only frameset and run, as the other servlets are for Engine things, such as the preview for the Eclipse designer, the parameter dialog, and the downloading of report documents.
Out of the two remaining servlets, frameset is the one that is typically used for user interaction with reports as it provides pagination options, parameter dialogs, table of contents viewing, and export and print dialogs. The run servlet provides only report the output feature.
There are a few URL parameters for the BIRT Web Viewer.
Any remaining URL parameters will be treated as a report parameter. In the following image, we are running the Employee_Sales_Percentage.rptDesign file with the start and end date parameters set.
More information on BIRT Viewer's usage can be found on the Eclipse BIRT Viewer page at http://www.eclipse.org/birt/phoenix/deploy/viewerSetup.php.