This is an application-writer's interface for using the BIRT report engine. To use the engine, first create an engine configuration object of type EngineConfig. Set configuration properties on the object, and then pass it to the report engine constructor (class ReportEngine).

A report engine supports running several types of task. Examples are GetParameterDefinitionTask, RunAndRenderReportTask, etc. To run and render a report, the following steps may be involved:

- The report design is opened by calling the ReportEngine.openReportDesign(...) The method returns an IReportRunnable object.
- With the IReportRunnable object, call ReportEngine.createGetParameterDefinitionTask(...) to obtain an IGetParameterDefinitionTask object, from which parameter definitions are retrieved. A UI page can be constructed based on the definitions to prompt end users for parameter values.
- An IRunReportTask object can be obtained by calling ReportEngine.createRunAndRenderReportTask(...). From the task, report parameters are set. Running options can also be set.
- The run() method on IRunAndRenderReportTask is called.

Code segments are shown below to demonstrate how to use the engine APIs.

### Simple Use of Report Engine, No Customization

To get a report to run, do the following:

`ReportEngine engine = new ReportEngine(null);
IReportRunnable design = engine.openReportDesign("C:/temp/test.rptdesign");
IRunAndRenderTask task = engine.createRunAndRenderTask(design);
IOutputSetting setting = new OutputSetting();
setting.setOutputFileName("C:/temp/test.html");
task.setOutputSetting(setting);
task.run();`

No customization is done so engine will asserts its default behavior: write the report to HTML format at C:/temp/test.html, assuming JVM locale. The report design can not contain images, charts ot hyperlinks, or otherwise engine has to be configured with corresponging image or action handlers. It is also assumed that test.rptdesign does not have parameters, so no GetParameterDefinition task is constructed.

### Using Report Engine with Customization

The following example customizes the engine:

`// Engine configuration
EngineConfig config = new EngineConfig();
config.setEngineHome("C:/birt/"); // Configuring where BIRT engine is installed
config.setImageHandler(new MyImageHandler(...)); // You define and instantiate class MyImageHandler
config.setActionHandler(new MyActionHandler(...)); // You define and instantiate class MYActionHandler
config.addScriptableJavaObject("foo", aFooinstance);// You can now write foo.bar() in your report
// Create engine and open report design
ReportEngine engine = new ReportEngine(config); //Create engine with configuration
IReportRunnable design = engine.openReportDesign("C:/temp/test.rptdesign");
// Get parameter definitions
IGetParameterDefinitionTask task = engine.createGetParameterDefinitionTask(design); task.setLocale(myLocale); // set rendering locale Collection parameters = task.getParameterDefns(false); // get parameter definitions
// Present parameter prompt page and receive inputs.
// Create task to run and render the report
IRunAndRenderTask task = engine.createRunAndRenderTask(design);
// Set parameters
task.setParameters(parameterMap); // parameterMap is a hash map of parameter name/value pairs
task.setLocale(myLocale);
// output options
XHTMLOutputSetting setting = new XHTMLOutputSetting(); // assume this is a third-party format
setting.setOutputFileName("C:/temp/test.html");
setting.setOutputFormat("xhtml"); // XHTML emitter supports "xhtml" format
setting.setEmbeddable(true); // XHTML also supports embeddable
task.setOutputSetting(setting);
task.run();`

## Package Specification

Application-writer's interface for the BIRT Engine.

@since 1.0