Package org.eclipse.birt.report.engine.api

This is an application-writer's interface for using the BIRT report engine.

See:
          Description

Interface Summary
IAction Defines an interface that allows engine to pass hyperlink information to an emitter, if the emitter determines to customize the hyperlinks calculated in engine, or it wants to use a totally different hyperlink string
ICascadingParameterGroup  
ICascadingParameterSelectionChoice  
IDataAction Data Action is used to generate a URL used to reterive the data from the data base.
IDataExtractionOption  
IDataExtractionTask an engine task that extracts data from a report.
IDataIterator An iterator on a result set from a prepared and executed query.
IDocumentWriter  
IEngineConfig  
IEngineTask defines common features for an engine task.
IExcelRenderOption  
IExtractionResults A handle used to retrieve data stored in a report.
IGetParameterDefinitionTask an engine task that retrieves parameter definitions from a report.
IHTMLActionHandler Defines an interface for action handler used in HTML format
IHTMLImageHandler Defines the image handler interface for use in HTML format
IHTMLRenderOption Interface of constants of the HTML Render Opitons.
IImage Defines an interface to communicate info about an image to image handler
IPageHandler An interface implemented by app developer to provide handler after each page is generated in factoery.
IParameterDefn base interface for a BIRT report parameter
IParameterDefnBase Captures properties shared by all types of parameters and parameter group, i.e., name, display name, help text and custom-defined properties.
IParameterGroupDefn The interface for objects which visually groups report parameters.
IParameterSelectionChoice defines one choice in a parameter selction value list
IPDFRenderOption Defines render options for PDF emitter.
IRenderOption Defines render options for emitters
IRenderTask An engine task that renders a Report Document to one of the output formats supported by the engine.
IReportDocument A report document (i.e., not modifiable) that can be rendered to other formats in the BIRT presentation engine This is the high-level report document interface.
IReportDocumentInfo the interface used to access the traisent informations of a report document.
IReportDocumentLock lock used to lock the report document.
IReportDocumentLockManager  
IReportEngine A report engine provides an entry point for reporting functionalities.
IReportEngineFactory a factory used to create the Report Engine.
IReportPart Base interface that provides accessible information for a report part
IReportRunnable A runnable report design (i.e., not modifiable) that can be run in the BIRT engine
IResultMetaData Describes the metadata of a detail row in an IResultIterator.
IResultSetItem  
IRunAndRenderTask an engine task that runs a report and renders it to one of the output formats supported by the engine.
IRunTask An engine task that runs a report and generates a report document.
IScalarParameterDefn Defines a scalar parameter
IStatusHandler Interface that defines several status handler callback functions.
ITaskOption  
ITOCTree Represents a whole TOC tree.
 

Class Summary
CachedImage Cached Image Created by the IHTMLImageHandler.
ComponentID a class that wraps around an identifier for a report component
DataExtractionFormatInfo  
DataExtractionOption  
DataID the data id of the data used by an instance.
DataSetID ID represent the data set.
DefaultStatusHandler default implementation for a status handler.
DOCRenderContext  
DocumentUtil  
EmitterInfo The descriptor of the plugin emitter.
EngineConfig Wraps around configuration settings for report engine.
EngineConstants Defines various constants that engine host may need to use
EXCELRenderOption  
HTMLActionHandler Defines a default action handler for HTML output format
HTMLCompleteImageHandler Default implementation for writing images in a form that is compatible with a web browser's "HTML Complete" save option, i.e., writes images to a predefined folder.
HTMLEmitterConfig Deprecated. since 2.2, use HTMLRenderOption or RenderOption directly
HTMLImageHandler  
HTMLRenderContext Deprecated. set the property to RenderOption directly.
HTMLRenderOption output settings for HTML output format
HTMLServerImageHandler Default implementation for writing images in a form that is used in a web-application.
ImageSize  
InstanceID a class that wraps around an identifier for a report element instance
PDFRenderContext Deprecated. set the option to RenderOption directly.
PDFRenderOption Defines render options for emitters
RenderOption Settings for rendering a report to an output format.
RenderOptionBase Deprecated. use RenderOption instead
ReportEngine This is a wrapper class for the IReportEngine.
ReportParameterConverter Utilites class to convert report paramete value between object and string.
ReportRunner Defines a standalone reporting application that uses StandaloneReportEngine class.
TaskOption  
TOCNode A node that wraps around a TOC entry.
TOCStyle  
 

Exception Summary
EngineException Define an engine exception that clients of the engine need to handle.
UnsupportedFormatException  
 

Package org.eclipse.birt.report.engine.api Description

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:

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


Copyright © 2008 Actuate Corp. All rights reserved.