A reporting application typically generates reports from report designs. When deploying this type of application, the report designs are deployed with the application. Any changes to the generated reports depend on the values of report parameters and the data from the data set. To access a report design, the application uses an IReportRunnable object.

Sometimes business logic requires changes to the report design before generating the report. Some changes are possible through using parameters and scripting. Other changes can only occur through modification of the report design itself. The API to perform these tasks is known as the model API. The package containing the classes and interfaces to work with the items in a report design, library, or template is org.eclipse.birt.report.model.api.

To access the structure of the report design, the application obtains a ReportDesignHandle object from the design engine. ReportDesignHandle provides access to all properties of the report design and to the elements that the report design contains.

The model API provides handle classes to access all Report Object Model (ROM) elements. For example, a GridHandle object provides access to a grid element in the report design. All ROM element handles, including the report design handle, inherit from DesignElementHandle. Report items inherit from ReportElementHandle and ReportItemHandle.

After making changes to a report design or its elements, the application writes the result to a stream or a file. To generate a formatted report or a binary report document, use the report engine to open an IReportRunnable object on the updated design. Then, use the report engine as described earlier in this chapter. To access the design engine, an application must first instantiate a report engine.

An application typically accesses the items in a report design to perform one of the following tasks:

A reporting application can access and modify the structures in a template or a library file in the same way as the structures in a report design. The techniques described in the rest of this chapter are as applicable to these file types as to report designs. A template has identical functionality to a report design. For this reason, the ReportDesignHandle class provides access to a template. The LibraryHandle class provides access to a library. Both these classes derive from the ModuleHandle class, which provides the fields and methods for the common functionality, such as accessing elements in the file.