About the BIRT Report Engine API
The BIRT report engine supports report generation and rendering in several different environments, such as:
*Stand-alone engine
A Java developer uses a stand-alone engine to render a BIRT report from an existing report design (.rptdesign) file. In this environment, the Java developer creates a command line application to write a complete report in any of the supported formats.
*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, which is embedded in Eclipse. This viewer contains an embedded report engine.
*Custom report designer with an embedded engine
A custom desktop reporting application integrates the BIRT report engine for the purpose of previewing the report.
*Web application that embeds the engine
A web application similar to the BIRT report viewer can use the BIRT report engine to generate a web-based report.
The BIRT report engine supports running and rendering reports in these diverse environments. It does not perform environment-dependent processing such as URL construction, image storage, and design file caching. The application using the engine API must provide such context information to the engine.
The BIRT Report Engine API consists of interfaces and implementation classes that support integrating the run-time part of BIRT into an application. The API provides task classes that support the following operations:
*Discovering the set of parameters defined for a report
*Getting the default values for parameters
*Running a report design to produce an unformatted report document
*Running a report design or report document to produce any of the supported output formats
*Extracting data from a report document
Creating the ReportEngine instance
Each application, whether it is stand-alone or web-based, only needs to create one ReportEngine instance. As the BIRT report engine is thread-safe, the single‑instance recommendation is not a restriction.
Use an IReportEngineFactory instance and an EngineConfig object to create the ReportEngine instance.
Using the BIRT Report Engine API
The BIRT Report Engine API supports the following key tasks to generate reports:
*Setting options for the report engine using an EngineConfig object
*Starting the platform
*Creating a ReportEngine object using the ReportEngineFactory
*Opening an existing report design using one of the openReportDesign( ) methods of ReportEngine or opening an existing report document using the openReportDocument( ) method
*Optionally, obtaining design details of the report parameters using an IGetParameterDefinitionTask object
*Running and rendering a report using IRunAndRenderTask or IRunTask followed by IRenderTask
*Cleaning up the report engine by calling destroy( ) on the engine instance to unload extensions and delete temporary files
A few key classes and interfaces provide the core functionality of the BIRT report engine. The following sections provide an overview of these classes.
EngineConfig class
The EngineConfig class wraps configuration settings for a report engine. Use the EngineConfig object to set global options for the environment of the report engine, including:
*Setting OSGi arguments
*Setting the platform context
*Setting resource locations
*Adding application-wide scriptable objects
*Setting the directory where the report engine writes temporary files
*Managing logging
ReportEngine class
The ReportEngine class represents the BIRT report engine. To instantiate the ReportEngine object, use a factory method that takes an EngineConfig object as an argument. Use a ReportEngine object to perform the following tasks:
*Getting the configuration object
*Opening a report design or a report document
*Creating an engine task to get parameter definitions
*Creating an engine task to access the data from a report item
*Getting supported report formats and MIME types
*Creating an engine task to run a report or render a report to an output format
*Creating an engine task to extract data from a report document
*Changing the logging configuration
*Cleaning up and destroying the engine
IReportRunnable interface
To use the engine to work with the report design, load the design using one of the openReportDesign( ) methods in the ReportEngine class. These methods return an IReportRunnable instance that represents the engine’s view of the report design. Use an IReportRunnable object to perform the following tasks:
*Getting standard report design properties, such as the report title
*Getting any images embedded within the report design
*Getting a handle to the report design
IReportDocument interface
To use a report document, load the document using one of the ReportEngine
.openReportDocument( ) methods. These methods return an IReportDocument instance. Use an IRenderTask object to render the report specified by an IReportDocument object to a supported output format. Use table of contents markers in the IReportDocument to determine pages to render. The IReportDocument interface also supports retrieving page counts, parameter values used while creating the report document, and bookmarks.
IEngineTask interface
The IEngineTask interface provides the framework for the tasks that the report engine performs. The IEngineTask interface manages the scripting context, getting and setting parameter values, setting the report’s locale, getting the current status of a task, and cancelling a task. The other task interfaces extend IEngineTask.
IGetParameterDefinitionTask interface
The IGetParameterDefinitionTask interface extends IEngineTask to provide access to information about parameters. Use the engine factory method to create an IGetParameterDefinitionTask object takes an IReportRunnable argument. Parameter definitions provide access to:
*Information that BIRT Report Designer specified at design time
*Static or dynamic selection lists
*User-supplied values
*Grouping structure of the parameters
*Custom XML
*User-defined properties
IDataExtractionTask interface
The IDataExtractionTask interface extends IEngineTask to provide access to the data stored in an IReportDocument object. Use an IDataExtractionTask object to examine the metadata for a set of data rows. Use the metadata to select a set of columns to extract, sort, or filter. This interface can extract the data from:
*The whole report document
*A single report item
*A single instance of a report item
IRunTask interface
The IRunTask interface provides the methods to run a report design. This task saves the result as a report document (.rptdocument) file on disk. An IRunTask object takes parameter values as a HashMap. Call the validateParameters( ) method to validate the parameter values before running the report.
IRenderTask interface
The IRenderTask interface provides the methods to render a report document to one of the supported output formats. This task can save the report to a file on disk or to a stream.
Use the RenderOption class to set options for rendering. Set options specific to particular output formats using subclasses of the RenderOption class. Pass the appropriate render option object to the IRenderTask object before rendering the report.
IRunAndRenderTask interface
The IRunAndRenderTask interface provides the methods to run a report and render it in one of the supported output formats. This task can save the report to disk or to a stream. This task does not create an intermediate report document (.rptdocument) file.
An IRunAndRenderTask object takes parameter values as a HashMap or individually. Call the validateParameters( ) method to validate the parameter values before running the report.
An IRunAndRenderTask object supports setting the same rendering options as an IRenderTask object. Pass the appropriate render option object to the IRunAndRenderTask object before running the report.
Report Engine API class hierarchy
The class hierarchy in Figure 4‑1 illustrates the organization of the classes in the report engine package. Unless otherwise specified, all classes and interfaces in this diagram are in the org.eclipse.birt.report.engine.api package.
Figure 4‑1 Classes within the report engine package
Figure 4‑1 Classes within the report engine package
Report Engine API interface hierarchy
Figure 4‑2 contains the interface hierarchy for the Report Engine API. Unless otherwise specified, all interfaces in this diagram are in the org.eclipse.birt.report.engine.api package.
Figure 4‑2 Interface hierarchy for the report engine package
Figure 4‑2 Interface hierarchy for the report engine package