org.eclipse.birt.report.engine.api

Interface IEngineTask

All Known Subinterfaces:

IDataExtractionTask, IDatasetPreviewTask, IExtractionTask, IGetParameterDefinitionTask, IRenderTask, IRunAndRenderTask, IRunTask

public interface IEngineTask

defines common features for an engine task. A task captures a set of operations that engine performs to get a unit of work done.

Field Summary

Fields

Modifier and Type	Field and Description
static int	CANCEL_ON_ERROR cancel the task execution if there is an error.
static int	CONTINUE_ON_ERROR continue the task execution if there is an error.
static int	STATUS_CANCELLED the task is finished by cancled
static int	STATUS_FAILED the task is finished with errors
static int	STATUS_NOT_STARTED the task is not running yet
static int	STATUS_RUNNING the task is running
static int	STATUS_SUCCEEDED the task is finished with sucessful
static int	TASK_DATAEXTRACTION
static int	TASK_DATASETPREVIEW
static int	TASK_GETPARAMETERDEFINITION
static int	TASK_RENDER
static int	TASK_RUN
static int	TASK_RUNANDRENDER
static int	TASK_UNKNOWN

Method Summary

Methods

Modifier and Type	Method and Description
void	addScriptableJavaObject(java.lang.String jsName, java.lang.Object obj) Deprecated. user should add it to appContext.
void	cancel() set the cancel flag if the task is running.
void	cancel(java.lang.Object signal) Deprecated. user should use cancel() instead.
void	close() close the task, relese any resources.
java.util.Map	getAppContext() returns the context objects for the task.
boolean	getCancelFlag() return a flag if the user called cancel.
IReportEngine	getEngine() returns the report engine object
java.util.List	getErrors() Gets all exceptions that are thrown out during executing this task.
int	getID() returns an identifier for the task.
java.util.Locale	getLocale() returns the locale for running the task
java.util.logging.Logger	getLogger() return the logger used by the task.
java.lang.Object	getParameterDisplayText(java.lang.String name) Gets parameter display text by parameter name.
java.lang.Object	getParameterValue(java.lang.String name) returns the value of a parameter.
java.util.HashMap	getParameterValues() returns the parameter name/value collection
IReportRunnable	getReportRunnable() returns the runnable report design object
int	getStatus() get the status of task
int	getTaskType() Gets the type of the engine.
ULocale	getULocale() returns the locale for running the task
void	setAppContext(java.util.Map context) sets the task context.
void	setDataSource(IDocArchiveReader dataSource) set the data source used by the engine task.
void	setDataSource(IDocArchiveReader dataSource, java.lang.String reportlet) set the data source used by the engine task.
void	setErrorHandlingOption(int option) set the error handling mode for the first error.
void	setLocale(java.util.Locale locale) sets the task locale
void	setLocale(ULocale locale) sets the task locale
void	setLogger(java.util.logging.Logger logger) set the logger used by the task.
void	setParameter(java.lang.String name, java.lang.Object[] values, java.lang.String[] displayText) Sets parameter value and display text.
void	setParameter(java.lang.String name, java.lang.Object value, java.lang.String displayText) Sets parameter value and display text.
void	setParameterDisplayText(java.lang.String name, java.lang.String displayText) Sets display text of a parameter with specified name.
void	setParameterDisplayText(java.lang.String name, java.lang.String[] text) Sets display text of a parameter with specified name.
void	setParameterValue(java.lang.String name, java.lang.Object value) sets one parameter value
void	setParameterValue(java.lang.String name, java.lang.Object[] values) sets one parameter values
void	setParameterValues(java.util.Map params) set all parameter valuess
void	setProgressMonitor(IProgressMonitor monitor) the a progress monitor to keep track of the report progress
void	setStatusHandler(IStatusHandler handler) set a task-level status handler, this handler will override the engine-level one
void	setTimeZone(TimeZone timeZone) Set the time zone information for the task.
void	setUserACL(java.lang.String[] acl) set user's ACL.
boolean	validateParameters()

Field Detail

TASK_UNKNOWN

static final int TASK_UNKNOWN

See Also:

Constant Field Values

TASK_GETPARAMETERDEFINITION

static final int TASK_GETPARAMETERDEFINITION

See Also:

Constant Field Values

TASK_RUN

static final int TASK_RUN

See Also:

Constant Field Values

TASK_RENDER

static final int TASK_RENDER

See Also:

Constant Field Values

TASK_RUNANDRENDER

static final int TASK_RUNANDRENDER

See Also:

Constant Field Values

TASK_DATAEXTRACTION

static final int TASK_DATAEXTRACTION

See Also:

Constant Field Values

TASK_DATASETPREVIEW

static final int TASK_DATASETPREVIEW

See Also:

Constant Field Values

STATUS_NOT_STARTED

static final int STATUS_NOT_STARTED

the task is not running yet

See Also:

Constant Field Values

STATUS_RUNNING

static final int STATUS_RUNNING

the task is running

See Also:

Constant Field Values

STATUS_SUCCEEDED

static final int STATUS_SUCCEEDED

the task is finished with sucessful

See Also:

Constant Field Values

STATUS_FAILED

static final int STATUS_FAILED

the task is finished with errors

See Also:

Constant Field Values

STATUS_CANCELLED

static final int STATUS_CANCELLED

the task is finished by cancled

See Also:

Constant Field Values

CONTINUE_ON_ERROR

static final int CONTINUE_ON_ERROR

continue the task execution if there is an error.

See Also:

Constant Field Values

CANCEL_ON_ERROR

static final int CANCEL_ON_ERROR

cancel the task execution if there is an error.

See Also:

Constant Field Values

Method Detail

setLocale

void setLocale(java.util.Locale locale)

sets the task locale

Parameters:

locale - the task locale

setLocale

void setLocale(ULocale locale)

sets the task locale

Parameters:

locale - the task locale

setTimeZone

void setTimeZone(TimeZone timeZone)

Set the time zone information for the task.

Only following tasks have the meaningful implementations:

RunAndRenderTask RenderTask GetParameterDefinitionTask

Parameters:

timeZone - the time zone information for the task

setAppContext

void setAppContext(java.util.Map context)

sets the task context. this method must be called before the run/render/execute etc.

Parameters:

context - - task contexts in a map. The map contains name-value pairs

getLocale

java.util.Locale getLocale()

returns the locale for running the task

Returns:

the locale for running the task

getULocale

ULocale getULocale()

returns the locale for running the task

Returns:

the locale for running the task

getAppContext

java.util.Map getAppContext()

returns the context objects for the task. The return appContext is read only, the user should never try to modify the value.

Returns:

the task contexts

getEngine

IReportEngine getEngine()

returns the report engine object

Returns:

the engine object

addScriptableJavaObject

void addScriptableJavaObject(java.lang.String jsName,
                           java.lang.Object obj)

Deprecated. user should add it to appContext.

defines an additional Java object that is exposed to BIRT scripting at a per-task level

Parameters:

jsName - the name that the object is referenced in JavaScript

obj - the Java object that is wrapped and scripted

getID

int getID()

returns an identifier for the task. The identifier can be used to identify the task, especially when writing logs in a multi-threaded environment.

Returns:

an identifier for the task.

getReportRunnable

IReportRunnable getReportRunnable()

returns the runnable report design object

Returns:

the runnable report design object

setParameterValues

void setParameterValues(java.util.Map params)

set all parameter valuess

Parameters:

params - a hash map with all parameters

setParameterValue

void setParameterValue(java.lang.String name,
                     java.lang.Object value)

sets one parameter value

Parameters:

name - parameter name

value - parameter value

setParameterValue

void setParameterValue(java.lang.String name,
                     java.lang.Object[] values)

sets one parameter values

Parameters:

name - parameter name

values - parameter values

getParameterValues

java.util.HashMap getParameterValues()

returns the parameter name/value collection

Returns:

the parameter names/values in a hash map

getParameterValue

java.lang.Object getParameterValue(java.lang.String name)

returns the value of a parameter.

Returns:

the parameter value.

validateParameters

boolean validateParameters()

Returns:

whether the parameter validation succeeds

setParameter

void setParameter(java.lang.String name,
                java.lang.Object value,
                java.lang.String displayText)

Sets parameter value and display text.

Parameters:

name - parameter name.

value - value.

displayText - display text.

setParameter

void setParameter(java.lang.String name,
                java.lang.Object[] values,
                java.lang.String[] displayText)

Sets parameter value and display text.

Parameters:

name - parameter name.

values - values.

displayText - display text.

getParameterDisplayText

java.lang.Object getParameterDisplayText(java.lang.String name)

Gets parameter display text by parameter name.

Parameters:

name - parameter name.

Returns:

display text.

setParameterDisplayText

void setParameterDisplayText(java.lang.String name,
                           java.lang.String displayText)

Sets display text of a parameter with specified name.

Parameters:

name - name of the parameter.

displayText - display text to set.

setParameterDisplayText

void setParameterDisplayText(java.lang.String name,
                           java.lang.String[] text)

Sets display text of a parameter with specified name.

Parameters:

name - name of the parameter.

displayText - display text to set.

cancel

void cancel()

set the cancel flag if the task is running. the task can re-run if it is cancedl.

cancel

void cancel(java.lang.Object signal)

Deprecated. user should use cancel() instead.

cancels the task with a signal. you can't call this method in the same thread with runTask The signal will be notified when the task finishes the cancel.

getCancelFlag

boolean getCancelFlag()

return a flag if the user called cancel.

Returns:

true the user has called cancel, false the user doesn't call cancel.

getStatus

int getStatus()

get the status of task

Returns:

the status

setErrorHandlingOption

void setErrorHandlingOption(int option)

set the error handling mode for the first error. If the options is set to cancel_on_error, the task is cancelled just like the user calls cancel(). If the option is set the continue_on_erro, the task will continue and saves the error into the error list.

Parameters:

option - the error handling mode.

close

void close()

close the task, relese any resources.

setDataSource

void setDataSource(IDocArchiveReader dataSource)

set the data source used by the engine task. The dataSource is closed by this task.

Parameters:

dataSource - data source archive.

setDataSource

void setDataSource(IDocArchiveReader dataSource,
                 java.lang.String reportlet)

set the data source used by the engine task.

Parameters:

dataSource - data source archive.

reportlet - the bookmark of the reportlet.

getErrors

java.util.List getErrors()

Gets all exceptions that are thrown out during executing this task. Each exception is supposed to be an instance of EngineException.

Returns:

the all the exceptions in a list.

getTaskType

int getTaskType()

Gets the type of the engine.

Returns:

task type including:

0 for GetParameterDefinition Task

1 for Run Task

2 for Render Task

3 for Run and Render Task

4 for DataExtraction Task

-1 default value for unknown task

getLogger

java.util.logging.Logger getLogger()

return the logger used by the task.

Returns:

logger used by the task.

setLogger

void setLogger(java.util.logging.Logger logger)

set the logger used by the task.

Parameters:

logger - the logger used to output messages.

setUserACL

void setUserACL(java.lang.String[] acl)

set user's ACL.

Parameters:

acl - a string array, each element is a single SID.

setProgressMonitor

void setProgressMonitor(IProgressMonitor monitor)

the a progress monitor to keep track of the report progress

Parameters:

monitor - a user defined progress monitor

setStatusHandler

void setStatusHandler(IStatusHandler handler)

set a task-level status handler, this handler will override the engine-level one

Parameters:

handler - a user defined status handler