How To Change a Complex Property of a Report Item
The code sample in Listing 5 shows how to use PrivateStyleHandle and ColorHandle objects to change the background color of a label. The variable, design, is a ReportDesignHandle object. This sample accesses the label by name. You can also access a report item by navigating the report structure.

Adding a Report Item to a Report Design Programmatically
A reporting application can use a simple report design or a template to create more complex designs. The application can add extra report items to the design's structure based on external conditions. For example, based on the user name of the user requesting the generation of a report, you can add extra information to the report for that category of user. You use the same techniques to add content to a new design if you create a design entirely with the API.

The class that creates new elements, such as report items, in a report design is ElementFactory. This class provides methods of the form, newXXX( ), where XXX is the report item or element to create. The method newElement( ) is a generic method that creates an element of any type. To access the element factory, call the ReportDesign.getElementFactory( ) method.

You can place new report items at the top level of the report design, directly in the Body slot, in containers such as a cell in a table or grid, or on the master page. You can add a simple item, such as a label, or complex items, such as a table with contents in its cells. Wherever you add a new report item, the location is a slot, such as the body slot of the report design or a cell slot in a row in a table. To add a report item to a slot, you use one of the SlotHandle.add( ) methods. The method has two signatures that support adding the report item to the end of a slot, or to a particular position in a slot.

Table and list elements are container items that iterate over the rows that a data set provides. For these report items to access the data rows, you must bind them to a data set. The table or list element provides data rows to the report items that it contains. For this reason, you usually bind only the container item to a data set, as described later in this article.

How To Add a Grid Item and Label Item to a Report Design
The code sample in Listing 6 creates a grid item then adds a label item to one of the cells in the grid. An application can create any other report item in a similar manner. The variable, design, is a ReportDesignHandle object.

Accessing a Data Source and Data Set with the API
This section will explain how to use ROM elements that aren't report items. To use other ROM elements, such as the libraries that the report design uses, you employ similar techniques.

You access the report design's data sources and data sets from methods on the ReportDesignHandle instance in a way similar to other report elements. The model classes that define a data source and data set are DataSourceHandle and DataSetHandle, respectively. A data set provides a report item such as a table with data from a data source. For a report item to access the data set, use the setDataSet() method.

You can use a finder method on the report design handle to access a data source or data set by name. The finder methods are findDataSource( ) and findDataSet( ), respectively.

Alternatively, to access all the data sources or data sets, you can use a getter method that returns a slot handle. The getter methods are getDataSources( ) and getDataSets( ), respectively. To access the individual data sources or data sets in a slot handle, you iterate over the contents of the slot handle in the same way as for any other slot handle.

Data Source Classes
DataSourceHandle is a subclass of Report
ElementHandle. You get and set report item properties for a data source in the same way as for any other report element. DataSourceHandle also provides methods to access the scripting methods of the data source.

The two subclasses of DataSourceHandle, OdaDataSourceHandle and ScriptDataSourceHandle, provide the functionality for the two families of BIRT data sources. For more information about ODA data sources, see the Javadoc for the ODA API in the Open Data Access (ODA) 3.0.0 API Reference. The scripting methods for a scripted data source fully define the data source.

Data Set Classes
DataSetHandle is a subclass of ReportElementHandle. You get and set properties for a data set in the same way as for any other report element. DataSetHandle also provides methods to access properties specific to a data set, such as the data source, the data set fields, and the scripting methods of the data set.

The two subclasses of DataSetHandle, OdaDataSetHandle and ScriptDataSetHandle, provide the functionality for the two families of BIRT data sets. For more information about ODA data sets, see the Javadoc for the ODA API.

Using a Data Set Programmatically
Typically, a reporting application uses data sets and data sources already defined in the report design. You can use the data set's setDataSource( ) method to change the data source of a data set. For example, based on the name of the user of the reporting application, you can report on the sales database for a particular geographical region, such as Europe or North America.

Changing the Properties of a Data Set
Changing the properties of a data set means considering the impact on the report design. If you change the data source of a data set, the type of data source must be appropriate for the type of data set. You must also be certain that the new data source can provide the same fields as the original data source.

How To Change the Data Source for a Data Set
The code sample in Listing 7 shows how to check for a particular data source and data set in a report design then changes the data source for the data set. The code finds the data source and data set by name.

Alternatively, use the getDataSets( ) and getDataSources( ) methods. Then use the technique for iterating over the contents of a slot handle. The variable, design, is a ReportDesignHandle object.