Package 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
Description
`static final int`
`CANCEL_ON_ERROR`
cancel the task execution if there is an error.
`static final int`
`CONTINUE_ON_ERROR`
continue the task execution if there is an error.
`static final int`
`STATUS_CANCELLED`
the task is finished by cancled
`static final int`
`STATUS_FAILED`
the task is finished with errors
`static final int`
`STATUS_NOT_STARTED`
the task is not running yet
`static final int`
`STATUS_RUNNING`
the task is running
`static final int`
`STATUS_SUCCEEDED`
the task is finished with sucessful
`static final int`
`TASK_DATAEXTRACTION`
`static final int`
`TASK_DATASETPREVIEW`
`static final int`
`TASK_GETPARAMETERDEFINITION`
`static final int`
`TASK_RENDER`
`static final int`
`TASK_RUN`
`static final int`
`TASK_RUNANDRENDER`
`static final int`
`TASK_UNKNOWN`

## Method Summary

Modifier and Type
Method
Description
`void`
`addScriptableJavaObject(String jsName, Object obj)`
Deprecated.
user should add it to appContext.
`void`
`cancel()`
set the cancel flag if the task is running.
`void`
`cancel(String reason)`
cancels the task by the given reason.
`void`
`close()`
close the task, relese any resources.
`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
`List`
`getErrors()`
Gets all exceptions that are thrown out during executing this task.
`int`
`getID()`
returns an identifier for the task.
`Locale`
`getLocale()`
returns the locale for running the task
`Logger`
`getLogger()`
return the logger used by the task.
`Object`
`getParameterDisplayText(String name)`
Gets parameter display text by parameter name.
`Object`
`getParameterValue(String name)`
returns the value of a parameter.
`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.
`com.ibm.icu.util.ULocale`
`getULocale()`
returns the locale for running the task
`void`
`setAppContext(Map context)`
sets the task context.
`void`
`setDataSource(org.eclipse.birt.core.archive.IDocArchiveReader dataSource)`
set the data source used by the engine task.
`void`
`setDataSource(org.eclipse.birt.core.archive.IDocArchiveReader dataSource, 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(com.ibm.icu.util.ULocale locale)`
sets the task locale
`void`
`setLocale(Locale locale)`
sets the task locale
`void`
`setLogger(Logger logger)`
set the logger used by the task.
`void`
`setParameter(String name, Object[] values, String[] displayText)`
Sets parameter value and display text.
`void`
`setParameter(String name, Object value, String displayText)`
Sets parameter value and display text.
`void`
`setParameterDisplayText(String name, String displayText)`
Sets display text of a parameter with specified name.
`void`
`setParameterDisplayText(String name, String[] text)`
Sets display text of a parameter with specified name.
`void`
`setParameterValue(String name, Object value)`
sets one parameter value
`void`
`setParameterValue(String name, Object[] values)`
sets one parameter values
`void`
`setParameterValues(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(com.ibm.icu.util.TimeZone timeZone)`
Set the time zone information for the task.
`void`
`setUserACL(String[] acl)`
set user's ACL.
`boolean`
`validateParameters()`

## Field Details

### 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 Details

### setLocale

void setLocale(Locale locale)
sets the task locale

Parameters:
  `locale` - the task locale

### setLocale

void setLocale(com.ibm.icu.util.ULocale locale)
sets the task locale

Parameters:
  `locale` - the task locale

### setTimeZone

void setTimeZone(com.ibm.icu.util.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(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

  Locale getLocale()
  returns the locale for running the task
  Returns:
    the locale for running the task

- ### getULocale

  com.ibm.icu.util.ULocale getULocale()
  returns the locale for running the task
  Returns:
    the locale for running the task

- ### getAppContext

  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

  @Deprecated void addScriptableJavaObject(String jsName, 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(Map params)
  set all parameter valuess
  Parameters:
    `params` - a hash map with all parameters

- ### setParameterValue

  void setParameterValue(String name, Object value)
  sets one parameter value
  Parameters:
    `name` - parameter name
    `value` - parameter value

- ### setParameterValue

  void setParameterValue(String name, Object[] values)
  sets one parameter values
  Parameters:
    `name` - parameter name
    `values` - parameter values

- ### getParameterValues

  HashMap getParameterValues()
  returns the parameter name/value collection
  Returns:
    the parameter names/values in a hash map

- ### getParameterValue

  Object getParameterValue(String name)
  returns the value of a parameter.
  Returns:
    the parameter value.

- ### validateParameters

  boolean validateParameters()
  Returns:
    whether the parameter validation succeeds

- ### setParameter

  void setParameter(String name, Object value, String displayText)
  Sets parameter value and display text.
  Parameters:
    `name` - parameter name.
    `value` - value.
    `displayText` - display text.

- ### setParameter

  void setParameter(String name, Object[] values, String[] displayText)
  Sets parameter value and display text.
  Parameters:
    `name` - parameter name.
    `values` - values.
    `displayText` - display text.

- ### getParameterDisplayText

  Object getParameterDisplayText(String name)
  Gets parameter display text by parameter name.
  Parameters:
    `name` - parameter name.
  Returns:
    display text.

- ### setParameterDisplayText

  void setParameterDisplayText(String name, 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(String name, 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 was cancelled.

- ### cancel

  void cancel(String reason)
  cancels the task by the given reason.

- ### 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(org.eclipse.birt.core.archive.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(org.eclipse.birt.core.archive.IDocArchiveReader dataSource, String reportlet)
  set the data source used by the engine task.
  Parameters:
    `dataSource` - data source archive.
    `reportlet` - the bookmark of the reportlet.

- ### getErrors

  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

  Logger getLogger()
  return the logger used by the task.
  Returns:
    logger used by the task.

- ### setLogger

  void setLogger(Logger logger)
  set the logger used by the task.
  Parameters:
    `logger` - the logger used to output messages.

- ### setUserACL

  void setUserACL(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