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:
Specifying the BIRT home, the location of the engine plug-ins and Java archive (.jar) files
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. If the configuration object is null, the environment must provide a BIRT_HOME variable that specifies the BIRT home. 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( ) method. 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.