By Jason Weathersby, Tom Bondur, Jane Tatchell | Article Rating: |
|
February 20, 2007 02:45 PM EST | Reads: |
101,943 |

The Eclipse platform is an open source, integrated system of application development tools that you implement and extend using a plug-in interface. The Eclipse Business Intelligence Reporting Tool (BIRT) is a set of plug-in extensions that enable a developer to add reporting functionality to an application. BIRT provides a Report Engine API that a developer can use to create a customized report generator application. The org.eclipse.birt.report.engine.api package contains a set of interfaces and implementation classes that supports integrating the runtime part of BIRT into an application.
The BIRT Report Engine can provide report generation and rendering services in the following environments:
- Stand-alone engine: A Java developer uses a stand-alone engine to render a BIRT report from a report design (.rptdesign) file. In this environment, the Java developer creates a command-line application that writes a report to disk, either in HTML or PDF format.
- BIRT report viewer: BIRT Report Designer uses the BIRT report viewer to view a report as paginated HTML. The BIRT report viewer is a Web application that runs in the Tomcat Application Server embedded in Eclipse. This viewer contains an embedded BIRT report engine.
- Customized report designer: A customized report design environment uses an embedded BIRT report engine to preview a report.
- Web application: A Web application similar to the BIRT report viewer uses an embedded BIRT report engine to generate a Web-based report.
- Creates and configures a report engine
- Opens a report design or report document
- Accesses data from a data source
- Generates a report in a supported output format
- Shuts down the engine
The main interfaces and classes in the org.eclipse.birt.report.engine.api package are:
- ReportEngine
- EngineConfig
- IReportRunnable
- IRenderOption and its descendants
- IEngineTask and its descendants
- Get a configuration object.
- Open a report design or a report document.
- Create an engine task to get parameter definitions and set parameter values.
- Create an engine task to access data from a data set.
- Get supported report formats and MIME types.
- Create an engine task to run a report or render a report to an output format.
- Create an engine task to extract data from a report document.
- Clean up and shut down the engine.
The EngineConfig class contains the configuration settings for the report engine. Use the EngineConfig object to specify the settings for the following properties:
- HTML emitter configuration for custom handling of images or actions for HTML output
- Logging to set the logging file location and level
- Platform context to indicate whether the application and engine home are in a stand-alone environment or packaged as a WAR file
- Resource files to set the location where the reporting application can access libraries and properties files
- Scripting configuration to provide external values and Java resources to scripting methods
Two engine configuration properties depend on whether the environment in which the application runs is stand-alone or in a WAR file on an application server. These properties are the platform context and the HTML emitter configuration. The platform context provides the report engine with the mechanism to access files. The HTML emitter configuration provides the functionality for processing images and handling hyperlinking and bookmark actions.
A ReportEngine constructor takes the EngineConfig object as its argument. If the configuration object is null, the report engine uses the default configuration. If the configuration object is null, the environment must provide a BIRT_HOME variable that specifies the directory containing the engine plug-ins and JAR files.
Listing 1 shows how to set up a report engine in a stand-alone application. The application uses the engine home located in the BIRT runtime directory. The report output format is HTML. The application configures the HTML emitter and creates the report engine using the settings contained in the EngineConfig object.
Opening a Report Design or Report Document
BIRT Report Engine can generate a report from either a report design or an existing report document. To open a report design, call one of the openReportDesign( ) methods on ReportEngine. These methods instantiate an IReportRunnable object using a String object that specifies the path to a report design or an input stream.
To open a report document, call the ReportEngine.openReportDocument( ) method. This method instantiates an IReportDocument object using a String object that specifies the path to a report document (.rptdocument) file. This method returns the IReportDocument object. You must handle the EngineException that these methods throw.
The IReportRunnable object provides direct access to basic properties of the report design. The names of report design properties are static String fields, such as IReportRunnable.AUTHOR. To access a report design property, use the getProperty( ) method with a string argument that contains one of these fields.
To access and set the values of parameters, use methods on a parameter definition task object, described later in this article. Listing 2 shows how to open a report design and find a property value. If the engine cannot open the specified report design, the code shuts down the engine. The variable, engine, is a ReportEngine object.
The IReportDocument object provides access to the data in a report and the report's structure. IReportDocument provides methods to retrieve table of content entries, bookmarks, and page information.
To access table of content entries, use the findTOC( ) method. This method takes a TOCNode argument and returns a TOCNode object. To find the root table of contents entry, use a null argument. To find the subentries of a table of contents entry, use the getChildren( ) method. This method returns a list of TOCNode objects. From a TOCNode object, you can retrieve the display value of the entry and a Bookmark object.
Published February 20, 2007 Reads 101,943
Copyright © 2007 Ulitzer, Inc. — All Rights Reserved.
Syndicated stories and blog feeds, all rights reserved by the author.
More Stories By Jason Weathersby
Jason Weathersby is a member of the extended BIRT development team at Actuate Corporation and has backgrounds in both computer science and technical writing. He has many years experience in technical consulting, training, writing, and publishing about reporting, business intelligence tools, and database technologies.
More Stories By Tom Bondur
Tom Bondur is a member of the extended BIRT development team at Actuate Corporation and has backgrounds in both computer science and technical writing. He has many years experience in technical consulting, training, writing, and publishing about reporting, business intelligence tools, and database technologies.
More Stories By Jane Tatchell
Jane Tatchell is a content development manager in the Developer Communications group of Actuate Engineering.
- Java Developer's Journal Exclusive: 2006 "JDJ Editors' Choice" Awards
- Eclipse Special: Remote Debugging Tomcat & JBoss Apps with Eclipse
- Creating Web Applications with the Eclipse Web Tools Project
- What's New in Eclipse?
- Configuring Eclipse for Remote Debugging a WebLogic Java Application
- JDJ Archives: Eclipse vs NetBeans - "Point/Counterpoint" Special
- Java Feature — Bringing Together Eclipse,WTP, Struts, and Hibernate
- SYS-CON Webcast: Eclipse IDE for Students, Useful Eclipse Tips & Tricks
- Eclipse: The Story of Web Tools Platform 0.7
- Developing an Application Using the Eclipse BIRT Report Engine API