This section shows how to use ROM elements that are not report items. To use other ROM elements, such as the libraries that the report design uses, employ similar techniques as for report items.

Access the report design’s data sources and data sets using methods on the ReportDesignHandle instance, in a similar way 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 item’s setDataSet( ) method.

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, 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, iterate over the contents of the slot handle in the same way as for any other slot handle.

DataSourceHandle is a subclass of ReportElementHandle. 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, install the Javadoc for the ODA API. The scripting methods for a scripted data source fully define the data source, as described earlier in this book.

DataSetHandle is a subclass of ReportElementHandle. 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.

Typically, a reporting application uses data sets and data sources already defined in the report design. 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, access data from the sales database for a particular geographical region, such as Europe or North America.

Changing the properties of a data set requires consideration of the impact on the report design. If the application changes the data source of a data set, the type of the data source must be appropriate for the type of the data set. Also ensure that the new data source provides the same data fields as the original data source.

The code sample in Listing 5‑25 shows how to check for a particular data source and data set in a report design and 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.

Call the report item’s setDataSet( ) method to set or change the data set used by a report item. If the application changes the data set used by a report item, ensure that the new data set supplies all the data bindings that the contents of the report item require. If necessary, change the references to data bindings in data elements, text elements, and scripting methods. If the data bindings in the old data set do not match the names or data types of the fields that the new data set provides, the application or a report developer must resolve the data bindings before generating a report from the modified report design.

Use the ReportItemHandle method, columnBindingsIterator( ), to iterate over the column bindings that the report item uses. The items in the list are of type ComputedColumnHandle. This class provides methods to access the name, expression, and data type of the column binding.

To access the data set column and expression that a data item uses, call the methods, getResultSetColumn( ) and getResultSetExpression( ). Then, compare the data type and name with the result-set columns that the data set returns.

The code sample in Listing 5‑26 shows how to check for a particular data set in a report design and changes the data set for a table. The code finds the table and data set by name. Alternatively, use slot handles to navigate the design structure. The variable, design, is a ReportDesignHandle object.