About the Design 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 develop a design tool. The Design Engine API supports creating, accessing, and validating a report design, library, or template.

The org.eclipse.birt.report.model.api package contains the interfaces and classes used to access the design model objects. The Design Engine API supports the following tasks:

Reading and writing design files

Maintaining the command history for undo and redo

Providing a rich semantic representation of the report design

Providing metadata about the ROM

Performing property value validation

Notifying the application when the model changes

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:

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. 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 it supports all the functionality of that class. 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 it supports all the functionality of that class. 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( ).

Design Engine API class hierarchy

Figure 4‑3 illustrates the hierarchy of the classes within the design engine package. Unless otherwise specified, all classes and interfaces in this diagram are in the org.eclipse.birt.report.model.api package.

Figure 4‑3 Classes within the report model package

DesignElementHandle hierarchy

Figure 4‑4 contains the class hierarchy for DesignElementHandle in the org.eclipse.birt.report.model.api package and the classes that derive from it.

Figure 4‑4 DesignElementHandle class hierarchy

ReportElementHandle hierarchy

Figure 4‑5 contains the class hierarchy for ReportElementHandle in the org.eclipse.birt.report.model.api package and the classes that derive from it. The interfaces that the classes implement are all in the org.eclipse.birt.report.model
.elements.interfaces and org.eclipse.birt.report.model.elements packages. Classes with names that have a prefix of olap are in the org.eclipse.birt.report.model.olap package.

Figure 4‑5 ReportElementHandle class hierarchy

ReportItemHandle hierarchy

Figure 4‑6 contains the class hierarchy for ReportItemHandle in the org.eclipse.birt.report.model.api package and the classes that derive from it. The interfaces that the classes implement are all in the org.eclipse.birt.report.model
.elements.interfaces and org.eclipse.birt.report.model.elements packages.

Figure 4‑6 ReportItemHandle class hierarchy

ElementDetailHandle hierarchy

Figure 4‑7 contains the class hierarchy for ElementDetailHandle in the org.eclipse.birt.report.model.api package and the classes that derive from it.

Figure 4‑7 ElementDetailHandle class hierarchy

StructureHandle hierarchy

Figure 4‑8 contains the class hierarchy for StructureHandle in the org.eclipse.birt.report.model.api package and the classes that derive from it.

Figure 4‑8 StructureHandle class hierarchy

Figure 4‑8 StructureHandle class hierarchy

Design Engine API interface hierarchy

Figure 4‑9 contains the interface hierarchy for the Design Engine API. All interfaces in this diagram are in the org.eclipse.birt.report.model.api package.

Figure 4‑9 Interface hierarchy for the design engine package