Preparing to generate the report

BIRT provides output emitters for HTML, Adobe PDF, Adobe PostScript (PS), Microsoft Excel (XLS), Microsoft PowerPoint (PPT), and Microsoft Word (DOC) formats. BIRT also supports custom output formats provided by renderers developed from the rendering extension points.

Three task classes support generating a report from a source. Sections earlier in this chapter described how to open the two types of source, a report design and a report document. The following tasks support generating a report from the source:

IRunAndRenderTask. An object of this type creates a report in one of the supported formats by running a report design directly. To instantiate this object, call the ReportEngine method, createRunAndRenderTask( ).

IRunTask. An object of this type creates a report document (.rptdocument) file from a report design. To instantiate this object, call the ReportEngine method, createRunTask( ). After creating the binary format report document, create the report output using an IRenderTask object.

IRenderTask. An object of this type creates a complete report or a set of pages from a report by formatting the contents of a binary report document. To instantiate this object, call the ReportEngine method, createRenderTask( ).

Each type of task object can act on multiple sources. When the application no longer needs the task object, call the task’s close( ) method.

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 supports reading but not 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 values for all the parameters in a report design. This method takes a HashMap as an argument. To create a suitable HashMap, use the techniques shown in Listing 5‑6 or Listing 5‑7, 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 having unset values.

Some report designs require access to external Java classes. The BIRT Report Engine uses class path information from various settings in its environment to locate the external classes. BIRT supports defining some of these locations by setting properties programmatically on the application context or on the EngineConfig object, or with the Java System class. To set the properties, use constants from the org.eclipse.birt.report.engine.api.EngineConstants class. To set a property on the application context, use the EngineTask object or the EngineConfig object, as shown in the following lines of code, where MyClass is the class that starts the report engine:

To set a CLASSPATH property on the EngineConfig object, use code similar to the following lines. The property value must be a valid CLASSPATH.

To use the Java System class to set a CLASSPATH property, use code similar to the following lines. The property value must be a valid CLASSPATH.

The CLASSPATH of the parent class loader that is set as the EngineConstants.APPCONTEXT_CLASSLOADER_KEY. Define this property on the application context.

BIRT supports an application passing previously instantiated objects into the report engine. Using this technique, the engine does not have to provide the code to create the object using information external to BIRT. The calling application can manipulate the object in memory immediately before calling the report engine. A typical use of external objects is in the BIRT scripting environment. After the application passes the object to the report engine, script expressions can reference the object by name at the appropriate stage in the report generation process. To supply an object to the report engine, use the application context, accessed from either the EngineConfig object or the task object, as shown in the code in Listing 5‑9.

myConnection mc = DriverManager.getConnection( myURL );

config = new EngineConfig( );

// Get the application context from the config or the task

HashMap hm = configOrTask.getAppContext( );

hm.put( "MyConnectionObject", mc );

configOrTask.setAppContext( hm );

// To refer to this object in a BIRT script

// or expression, use MyConnectionObject.myMethod()

A binary report document contains all the information required to create a formatted report. The document contains appearance, data, and pagination information. Generate a binary report document if the same information must be rendered to multiple formats, if the output format is unknown at the time the report runs, or to render a subset of the pages in the report. Call an IRunTask.run( ) method to create a binary report document.

The code sample in Listing 5‑10 uses an IRunTask object to set the output file name. The variable, engine, is a ReportEngine object. The variable, runnable, is an object of type IReportRunnable. The variable, name, is the name of the report design. The variable, str_DateStamp, is a String representing today’s date.

// Create a run task object.

IRunTask task = engine.createRunTask( runnable );

String output = name.replaceFirst( ".rptdesign", str_DateStamp + ".rptdocument" );

try {

task.run( output );

task.close( );

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

}

catch ( EngineException e1 ) {

System.err.println( "Report " + output + " creation failed." );

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

}