BIRT consists of hundreds of Java classes and interfaces, but most of them are only of interest to contributors to the BIRT open source project. Developers of applications only require access to the classes and interfaces that are in the public API. The public API consists of the classes and interfaces in the following package hierarchies:
Report engine API
The org.eclipse.birt.report.engine.api package hierarchy contains the API that a developer of a custom report generator uses. This API provides the most commonly used functionality for a reporting application. The key class in the report engine API is ReportEngine. This class provides access to creating a report from a report design or a report document.
Design engine API
The org.eclipse.birt.report.model.api package hierarchy is by far the larger of the two reporting APIs. This API provides access to the content and structure of a report design, a template, or a library. A reporting application can use this API to change the structure of a design. The design engine API is also the API that a developer of a custom report designer uses.
Chart engine API
The org.eclipse.birt.chart package hierarchy contains the API that a developer of a custom chart generator uses. A reporting application can also use this API to modify charts in a report design.
Extension APIs
BIRT also provides a set of extension APIs for creating custom report items, custom data sources and data sets, custom rendering formats, and custom charts. Chapters later in this book describe how to use these extensions.
For information on class and interface methods, see the API Javadoc, which you can access from the BIRT Report Designer or Eclipse Workbench main menu at Help →Help Contents →BIRT Developer Guide.
This chapter section contains hierarchical diagrams for packages. These diagrams show the hierarchy of the classes in the package and interfaces local to the package or implemented by classes in the package. Classes and interfaces preceded by a package name are not local to the package. The hierarchical diagrams indicate different attributes and relationships in the classes and interfaces by means of the graphics shown in Table 12-1.
The BIRT Report Engine provides report generation and rendering services in several different environments, including the following environments:
Stand-alone engine
A Java developer uses a stand-alone engine to render an existing BIRT report from a report design (.rptdesign) file. In this environment, the Java developer creates a command line application that writes a complete 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, 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 is designed for easy customization to support the diverse environments in which it can be used. The BIRT Report Engine also supports seamless extension. The core engine runs and renders reports, leaving environment-dependent processing such as URL construction, image storage, and design file caching to the application that hosts the engine.
The BIRT Report Engine API consists of a set of interfaces and implementation classes. The BIRT Report Engine API supports integrating the run-time part of BIRT into your application. The API provides a set of task classes that support the following operations:
Discover the set of parameters defined for a report.
Get the default values for parameters.
Run a report design to produce an unformatted report document.
Run a report design or report document to produce an HTML or PDF formatted report.
Extract data from a report document.
Each application, whether it is stand-alone or web-based, only needs to create one ReportEngine instance. Since the BIRT Report Engine is thread-safe, the single-instance recommendation is not a restriction.
Create the BIRT Report Engine with a constructor that takes an EngineConfig object as an argument. The configuration object can be null, in which case a default engine configuration is used. At termination, the application should call shutdown( ) to unload extensions and delete temporary files.
The following are the primary steps in using the BIRT Report Engine API:
Create an instance of EngineConfig to set options for the report engine.
Create an instance of the ReportEngine class.
Open a report design using one of the openReportDesign( ) methods of ReportEngine or open a report document using the openReportDocument( ) method.
Obtain information about report parameters using IGetParameterDefinitionTask.
Run and render a report using IRunAndRenderTask or IRunTask followed by IRenderTask.
Call shutdown( ) on your engine instance.
There are a few primary classes and interfaces that provide the core functionality of the BIRT Report Engine. The following sections provide an overview of these classes. For full details, see the Javadoc.
The EngineConfig class wraps configuration settings for a report engine. Use the EngineConfig object to set global options for the report engine, including:
Specifying the location of engine plug-ins and Java archive (.jar) files
Specifying the location of data drivers
Adding application-wide scriptable objects
Managing logging
The ReportEngine class represents the BIRT report engine. You create the ReportEngine class with a constructor that takes an EngineConfig object. If the configuration object is null, the environment must provide a BIRT_HOME variable that specifies the directory that contains the engine plug-ins and JAR files.
You use a ReportEngine object to perform the following tasks:
Get the 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 the 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.
To work with the report design with the engine, you must 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.
You use an IReportRunnable object to perform the following tasks:
Get any parameter data.
Get properties such as the report title and report author.
Get any images embedded within the report design.
Run the report.
To work with a report document with the engine, you must load the document using the ReportEngine.openReportDocument( ) method. This method returns an IReportDocument instance.
You use an IReportDocument object to render a report to HTML or PDF with an IRenderTask object. You can use the table of contents markers in the IReportDocument to determine which pages to render.
The IEngineTask interface provides the framework for the tasks that the report engine performs. The IEngineTask interface manages the scripting context and report locales. The other task interfaces extend IEngineTask.
The IGetParameterDefinitionTask interface extends IEngineTask to provide access to information about parameters. 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
The grouping structure of the parameters
Custom XML
User-defined properties
The IDataExtractionTask interface extends IEngineTask to provide access to the data stored in an IReportDocument object. You can use an IDataExtractionTask object to examine the metadata for a set of data rows. Using the metadata, you can 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
The IRunTask interface provides the methods to run a report design. This task saves the result as a report document (.rptdocument) file to disk.
An IRunTask object takes parameter values as a HashMap. Call the validateParameters( ) method to validate the parameter values before you run the report.
The IRenderTask interface provides the methods to render a report document to PDF or to paginated or unpaginated HTML. This task can save the report to disk or to a stream.
You can set options that are specific to each of the HTML and PDF formats. Set these options through the HTMLRenderOption and PDFRenderOption classes. Pass the appropriate render option object for your report to the IRenderTask object before rendering the report.
The IRunAndRenderTask interface provides the methods to render a report as unpaginated HTML. This task can save the report to disk or to a stream.
An IRunAndRenderTask object takes parameter values as a HashMap. Call the validateParameters( ) method to validate the parameter values before you run the report.
You can set options that are specific to HTML format. Set these options through the HTMLRenderOption class. Pass the render option object for your report to the IRunAndRenderTask object before running the report.
The class hierarchy in Figure 12-1 illustrates the organization of the classes within the report engine package. The names of the classes in the diagram do not include the package name, which is org.eclipse.birt.report.engine.api.
Figure 12-2 contains the interface hierarchy for the report engine API.
The design engine API is also known as the report model API. The design engine API is the API that a tool writer uses to build a design tool. The design engine API contains classes and methods to create, access, and validate a report design.
The org.eclipse.birt.report.model.api package contains the interfaces and classes that the tool writer uses to access the design model objects. Through the design engine API, you can do the following tasks:
Read and write design files.
Maintain the command history for undo and redo.
Provide a rich semantic representation of the report design.
Provide metadata about the ROM.
Perform property value validation.
Notify the application when the model changes.
The purpose of the BIRT design engine API is to modify or create a report design file that the BIRT report engine can use to generate a report. BIRT Report Designer, for example, uses the BIRT design engine API for this purpose. A custom report design tool, written for the same general purpose as BIRT Report Designer, can also use the BIRT design engine API to generate a design file. The design engine API also supports libraries and templates in the same way as report designs.
The BIRT design engine API does not include a user interface. A custom report design tool must provide its own user interface code.
With the design engine, you can create a BIRT report design by performing the following tasks:
With a static DesignEngine method, instantiating a SessionHandle object to load the property definitions of the report elements and to begin a user session
With the SessionHandle object, setting session parameters and creating an instance of the ReportDesignHandle class
With the ReportDesignHandle object, setting the report-specific properties, adding elements to the report design, and providing access to the report elements
Saving the report design file
The following sections describe the primary classes of the BIRT design engine API.
The DesignEngine class is the gateway to creating the other objects you need to build a report design tool. Use the static methods of the DesignEngine class to:
Load the metadata system.
The initialize( ) method takes an argument containing the path to a file containing report element metadata. The metadata system describes the BIRT ROM elements and their properties and relationships. The metadata file that BIRT Report Designer uses is called rom.def. If you use this file, you do not need to call initialize( ).
Create a SessionHandle object.
Use the newSession( ) method to perform this task. The SessionHandle provides a gateway to the ReportDesign object.
The SessionHandle class represents the user session. A SessionHandle object provides access to the set of open designs. A session has a set of default values for style properties and a default unit of measure. The session also has methods to create and open report designs, templates, and libraries. The methods to create or open a report design return a ReportDesignHandle object.
ModuleHandle provides access to the common structure and functionality of report designs, templates, and libraries. It is the parent class of the ReportDesignHandle and LibraryHandle classes. ModuleHandle provides access to the generic properties, such as author and comments. You also use ModuleHandle for many tasks on the file, including:
Saving the module to a file
Accessing the command stack for undo and redo
Navigating to the various parts of the module
Accessing the command stack
Getting configuration variables
The ModuleHandle also has methods to get handles to the individual report items and all the other elements in a report design, template, or library. These elements and supporting components include:
Report items. These elements are visual report elements such as tables, grids, images, and text elements.
Code modules. These modules are global scripts that apply to the file as a whole.
Parameters.
Data sources and data sets.
Color Palette. This component is a set of custom color names.
CSS files that the module uses.
Theme. The theme is a group of styles that the module uses for formatting report elements.
Master page. This element defines the layout of pages in paginated report output.
Libraries. Any module can use one or more libraries to provide predefined elements.
Resources. External files provide lists of messages in localized forms.
Embedded images.
ReportDesignHandle provides access to the report design-specific properties such as the scripts that execute when generating or rendering a report. This class also provides access to properties that templates use, such as the cheat sheet, display name, and icon file.
ReportDesignHandle inherits most of its behavior and functionality from ModuleHandle. You also use ReportDesignHandle to get handles to the individual report items and for many report design-specific tasks, including:
Navigating to the various parts of the design
Setting the initialization script that runs when the report executes
The ReportDesignHandle also has methods to gain access to the following report components:
Styles, the list of user-defined styles for formatting report elements
Base directory, used to find the location of file system resources that have relative paths
Body, a list of the report sections and report items in the design
Scratch Pad, a temporary place to move report items while restructuring a report
LibraryHandle provides access to the library-specific properties, as shown in the following list. LibraryHandle inherits most of its behavior and functionality from ModuleHandle.
Imported CSS styles
Styles imported from CSS files
Themes
Groups of styles for formatting report elements
The DesignElementHandle class is the base class for report elements. The DesignElementHandle class provides generic services for all elements, including such things as:
Adding a report item to a slot
Registering a change event listener
Getting and setting properties, names, and styles
Dropping an element from the design
The individual element handle classes derive from ReportDesignHandle. Each report element has its own handle class. To work with operations unique to a given report element, you cast the ReportDesignHandle to the appropriate subclass for the element. For example, the CellHandle class has methods such as getColumn( ), while the DataSourceHandle class has methods such as setBeforeOpen( ).
Figure 12-3 illustrates the hierarchy of the classes within the design engine package. The hierarchy diagram omits package prefixes on class names for the classes and interfaces in the package org.eclipse.birt.report.model.api.
Figure 12-4 contains the class hierarchy for ReportElementHandle and the classes that derive from it.
Figure 12-5 contains the class hierarchy for ReportItemHandle and the classes that derive from it.
Figure 12-6 contains the class hierarchy for ElementDetailHandle and the classes that derive from it.
Figure 12-7 contains the class hierarchy for StructureHandle and the classes that derive from it.
The Chart Engine API is based upon the EMF as a structured data model. The Chart Engine API includes many packages in the org.eclipse.birt.chart hierarchy.
Use the classes and interfaces in the chart engine API to modify chart objects within a BIRT reporting application or in a stand-alone charting application.
The model.* packages contain the core chart model interfaces and enumeration classes generated using EMF. The model.*.impl packages contain the core chart model implementation classes generated using EMF. All other packages are dependencies and indirect references from the core model.
There is a one-to-one correspondence between the classes in the impl packages and the interfaces in corresponding model packages. The classes in the impl packages implement the methods in the interfaces of the corresponding model classes. The impl classes also contain factory methods that you use to create an instance of a class.
Although there are over 500 classes and interfaces in the BIRT Chart Engine API, most of functionality for creating or modifying a chart is concentrated in a small subset of classes and interfaces.
The primary interface in the BIRT Chart Engine API is the Chart interface. An object of the Chart type is called the chart instance object. The Chart interface has two subinterfaces, ChartWithAxes and ChartWithoutAxes. DialChart is a third interface that inherits from ChartWithoutAxes. You create a chart instance object with the create( ) method of either ChartWithAxesImpl, ChartWithoutAxesImpl, or DialChartImp, as in the following statement:
ChartWithAxes myChart = ChartWithAxesImpl.create( );
You set the basic properties of a chart, such as its title and dimensionality with setter methods of the Chart interface, such as:
myChart.setTitle( "Monthly Sales" ); myChart.setDimension( ChartDimension.THREE_DIMENSIONAL );
You set the more complex properties of a chart, like the characteristics of the chart’s axes and series by getting an instance of the object you want to modify and then setting its properties. For example, to set the caption of a chart’s x-axis, you can use the following code:
Axis xAxis = myChart.getPrimaryBaseAxes( )[0]; xAxis.getTitle( ).getCaption( ).setValue( "Months" );
Although charts are often identified by type, such as a pie chart or a line chart, a chart with multiple series of differing types cannot be classified as one type. A series, on the other hand, has a specific type. With the BIRT Chart Engine API, you can create a specific type of series by using the create( ) method of one of the SeriesImpl subclasses. For example, the following code creates a bar series:
BarSeries barSeries1 = ( BarSeries ) BarSeriesImpl.create( );
For more information about using the BIRT Chart Engine API, see the chapter about programming with the BIRT Chart Engine APIs.
The diagrams that follow contain hierarchies for the following chart engine packages:
org.eclipse.birt.chart.aggregate
org.eclipse.birt.chart.datafeed
org.eclipse.birt.chart.device
org.eclipse.birt.chart.event
org.eclipse.birt.chart.exception
org.eclipse.birt.chart.log
org.eclipse.birt.chart.model
org.eclipse.birt.chart.model.attribute
org.eclipse.birt.chart.model.component
org.eclipse.birt.chart.model.data
org.eclipse.birt.chart.model.layout
org.eclipse.birt.chart.model.type
org.eclipse.birt.chart.render
org.eclipse.birt.chart.script
org.eclipse.birt.chart.util
The hierarchy diagrams for the org.eclipse.birt.chart.model.*.impl packages are not included because they are simply implementations of the interfaces in the corresponding org.eclipse.birt.chart.model.* packages. The model packages, with two exceptions, contain only interfaces.
The first exception is org.eclipse.birt.chart.model, which has one class, ScriptHandler. The second exception is org.eclipse.birt.chart.model.attribute, which has a set of enumeration classes, one for each attribute. Each of the enumeration classes only contains a list of legal values for its attribute.
Figure 12-8 contains the class hierarchy for org.eclipse.birt.chart.aggregate.
Figure 12-9 contains the class hierarchy for org.eclipse.birt.chart.datafeed.
Figure 12-10 contains the class hierarchy for org.eclipse.birt.chart.device.
Figure 12-11 contains the interface hierarchy for org.eclipse.birt.chart.device.
Figure 12-12 contains the class hierarchy for org.eclipse.birt.chart.event.
Figure 12-13 contains the class hierarchy for org.eclipse.birt.chart.exception.
Figure 12-14 contains the class hierarchy for org.eclipse.birt.chart.factory.
Figure 12-15 contains the class hierarchy for org.eclipse.birt.chart.log.
Figure 12-16 contains the class hierarchy for org.eclipse.birt.chart.model.
Figure 12-17 contains the interface hierarchy for org.eclipse.birt.chart.model.attribute.
Figure 12-18 contains the class hierarchy for org.eclipse.birt.chart.model.attribute.
Figure 12-19 contains the interface hierarchy for org.eclipse.birt.chart.model.component.
Figure 12-20 contains the interface hierarchy for org.eclipse.birt.chart.model.data.
Figure 12-21 contains the interface hierarchy for org.eclipse.birt.chart.model.layout.
Figure 12-22 contains the interface hierarchy for org.eclipse.birt.chart.model.type.
Figure 12-23 contains the class and interface hierarchy for org.eclipse.birt.chart.render.
Figure 12-24 contains the class and interface hierarchy for org.eclipse.birt.chart.script.
Figure 12-25 contains the class hierarchy for org.eclipse.birt.chart.util.
