The report engine supports extensions for custom report items, data access, and custom output formats. Extensions are discussed elsewhere. This section will focus on how your application integrates with the report engine.
The BIRT Viewer sample is also bundled with the Report Engine download. It is located under the WebViewerExample directory. If you decide to use this example, see Viewer Setup for an explanation. The Viewer uses the RE API to generate reports within the context of a servlet. It provides additional features, such as printing, TOCs, Page controls, etc. Before using the RE API, verify that the Viewer is not applicable to your application.
If you prefer to work directly with the BIRT source code, the Engine API is
in the org.eclipse.birt.report.engine project within Eclipse CVS
Eclipse CVS. The source is also available from the BIRT site in one package (the BIRT Source Code Package), which can be downloaded from the download site.
This page provides an overview of the engine. To do actual development, consult the Engine Javadoc. These docs are available within BIRT Help.
You must configure the engine to include any JDBC drivers that you need.
To do this, copy the driver jar file to the ReportEngineInstall/birt-runtime-version/ReportEngine/plugins/org.eclipse.birt.report.data.oda.jdbc_version/drivers Directory.
The following are the key steps to use the API, identifying the classes and interfaces you use for each step.
EngineConfig to set options for the report engine.ReportEngine class. You can use this object to
perform multiple tasks.openReport( ) methods of ReportEngine.IGetParameterDefinitionTask. This is only needed if you want to build a custom parameter page or collect parameter definition information. The IRunTask and the IRunAndRenderTask interfaces have methods for setting parameter values.IRunAndRenderReportTask or IRunTask and IRenderTask.shutdown( ) on your engine instance. If using the engine in a servlet shudown the engine when the servlet shuts down.The following sections describe the primary Engine classes in detail. The Engine API includes a number of secondary helper classes referenced within each description. The diagram below, serves as an overview of the classes needed to accomplish a given task.
Use the EngineConfig class to set global options for the report engine as a
whole. Use it to specify the location of engine plug-ins, the location of data
drivers, and to add application-wide scriptable objects.
> EngineConfig config = new EngineConfig( ); config.setEngineHome( "put engine path here" );
Other functions of interest within this class are:
setLogConfig(String directoryName, Level level)
The ReportEngine class represents the BIRT Report Engine. There is a significant cost associated with creating an engine instance, due
primarily to the cost of loading extensions. Therefore, each application should
create just one ReportEngine instance and use it to run multiple reports.
This is important to remember when deploying the engine in a servlet as well.
The report engine is created through a factory supplied by the Platform. Before creating the
engine, you should start the Platform, which will load the appropriate plug-ins. This is done by calling
Platform.startup(config) that takes an
EngineConfig object as argument. After using the engine, call
Plaform.shutdown()( ) function to do clean up work, which includes unloading the extensions.
try{
final config = new EngineConfig( );
config.setEngineHome( "C:\birt-runtime-2_1_0\birt-runtime-2_1_0\ReportEngine" );
config.setLogConfig(c:/temp, Level.FINE);
Platform.startup( config ); //If using RE API in Eclipse/RCP application this is not needed.
IReportEngineFactory factory = (IReportEngineFactory) Platform
.createFactoryObject( IReportEngineFactory.EXTENSION_REPORT_ENGINE_FACTORY );
IReportEngine engine = factory.createReportEngine( config );
engine.changeLogLevel( Level.WARNING );
}catch( Exception ex){
ex.printStackTrace();
}
// Run reports, etc.
...
// destroy the engine.
try
{
engine.destroy();
Platform.shutdown();
}
catch ( EngineException e1 )
{
// Ignore
}
Other functions of interest within this class are:
engine.changeLogLevel(java.util.logging.Level.FINE);
BIRT report designs are stored as XML files. By default the extension is rptdesign.
To work with the report design in the engine, you must first load the report using one of the openDesign( ) methods in
the ReportEngine class.
The report design open methods return a
IReportRunnable instance that represents the engine's view of the
report design.
IReportRunnable report = engine.openReportDesign( name );
Note that BIRT supplies many options for opening reports such as the filename or an input stream.
Use the returned object to obtain parameter data or run the report.
The class
provides methods for getting report properties such as the title, author and so
on. It also provides methods for getting images embedded (stored) within the
report design. If your application requires more information about the design, you can
obtain a Design Engine report handle, then use the BIRT
Design Engine API to traverse the report design.
BIRT optionally can store reports in an intermediate format, after generation and before rendering.
This document, with the default extension rptdocument, can be manipulated with the IReportDocument interface.
The Engine will create this document when the runTask is used. The BIRT viewer uses this
format to do pagination, TOCs, CSV extraction, bookmarks, etc. When finished with a IReportDocument, be sure to close it, with the close() method.
The Engine's openDocument method returns a IReportDocument that represents the intermediate report document.
The example below illustrates getting the TOC from the report document, after the runTask is used to generate the report.
IReportDocument ird = engine.openReportDocument("c:/work/test/TOCTest.rptdocument");
//get root node
TOCNode td = ird.findTOC(null);
List children = td.getChildren( );
//Loop through Top Level Children
if ( children != null && children.size( ) > 0 )
{
for ( int i = 0; i < children.size( ); i++ )
{
TOCNode child = ( TOCNode ) children.get( i );
System.out.println( "Node ID " + child.getNodeID());
System.out.println( "Node Display String " + child.getDisplayString());
System.out.println( "Node Bookmark " + child.getBookmark());
}
}
BIRT reports support scripting. Operations that execute scripts require a scripting context. Report operations also require a locale. BIRT Engine tasks provide the framework for managing the scripting context, report locales and so on. In general, if an operation requires neither a script context nor a locale, it will appear as a method on the engine or the report design. However, if the operation does require these items, then a task class represents the operation.
For example, opening a design file or retrieving an image in the design file does not require setting up a scripting context. Other operations, such as retrieving default parameters, retrieving a dynamic selection list, and running and rendering a report, all support scripting, require a scripting context, and are represented as tasks.
Create tasks using the factory methods on the ReportEngine class.
The supported Tasks are shown below:
engine.createDataExtractionTask();
engine.createGetParameterDefinitionTask();
engine.createRenderTask();
engine.createRunTask();
engine.createRunAndRenderTask();
Use this task to extract data from a report document. The BIRT viewer uses
this class to extract report data into CSV format. This class supports extracting
data from the report document by specifying the result set and columns you would
like to have extracted.
From the Viewer code
dataTask.selectResultSet( resultSetName ); dataTask.selectColumns( columnNames ); dataTask.setLocale( locale );
Below is an example that uses the Data Extraction Task to extract the first two columns of data.
//Open previously created report document
IReportDocument iReportDocument = engine.openReportDocument("c:/work/test/TOCTest.rptdocument");
//Create Data Extraction Task
IDataExtractionTask iDataExtract = engine.createDataExtractionTask(iReportDocument);
//Get list of result sets
ArrayList resultSetList = (ArrayList)iDataExtract.getResultSetList( );
//Choose first result set
IResultSetItem resultItem = (IResultSetItem)resultSetList.get( 0 );
String dispName = resultItem.getResultSetName( );
iDataExtract.selectResultSet( dispName );
IExtractionResults iExtractResults = iDataExtract.extract();
IDataIterator iData = null;
try{
if ( iExtractResults != null )
{
iData = iExtractResults.nextResultIterator( );
//iterate through the results
if ( iData != null ){
while ( iData.next( ) )
{
Object objColumn1;
Object objColumn2;
try{
objColumn1 = iData.getValue(0);
}catch(DataException e){
objColumn1 = new String("");
}
try{
objColumn2 = iData.getValue(1);
}catch(DataException e){
objColumn2 = new String("");
}
System.out.println( objColumn1 + " , " + objColumn2 );
}
iData.close();
}
}
}catch( Exception e){
e.printStackTrace();
}
iDataExtract.close();
Use this task to obtain information about parameters. Parameter default values are expressions, and so a scripting context (represented by the task) is required. Parameter definitions provide access to the parameter definition information that the report designer entered at design time. If a parameter has custom XML or user-defined properties defined, then these are also available. Parameters can be organized into groups. Your application has the choice of retrieving the parameters organized by group (as they should be displayed to the user), or in ungrouped form (useful for creating a programmatic interface.)
The IParameterGroupDefn and IScalarParameterDefn
interfaces provide
information about parameter groups and individual parameters.
The following example opens a report design and iterates through the parameters and parameter groups. If a List Box parameter is found, which is not in a group, the selection values are retrieved.
//Open a report design
IReportRunnable design = engine.openReportDesign("C:/work/test/parameters.rptdesign");
IGetParameterDefinitionTask task = engine.createGetParameterDefinitionTask( design );
Collection params = task.getParameterDefns( true );
Iterator iter = params.iterator( );
//Iterate over all parameters
while ( iter.hasNext( ) )
{
IParameterDefnBase param = (IParameterDefnBase) iter.next( );
//Group section found
if ( param instanceof IParameterGroupDefn )
{
//Get Group Name
IParameterGroupDefn group = (IParameterGroupDefn) param;
System.out.println( "Parameter Group: " + group.getName( ) );
//Get the parameters within a group
Iterator i2 = group.getContents( ).iterator( );
while ( i2.hasNext( ) )
{
IScalarParameterDefn scalar = (IScalarParameterDefn) i2.next( );
System.out.println(" " + scalar.getName());
}
}
else
{
//Parameters are not in a group
IScalarParameterDefn scalar = (IScalarParameterDefn) param;
System.out.println(param.getName());
//Parameter is a List Box
if(scalar.getControlType() == IScalarParameterDefn.LIST_BOX)
{
Collection selectionList = task.getSelectionList( param.getName() );
//Selection contains data
if ( selectionList != null )
{
for ( Iterator sliter = selectionList.iterator( ); sliter.hasNext( ); )
{
//Print out the selection choices
IParameterSelectionChoice selectionItem = (IParameterSelectionChoice) sliter.next( );
String value = (String)selectionItem.getValue( );
String label = selectionItem.getLabel( );
System.out.println( label + "--" + value);
}
}
}
}
}
task.close();
Use the IGetParameterDefinitionTask class to evaluate the default value for a parameter. The parameter
default value is an expression, and the task provides the required execution
context.
IScalarParameterDefn param = ...; IGetParameterDefinitionTask task = ...; Object value = task.getDefaultValue( param );
Use this task to render a report document to a specific output (eg, HTML, PDF, ...). This task expects the document to exist, which means it has been generated with the RunTask engine task. This class renders the report, based on the supplied page range, page number or all if no page is specified.
The following example renders the first two pages of the "Pages" report document. You will notice that it renders the two pages as one page of HTML.
//Open a report document
IReportDocument iReportDocument = engine.openReportDocument("c:/work/test/Pages.rptdocument");
//Create Render Task
IRenderTask task = engine.createRenderTask(iReportDocument);
//Set parent classloader report engine
task.getAppContext().put(EngineConstants.APPCONTEXT_CLASSLOADER_KEY, RenderTaskExample.class.getClassLoader());
IRenderOption options = new RenderOption();
options.setOutputFormat("html");
options.setOutputFileName("output/resample/eventorder.html");
if( options.getOutputFormat().equalsIgnoreCase("html")){
HTMLRenderOption htmlOptions = new HTMLRenderOption( options);
htmlOptions.setImageDirectory("output/image");
htmlOptions.setHtmlPagination(false);
//set this if you want your image source url to be altered
//If using the setBaseImageURL, make sure to set image handler to HTMLServerImageHandler
htmlOptions.setBaseImageURL("http://myhost/prependme?image=");
htmlOptions.setHtmlRtLFlag(false);
htmlOptions.setEmbeddable(false);
}else if( options.getOutputFormat().equalsIgnoreCase("pdf") ){
PDFRenderOption pdfOptions = new PDFRenderOption( options );
pdfOptions.setOption( IPDFRenderOption.FIT_TO_PAGE, new Boolean(true) );
pdfOptions.setOption( IPDFRenderOption.PAGEBREAK_PAGINATION_ONLY, new Boolean(true) );
}
//Use this method if you want to provide your own action handler
options.setActionHandler(new MyActionHandler());
//file based images
//options.setImageHandler(new HTMLCompleteImageHandler())
//Web based images. Allows setBaseImageURL to prepend to img src tag
options.setImageHandler(new HTMLServerImageHandler());
IRenderTask task = engine.createRenderTask(document);
task.setRenderOption(options);
task.setPageRange("1-2");
task.render();
iReportDocument.close();
Use this task to run a report and
generate a report document, which is saved to disk. The report document can then be used with the
IRenderTask to support features such as paging.
The following example simply creates a report document and saves it to disk.
//Open a report design
IReportRunnable design = engine.openReportDesign("C:/work/test/MyOrders.rptdesign");
//Create task to run the report - use the task to execute the report and save to disk.
IRunTask task = engine.createRunTask(design);
//Set parent classloader for engine
task.getAppContext().put(EngineConstants.APPCONTEXT_CLASSLOADER_KEY, RunTaskExample.class.getClassLoader());
//run the report and destroy the engine
task.run("c:/work/test/MyOrders.rptdocument");
task.close();
Use this task to run a report and output it to one of the supported output formats. This task does not create a report document. Create a new task for each report that you run.
Reports may take parameters. The IRunAndRenderReportTask takes parameter
values as a HashMap or you can set them individually. The IRunAndRenderReportTask provides
the validateParameters( ) method to validate the parameter values before you run
the report.
//Open the report design
IReportRunnable design = engine.openReportDesign("Reports/TopNPercent.rptdesign");
//Create task to run and render the report,
IRunAndRenderTask task = engine.createRunAndRenderTask(design);
//Set parent classloader for engine
task.getAppContext().put(EngineConstants.APPCONTEXT_CLASSLOADER_KEY, RunAndRenderTaskExample.class.getClassLoader());
//Set parameter values and validate
task.setParameterValue("Top Percentage", (new Integer(3)));;
task.setParameterValue("Top Count", (new Integer(5)));
task.validateParameters();
//Setup rendering to HTML
HTMLRenderOption options = new HTMLRenderOption();
options.setOutputFileName("output/resample/TopNPercent.html");
options.setOutputFormat("html");
//Setting this to true removes html and body tags
options.setEmbeddable(false);
task.setRenderOption(options);
//run and render report
task.run();
task.close();
Described below are some miscellaneous items that bear mentioning when using the BIRT Report Engine API
BIRT's script engine supports adding Java objects at the API level. If you wish the Java object to be available to the Report, retrieve the application context at the EngineConfig or Task level and add the object to the Map. For example, adding a Java object to the task.
Add the following code to your task.
MyJavaObject jo = new MyJavaObject();
task.getAppContext().put("MyJavaScriptItem", jo);
Now within the the script editor, you can reference your Java Object as follows:
testMyJavaObject = MyJavaScriptItem.getMyMethod();
When rendering a report it may be desirable to output the report to an output stream, such as HttpServletResponse.
To do this modify your RenderOption instance to use setOutputStream instead of setOutputFileName.
For example,
public void webReport( HttpServletResponse response )
{
.
.
.
//Set rendering options
HTMLRenderOption options = new HTMLRenderOption();
options.setOutputStream(response);
task.setRenderOption(options);
//run the report
task.run();
}
By default BIRT loads plug-ins located in the BIRT_HOME/plugins directory. The plug-ins loaded provide functionality for connecting to data sources,
emitters (eg, PDF, WORD, XLS, HTML ...), and chart rendering. BIRT_HOME in the examples on this page is set using the setEngineHome method of the EngineConfig class.
BIRT loads these plug-ins using the Java File API.
This method is usually sufficient. If deployed to a web application, the developer can usually call ServletContext.getRealPath to retrieve the real path and set the BIRT_HOME accordingly. This can present a problem when deploying to a war file. Certain application servers will return null when getRealPath is called. This will result in the plug-ins not getting loaded.
The IPlatformContext interface describes the methods needed to load the resources required by the BIRT runtime. Within BIRT there are two implementations
of this interface, PlatformFileContext() and PlatformServletContext(). The Platform Context is set using the setEngineContext method of the
EngineConfig class. If this method is not called it defaults to PlaformFileContext() and uses the Java File API to load the resources. The
PlatformServletContext class uses Resource based operations.
So if you are deploying an application to the Web that uses the BIRT API and it is not contained in a war you can use the default and
set your engine home to something similar to:
config.setEngineHome( servletContext.getRealPath("/WEB-INF"));
The BIRT Viewer application will load the plug-ins from /WEB-INF/Plugins directory.
If you deploy your application in a war, setup your code like:
//this causes the plug-in loader to look in the current directory.
config.setEngineHome("");
//Using the PlatformServletContext will cause the OSGi loader to look for the
//plug-ins in the WEB-INF/Platform directory. If this directory
//does not exist create it.
//Next copy the plug-ins directory from the ReportEngine directory to
//the WEB-INF/Platform/ directory.
IPlatformContext context = new PlatformServletContext( sc );
config.setPlatformContext( context );
If you need to embed your report output into an existing web page you can use the options.setEmbeddable(true); method.
This will remove the <HTML> and <BODY> tags in the generated report.
For example,
public void embedReport( HttpServletResponse response )
{
.
.
.
//Set rendering options
HTMLRenderOption options = new HTMLRenderOption();
options.setOutputStream(response);
options.setEmbeddable(true);
task.setRenderOption(options);
//run the report
task.run();
}
An "emitter" is the component of the report engine that produces output. BIRT provides many emitters such as HTML, XLS and PDF. To configure emitter options you need to use the RenderOption class. In some of the examples above this was done, with code similar to the following:
IRenderOption options = new RenderOption();
options.setOutputFormat("html");
options.setOutputFileName("output/resample/eventorder.html");
BIRT also provides an extended RenderOption class for the PDF and HTML emitters (PDFRenderOption and HTMLRenderOption).
The PDFRenderOption class provides methods for handling fonts and the HTMLRenderOption class provides methods for
handling images, url encoding, and other html specific settings.
You may need to configure the HTML emitter to manage images.Your application must have a policy for handling images in HTML. URL-based
images are usually no problem. However, you'll need to handle the others. The
IHTMLImageHandler interface defines the policy. The BIRT Engine provides two
default implementations:
HTMLCompleteImageHandler: used to write images to disk when rendering a
report to produce an HTML file on disk.HTMLServerImageHandler: used to handle images for an engine running in an
app server. This class is used by the BIRT example web viewer.When you instantiate a EngineConfig class the HTMLCompleteImageHandler class is used by default.
Images will be created in your temporary files location (ie C:\Documents and Settings\User\Local Settings\Temp).
If this is not desired you can use the HTMLRenderOption class to change this location.
HTMLRenderOption htmlOptions = new HTMLRenderOption( options);
htmlOptions.setImageDirectory("output/image");
Setting the Image Directory instructs the RE API to store images, used within the report output, in that directory.
If your emitter is setup with the standard HTMLCompleteImageHandler, the output image src attribute will point to this directory using
the File protocol. If your emitter is configured with the HTMLServerImageHandler, you can specify an image base URL using the HTMLRenderOption class. The engine
will prepend all images with this URL in the src attribute of the report output.
HTMLRenderOption options = new HTMLRenderOption();
options.setOutputFileName("output/resample/TopNPercent.html");
options.setOutputFormat("html");
options.setImageDirectory("C:\apps\apache-tomcat-5.5.20\webapps\2.2\images");
options.setBaseImageURL("http://localhost:8080/2.2/images/");
options.setImageHandler(new HTMLServerImageHandler());
task.setRenderOption(options);
You can also create your own implementation of IHTMLImageHandler if the above
don't meet your needs.
If your code is going to be run in a servlet, please review the
ReportEngineService.java code in CVS ReportEngineService.java
The BIRT Viewer uses this class to configure the engine. The constructor for the ReportEngineService uses the HTMLServerImageHandler class,
which in turn reads Image locations from the web.xml file.