One way to view a BIRT report on the web is to deploy the BIRT report viewer to an application server, such as Apache Tomcat, IBM WebSphere, JBOSS, or BEA WebLogic.
You deploy the BIRT report viewer by copying files from the BIRT Report Engine, which you must install separately from the BIRT Report Designer. The BIRT Report Engine includes the BIRT report viewer as a web archive (.war) file and as a set of files and folders.
This chapter provides information about deploying the BIRT report viewer using either of these sources.
The instructions in this chapter specifically address deploying a BIRT report to Apache Tomcat version 5.5.7. While the information in this chapter is specific to this version of Tomcat, a BIRT report can also be deployed to other versions of Tomcat and to other application servers.
There are only minor differences between the requirements for deploying to Tomcat version 5.5.7 and deploying to earlier versions of Apache Tomcat. Apache Tomcat 5.5.7 runs Java 5 by default, which is also the recommended version to use for BIRT 2.1. If you use an earlier version of Java, you need to install a compatibility package and configure Apache Tomcat to use the Java 1.4 run-time environment. For information about configuring Apache Tomcat to use Java run-time 1.4, see the Apache Tomcat help pages. You can download Apache Tomcat from jakarta.apache.org/tomcat.
Most application servers require a WAR file that contains everything that the application requires, including a web.xml file describing the application and various deployment preferences. A WAR file appropriate for Tomcat is included with BIRT. In most cases, the WAR file will not require modification. In some cases, however, developers who have experience with other application servers can modify the web.xml file to reflect the requirements of their environments. For more information about setting the web.xml parameters, see the section on mapping the report viewer folders, later in this chapter.
If you are deploying to JBoss, you might need to copy axis.jar and axis-ant.jar from WEB-INF/lib to the following directory:
jboss/server/default/lib
This step might not be necessary for some versions of JBoss, but if you are experiencing difficulty with a JBoss deployment, copying these files might be the solution to your problem.
You must place the BIRT report viewer in a location where Apache Tomcat can access it. The most common location is in the $TOMCAT_INSTALL/webapps directory. By placing the BIRT report viewer in $TOMCAT_INSTALL/webapps, Apache Tomcat automatically recognizes and starts the BIRT report viewer the next time you restart Apache Tomcat.
You must also install an auxiliary file, as explained later in this chapter.
The following instructions assume that you have installed the BIRT Report Engine from the BIRT web site, that your web application directory is $TOMCAT_INSTALL/webapps, and that your BIRT run-time install directory is $BIRT_RUNTIME.
To install the BIRT report viewer from the BIRT Report Engine WAR file, first place the BIRT report viewer WAR file on Apache Tomcat by copying birt.war to $TOMCAT_INSTALL/webapps, as illustrated in the following DOS command:
copy $BIRT_RUNTIME/birt.war $TOMCAT_INSTALL/webapps
Then, restart Apache Tomcat.
How to install the BIRT report viewer from the BIRT Report Engine viewer folder
Navigate to $TOMCAT_INSTALL/webapps.
Create a subdirectory named birt.
To place the BIRT Report Engine on Apache Tomcat, copy the web viewer example directory and all its subdirectories to:
$TOMCAT_INSTALL/webapps
as illustrated in the following DOS command:
xcopy /E "$BIRT_RUNTIME/WebViewerExample" $TOMCAT_INSTALL/webapps/birt
Restart Apache Tomcat.
There is one auxiliary file that you must install on Apache Tomcat. The file is itext_1.3.jar and you must place it in the following directory:
$TOMCAT_INSTALL/birt/WebViewerExample/WEB-INF/platform/ plugins/com.lowagie.itext/lib
You can download itext_1.3.jar from:
http://prdownloads.sourceforge.net/itext/itext-1.3.jar
To test the installation of the BIRT report viewer, type the following URL in a web browser address:
http://server_name/birtwhere server_name is the name of the application server.
There is a JavaServer Page (JSP) called index.jsp in both the WAR file and in the /birt directory. There is also a simple BIRT report design file, test.rptdesign, in both the WAR file and the /birt directory. If the BIRT report viewer is installed correctly, Tomcat uses index.jsp to process the report design file and generate the report described by the design file.
By default, the context root of the URL for a web application is the path to the application directory or the WAR file. The default application directory for the BIRT report viewer is /birt, so the default URL to access a BIRT report from Apache Tomcat is:
http://localhost:8080/birt/run?__report=myReport.rptdesign
To change the BIRT context root, change the name of the /birt directory or the WAR file in $TOMCAT_INSTALL/webapps. After making this change, you must restart Apache Tomcat. Whatever name you choose, specify that name in the URL to access your BIRT report. For example, if you choose reportViewer, the URL to access a BIRT report becomes:
http://localhost:8080/reportViewer/ run?__report=myReport.rptdesign
The URL examples shown in this section access the report design with a relative path. You must set the BIRT_VIEWER_WORKING_FOLDER variable to access the report design with relative paths.
If you choose to place the BIRT report viewer in a location other than $TOMCAT_INSTALL/webapps, you must add a context mapping entry to the server.xml file in $TOMCAT_INSTALL/conf.
To add a context mapping entry, add the following lines to server.xml just above the </host> tag near the end of the file:
<Context path="/birt"
docBase="BIRT_Path"/>where BIRT_Path is the absolute path to the directory containing the BIRT report viewer.
Save your changes to server.xml and restart Apache Tomcat to make your changes active.
To determine the locations for report designs, images in reports, and log files, the BIRT report viewer uses context parameters defined in the web.xml file. Table 5-1 describes the context parameters for mapping folders. The default values of some of the context parameters described in the table depend on whether the application is deployed as a WAR file or a folder structure. When an application is deployed as a WAR file, the application is referred to as a WAR deployment. When an application is deployed as a folder structure, the application is referred to as a non-WAR deployment.
Table 5-1. BIRT context parameters
Description | Default value | |
|---|---|---|
BIRT_VIEWER_IMAGE_DIR | Required for WAR deployment. | No default value for WAR deployment |
Optional for non-WAR deployment. | ||
Absolute path to a writable directory for creating images and chart representations for a report. | <context root>/report/images for non-WAR deployment | |
BIRT_VIEWER_LOG_DIR | Optional. | No default value for WAR deployment |
Absolute path to a writable directory for BIRT Report Engine log messages. | <context root>/logs for non-WAR deployment | |
For WAR deployment, BIRT Report Engine logs messages only when this parameter has a value. | ||
BIRT_VIEWER_WORKING_FOLDER | Optional. | No default value for either WAR |
Absolute path to a writable directory for report designs and temporary files. | deployment or non-WAR deployment | |
Specifying report designs by relative path is possible only when this parameter has a value. | ||
BIRT_VIEWER_SCRIPTLIB_DIR | Optional. | No default value for WAR deployment |
Absolute path to a directory containing Java event handler JAR files. | <context root>/scriptlib for non-WAR deployment | |
BIRT_VIEWER_LOG_LEVEL | Defines the level of error logging, using the standard Java logging level identifiers. Allowable values are ALL, CONFIG, FINE, FINER, FINEST, INFO, OFF, SEVERE, WARNING. For more information about the logging levels, see the Javadoc for java.util.logging.Level. | OFF for both WAR deployment and non-WAR deployment |
How to set the location for report designs
You can avoid including the full path to the report design in the URL if you define BIRT_VIEWER_WORKING_FOLDER in the BIRT report viewer application’s web.xml file.
Open web.xml in a code editor.
To open web.xml in an editor, perform one of the following steps, based on your deployment configuration:
Locate the following element:
<context-param> <param-name>BIRT_VIEWER_WORKING_FOLDER</param-name> <param-value /> </context-param>
Change the param-value element, so that it includes the absolute path to the folder for the report designs:
<context-param> <param-name>BIRT_VIEWER_WORKING_FOLDER</param-name> <param-value>Report_Folder</param-value> </context-param>where
Report_Folderis the absolute path to the folder for the report designs.If you prefer not to use the default directory for event handler JAR files, define the desired path by creating or modifying the following context parameter:
<context-param> <param-name>BIRT_VIEWER_SCRIPTLIB_DIR</param-name> <param-value>Event_Handlers</param-value> </context-param>where
Event_Handlersis the absolute path to the folder containing the event handler JAR files.Save web.xml and close the editor.
If you use a WAR file to deploy the BIRT report viewer, replace web-inf/web.xml in birt.war with the name of the file you just modified.
Copy your report designs into the folder you specified in the param-value element for BIRT_VIEWER_WORKING_FOLDER.
If your report uses Java event handler classes, copy the JAR files containing the event handler classes into <BIRT_VIEWER_SCRIPTLIB_DIR>.
Restart Apache Tomcat.
To verify that Apache Tomcat is running BIRT report viewer, run the Tomcat manager. To run the Tomcat manager, you need a manager’s account. If you have not already set up a Tomcat manager account, you can do so by adding the following two lines to $TOMCAT_INSTALL/conf/tomcat-users.xml:
<role rolename="manager"/> <user username="admin" password="tomcat" roles="manager"/>
Once you have a manager’s account open the Tomcat account manager by opening the Tomcat main page, which for a typical Apache Tomcat installation is http://localhost:8080, shown in Figure 5-1.
On the Tomcat main page, choose Tomcat Manager. In the manager login window, supply the username and password from the manager account entry in tomcat-users.xml file. The Running status for the Eclipse BIRT report viewer is true, as shown in Figure 5-2.
BIRT Report Engine requires certain TrueType fonts in order to display a PDF report. BIRT searches for fonts in the common font directories for Windows and Linux. The list of directories that BIRT searches is quite long but includes:
/windows/fonts for drives A through G
/WINNT/fonts for drives A through G
/usr/share/fonts/default/TrueType
/usr/share/fonts/truetype
If your PDF reports appear to be missing content, you can place the appropriate fonts in any of the directories in the preceding list. You also can specify your own font search path by creating the environment variable BIRT_FONT_PATH.
Once you deploy the BIRT report viewer to your J2EE container, you can access your BIRT reports using a web browser. To view a BIRT report using a browser, you navigate to a URL having one of the following two formats:
http://localhost:8080/birt/run?parameter_list http://localhost:8080/birt/frameset?parameter_list
where parameter_list is a list of URL parameters.
For more information about the URL parameters that you can use, see the section about URL parameters, later in this chapter.
When you use the run servlet, it displays the report as a stand-alone web page or a PDF file. If the report requires parameters, you must specify them in the URL.
When you use the frameset servlet, the browser displays a page with a toolbar with four buttons to do the following tasks:
Print the report.
Display a table of contents.
Display a parameters dialog.
Display a dialog for exporting data.
The parameter list for the run and frameset servlets must contain the__report parameter. The other parameters are optional.
Table 5-2 lists the URL parameters for accessing BIRT reports.
Table 5-2. URL parameters for accessing BIRT reports
Parameter | Values | Required? | Default value |
|---|---|---|---|
__report | Path to report design file | The URL must contain either a __report parameter or a __document parameter. | No default |
__document | Path to document file | The URL must contain either a __report parameter or a __document parameter. | No default |
__format | html or pdf | Optional | html |
__locale | Locale code | Optional | JVM locale |
__isnull | Any user-defined report parameter values | Optional | Not applicable |
__svg | true or false | No | false |
Other report parameters | User-defined | As specified in the report design | As specified in the report design |
The __report parameter specifies the name and location of the report design file for the report you want to display. If the URL contains a __report parameter, a new report document file is generated from the report design file specified by this parameter. The URL must contain either a __report parameter or a __document parameter, but not both.
The path can be either absolute or relative. If you specify an absolute path, the servlet uses that absolute path. If the path is relative, the location depends on whether the working folder parameter, BIRT_VIEWER_WORKING_FOLDER, is defined in the web.xml file. If the working folder parameter is defined in web.xml, the base for the relative path is the path that the working folder parameter specifies. If your application is deployed as a folder structure instead of a WAR file and the working folder parameter is not defined in web.xml, then the base for the relative path defaults to $TOMCAT_INSTALL/webapps/birt. If your application is deployed using a WAR file, BIRT_VIEWER_WORKING_FOLDER must specify a value.
The following three examples of a __report parameter illustrate the possibilities:
The path to the report is an absolute path and the parameter is:
__report=C:myReport.rptdesign
The report path is:
C:myReport.rptdesign
The path in this example is absolute, so the value of BIRT_VIEWER_WORKING_FOLDER is not relevant.
The path to the report is relative, BIRT_VIEWER_WORKING_FOLDER is not defined in web.xml, and the parameter is:
__report=ReportmyReport.rptdesign
The path to this report is:
$TOMCAT_INSTALLlwebappsirtReportmyReport.rptdesign
The path to the report is relative, BIRT_VIEWER_WORKING_FOLDER is defined as C:Reports, and the parameter is:
__report=myReport.rptdesign
The path to this report is:
C:ReportsmyReport.rptdesign
The __document parameter specifies the name and location of the report document file for the report you want to display. If the __document parameter is present, the report viewer displays the report encapsulated in the specified file. The URL must contain either a __report parameter or a __document parameter, but not both. The rules for specifying the name and location of the report document file are the same as the rules for specifying a report design file, as explained in the previous section.
Use the __format parameter to specify whether the report should display as an HTML page or as a PDF document.
Use the __locale parameter to specify a Java locale, such as en for English or chzh for Chinese. The choice of locale affects the language in which certain report items appear in the report. The report items that have internationalization capability are those whose ROM elements contain a resource property.
Use the __isnull parameter to specify that one of the other optional parameters is null. The following rules govern the setting of parameter values:
If you include __isnull=parameterName in the URL and this parameter does not appear elsewhere in the URL, then parameterName takes the value null, which, in this context, means unknown.
If you include __isnull=parameterName in the URL but this parameter is also set to a value in the URL, then parameterName takes the value of a blank string.
If you do not include __isnull=parameterName in the URL and this parameter is set to a value in the URL, then parameterName takes the value assigned in the URL.
If you do not include __isnull=parameterName in the URL and this parameter does not appear elsewhere in the URL, then parameterName is assigned its default value.
Use the __svg parameter to enable Scalable Vector Graphics (SVG) support in the report engine when the browser does not contain SVG support. SVG support is only relevant for charts and the __svg parameter is only relevant for the run servlet, not the frameset servlet. A parameter value of true enables SVG support.