Wednesday, August 20, 2008

Deploying BIRT to a JBoss Portlet


BIRT uses OSGi plugins to implement most of its functionality. This works great in most cases, but when deploying to servers, configuration can be problematic especially if you are new to OSGi. If you have used BIRT’s Report Engine API before you are probably familiar with setting BIRT_HOME or using the EngineConfig.setBirtHome method. This method essentially just points to the location of the BIRT plugins.

The BIRT EngineConfig class also has a method for setting the PlatformContext (setPlatformContext). This method takes an instance of a class that implements the IPlatformContext interface. This interface is fairly simple in that it has only one method, named getPlatform which returns the path that contains the BIRT plugins. BIRT provides two default implementations of this interface (PlatformServletContext and PlatformFileContext). If the setPlatformContext is never called, BIRT defaults to a PlatformFileContext, which looks for a BIRT home location that is either set using:

System.setProperty(“BIRT_HOME”, locationtobirtplugins);
Or
EngineConfig.setBIRTHome(locationtobirtplugins);

The PlatformServletContext class is used when deploying BIRT to a web application and uses resource based operations for locating the plugins which can be included in the application. For an example of using the PlatformServletContext go
here.

This brings us the intent of this post “Deploying BIRT to a JBoss Portlet”. Within the BIRT wiki is an example of deploying BIRT to a portlet. The example is located
here.

This example works fine, but not with JBoss’s Portal Server. The reason for this is in that example the ServletContext is used to locate the BIRT plugins. Within a JBoss Portlet, I found no ready way of retrieving the ServletContext. It may be possible, but instead of going that route I decided to implement my own version of the IPlatformContext interface, which would use the PortalContext to locate the BIRT plugins.

In the example I built, I just copied the PlatformServletContext class from the BIRT source and modified it to take a PortletContext instead of a ServletContext. Being that it was only two small changes I will not post it here, but it is in the example. I then modified the example BirtEngine.java class from the portlet example above to create an instance of my new PlatformPortletContext class and set it in the engine config with the following code:



IPlatformContext context = new PlatformPortletContext( pc );
config.setPlatformContext( context );

try
{
Platform.startup( config );
}
catch ( BirtException e )
{
}


I also modified the example above to use the PortletContext to set image directories and base image url. The Portlet code looks like this:



package org.eclipse.birt.examples;
import javax.portlet.GenericPortlet;
import javax.portlet.PortletException;
import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;
import javax.portlet.UnavailableException;
import java.io.IOException;
import java.io.PrintWriter;

//+++++++++++++BIRT
import org.eclipse.birt.report.engine.api.EngineConfig;
import org.eclipse.birt.report.engine.api.IReportEngine;
import org.eclipse.birt.core.framework.IPlatformContext;
import org.eclipse.birt.core.framework.Platform;
import org.eclipse.birt.core.exception.BirtException;
import org.eclipse.birt.report.engine.api.IReportEngineFactory;
import java.util.logging.Level;
import org.eclipse.birt.report.engine.api.EngineConstants;
import org.eclipse.birt.report.engine.api.HTMLRenderOption;
import org.eclipse.birt.report.engine.api.IReportRunnable;
import org.eclipse.birt.report.engine.api.IRunAndRenderTask;
import org.eclipse.birt.report.engine.api.IReportEngine;
import org.eclipse.birt.report.engine.api.HTMLServerImageHandler;
import java.util.logging.*;
public class JbossBirtPortlet extends javax.portlet.GenericPortlet {
/**
*
*/
private static final long serialVersionUID = 1L;

/**
* Constructor of the object.
*/
private IReportEngine birtReportEngine = null;
protected static Logger logger = Logger.getLogger( "org.eclipse.birt" );
public JbossBirtPortlet() {
super();
}
/**
* Destruction of the portlet.
*/
public void destroy() {
super.destroy();
BirtEngine.destroyBirtEngine();
}
protected void doView(RenderRequest rRequest, RenderResponse rResponse) throws PortletException, IOException, UnavailableException {
rResponse.setContentType("text/html");
this.birtReportEngine = BirtEngine.getBirtEngine(rRequest.getPortletSession().getPortletContext());
logger.log( Level.FINE, "image directory " + rRequest.getPortletSession().getPortletContext().getRealPath("/images"));
IReportRunnable design;
try
{
//Open report design
design = this.birtReportEngine.openReportDesign( rRequest.getPortletSession().getPortletContext().getRealPath("/Reports/TopNPercent.rptdesign"));
//create task to run and render report
IRunAndRenderTask task = birtReportEngine.createRunAndRenderTask( design );
//set output options
HTMLRenderOption options = new HTMLRenderOption();
options.setOutputFormat(HTMLRenderOption.OUTPUT_FORMAT_HTML);
options.setImageHandler( new HTMLServerImageHandler() );
options.setOutputStream(rResponse.getPortletOutputStream());
options.setBaseImageURL(rRequest.getContextPath()+"/images");
options.setImageDirectory(rRequest.getPortletSession().getPortletContext().getRealPath("/images"));
task.setRenderOption(options);
//run report
task.run();
task.close();
}catch (Exception e){
e.printStackTrace();
throw new javax.portlet.PortletException( e );
}
}

/**
* Initialization of the portlet.
*
* @throws PortletException if an error occure
*/
public void init() throws javax.portlet.PortletException {
BirtEngine.initBirtConfig();
}
}






A couple of things to note: Doing it this way requires that the BIRT plugins be included as part of the Portlet WAR. This can create big war files. A better approach may be to deploy the BIRT plugins to a hard location on the system and use the system property and the default PlatformFileContext class to set the BIRT home. I also had to up the PermGen space for the JBoss AS. If you wish to download the example it is located here. Be sure to read the readme for instructions on building the WAR. The example is based off of the JBoss sample HelloWorld portlet and is located
here.

Wednesday, June 25, 2008

BIRT 2.3 Released



BIRT 2.3 has arrived and with this release many new features are available. Most notable are the JavaScript improvements that include an improved JavaScript Editor (validation, line numbers, code folding), a new JavaScript Debugger, and the ability to add JavaScript files to a report design using the GUI. Also new scripting events are available for crosstabs and charts. BIDI support is also provided in all output formats. Many crosstab enhancements were made, including the ability to display measure data using charts within the crosstab. With BIRT 2.3 crosstabs support derived measures as well.


To read more about the new BIRT 2.3 features see the BIRT New and Notable Features.

To view a webinar on the new feature, check out this Eclipse Live recording. The examples used in this webinar are available on
BIRT-Exchange.

Tuesday, June 10, 2008

BIRT - Help Wanted

The majority of the work on the BIRT project is done by the core BIRT committers. At the same time, we recognize that we have a huge community of users and integrators that may want to dedicate some time back to our community.

Unfortunately, it is a little difficult to find a place to start. Yes, there are a lot of open issues in Bugzilla, but it is difficult to determine which items would be best to take on. Unless you are well versed on the internals of BIRT, it is difficult to tell which items are easy, and which are difficult. To complicate things a bit, those items that are easy and relatively high priority tend to get fixed pretty quickly.

In an effort to provide better entry points for people that are interested in contributing code to the BIRT project, we have started to tag bugzilla entries with the keyword "helpwanted". You can find the bugs by using this search. The assumption is that discussion and contributions towards the resolution would be handled through Bugzilla.

If you do come up with a contribution for the BIRT team, please make sure that you select the IP review box if you are submitting code. Also please note that the helpwanted tag is new effort for the BIRT team, and will be a bit of a work in progress.

One other friendly reminder is that the BIRT team is in the closing cycles of the Ganymede release at the end of this month. If you decided to get active, please understand that the entire development team is very focused on the release and may take a while to respond to your contributions and questions.

Friday, May 23, 2008

Designing High Performance BIRT Reports

Over the last couple of months BIRT-Exchange has hosted many webinars explaining and demonstrating BIRT technology. Last weeks webinar featured Mica Block discussing BIRT performance. In this presentation, Mica explains how to gauge performance and provides tips for improving generation time. If you missed it or any of the others, they are available
here.

In addition the following topics will be discussed in the future:

5/30/2008
Using the BIRT Report Engine API
Virgil Dodson

6/13/2008
Using the BIRT Design Engine API
Jason Weathersby

6/27/2008
What's New with BIRT 2.3
Virgil Dodson

7/11/2008
Ad-hoc BIRT Reporting for End Users
Rob Murphy

7/25/2008
BIRT Charting Primer
Virgil Dodson

8/8/2008
Using the BIRT Chart API
Jason Weathersby

Thursday, May 22, 2008

Embed HTML

So this is a really simple problem that Jason solved for me. If you have HTML in your database and you want to embed it into your report as HTML you need to do a few things. First start with a Text control.

1) Change the top drop-down to HTML

2) Change the second drop-down to Dynamic Text

3) Click on the tag and use the expression builder to select the appropriate field.





4) Manually insert the attribute format="HTML" into the VALUE-OF entity













If you follow these steps your HTML text will show up in your report document as formatted text that obeys the HTML rules.


Monday, May 19, 2008

Java Event Handler ClassPaths

One of the most common questions that comes up when developing Java Event Handlers is:

"Where do I put my classes?"

Rather than write it up here, I added an entry to the BIRT FAQ here.

Friday, May 09, 2008

BIRT: Swapping Data Set at Runtime

Often it is a requirement to design a report against a development database and then switch the connection at runtime. This can be done in many ways with BIRT. The options include:

JNDI - Look up the data source.
Property Binding - Swap the data source at runtime using property binding expression.
Script – Write a script in the beforeOpen event handler to modify the data source properties.
Connection Profiles – Store the connection information in a shared profile.
DTP driverBridge extension – Implement a driverBridge extension to intercept calls to a specific driver.
Design Engine API (DE API) - Swap the dataset property on a specific table before running the report.

Using the DE API often serves as a useful alternative, because the data sources may be different types. For example your deployed report may use a scripted data source to retrieve some EJB value, but at design time you may not have access to this data source. So you could develop a stubbed data source that uses JDBC to test your report layout and when deployed swap the data set on elements that are bound to the data set. To do this you need to do a few things. First name your elements that use the data set to be swapped. This can be set in the general properties for each report element. Next make sure your two data sets (one for design time and one for deploy time) have the same result columns. If the result columns are not the same much more work needs to be done in order to implement this solution. Finally implement a beforeFactory script that modifies the report design before it is executed. Assume we have two data sources/data sets and one table. If I name my table “mytable” and my data sets are named “viewer” and “designer” the beforeFactory event script would look as follows:



des = reportContext.getHttpServletRequest().getParameter("__designer");

if( des == null || des == "false" ){
mytable = reportContext.getReportRunnable().designHandle.getDesignHandle().findElement("mytable");
mytable.setProperty( "dataSet", "viewer" );
}


Note that the “designer” data set is the default data set used in the report. This is the data set that you should drag to the canvas to build your report


The first line of code determines whether we are using the designer. The designer adds the __designer parameter to URL when the report is previewed. This parameter will not exist when deployed. If this parameter does not exist or is set to false we assume that the report is deployed. This line:



reportContext.getReportRunnable().designHandle.getDesignHandle()



returns the report design handle. BIRT 2.3 has an easier way of getting the report design, but this method should work for BIRT 2.2 and 2.3. We then use the report design handle to locate the table element to be modified. Finally we set the dataSet property to the viewer dataset.


An example report illustrating this concept is located here.