When writing event handlers, understanding the event order is imperative. The order in which events fire depends on several factors. These factors include which BIRT processing phase is executing, the engine task executing the process, and what event type is processing.

The scripting chapters make continuous reference to engine task processes. This section provides an overview of what these processes are and how they affect scripting.

The report engine that executes reports is task-oriented and provides three tasks related to the execution and rendering of reports. These tasks are RunAndRenderTask, RunTask, and RenderTask.

The RunAndRenderTask uses one process to open the report design and produce a specific output, such as PDF. The RunTask opens a report design and executes the report producing a report document file with a .rptdocument extension. This report document is an intermediate binary file that can then be used by a RenderTask to produce a report output type, such as HTML, PDF, PPT, PS, Word, or XLS. The RenderTask opens a report document (.rptdocument) and renders the appropriate output format. This task can be executed any time after a RunTask. This task can even occur on a separate system.

BIRT Report Designer uses the report engine to show a preview of a report. Selecting Preview in the Editor launches a RunAndRenderTask to produce the report. Selecting any other previewing option in BIRT Report Designer toolbar launches a RunAndRenderTask to produce the output, with the exception of the Run report in BIRT Web Viewer, which produces the report using a RunTask followed by a RenderTask.

The tasks RunTask and RenderTask can be used when the tasks need to occur at separate times or on separate systems. Using separate run and render tasks therefore requires two processes to run and render a report to a particular output format.

When RunAndRenderTask processes a report, the event firing order is different from the RunTask and RenderTask are used as two separate processes. The differences in processing are discussed throughout these chapters.

The following sections describe how the report engine processes reports in the BIRT Report Designer environment.

The example BIRT Web Viewer application is a J2EE application that encapsulates the report engine to produce reports. This viewer contains three Servlet mappings used to generate reports. These are the frameset, run, and preview mappings.

In the example web viewer, two processes, RunTask and RenderTask, generate content and render to the requested output format to create a report document. Selecting the Export report icon in the web viewer toolbar initiates an additional RenderTask to execute on the current report document.

The BIRT services for generating and presenting report data create a report during the following processing phases:

RunTask handles the preparation and generation phases and RenderTask handles the presentation phase. RunAndRenderTask handles all phases of report processing. The types of events and the order in which these events fire depends on the processing phase currently executing in an engine task.