Rendering formatted output

To generate a formatted report, the application calls the run( ) method on an IRunAndRenderTask or the render( ) method on an IRenderTask object. The application must handle the EngineException that these methods can throw. After generating the report, the application can reuse the report engine and the task to generate further reports. If the application generates only a single report, close the task and destroy the engine after performing the report generation.

The IRunAndRenderTask.run( ) method creates a formatted document containing all the data in the report. The IRenderTask.render( ) method is more versatile. This method supports rendering the whole report or a subset of pages based on a bookmark, a page number, or a page range. A bookmark is a String that identifies a location in the report document. Use a value defined by the report developer using BIRT Report Designer or navigate the table of contents to identify the required portion of a report.

To access table of contents entries, use ITOCTree and TOCNode objects. The ITOCTree interface provides access to the tree of table of contents entries. A TOCNode object defines each table of contents entry. Each entry contains three strings: the identifier, the display value, and the bookmark of the entry. Get an ITOCTree object by calling the IRenderTask.getTOCTree( ) method. Then, use the ITOCTree.getRoot( ) method to retrieve the root TOCNode object. To find the subentries of a table of contents entry, use the TOCNode.getChildren( ) method. This method returns a List of TOCNode objects. Alternatively, call the findTOCByValue( ) method to retrieve a List of all TOCNode objects having a particular value. Use the bookmark String to locate the page to which the bookmark links by calling the getPageNumber( ) method. Using this information, the application calls the setPageNumber( ) or setPageRange( ) methods to specify pages to render to a formatted report.

The code sample in Listing 5‑13 generates a report from a report design and then closes the task. The variable, task, is an IRunAndRenderTask object. The variable, htmlRO, is an HTMLReportOption object. The variable, name, is the name of the report design. The variable, output, is the name of the output file.

task.setRenderOptions( htmlRO );

try {

task.run( );

System.out.println( "Created Report " + output + "." );

task.close( );

}

catch ( EngineException e1 ) {

System.err.println( "Report " + name + " run failed." );

System.err.println( e1.toString( ) );

}

The code sample in Listing 5‑14 generates a single page of a report from a binary report document. The sample shows two techniques to locate the page to generate. The variable, htmlRO, is an HTMLReportOption object. The variable, name, is the name of the report design. The variable, output, is the name of the output file. The variable, engine, is a ReportEngine object.

IReportDocument binaryDoc = engine.openReportDocument(output);

// Create a render task object.

IRenderTask task = engine.createRenderTask( binaryDoc );

// Get the root of the table of contents.

ITOCTree tocTree = task.getTOCTree( );

TOCNode td = tocTree.getRoot( );

// Traverse the tree of top-level items in the table of contents.

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( "157" ) ) {

// Get the number of the page that contains the data.

pNumber = binaryDoc.getPageNumber( child.getBookmark( ));

task.setPageNumber( pNumber );

}

// Alternatively, use the first entry having the correct value.

java.util.List desiredNodes = tocTree.findTOCByValue( "157" );

if ( desiredNodes != null && desiredNodes.size( ) > 0 ) {

TOCNode child = (TOCNode) desiredNodes.get(0);

pNumber = binaryDoc.getPageNumber( child.getBookmark( ) );

task.setPageNumber( pNumber );

}

// Render the page. Then, close the document and the task.

output = output.replaceFirst( ".rptdocument", ".html" );

htmlRO.setOutputFileName( output );

task.setRenderOption( htmlRO );

task.render();

binaryDoc.close();

task.close();

After generating a formatted report document as a file on disk, access the file in the same way as any other file. For example, open an HTML document in a web browser and a PDF document using Adobe Reader. If the application sends the report to a stream, the stream must be able to process the content.