Understanding the BIRT interfaces
A developer of Java event handlers needs to be familiar with several Java interfaces. Most of the handler method parameters and return values are Java interfaces rather than classes. The most important Java interfaces for developing Java event handlers are:
*For an element design, IReportElement
*For an element instance:
*IReportContext
*IColumnMetaData
*IDataSetInstance
*IDataSourceInstance
*IDataSetRow
*IRowData
Element design interfaces
Every element has a unique element design interface. The Java interface specifies methods for accessing and setting specific features of the element design. Every element design interface inherits methods from IReportElement.
Methods for each report element
As well as the methods defined in IDesignElement, each report element has methods that are relevant only for that report element. For example, ICell, the design interface for a Cell object, includes the following methods in addition to those defined in IDesignElement:
*getColumn( )
*getWidth( )
*getColumnSpan( )
*setColumn( int column )
*getDrop( )
*setColumnSpan( int span )
*getHeight( )
*setDrop( java.lang.String drop )
*getRowSpan( )
 
In contrast, the methods for ITextItem, the design interface for a text element, includes these additional methods:
*getContent( )
*setContent( java.lang.String value )
*getContentKey( )
*setContentKey( java.lang.String resourceKey )
*getContentType( )
*setContentType( java.lang.String contentType )
*getDisplayContent( )
 
IReportElement interface
The IReportElement interface is the base interface for all the report element interfaces. IReportElement has the following methods:
*getComments( )
*getUserProperty( java.lang.String name )
*getCustomXml( )
*setComments( java.lang.String theComments )
*getDisplayName( )
*setCustomXml( java.lang.String customXml )
*getDisplayNameKey( )
*setDisplayName( java.lang.String displayName )
*getName( )
*setDisplayNameKey( java.lang.String displayNameKey )
*getNamedExpression( java.lang.String name )
*setName( java.lang.String name )
*getParent( )
*setNamedExpression( java.lang.String name, java.lang.String exp )
*getQualifiedName( )
*setUserProperty( java.lang.String name, java.lang.Object value )
*getStyle( )
 
Element instance interfaces
The element instance interfaces are available at run time, but not at design time. These interfaces provide access to the run-time instance of the element. Both onCreate( ), the generation phase event handler, and onRender( ), the presentation phase event handler, receive the element instance interface as an argument. Through instance interfaces, you have access to a different set of properties than you do at design time.
There is no superinterface from which all element instance interfaces inherit. Like the element design interface, the set of methods in the instance interfaces vary from element type to element type. For example, ICellInstance, the Cell instance interface, has the following methods:
*getColSpan( )
*setColSpan( int colSpan )
*getColumn( )
*setRowSpan( int rowSpan )
*getRowSpan( )
 
By comparison, IRowInstance, the Row instance interface, has these methods:
*getBookmarkValue( )
*setBookmark( )
*getHeight( )
*setHeight( )
*getStyle( )
 
IReportContext interface
All event handlers except those for ScriptedDataSource and ScriptedDataSet objects use an object of type IReportContext.Event handlers can share data by using the setPersistentGlobalVariable( ) method on reportContext. The IReportContext interface includes the methods shown in Table 38‑7.
Table 38‑7 IReportContext interface methods
Method
Task
deleteGlobalVariable( java.lang.String name )
Removes a global variable created using the setGlobalVariable( ) method.
deletePersistentGlobalVariable( java.lang.String name )
Removes a persistent global variable created using the setPersistentGlobalVariable( ) method.
getAppContext( )
Retrieves the application context object as a java.util.Map object. The report application can use the application context object to pass any information that is application‑specific.
getGlobalVariable( java.lang.String name )
Returns the object saved with the setGlobalVariable( ) method. The string argument is the key used when saving the object.
getHttpServletRequest( )
Returns the HttpServletRequest object associated with the URL requesting the report. The HttpServletRequest object provides access to the HTTP session object, the request URL, and any parameters appended to the request.
getLocale( )
Returns the locale of the report execution or rendering task. This locale can be different from the local machine’s system or user locale.
getMessage( java.lang.String key )
Returns a message from the default properties file.
getMessage( java.lang.String key, java.util.Locale locale, java.lang.Object [ ] params )
Returns a message from the properties file for a specified locale, using a parameters array.
getMessage( java.lang.String key, java.lang.Object[ ] params )
Returns a message from the default properties file, using a parameters array.
getOutputFormat( )
Returns a string containing the format specified in the _ _format parameter of the request URL.
getParameterValue( java.lang.String name )
Returns the value of the parameter named in the name argument as a java.lang.Object.
getPersistentGlobalVariable( java.lang.String name )
Returns the serializable object saved using setPersistentGlobalVariable( ) method. The string argument is the key used when saving the serializable object.
getRenderOption( )
Gets the render options used to render the report.
getReportRunnable( )
Gets the report runnable instance used to create or render this report.
getTaskType()
Gets the type of the current task.
setGlobalVariable( java.lang.String name,java.lang.Object obj )
Saves an object that can be retrieved in the same execution phase as it is saved. This method takes a string argument and an Object argument. Use the string argument as a key with which to retrieve the saved object.
setParameterDisplayText( java.lang.String name, java.lang.Object value )
Sets the display text for a parameter.
setParameterValue( java.lang.String name,java.lang.Object value )
Sets the value of a named parameter with the value contained in the value argument.
setPersistentGlobalVariable( java.lang.String name,java.io.Serializable obj )
Saves an object that can be retrieved in a different execution phase from the phase that saves the object. This method takes a string argument and a serializable object argument. Use the string argument as a key with which to retrieve the serializable object. The serializable object is saved in the report document. The object is serializable to persist it between phases supporting executing the two phases at different times and possibly on different machines.
IColumnMetaData interface
The IColumnMetaData interface provides information about the columns of the data set. Table 38‑8 lists the methods in the IColumnMetaData interface.
Table 38‑8 IColumnMetaData interface methods
Method
Returns
getColumnAlias( int index )
Alias assigned to the column by index
getColumnCount( )
Count of columns in the data set
getColumnLabel( int index )
Label assigned to the column by index
getColumnName( int index )
String containing the name of the column by index
getColumnNativeTypeName( int index )
Name of the native type of data in the column by index
getColumnType( int index )
Data type of the column by index
getColumnTypeName( int index )
Name of the type of data in the column by index
isComputedColumn( int index )
True or false, depending on whether the column indicated by index is a computed field
IDataSetInstance interface
The IDataSetInstance interface provides access to many aspects of the data set and associated elements. Every DataSet event handler method receives an IDataSetInstance object as an argument. Table 38‑9 describes the methods in the interface IDataSetInstance.
Table 38‑9 IDataSetInstance interface methods
Method
Returns
getAllExtensionProperties( )
The data set extension properties in the form of a java.util.Map object. The map object maps data extension names to their values.
getColumnMetaData( )
An IColumnMetaData object that provides the data set’s metadata.
getDataSource( )
A DataSource object associated with the data set.
getExtensionID( )
The unique ID that identifies the type of the data set, assigned by the extension that implements this data set.
getExtensionProperty( java.lang.String name )
The value of a data set extension property.
getName( )
The name of this data set.
getQueryText( )
The query text of the data set.
setExtensionProperty( java.lang.String name, java.lang.String value )
The value of an extension property.
setQueryText( java.lang.String queryText )
The query text of the data set.
IDataSetRow interface
An object of the IDataSetRow type passes to the DataSet.onfetch( ) event handler method. IDataSetRow has two getColumnValue( ) methods, which differ in the argument specifying the column containing the value. They both return a java.lang.Object object, which you must cast to the appropriate type for the column. Table 38‑10 lists the methods in the IDataSetRow interface.
Table 38‑10 IDataSetRow interface methods
Method
Returns
getColumnValue( int index )
The column data by index. This index is 1-based.
getColumnValue( java.lang.String name )
The column data by column name.
getDataSet( )
An IDataSetInstance object representing the data set that contains this row.
IRowData interface
The getRowData( ) method of IReportElementInstance, which every report element instance interface extends, returns an object of the IRowData type. IRowData provides access to the bound values t in the table or list. IRowData has two getColumnValue( ) methods, which differ in the argument specifying the required column. Both methods return the display value for a specific column in the table. Table 38‑11 lists the methods in the IRowData interface.
Table 38‑11 RowData interface methods
Method
Returns
getColumnCount( )
The count of the columns.
getColumnName( int index )
The name of the column by index.
getColumnValue( int index )
The value of the column by index. This index is 1‑based.
getColumnValue( String name )
The value of the column by name.