BIRT/FAQ/Deployment

< To: BIRT/FAQ

BIRT POJO Runtime Deployment

Q: How do I use the BIRT POJO Runtime?

Starting the the release of BIRT 3.7, BIRT now offers a new runtime. This runtime is POJO based and affects the Web Viewer deployment and API deployment scenarios. See BIRT 3.7 Runtime Deployment Guide for more details.

Application Server

Q: How do I install the BIRT Report Engine in my app server?

The Eclipse (BIRT) Reporting Engine (ERE) is a series of Java class files that can be deployed in any Java/J2EE environment – this could be within a server based application, or a client-side application. The ERE is the runtime component of BIRT – when you call it in the context of your application, you pass it a report design. The ERE then will access the data source, retrieve the data, do the required aggregations/sorting, etc., and then format the report for presentation as HTML or PDF, for example.

The BIRT report viewer is included with the report designer and is used to preview reports. It doubles as an example of how to integrate the Report Engine into a J2EE application.

Q: How do I install BIRT in Tomcat?

See complete instructions on the BIRT Integration pages.

Q: How do I install BIRT in JBoss?

Take the viewer deployment from the BIRT Runtime download(as described for Tomcat), and copy it to your JBoss deploy directory as viewer.war.

However, BIRT uses an older version of the Rhino scripting engine, and this causes a conflict with the version installed with JBoss. To work around this temporarily, put BIRT's js.jar in JBoss's server/default/lib.

Q: How do I install BIRT in WebSphere?

See complete instructions on the Birt WebSphere Deployment page for all version's apart from 6.0.0.0 which is documented here Birt WebSphere 6.0.0.0 Deployment . Here is how to deploy BIRT 2.2 on Websphere 6.0.2.0

Q: How do I install BIRT in WebLogic 10.0

You may have issues with WebLogic having an older version of the Rhino scripting engine. If you are deploying as part of an EAR you can workaround this by adding js.jar to your APP-INF\lib folder and modifying weblogic-application.xml to tell weblogic to prefer the application classes.

  <wls:prefer-application-packages>
    <wls:package-name>org.mozilla.javascript.*</wls:package-name>
    <wls:package-name>org.mozilla.classfile.*</wls:package-name>
  </wls:prefer-application-packages>

N.B. There can be deployment issues when trying to use the <prefer-web-inf-classes> in weblogic.xml of the WAR so doing it at EAR level is a good alternative.

Q: How do I install BIRT in WebSphere Community Edition (Apache Geronimo)?

See complete instructions on the Birt WAS CE page.

Q: How do I install BIRT in Oracle Application Server IAS/OAS?

See complete instructions about How do I install BIRT in Tomcat.

Additionally put in WEB-INF/lib from your project, the apache commons-logging libraries, for example, commons-logging-x.x.x.jar and commons-logging-api-x.x.jar

Oracle 10.1.3.2.0

Specific to BIRT 2.3.x and >.

You have to replace embedded oracle.xml library by xerces, to do so:

• Create a shared lib that embeds xercesImpl and xml-apis (choose last versions)
• Create a shared lib that embeds xalan
• During deployment, go to ClassLoader configuration and uncheck oracle.xml and check the 2 new created shared lib

Q: How do I install BIRT to Sun's Application Server?

See complete instructions about How do I install BIRT in Tomcat.

Additionally add commons-logging-x.x.x.jar to the WebViewerExample/WEB-INF/lib, and re-war the WebViewerExample diretory to birt.war.

Q: How do I setup BIRT to use Tomcat Connection Pooling

1. Install Your JDBC Driver make an appropriate JDBC driver available to both Tomcat internal classes and to your web application. This is most easily accomplished by installing the driver's JAR file(s) into the $CATALINA_HOME/common/lib directory

That means, copy the jdbc driver jar file that you want its JNDI Data Source service to use into the <Tomcat_Home>/common\lib folder

2. Declare Your Resource Requirements

• in the webapps/WebViewerExample/WEB-INF/web.xml file, add the following entry to setup your JNDI service:

   <resource-ref> 
       <description>Resource reference to a factory for java.sql.Connection</description> 
       <res-ref-name>jdbc/MySqlDB</res-ref-name> 
       <res-type>javax.sql.DataSource</res-type> 
       <res-auth>Container</res-auth> 
   </resource-ref> 

where MySqlDB is your JNDI name

3. Configure Tomcat's Resource Factory

To configure Tomcat's resource factory, add an element like this to the /META-INF/context.xml file in the web application.

• In the webapps/WebViewerExample/META-INF/context.xml file, add the following entry to setup your JNDI data source factory:

 <Resource name="jdbc/MySqlDB" 
       auth="Container" 
           type="javax.sql.DataSource" 
       maxActive="5" maxIdle="-1" maxWait="10000" 
       username="acTest" password="xxx" 
           driverClassName="com.mysql.jdbc.Driver" 
       url="jdbc:mysql://birtdb2-w2k:3306/acTestDb" 
       description="MySQL Sfdata DB"/> 

• No need to setup jndi.properties in the WebViewerExample's oda.jdbc/drivers folder, since the default setting is fine

• Since Tomcat by itself does not support client-side access, no need to setup jndi.properties for the BIRT report designer

• The JNDI URL name to specify in the oda.jdbc connection property, using the above example, will be:

       java:comp/env/jdbc/MySqlDB

Q: How do I install BIRT in webMethods Integration Server?

webMethods Integration Server provides a Apache Tomcat package (WmTomcat) that will serve as container for Eclipse BIRT.

Integration of Eclipse BIRT into webMethods Platform involves similar steps as integration of BIRT with Tomcat. However, due to webMethods implementation of WmTomcat package and the way it interacts with Integration Server, installation steps will require additional configuration, specific to webMethods platform.

Known Issues

webMethods Integration Server 6.1

Integration Server version 6.1 by default uses older version of Tomcat 4.0 that is not compatible with Eclipse BIRT 2.1.2. Integration Server version 6.1 WmTomcat package has to be upgraded to Apache Tomcat version 5.0 by applying webMethods patch/fix: IS 6.1 SP1 Tomcat Fix 1 file name – (IS_Tomcat_6-1_SP1_Fix1.zip). Newer versions of Integration Server such as 6.5 or later include a newer version of Tomcat package.

webMethods Integration Server 6.5.x - 7.x

The WmTomcat package that is installed with Integration Server version 6.5.x has Tomcat 5.0 however, package includes tools.jar file from JVM 1.4. Default installation of 6.5 uses JVM 1.5, as a result the Tomcat jsp pages will not compile correctly and BIRT will not work with this version. To work around this problem use tools.jar file provided with JVM 1.5. Copy new tools.jar file from JVM 1.5 into WmTomcat/code/jars directory and restart Integration Server.

To deploy the BIRT Viewer application inside WM IS. Follow these steps:

• Download the zip file with the BIRT report engine runtime. The file is named birt-runtime-version#.zip, in this example we download file – birt-runtime-2_1_1.zip http://download.eclipse.org/birt/downloads/.
• Unzip the file in a staging area (any work directory).
• Start Integration Server if it is not already running.
• Create new package under webMethods IS, for this example we create package name: BIRTTest. (For instructions on how to create WM packages refer to webMethods platform and webMethods Developer documentation.)
• Set newly created package dependency to WmTomcat package, to make Tomcat libraries, jar files visible to BIRT.
• Look under the birt-runtime-2_1_1 directory and locate the "Web Viewer Example" directory.
• Copy the contents of Web Viewer Example directory to the web directory of your WM IS package BIRTTest. The directory path will look similar to this: <Integration Server>/packages/BIRTTest/web.
• Copy additional files to the directory structure described in the BIRT Runtime Note below (iText, and iTextAsian). Earlier versions of BIRT 2.0.x also require (prototype.js). In BIRT runtime 2.1.1 prototype.js has been included into standard distribution.
• Copy itext-1.3.jar to /BIRTTest/web/WEB-INF/platform/plugins/com.lowagie.itext/lib. Create lib directory if it does not exist.
• Copy iTextAsian.jar to /BIRTTest/web/WEB-INF/platform/plugins/com.lowagie.itext/lib.
• Create new directory <Integration Server>/packages/BIRTTest/web/styles/iv.
• Look under the birt-runtime-2_1_1 directory and locate the "Web Viewer Example/webcontent/birt" directory and find directory styles.
• Copy contents/files from directory birt-runtime-2_1_1/ Web Viewer Example/webcontent/birt/styles to WM directory <Integration Server>/packages/BIRTTest/web/styles/iv.
• Stop, then restart Integration Server and ensure that WmTomcat and our BIRTTest packages has loaded successfully.
• Display the Tomcat welcome page to check that it is deployed: http://localhost:5555/ and click on WmTomcat home page.
• Display the BIRTTest welcome page application to check that the BIRT viewer is deployed: http://localhost:5555/web/BIRTTest.
• A page confirming that the BIRT viewer has been installed should be displayed. Click on the link labeled "View Example" to confirm that your installation is working properly.
• The example report will be shown by clicking on View Example. It may take some time for server and Tomcat to compile and set this sample report for the first time.

At this time user can create any reports using Eclipse IDE or webMethods Designer 7 tools and deploy them under webMethods Integration server.

Eclipse BIRT reports can be stored under any Integration Server package. However, it is not recommended to deploy reports under webMethods standard packages such as WmPublic or WmTomcat. It is recommended to create a custom package to host BIRT reports.

Q: How do I install BIRT Framework into webMethods Designer Tool?

webMethods Designer 7 is Eclipse based development tool. BIRT Rerport Designer framework can be directly integrated into webMethods Designer by following same instructions for installing BIRT Report Designer on existing Eclipse installation: http://www.eclipse.org/birt/phoenix/build/#designer.

BIRT Viewer

Q: Why does a red asterisk appear next to some of my parameters in the Viewer's parameter UI?

The asterisk indicates that a parameter is required. A parameter is required if:

• The parameter is a string, the default value is blank, and the parameter does not allow blank values.
• The parameter is other than a string, the default value is blank, and the parameter does not allow null values.

Note that a blank value is considered to be a blank string ("") for string values, but a (database null) value (unknown) for non-string types such as numbers and dates.

Q: I get: Could not initialize class sun.print.CUPSPrinter when deploying to BIRT Viewer to FreeBSD. What is the issue?

See https://bugs.eclipse.org/bugs/show_bug.cgi?id=297910 for a description of the problem and a work around.

Other Integrations

Q: Can I use BIRT within a Rich Client Application (RCP)?

Community member Stavros Kounis made an Eclipse plug-in that starts BIRT's Viewer webapp using the Eclipse internal application server and views reports inside RCP using an editor that contains a browser control. He posted it on his blog at http://tools.osmosis.gr/blog.

If your RCP APP needs to call the BIRT Viewer and uses scripted a scripted data source see this example on BIRT-Exchange. http://www.birt-exchange.org/org/devshare/designing-birt-reports/889-rcp-app-with-birt-and-scripted-datasource/

Q: Can I store report designs in a location other than the file system?

Not at present, but we are looking into possible changes to support this. Also, Eclipse itself may be looking into this.

Q: Do BIRT reports need to be compiled before they are run?

No, there is no compile step. The BIRT Report Engine directly executes the report design XML file. (This is one reason that BIRT uses interpreted JavaScript instead of compiled Java as its scripting language.)

Q: Can BIRT reports be saved on disk?

Reports are created in two phases, Generation and Presentation. The Report Engine API has three tasks that can be used for report creation. One for generating the report, another for rendering and one that combines generation and presentation tasks. The WebViewer Example uses the combined task when generating report content using the /run servlet mapping and uses the two separate task when using the /frameset mapping. The WebViewer Example has a URL parameter __document that allows the intermediate report document to be saved for later rendering. See the Report Engine API page for more details. See the Viewer Usage page for details on the WebViewer parameters.

Logging

Q: Can I use Log4j with BIRT?

You can use log4j as follows:

1. create a handler which uses log4j logger to log out information:

package test;
import java.util.logging.Handler;
import java.util.logging.Level;
import java.util.logging.LogRecord;
import org.apache.log4j.Logger;
public class Log4jHandler extends Handler
{
       public void close( ) throws SecurityException
       {
       }
       public void flush( )
       {
       }
       public void publish( LogRecord record )
       {
               String loggerName = record.getLoggerName();
               
               if (loggerName == null)
                       loggerName = record.getSourceClassName();
               
               if (loggerName == null)
                       loggerName = "org.eclipse.birt.UNKNOWN";
               
               Logger log = Logger.getLogger(loggerName);
               Level level = record.getLevel( );
               String message = record.getMessage( );
               if ( Level.SEVERE.equals( level ) )
               {
                       log.fatal( message );
               }
               else if ( Level.INFO.equals( level ) )
               {
                       log.info( message );
               }
               else if ( Level.WARNING.equals( level ))
               {
                       log.warn( message );
               }
       }
}

2. create configuration file "logging.properties" and specify above hander as handers: handlers=test.Log4jHandler

3. place the file created in step 2 in "java.home" folder, or, put it in any folder and define the position by system property as "java.util.logging.config.file=logger.properties".

Update (Unconfirmed) - If using the Web Viewer in Tomcat, this file should be placed in /webapps/[AppName]/WEB-INF/classes.

4. configure log4j correctly and it should work.

Update (Unconfirmed) - These steps don't specify where to place the JAR file containing your Log4jHandler.