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

# Class ReportEngine

java.lang.Object
org.eclipse.birt.report.engine.api.ReportEngine

All Implemented Interfaces:
  `IReportEngine`

public class ReportEngine extends Object implements IReportEngine
This is a wrapper class for the IReportEngine. The new user should use the IReportEngineFactory to create the IReportEngine instead of use this class directly.

See Also:
  - invalid reference

        org.eclipes.birt.report.engine.api.ReportRunner

## Field Summary

Fields
Modifier and Type
Field
Description
`protected IReportEngine`
`engine`
the report engine.
`protected static Logger`
`logger`
the logger

## Constructor Summary

Constructors
Constructor
Description
`ReportEngine(EngineConfig config)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`void`
`changeLogLevel(Level newLevel)`
Change the log level to newLevel
`IDataExtractionTask`
`createDataExtractionTask(IReportDocument reportDocument)`
creates a task that allows data extraction from a report document
`IDatasetPreviewTask`
`createDatasetPreviewTask()`
`IEngineTask`
`createEngineTask(String taskName)`
create an engine task
`IGetParameterDefinitionTask`
`createGetParameterDefinitionTask(IReportRunnable reportRunnable)`
creates an engine task for obtaining report parameter definitions
`IGetParameterDefinitionTask`
`createGetParameterDefinitionTask(IRunnable reportRunnable)`
creates an engine task for obtaining report parameter definitions
`IRenderTask`
`createRenderTask(IReportDocument reportDocument)`
creates a task that renders the report to a specific output format.
`IRenderTask`
`createRenderTask(IReportDocument reportDocument, IReportRunnable reportRunnable)`
create a task that renders the report to a specific output format.
`IRunAndRenderTask`
`createRunAndRenderTask(IReportRunnable reportRunnable)`
creates an engine task for running and rendering report directly to output format
`IRunTask`
`createRunTask(IReportRunnable reportRunnable)`
creates a task to run a report to generate a report document
`void`
`destroy()`
shuts down the report engine
`EngineConfig`
`getConfig()`
returns the engine configuration object
`DataExtractionFormatInfo[]`
`getDataExtractionFormatInfo()`
Returns data extraction extension information.
`EmitterInfo[]`
`getEmitterInfo()`
Return all the emitter information which BIRT Engine can load.
`Logger`
`getLogger()`
get the logger used by report engine
`String`
`getMIMEType(String format)`
the MIME type for the specific formatted supported by the extension.
`Object`
`getRootScope()`
get the root scope used by the engine
`String[]`
`getSupportedFormats()`
returns all supported output formats through BIRT engine emitter extensions
`String`
`getVersion()`
get the BIRT version
`IDocumentWriter`
`openDocumentWriter(org.eclipse.birt.core.archive.compound.IArchiveFile file)`
creates a document writer that can write this archive file
`IReportRunnable`
`openReportDesign(InputStream designStream)`
opens a report design stream and creates a report design runnable.
`IReportRunnable`
`openReportDesign(String designName)`
opens a report design file and creates a report design runnable.
`IReportRunnable`
`openReportDesign(String name, InputStream designStream)`
opens a report design stream and creates a report design runnable.
`IReportRunnable`
`openReportDesign(String name, InputStream designStream, Map options)`
open the report design and return the runnable
`IReportRunnable`
`openReportDesign(String name, InputStream designStream, org.eclipse.birt.report.model.api.IResourceLocator locator)`
opens a report design stream and creates a report design runnable.
`IReportRunnable`
`openReportDesign(String designName, org.eclipse.birt.report.model.api.IResourceLocator locator)`
opens a report design file and creates a report design runnable.
`IReportRunnable`
`openReportDesign(org.eclipse.birt.report.model.api.ReportDesignHandle designHandle)`
opens a report designHandle and creates a report design runnable.
`IReportDocument`
`openReportDocument(String fileName)`
opens a report document and returns an IReportDocument object, from which further information can be retrieved.
`IReportDocument`
`openReportDocument(String systemId, String fileName)`
opens a report document and returns an IReportDocument object, from which further information can be retrieved.
`IReportDocument`
`openReportDocument(String systemId, String fileName, Map options)`
opens a report document and returns an IReportDocument object, from which further information can be retrieved.
`IReportDocument`
`openReportDocument(String systemId, String fileName, org.eclipse.birt.report.model.api.IResourceLocator locator)`
opens a report document and returns an IReportDocument object, from which further information can be retrieved.
`IReportDocument`
`openReportDocument(String systemId, org.eclipse.birt.core.archive.IDocArchiveReader reader, Map options)`
opens a report document and returns an IReportDocument object, from which further information can be retrieved.
`IReportDocument`
`openReportDocument(String fileName, org.eclipse.birt.report.model.api.IResourceLocator locator)`
opens a report document and returns an IReportDocument object, from which further information can be retrieved.
`void`
`setLogger(Logger logger)`
set the logger used by report engine.
`void`
`shutdown()`
Deprecated.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### logger

protected static Logger logger
the logger

### engine

protected IReportEngine engine
the report engine.

## Constructor Details

### ReportEngine

public ReportEngine(EngineConfig config)
Constructor. If config is null, engine derives BIRT_HOME from the location of the engine jar file, and derives data driver directory as $BIRT_HOME/drivers. For a simple report with no images and links, engine will run without complaining. If the report has image/chart defined, the engine has to be configured with relevant image and chart handlers.

Parameters:
  `config` - an engine configuration object used to configure the engine

## Method Details

### getRootScope

public Object getRootScope()
get the root scope used by the engine

Specified by:
  `getRootScope` in interface `IReportEngine`
Returns:

### changeLogLevel

public void changeLogLevel(Level newLevel)
Change the log level to newLevel

Specified by:
  `changeLogLevel` in interface `IReportEngine`
Parameters:
  `newLevel` - - new log level

### getConfig

public EngineConfig getConfig()
returns the engine configuration object

Specified by:
  `getConfig` in interface `IReportEngine`
Returns:
  the engine configuration object

### openReportDesign

public IReportRunnable openReportDesign(String designName) throws EngineException
opens a report design file and creates a report design runnable. From the ReportRunnable object, embedded images and parameter definitions can be retrieved. Constructing an engine task requires a report design runnable object.

Specified by:
  `openReportDesign` in interface `IReportEngine`
Parameters:
  `designName` - the full path of the report design file
Returns:
  a report design runnable object
Throws:
  `EngineException` - throwed when the input file does not exist, or the file is invalid

### openReportDesign

public IReportRunnable openReportDesign(org.eclipse.birt.report.model.api.ReportDesignHandle designHandle) throws EngineException
opens a report designHandle and creates a report design runnable. From the ReportRunnable object, embedded images and parameter definitions can be retrieved. Constructing an engine task requires a report design runnable object.

Specified by:
  `openReportDesign` in interface `IReportEngine`
Parameters:
  `designHandle` -
Returns:
  a report design runnable object
Throws:
  `EngineException`

### openReportDesign

public IReportRunnable openReportDesign(InputStream designStream) throws EngineException
opens a report design stream and creates a report design runnable. From the ReportRunnable object, embedded images and parameter definitions can be retrieved. Constructing an engine task requires a report design runnableobject.

Specified by:
  `openReportDesign` in interface `IReportEngine`
Parameters:
  `designStream` - the report design input stream
Returns:
  a report design runnable object
Throws:
  `EngineException` - throwed when the input stream is null, or the stream does not yield a valid report design

### openReportDesign

public IReportRunnable openReportDesign(String name, InputStream designStream) throws EngineException
opens a report design stream and creates a report design runnable. From the ReportRunnable object, embedded images and parameter definitions can be retrieved. Constructing an engine task requires a report design runnable object.

Specified by:
  `openReportDesign` in interface `IReportEngine`
Parameters:
  `name` - system id of the report design
  `designStream` - input stream of the report design
Returns:
  a report design runnable object
Throws:
  `EngineException` - throwed when the input stream is null, or the stream does not yield a valid report design

### createRunAndRenderTask

public IRunAndRenderTask createRunAndRenderTask(IReportRunnable reportRunnable)
creates an engine task for running and rendering report directly to output format

Specified by:
  `createRunAndRenderTask` in interface `IReportEngine`
Parameters:
  `reportRunnable` - the runnable report design object
Returns:
  a run and render report task

### createGetParameterDefinitionTask

public IGetParameterDefinitionTask createGetParameterDefinitionTask(IRunnable reportRunnable)
creates an engine task for obtaining report parameter definitions

Specified by:
  `createGetParameterDefinitionTask` in interface `IReportEngine`
Parameters:
  `reportRunnable` - the runnable report design object
Returns:
  a run and render report task

### createGetParameterDefinitionTask

public IGetParameterDefinitionTask createGetParameterDefinitionTask(IReportRunnable reportRunnable)
creates an engine task for obtaining report parameter definitions

Specified by:
  `createGetParameterDefinitionTask` in interface `IReportEngine`
Parameters:
  `reportRunnable` - the runnable report design object
Returns:
  a GetParameterDefinitionTask

### getSupportedFormats

public String[] getSupportedFormats()
returns all supported output formats through BIRT engine emitter extensions

Specified by:
  `getSupportedFormats` in interface `IReportEngine`
Returns:
  all supported output formats through BIRT engine emitter extensions

### getEmitterInfo

public EmitterInfo[] getEmitterInfo()
Return all the emitter information which BIRT Engine can load.

Specified by:
  `getEmitterInfo` in interface `IReportEngine`
Returns:
  the emitter information

### getMIMEType

public String getMIMEType(String format)
the MIME type for the specific formatted supported by the extension.

Specified by:
  `getMIMEType` in interface `IReportEngine`
Parameters:
  `format` - the output format
  `extensionID` - the extension ID, which could be null if only one plugin supports the output format
Returns:
  the MIME type for the specific formatted supported by the extension.

### destroy

public void destroy()
shuts down the report engine

Specified by:
  `destroy` in interface `IReportEngine`

### createRunTask

public IRunTask createRunTask(IReportRunnable reportRunnable)
creates a task to run a report to generate a report document

Specified by:
  `createRunTask` in interface `IReportEngine`
Parameters:
  `reportRunnable` - the runnable report design object
Returns:
  a task that runs the report

### createRenderTask

public IRenderTask createRenderTask(IReportDocument reportDocument)
creates a task that renders the report to a specific output format.

Specified by:
  `createRenderTask` in interface `IReportEngine`
Parameters:
  `reportDocument` - a handle to an IReportDocument object
Returns:
  a task that renders a report to an output format

### openReportDocument

public IReportDocument openReportDocument(String fileName) throws EngineException
opens a report document and returns an IReportDocument object, from which further information can be retrieved.

Specified by:
  `openReportDocument` in interface `IReportEngine`
Parameters:
  `fileName` - the report document name. report document is an archive in BIRT.
Returns:
  A handle to the report document
Throws:
  `EngineException` - throwed when the report document archive does not exist, or the file is not a valud report document

### createDataExtractionTask

public IDataExtractionTask createDataExtractionTask(IReportDocument reportDocument)
creates a task that allows data extraction from a report document

Specified by:
  `createDataExtractionTask` in interface `IReportEngine`
Parameters:
  `reportDocument` - a handle to an IReportDocument object
Returns:
  a task that renders a report to an output format

### shutdown

@Deprecated public void shutdown()
Deprecated.
shut down the engine, release all the resources.

Specified by:
  `shutdown` in interface `IReportEngine`

### openReportDocument

public IReportDocument openReportDocument(String systemId, String fileName) throws EngineException
opens a report document and returns an IReportDocument object, from which further information can be retrieved.

Specified by:
  `openReportDocument` in interface `IReportEngine`
Parameters:
  `systemId` - the system id the opend document. It is used to access the resources with relative path in the report document. If it is NULL, a saved one is used.
  `fileName` - the report document name. report document is an archive in BIRT.
Returns:
  A handle to the report document
Throws:
  `EngineException` - throwed when the report document archive does not exist, or the file is not a valid report document

### openReportDesign

public IReportRunnable openReportDesign(String designName, org.eclipse.birt.report.model.api.IResourceLocator locator) throws EngineException
opens a report design file and creates a report design runnable. From the ReportRunnable object, embedded images and parameter definitions can be retrieved. Constructing an engine task requires a report design runnable object.

Specified by:
  `openReportDesign` in interface `IReportEngine`
Parameters:
  `designName` - the full path of the report design file
  `locator` - the resource locator used to locate files referenced in the design
Returns:
  a report design runnable object
Throws:
  `EngineException` - throwed when the input file does not exist, or the file is invalid

### openReportDesign

public IReportRunnable openReportDesign(String name, InputStream designStream, org.eclipse.birt.report.model.api.IResourceLocator locator) throws EngineException
opens a report design stream and creates a report design runnable. From the ReportRunnable object, embedded images and parameter definitions can be retrieved. Constructing an engine task requires a report design runnable object.

Specified by:
  `openReportDesign` in interface `IReportEngine`
Parameters:
  `name` - system id of the report design
  `designStream` - input stream of the report design
  `locator` - the resource locator used to locate files referenced in the design
Returns:
  a report design runnable object
Throws:
  `EngineException` - throwed when the input stream is null, or the stream does not yield a valid report design

### openReportDesign

public IReportRunnable openReportDesign(String name, InputStream designStream, Map options) throws EngineException
open the report design and return the runnable

Specified by:
  `openReportDesign` in interface `IReportEngine`
Parameters:
  `name` - system id of the report design.
  `designStream` - input stream of the report desgin.
  `options` - options used to parse the design.
Returns:
  a report design runnable object
Throws:
  `EngineException`
See Also:
  - invalid reference

        ModelOptions

### openReportDocument

public IReportDocument openReportDocument(String fileName, org.eclipse.birt.report.model.api.IResourceLocator locator) throws EngineException
opens a report document and returns an IReportDocument object, from which further information can be retrieved.

Specified by:
  `openReportDocument` in interface `IReportEngine`
Parameters:
  `fileName` - the report document name. report document is an archive in BIRT.
  `locator` - the resource locator used to locate files referenced in the design
Returns:
  A handle to the report document
Throws:
  `EngineException` - throwed when the report document archive does not exist, or the file is not a valud report document

### openReportDocument

public IReportDocument openReportDocument(String systemId, String fileName, org.eclipse.birt.report.model.api.IResourceLocator locator) throws EngineException
opens a report document and returns an IReportDocument object, from which further information can be retrieved.

Specified by:
  `openReportDocument` in interface `IReportEngine`
Parameters:
  `systemId` - the system id the opend document. It is used to access the resources with relative path in the report document. If it is NULL, a saved one is used.
  `fileName` - the report document name. report document is an archive in BIRT.
  `locator` - the resource locator used to locate files referenced in the design
Returns:
  A handle to the report document
Throws:
  `EngineException` - throwed when the report document archive does not exist, or the file is not a valud report document

### openReportDocument

public IReportDocument openReportDocument(String systemId, String fileName, Map options) throws EngineException
opens a report document and returns an IReportDocument object, from which further information can be retrieved.

Specified by:
  `openReportDocument` in interface `IReportEngine`
Parameters:
  `systemId` - the system id the opend document. It is used to access the resources with relative path in the report document. If it is NULL, a saved one is used.
  `fileName` - the report document name. report document is an archive in BIRT.
  `options` - Map defines the options used to parse the design file.
Returns:
  A handle to the report document
Throws:
  `EngineException` - throwed when the report document archive does not exist, or the file is not a valid report document

### openReportDocument

public IReportDocument openReportDocument(String systemId, org.eclipse.birt.core.archive.IDocArchiveReader reader, Map options) throws EngineException
opens a report document and returns an IReportDocument object, from which further information can be retrieved.

Specified by:
  `openReportDocument` in interface `IReportEngine`
Parameters:
  `systemId` - the system id the opend document. It is used to access the resources with relative path in the report document. If it is NULL, a saved one is used.
  `reader` - a report archive for reading
  `options` - Map defines the options used to parse the design file.
Returns:
  A handle to the report document
Throws:
  `EngineException` - throwed when the report document archive does not exist, or the file is not a valid report document

### getLogger

public Logger getLogger()
get the logger used by report engine

Specified by:
  `getLogger` in interface `IReportEngine`
Returns:
  the logger used by the report engine

### setLogger

public void setLogger(Logger logger)
set the logger used by report engine.

Specified by:
  `setLogger` in interface `IReportEngine`
Parameters:
  `logger` -

### createRenderTask

public IRenderTask createRenderTask(IReportDocument reportDocument, IReportRunnable reportRunnable)
create a task that renders the report to a specific output format.

Specified by:
  `createRenderTask` in interface `IReportEngine`
Parameters:
  `reportDocument` - a handle to an IReportDocument object
  `reportRunnable` - the runnable report design object
Returns:
  a task that renders a report to an output format

### getDataExtractionFormatInfo

public DataExtractionFormatInfo[] getDataExtractionFormatInfo()
Returns data extraction extension information.

Specified by:
  `getDataExtractionFormatInfo` in interface `IReportEngine`
Returns:
  the data extraction extension information

### openDocumentWriter

public IDocumentWriter openDocumentWriter(org.eclipse.birt.core.archive.compound.IArchiveFile file) throws EngineException
creates a document writer that can write this archive file

Specified by:
  `openDocumentWriter` in interface `IReportEngine`
Parameters:
  `file` - the archive file
Returns:
  a document writer of this archive file
Throws:
  `EngineException`

### getVersion

public String getVersion()
get the BIRT version

Specified by:
  `getVersion` in interface `IReportEngine`
Returns:
  the version of BIRT

### createEngineTask

public IEngineTask createEngineTask(String taskName) throws EngineException
Description copied from interface: `IReportEngine`
create an engine task

Specified by:
  `createEngineTask` in interface `IReportEngine`
Parameters:
  `taskName` - the extension name to identify a task
Returns:
  an engine task
Throws:
  `EngineException`

### createDatasetPreviewTask

public IDatasetPreviewTask createDatasetPreviewTask() throws EngineException

Specified by:
  `createDatasetPreviewTask` in interface `IReportEngine`
Throws:
  `EngineException`