Using the BIRT Design Engine API
The purpose of the BIRT Design Engine API is to modify or create a 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 supports libraries and templates in the same way as report designs. The BIRT Design Engine API does not include any user interface classes. A custom report design tool must provide its own user interface code.
The design engine supports the following tasks to create or modify a BIRT report design:
Setting options for the design engine by using a DesignConfig object
Starting the Platform, if not already started
Creating a DesignEngine object using the DesignEngineFactory
Beginning a user session by using the DesignEngine.newSessionHandle( ) method to instantiate a SessionHandle object
Setting session parameters and loading the property definitions of the report elements by using the SessionHandle object to create an instance of the ReportDesignHandle class
Using the ReportDesignHandle to create an ElementFactory, which can create report elements
Using the ReportDesignHandle to add new elements to the report design or modify existing elements
Saving the report design file by using the ReportDesignHandle
The following sections describe the primary classes of the BIRT Design Engine API.
DesignConfig class
The DesignConfig class wraps configuration settings for a design engine. Use a DesignConfig object to set global options for the design engine, including:
Specifying the location of engine plug-ins and Java archive (.jar) files
Setting the Platform Context
Specifying configuration variable
Set OSGi arguments
DesignEngine class
The DesignEngine class represents the BIRT design engine. Create the DesignEngine with a factory method that takes a DesignConfig object. If the configuration object is null, the environment must provide the path to the BIRT home, the directory that contains the engine plug-ins and JAR files. The DesignEngine class is the gateway to creating the other objects needed to build a report design tool. Use the methods of the DesignEngine class to create a locale-specific SessionHandle object by calling the newSession( ) method. The SessionHandle provides access to report design objects.
SessionHandle class
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, as well as setting the path and algorithm used to locate resources. The methods to create or open a report design return a ReportDesignHandle object.
ModuleHandle class
ModuleHandle provides access to the common structure and functionality of report designs, templates, and libraries. The ModuleHandle class is the parent class of the ReportDesignHandle and LibraryHandle classes. ModuleHandle provides access to the generic properties, such as author and comments. 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
Retrieving the module location
Getting configuration variables
Other ModuleHandle methods support getting 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, data sets, and cubes.
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, for example, providing images or lists of messages in localized forms.
Embedded images.
ReportDesignHandle class
ReportDesignHandle provides access to 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 is a subclass of ModuleHandle, so supports all that class’s functionality. Use ReportDesignHandle to get handles to individual report items and for many report design-specific tasks, including:
Navigating to the various parts of the design
Setting the event-specific scripts that execute when the report engine runs and renders the report
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, the location of file system resources with relative paths
Body, a list of the report sections and report items in the design
Scratch Pad, a temporary place to hold report items while restructuring a report
LibraryHandle class
LibraryHandle is a subclass of ModuleHandle, so supports all that class’s functionality. LibraryHandle also provides access to the following library-specific properties:
Name space, the name that a module including a library uses to identify the elements that the library defines
The set of themes that the library defines
Imported CSS styles used by themes
DesignElementHandle class
DesignElementHandle is the base class for all report elements, both visual report item elements and non-visual ones, such as data sets and cubes. DesignElementHandle provides generic services for all elements, such as:
Adding a report item to a slot
Registering a change event listener
Getting and setting properties, names, and styles
Getting available choices for specific properties
Dropping an element from the design
Copying, pasting, and moving report items
Individual element handle classes
Element handle classes derive from ReportElementHandle. Each report element has its own handle class. To work with operations unique to a given report element, cast the ReportElementHandle to the appropriate subclass for the element. For example, the CellHandle class provides methods such as getColumn( ), and the DataSourceHandle class has methods such as setBeforeOpen( ).