To access a report design and its contents, the application must instantiate first, a report engine, and second, a ReportDesignHandle object. The ReportDesignHandle object provides access to the ROM elements in the design opened by the report engine. Instantiate a ReportDesignHandle by calling a method on either the model class, SessionHandle, or the report engine interface, IReportRunnable.

The SessionHandle object manages the state of all open report designs. Use a SessionHandle to open, close, and create report designs, and to set global properties, such as the locale and the units of measure for report elements. The SessionHandle can open a report design from a file or a stream. Create the session handle only once. BIRT supports only a single SessionHandle for a user of a reporting application.

The DesignEngine class provides access to all the functionality of the ROM in the same way that the ReportEngine class provides access to report generation functionality. Before creating a DesignEngine object, create a DesignConfig object to contain configuration settings for the design engine. The DesignConfig object sets up custom access to resources and custom configuration variables for scripting.

Use a factory service to create a DesignEngine in the same way as creating a ReportEngine. After setting configuration properties, create a design engine by calling the Platform.createFactoryObject( ) and the IDesignEngineFactory
.createDesignEngine( ) methods. The DesignConfig object defines the settings for this process. If the application has already started the platform in order to set up a report engine, use the same platform instance to create the design engine. If the application runs in an RCP environment, do not start the platform.

Create the SessionHandle object by calling the method, newSessionHandle( ) on the DesignEngine object. To open the report design, call the method, openDesign( ), on the SessionHandle object. This method takes the name of the report design as an argument and instantiates a ReportDesignHandle.

The code sample in Listing 5‑16 creates a DesignEngine object from which to create a SessionHandle object. The code uses the SessionHandle object to open a report design.

An alternative way to open a report design is by calling the getDesignHandle( ) method on an IReportRunnable object. Use a design engine to access the elements in this report design in the same way as for any other design handle.