The engine home directory has a subdirectory, plugins, that contains the org.eclipse.birt and other plug-ins that a reporting application can use. Depending on the requirements of your reporting application and the items in your report designs, you can omit plug-ins that provide functionality that the application and designs do not use.

The lib subdirectory of the engine home directory contains the JAR files described in Table 13-1. This location within the report engine ensures that the class loader of the application server in which you deploy the report engine can locate the libraries. To support generation of reports in PDF format, the library itext-1.3.jar must exist in the lib subdirectory of the report.engine.emitter.pdf plug-in.

Depending on the requirements of your reporting application and the items in your report designs, you can omit libraries that provide functionality that the application and designs do not use.

The engine home plugins/org.eclipse.birt.report.data.oda.jdbc_<version> subdirectory contains a subdirectory, drivers. Place the driver classes or Java archive (.jar) files that you require to access JDBC data sources in this location.

The engine home is the key property that the report engine requires. The report engine cannot parse the report design nor run the report without a defined engine home.

For a stand-alone application, the engine home is an absolute path to a file system location. For an application running from a web archive (.war) file on an application server, the engine home is a relative path in the WAR file.

To set the engine home location, you use one of the following techniques:

Optionally, you can also set other configuration properties using methods on an EngineConfig object. Table 13-2 describes these properties and how to set them with EngineConfig methods. The EngineConfig class also provides getter methods to access these properties. Sections later in this chapter provide examples of setting engine configuration properties and how an application uses them.

Two engine configuration properties depend on whether the environment in which the application runs is stand-alone or in a web archive (.war) file in an application server. These properties are the platform context and the HTML emitter configuration. The platform context provides the report engine with the mechanism to access files. The HTML emitter configuration provides the functionality to process images and handle hyperlinking and bookmark actions.

// Instantiate an engine configuration object.
EngineConfig config = new EngineConfig( );
// Set the relative path of the engine home in the WAR file.
config.setEngineHome( "" );
// Create the platform context as a hard-coded string.
// Alternatively, use HTTPServletRequest methods to retrieve
// the context dynamically.
// In this code, servletContext is a ServletContext object.
IPlatformContext context = new PlatformServletContext
   ( servletContext, "http://localhost:8080/MarketApp" );
// Set the engine context in the configuration object.
config.setEngineContext( context );

// Create an EngineConfig object.
EngineConfig config = new EngineConfig( );
// Set up the path to your engine home directory.
config.setEngineHome
   ( "C:/Program Files/birt-runtime-2_1_0/ReportEngine" );
// Explicitly set up the stand-alone application
IPlatformContext context = new PlatformFileContext( );
config.setEngineContext( context );
// Set up writing images or charts embedded in HTML output.
HTMLCompleteImageHandler imageHandler =
   new HTMLCompleteImageHandler( );
HTMLEmitterConfig hc = new HTMLEmitterConfig( );
hc.setImageHandler( imageHandler );
config.setEmitterConfiguration
   ( RenderOptionBase.OUTPUT_FORMAT_HTML, hc );
// Create the engine.
ReportEngine engine = new ReportEngine( config );

BIRT Report Engine uses the java.util.logging classes, Logger and Level, to log information about the processing that the engine performs. When you run an application in the Eclipse workbench, by default, the messages appear in the console. When you run an application external to Eclipse, the default location of the log messages depends on your environment. The default logging threshold is Level.INFO. Typically, you change this level in your application to reduce the number of internal logging messages.

To set up the logging environment to write the engine’s log messages to a file on disk, use the EngineConfig.setLogConfig( ) method. This method takes two arguments, the directory in which to create the log file and the lowest level at which to log information. BIRT Report Engine creates a log file with a name whose format is ReportEngine_YYYY_MM_DD_hh_mm_ss.log. Set the logging level to a high threshold so that the engine logs a reduced number of messages.

Typically, you want to see information at INFO level when you first develop a block of code. To modify the amount of information that the engine logs, use the ReportEngine.changeLogLevel( ) method. This method takes a single argument, which is a Level constant. When the code is stable, you no longer need to see all the engine’s INFO messages. At that point, you can delete or comment out the call to changeLogLevel( ).

The IReportRunnable object provides direct access to basic properties of the report design. The names of report design properties are static String fields, such as IReportRunnable.AUTHOR. To access a report design property, use the getProperty( ) method with a String argument that contains one of these fields.

To access and set the values of parameters, you use methods on a parameter definition task object, described later in this chapter. To generate a report from a design, open the report design as shown in the following example, then perform the tasks shown later in this chapter.

String designName = "./SimpleReport.rptdesign";
IReportRunnable runnable = null;
try {
  runnable = engine.openReportDesign( designName );
}
catch ( EngineException e )
{
  System.err.println
     ( "Design " + designName + " not found!" );
  engine.shutdown( );
  System.exit( -1 );
}
// Get the value of a simple property.
String author = ( String ) runnable.getProperty
   ( IReportRunnable.AUTHOR );

The IReportDocument object provides access to the data in a report and the report’s structure. IReportDocument provides methods to retrieve table of contents entries, bookmarks, and page information.

To access table of contents entries, use the findTOC( ) method. This method takes a TOCNode argument and returns a TOCNode object. To find the root table of contents entry, use an argument of null. To find the subentries of a table of contents entry, use the getChildren( ) method. This method returns a List of TOCNode objects. From a TOCNode object, you can retrieve the display value of the entry and a Bookmark object.

In turn, you can use the Bookmark object as an argument to the getPageNumber( ) method, which returns the number of the page to which the bookmark links. With this information, you can specify particular pages to render to a formatted report.

How to access a report document

Listing 13-4 shows how to open a report document and navigate its table of contents to find a page. If the engine cannot open the specified report design, the code shuts down the engine. The variable, engine, is a ReportEngine object.

String dName = "./SimpleReport.rptdocument";
IReportDocument doc = null;
try { doc = engine.openReportDocument( dName );
} catch ( EngineException e ) {
   System.err.println( "Document " + dName + " not found!" );
   engine.shutdown( );
   System.exit( -1 );
}
// Get the root of the table of contents.
TOCNode td = doc.findTOC( null );
java.util.List children = td.getChildren( );
long pNumber;
// Loop through the top level table of contents entries.
if ( children != null && children.size( ) > 0 ) {
  for ( int i = 0; i < children.size( ); i++ ) {
     // Find the required table of contents entry.
     TOCNode child = ( TOCNode ) children.get( i );
     if ( child.getDisplayString( ).equals( "103" ) ) {
        // Get the number of the page that contains the data.
        pNumber = doc.getPageNumber( child.getBookmark( ) );
        System.out.println( "Page to print is " + pNumber );
     }
  }
}

A single IGetParameterDefinitionTask object provides access to all parameters in a report design. Create only one of these objects for each report design, by using the ReportEngine.createGetParameterDefinitionTask( ) method.

To test if a report design has report parameters, call the getParameterDefns( ) method on IGetParameterDefinitionTask. This method returns a Collection. To test whether the Collection has elements call the Collection.isEmpty( ) method. If the application runs only known report designs, you do not need to perform this task.

To access a single report parameter with a known name, use the IGetParameterDefinitionTask.getParameterDefn( ) method. This method returns an object of type IParameterDefnBase. Alternatively, use the IGetParameterDefinitionTask.getParameterDefns( ) method to return a Collection of IParameterDefnBase objects. The application can then use an Iterator to access each report parameter from this Collection in turn.

The getParameterDefns( ) method takes a Boolean argument. When the argument is false, the method returns an ungrouped set of report parameters. When the argument is true, the method returns parameter groups, as defined in the report design. To create a user interface that replicates the parameter group structure, use a value of true.

To check whether a report parameter is a group, the application must call IParameterDefnBase.getParameterType( ). This method returns IParameterDefnBase.PARAMETER_GROUP when the parameter is a group or IParameterDefnBase.CASCADING_PARAMETER_GROUP when the parameter is a cascading parameter group.

To access the group’s report parameters, use the IParameterGroupDefn.getContents( ) method. This method returns an ArrayList object that contains objects of type IScalarParameterDefn.

This task is optional. To get the default value of a single known report parameter, use IGetParameterDefinitionTask.getDefaultValue( ). This method returns an Object. To determine the effective class of the Object, use IScalarParameterDefn.getDataType( ). This method returns an int value, which is one of the static fields in IScalarParameterDefn.

To get the default value of all parameters in the report design, use IGetParameterDefinitionTask.getDefaultValues( ). This method returns a HashMap object, which maps the report parameter names and their default values.

Some report parameters accept only values from a restricted list. In some cases, this list is a static list of values, such as RED, BLUE, or GREEN. In other cases, the list is dynamic and a query to a database provides the valid values. For example, a query can return the set of sales regions in a sales tracking database.

To determine the list of valid values, call the IGetParameterDefinitionTask.getSelectionList( ) method. This method returns a Collection of IParameterSelectionChoice objects. IParameterSelectionChoice has two methods.getLabel( ) returns the display text and getValue( ) returns the value. If the Collection is null, the report parameter can take any value.

This task is optional. To get the attributes of a report parameter, use the IScalarParameterDefn methods. The application can use the attributes to generate a customized user interface. For example, to get the data type of a report parameter, use the getDataType( ) method.

To provide new values for the report parameters, provide application logic such as a user interface or code to retrieve values from a database. To set the value of the parameter, call IGetParameterDefinitionTask.setParameterValue( ).

If you provide a user interface that returns String values to your application for date and number parameters, you must convert the String into a locale-independent format before setting the value. To perform this task, first call ReportParameterConverter.parse( ) to set the value to a locale-independent format. Next, call IGetParameterDefinitionTask.setParameterValue( ).

After setting the report parameter values, call the IGetParameterDefinitionTask.getParameterValues( ) method. This method returns a HashMap object that contains values that calls to IGetParameterDefinitionTask.setParameterValue( ) set. You can later use this HashMap object to set the report parameter values for report generation, as described later in this chapter.

// Create a parameter definition task.
IGetParameterDefinitionTask task =
   engine.createGetParameterDefinitionTask( runnable );
// Instantiate a scalar parameter.
IScalarParameterDefn param = (IScalarParameterDefn)
   task.getParameterDefn( "customerID" );
// Get the default value of the parameter.
// The code assumes that the data type of the parameter,
// customerID, is Double.
int customerID =
   ((Double) task.getDefaultValue( param )).intValue( );

// Get a value for the parameter. This example does not
// provide the code for this task. This example assumes that
// this step creates a correctly typed object, inputValue.

// Set the value of the parameter.
task.setParameterValue( "customerID", inputValue );
// Get the values set by the application for all parameters.
HashMap parameterValues = task.getParameterValues( );

A cascading parameter group uses a query to retrieve values from a database. The parameter definition task filters the values for each parameter in the group, based on the values of preceding parameters in the group. For example, consider a cascading parameter group that uses the following query.

SELECT
   PRODUCTS.PRODUCTLINE,
   PRODUCTS.PRODUCTNAME,
   PRODUCTS.PRODUCTCODE
FROM CLASSICMODELS.PRODUCTS

// Create a parameter definition task.
IGetParameterDefinitionTask task =
   engine.createGetParameterDefinitionTask( runnable );
// Create a collection of the parameters in the report design.
// This example does not use the parameter grouping.
Collection params = task.getParameterDefns( false );
// Get the default values of the parameters.
HashMap parameterValues = task.getDefaultValues( );

// Get values for the parameters. This example does not
// provide the code for this task. Later code in this example
// assumes that this step creates a HashMap object,
// inputValues. The keys in the HashMap are the parameter
// names and the values are those that the user provided.

// Iterate through the report parameters, setting the values
// to use for generating the report. Ensure that the values
// are in standard locale-independent format.
Iterator iterOuter = params.iterator( );
while ( iterOuter.hasNext( ) )
{
   IParameterDefnBase param =
     (IParameterDefnBase) iterOuter.next( );
   String pname = param.getName( );
   String value = (String) inputValues.get( pname );
   if ( value != null )
   {
     ReportParameterConverter cfgConverter = new
        ReportParameterConverter( "", Locale.getDefault() );
     Object obj =
       cfgConverter.parse( value, param.getDataType( ) );
     parameterValues.put( pname, obj );
   }
}

The group contains two parameters, ProductLine on PRODUCTS.PRODUCTLINE and ProductCode on PRODUCTS.PRODUCTCODE. The display text for ProductCode is PRODUCTS.PRODUCTNAME. Figure 13-1 shows the appearance of the requester that prompts for values for these parameters when you preview the report in BIRT Report Designer.

Figure 13-1. Cascading report parameters

To use the report engine API to get the values for cascading parameters, perform the tasks in the following list. Figure 13-1 shows an example of performing these tasks.

// Create a grouped collection of the design’s parameters.
Collection params = task.getParameterDefns( true );
// Iterate through the parameters to find the cascading group.
Iterator iter = params.iterator( );
while ( iter.hasNext( ) ) {
   IParameterDefnBase param = (IParameterDefnBase)
   iter.next();
   if ( param.getParameterType() ==
     IParameterDefnBase.CASCADING_PARAMETER_GROUP ) {
     ICascadingParameterGroup group =
        (ICascadingParameterGroup) param;
     Iterator i2 = group.getContents( ).iterator( );
       // Run the query for the cascading parameters.
       task.evaluateQuery( group.getName() );
       Object[] userValues =
          new Object[group.getContents( ).size( )];
       // Get the report parameters in the cascading group.
       int i = 0;
       while ( i2.hasNext( ) ) {
          IScalarParameterDefn member =
             (IScalarParameterDefn) i2.next( );
          // Get the values for the parameter.
          Object[] setValues = new Object[i];
          if ( i > 0 )
             System.arraycopy( userValues, 0, setValues, 0, i );
          Collection c =
             task.getSelectionListForCascadingGroup
                ( group.getName(), setValues );
          // Iterate through the values for the parameter.
          Iterator i3 = c.iterator();
          while ( i3.hasNext( ) ) {
             IParameterSelectionChoice s =
                ( IParameterSelectionChoice ) i3.next( );
             String choiceValue = s.getValue( );
             String choiceLabel = s.getLabel( );
          }
// Get the value for the parameter from the list of choices.
// This example does not provide the code for this task.
        userValues[i] = inputChoiceValue;
        i++;
     }
  }

To set the values for parameters for generating a report, use methods on an IRunAndRenderTask or an IRunTask object. These tasks run a report design to generate output. IRenderTask does not support changing the parameters for a report because its source is a report document. The IRunTask object that created the report document already specified the parameter values.

Call setParameterValues( ) to set the values for all the parameters. This method takes a HashMap as an argument. To create a suitable HashMap, perform the tasks described in “Accessing a report parameter programmatically,” earlier in this chapter.

To set the value for a single parameter when generating a report, call the setParameterValue( ) method. When the task generates the report or the report document, it uses the default values for any parameters that were not set by either of these methods.

Before generating a report to either HTML or PDF, the application must set options that determine features of the output. The options must specify either an output file name or a stream. Other configuration options, such as setting whether to create embeddable HTML, are optional. BIRT supports two types of HTML output, HTML and embeddable HTML. Embeddable HTML is suitable for including inside another web page. This format contains no header information nor the <html> tag.

The application uses a rendering options object to set the output options on an IRunAndRenderTask or an IRenderTask object. The format-specific rendering options classes implement IRenderOption and extend RenderOptionBase. The rendering options class supporting the HTML format is HTMLRenderOption. There are no format-specific options for PDF output. To set options for PDF output, use the RenderOptionBase class.

Before generating a report, the application must provide context settings to the rendering task. Use the setAppContext( ) method on an IRenderTask or an IRunAndRenderTask object. This method performs no function on an IRunTask object because this task does not render to an output format.

To set up the context for HTML rendering, use an HTMLRenderContext object. To set up the context for PDF rendering, use a PDFRenderContext object. To apply a context setting, use setter methods on the rendering context object. These classes also have getter methods that retrieve context settings.

Both HTML and PDF rendering contexts support a base URL for an action handler and a list of the image formats that the output format accepts, as shown in the following list. The output format of the report defines which other context settings are available.

After creating the rendering context object, call the task’s setContext( ) method. This method takes a HashMap object as an argument. The key to the hash-map entry is one of the constants APPCONTEXT_HTML_RENDER_CONTEXT or APPCONTEXT_PDF_RENDER_CONTEXT in the EngineConstants class. The value of the entry is the rendering context object. Listing 13-8 includes code that sets the rendering context for HTML.

Before generating an HTML report that uses images on disk or creates images or charts in a report, the application must provide additional context settings. The HTMLRenderContext class provides the following settings:

Before generating a PDF report that uses fonts from non-standard locations or needs to embed fonts in a report, the application must provide additional context settings. The PDFRenderContext class provides the following settings:

// Create a run and render task object.
IRunAndRenderTask task =
   engine.createRunAndRenderTask( runnable );
// Set values for all parameters in a HashMap, parameterValues
task.setParameterValues( parameterValues );
// Validate parameter values.
boolean parametersAreGood = task.validateParameters( );
// Set the name of an output file.
HTMLRenderOption options = new HTMLRenderOption( );
String output = name.replaceFirst( ".rptdesign", ".html" );
options.setOutputFileName( output );
// Apply the rendering options to the task.
task.setRenderOption( options );
// Instantiate an HTML rendering context object and
// set the name of the directory for images.
HTMLRenderContext renderContext = new HTMLRenderContext();
renderContext.setImageDirectory("image");
// Apply the rendering context to the task.
HashMap appContext = new HashMap( );
appContext.put
  ( EngineConstants.APPCONTEXT_HTML_RENDER_CONTEXT,
  renderContext );
task.setAppContext( appContext );

In many application server environments, web applications have access to a pool of Connection objects. In order to use an external connection from such a pool for the data source in a report design, you must pass information to the data driver plug-in that the report design uses. You pass the information in the rendering context HashMap object. For example, the code in Listing 13-9 sets up the connection to a custom driver, mydatapluginname. The variable task is an IRunAndRenderTask object or an IRunTask object.

The standard data drivers in BIRT do not support using an external connection. You must extend the drivers to perform this task. Later chapters in this book explain this process.

HashMap contextMap = new HashMap( );
HTMLRenderContext renderContext = new HTMLRenderContext();
contextMap.put
   ( EngineConstants.APPCONTEXT_HTML_RENDER_CONTEXT,
   renderContext );
// Get a connection from the pool
Connection myConnection = getConnectionFromPool( );
contextMap.put( "org.eclipse.birt.mydatapluginname",
   myConnection );
task.setContext( contextMap );

The DesignEngine class provides access to all the functionality of the Report Object Model (ROM) in the same way that the ReportEngine class provides access to report generation functionality. To create a DesignEngine object, you first 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. Instantiate a DesignEngine object with the DesignConfig object as an argument to the constructor.

Create the SessionHandle object by calling the method, newSessionHandle( ) on the DesignHandle 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 object.

You can also open a report design from an IReportRunnable object by using the getDesignHandle( ) method. The ReportDesignHandle object provides access to the design opened by the report engine. Changes to the report design do not affect the IReportRunnable object. To generate a report from the changed report design, you must reopen the design as an IReportRunnable object.

How to open a report design for editing

The code sample in Listing 13-11 creates a DesignEngine object, which it uses to create a SessionHandle object. The code then uses the SessionHandle object to open a report design.

// Create a design engine configuration object.
DesignConfig dConfig = new DesignConfig( );
DesignEngine dEngine = new DesignEngine( dConfig );
// Create a session handle, using the system locale.
SessionHandle session = dEngine.newSessionHandle( null );
// Create a handle for an existing report design.
String name = "./SimpleReport.rptdesign";
ReportDesignHandle design = null;
try {
   design = session.openDesign( name );
} catch (Exception e) {
   System.err.println
      ( "Report " + name + " not opened!
Reason is " +
      e.toString( ) );
   return null;
}

To make a report item accessible by name, the item must have a name. A report developer can set the name in BIRT Report Designer or programmatically by using the item’s setName( ) method. To find a report item by name, use the findElement( ) method. This method returns a DesignElementHandle object. All report items derive from this class.

To access a report item through the report design’s structure, the application first gets the slot handle of the report body by calling the getBody( ) method. This slot handle holds the top-level report items in the report design. For example, consider a simple report structure that has three top-level items: a grid containing header information, a table containing data, and a label that displays a report footer. Figure 13-2 shows its outline view in BIRT Report Designer.

Figure 13-2. Slots in a report design

To access the top-level items in this report design, you iterate over the contents of the body slot handle. These contents all derive from DesignElementHandle. To access the iterator for a slot handle, call SlotHandle.iterator( ). Each call to Iterator.getNext( ) returns a report item. Alternatively, to access a report item at a known slot index, call SlotHandle.get( ). The slot index number is zero-based. The ReportDesignHandle class also provides finder methods, which can access an item or other report element by name.

To examine a report item, check the class of the report item, cast the object to its actual class, then call methods appropriate to that class. For example, the class of a label element handle is LabelHandle. To get the text that the label displays, call LabelHandle.getText( ).

Some report items, such as a label or a text element, are simple items. Other items, such as a grid or a table element, are structured items. You can access properties for the whole of a structured item in the same way as for a simple item.

You can also iterate over the contents of the structured item. For example, use this technique to determine the contents of a cell in a table. To access the contents of a structured item, you call a method to retrieve the slot handle for rows or columns. For example, to access the RowHandle objects that make up a table element’s footer, call TableHandle.getFooter( ). Table and list elements also have a slot for groups. Like the body slot handle, the slot handles for the contents of structured report items can contain zero, one, or multiple elements.

To provide information about report items, each class has getter methods specific to the report item type. For example, an image element handle, ImageHandle, has the getURI( ) method. This method returns the URI of an image referenced by URL or file path. The DesignElementHandle class and other ancestor classes in the hierarchy also provide generic getter methods, such as getName( ).

Some properties of a report item are simple properties, with types that are Java types or type wrapper classes. An example of this type of property is the name property, which is a String object. Some of these properties, like name, have arbitrary values.

Other simple properties have restricted values from a set of BIRT String constants. The interface, DesignChoiceConstants in the org.eclipse.birt.report.model.api.elements package, defines these constants. For example, the image source property of an image element can have only one of the values, IMAGE_REF_TYPE_EMBED, IMAGE_REF_TYPE_EXPR, IMAGE_REF_TYPE_FILE, IMAGE_REF_TYPE_NONE, or IMAGE_REF_TYPE_URL.

Other properties are complex properties and the getter method returns a handle object. For example, the DesignElementHandle.getStyle( ) method returns a StyleHandle object and ReportItemHandle.getWidth( ) returns a DimensionHandle object.

The handle classes provide access to complex properties of a report item, as described later in this chapter. These classes provide getter methods for related properties. For example, StyleHandle classes provide access to font and background color.

How to access a report item by name

The code sample in Listing 13-12 finds an image item by name, checks its type, then examines its URI. The variable, design, is a ReportDesignHandle object.

DesignElementHandle logoImage =
   design.findElement( "Company Logo" );
// Check for the existence of the report item.
if ( logoImage == null) {
   return null;
}
// Check that the report item has the expected class.
if ( !( logoImage instanceof ImageHandle ) ) {
  return null;
}
// Retrieve the URI of the image.
String imageURI = ( (ImageHandle ) logoImage ).getURI( );
return imageURI;

How to use the report structure to access a report item

The code sample in Listing 13-13 finds an image item in a grid, checks its type, then examines its URI. Use this technique for generic code to navigate a report design structure or if you need to find an item that does not have a name. The variable, design, is a ReportDesignHandle object.

To set the simple properties of report items, each class has setter methods specific to the report item type. For example, an image element handle, ImageHandle, has the setURI( ) method. This method sets the URI of an image referenced by URL or file path. The DesignElementHandle class and other ancestor classes in the hierarchy also provide generic setter methods, such as setName( ). Setter methods throw exceptions, such as NameException, SemanticException, and StyleException.

To set attributes of a complex property, such as a style, you must call methods on a handle object, as described later in this chapter. These classes provide setter methods for related properties. For example, StyleHandle classes provide access to style properties, such as font and background color.

// Instantiate a slot handle and iterator for the body slot.
SlotHandle shBody = design.getBody();
Iterator slotIterator = shBody.iterator()
// To retrieve top-level report items, iterate over the body.
while (slotIterator.hasNext()) {
  Object shContents = slotIterator.next();
  // To get the contents of the top-level report items,
  // instantiate slot handles.
  if (shContents instanceof GridHandle) {
    GridHandle grid = ( GridHandle ) shContents;
    SlotHandle grRows = grid.getRows( );
    Iterator rowIterator = grRows.iterator( );
    while (rowIterator.hasNext()) {
       // Get RowHandle objects.
       Object rowSlotContents = rowIterator.next();
       // To find the image element, iterate over the grid.
       SlotHandle cellSlot =
          ( ( RowHandle ) rowSlotContents ).getCells( );
       Iterator cellIterator = cellSlot.iterator( );
       while ( cellIterator.hasNext( ) ) {
          // Get a CellHandle object.
         Object cellSlotContents = cellIterator.next( );
         SlotHandle cellContentSlot =
            ((CellHandle) cellSlotContents).getContent( );
         Iterator cellContentIterator =
            cellContentSlot.iterator( );
         while (cellContentIterator.hasNext( )) {
            // Get a DesignElementHandle object.
            Object cellContents =
               cellContentIterator.next( );
               // Check that the element is an image.
               if (cellContents instanceof ImageHandle) {
                  String imageSource = ( ( ImageHandle )
                     cellContents ).getSource( );
                  // Check that the image has a URI.
                  if ((imageSource.equals( IMAGE_REF_TYPE_URL ))
                  || (imageSource.equals(IMAGE_REF_TYPE_FILE))){
                     // Retrieve the URI of the image.
                     String imageURI = ( ( ImageHandle )
                        cellContents ).getURI( );
                  }
               }
            }
         }
      }
   }
}

Changes that you make to items in the report design do not affect the design file until you save the design to disk or to a stream. After saving the design, get an IReportRunnable handle for the modified design in order to generate a report.

How to change a simple property of a report item

The code sample in Listing 13-14 uses a method on LabelHandle to change the text in 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.

// Access the label by name.
LabelHandle headerLabel =
   ( LabelHandle ) design.findElement( "Header Label" );
try {
   headerLabel.setText( "Updated " + headerLabel.getText( ) );
} catch ( Exception e ) {
   // Handle the exception
}

Complex properties use BIRT handle objects to access data structures. For example, a DimensionHandle object provides access to size and position properties, such as the absolute value and the units of the width of a report item.

Some String properties on a handle object, such as font style and text alignment on a style handle, have restricted values defined by constants in the interface, DesignChoiceConstants in the org.eclipse.birt.report.model.api.elements package. For example, the font style property can have only one of the values, FONT_STYLE_ITALIC, FONT_STYLE_NORMAL, and FONT_STYLE_OBLIQUE.

// Access the label by name.
LabelHandle headerLabel =
   ( LabelHandle ) design.findElement( "Header Label" );
try {
   // To prepare to change a style property, get a
   StyleHandle.
   StyleHandle labelStyle = headerLabel.getPrivateStyle();
   // Update the background color.
   ColorHandle bgColor = labelStyle.getBackgroundColor();
   bgColor.setRGB( 0xFF8888 );
} catch ( Exception e ) {
   // Handle any exception
}

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 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, within 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 the 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 chapter.

How to add a grid item and label item to a report design

The code sample in Listing 13-16 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.

// Instantiate an element factory.
ElementFactory factory = design.getElementFactory( );
try {
   // Create a grid element with 2 columns and 1 row.
   GridHandle grid = factory.newGridItem( "New grid", 2, 1 );
   // Set a simple property on the grid, the width.
   grid.setWidth( "50%" );
   // Create a new label and set its properties.
   LabelHandle label = factory.newLabel( "Hello Label" );
   label.setText( "Hello, world!" );
   // Get the first row of the grid.
   RowHandle row = ( RowHandle ) grid.getRows( ).get( 0 );
   // Add the label to the second cell in the row.
   CellHandle cell = ( CellHandle ) row.getCells( ).get( 1 );
   cell.getContent( ).add( label );
   // Get the Body slot. Add the grid to the end of the slot.
   design.getBody( ).add( grid );
} catch ( Exception e ) {
   // Handle any exception
}

DataSourceHandle is a subclass of ReportElementHandle. 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 Open Data Access (ODA) 3.0.0 API Reference. 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. 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.

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 for North America.

// Find the data set by name.
DataSetHandle ds = design.findDataSet( "Customers" );
// Find the data source by name.
DataSourceHandle dso = design.findDataSource( "EuropeSales" );
// Check for the existence of the data set and data source.
if (dso == null) || ( ds == null )
{
  System.err.println( "EuropeSales or Customers not found" );
  return;
}
// Change the data source of the data set.
try
{
   ds.setDataSource( dso );
} catch ( SemanticException e1 ) {
   e1.printStackTrace( );
}

// Find the table by name.
TableHandle table =
   ( TableHandle ) design.findElement( "Report Data" );
// Find the data set by name.
DataSetHandle ds = design.findDataSet( "EuropeanCustomers" );
// Check for the existence of the table and the data set.
if (table == null) || ( ds == null ) {
   System.err.println( "Incorrect report structure" );
   return;
}
// Change the data set for the table.
try {
   table.setDataSet( ds );
} catch (Exception e) {
   System.err.println( "Could not set data set for table" );
}