com.attachmate.tasks
Interface ITask

public interface ITask

Contains method definitions to be implemented by all Task Beans.

Task Beans are standard Java beans that represent a particular task to be performed. A task may require zero or more inputs that are represented as "Read-Write" properties on the Task Bean and may provide zero or more outputs that are represented as Read-Only properties. The properties are provided by the specific bean implementation and are not part of the ITask interface. The task may be executed either synchronously or asynchronously via the ITask interface and provides status events via the ITaskListener interface.

The typical way to use a Task Bean is:-

1. Create the task bean
2. Set its input properties
3. Execute the task
4. Get its output properties
5. Destroy the task bean (garbage collection in Java)

Different products provide their own implementations of Task Beans which represent client or server tasks such as screen navigation task, CICS transaction execution task etc. Task beans may be generated by a utility automatically based on predefined inputs or may be hand-coded as custom code.

Table data inputs or outputs of a task bean are represented by indexed properties.

A task bean may use back-end resources to execute the task such as a TCP/IP session or a terminal session. Such a resource is represented in an abstract form known as the "Context". Server implementations are typically optimized to use "just-in-time" management of back-end resources. This causes the resource to be allocated just before task execution and freed up immediately after task completion. However, there are situations when it is necessary to continue execution from one task bean to another using the same back-end resource. The ITask interface provides the client the ability to preserve the back-end resource context after the execution of the task using the setPreserveContext and transferContext methods. Some task beans may also allow sharing the resource context by using copyContext.

The Context creation, back-end resource association/selection and destruction is handled by the task bean. A client program may only choose to transfer or copy the context to another task bean when the context is valid. The context validity depends on the status of the task and the various preserve modes as given in the following table.

Preserve Context Mode	TASK_CREATED	TASK_STARTED	TASK_SUCCESSFUL	TASK_CANCELED	TASK_FAILED	TASK_TIMEOUT
PRESERVE_ALWAYS	No	Yes	Yes	Yes	Yes	Yes
PRESERVE_ON_ERROR	No	Yes	No	No	Yes	Yes
PRESERVE_NEVER	No	Yes	No	No	No	No

Table 1: Context availability

Implementation Notes:

1. Beans implementing this interface must supply a zero-argument constructor for use with scripting engines and other containers.
2. Task bean implementations may need to run on a remote client. One way to do this is to use RMI between an ultra-thin task bean and the remote server that actually performs the task. Different products may have other ways to do the remoting.
3. Task implementors may need to synchronize on the context object, the execute methods and context management methods to prevent unintentional concurrent resource access.
4. This interface provides no mechanism to gain access to the context object. This means that context cannot be passed as a parameter between beans in separate methods or scope.
5. This interface does not provide full transaction support. Beans that support local transactions (begin, commit and rollback) will need to also implement IConnectorLocalTransaction.

Field Summary

static int	PRESERVE_ALWAYS Always preserve context after task execution
static int	PRESERVE_NEVER Do not preserve context after task execution (default)
static int	PRESERVE_ON_ERROR Preserve context on task execution errors only

Method Summary

void	addTaskListener(ITaskListener listener) Adds a new task listener to this bean.
void	cancel() Cancels the currently executing task and fires a task status change event with a TASK_CANCELED completion status.
void	clearContext() Removes a context from a bean.
void	copyContext(ITask source) Copies a context from one bean to another.
void	executeAsync() Asynchronously executes the task using the current property settings.
void	executeSync() Synchronously executes the task using the current property settings.
java.lang.String	getInstanceName() Retrieves a user-defined instance name, such as an identifier for the bean on a web page or other bean container.
java.lang.String	getJobName() Retrieves user-defined job name, such as a JSP web path.
java.util.Locale	getLocale() Retrieves the locale property for the current instance of this bean.
int	getPreserveContext() Retrieves the current preserve context mode.
java.lang.String	getResourceName() Retrieves the name of the resource configuration in use by this bean
TaskStatusChangeEvent	getStatus() Returns the current task execution status.
long	getTimeout() Retrieves the current task timeout in milliseconds.
java.lang.String	getVersion() Retrieves the version of the user's development environment or other user-specified version information, such as a date code.
void	removeTaskListener(ITaskListener listener) Removes the specified task listener from this bean.
void	setInstanceName(java.lang.String name) Sets a user-defined instance name, such as an identifier for the bean on a web page or other bean container.
void	setJobName(java.lang.String name) Sets a user-defined job name, such as a JSP web path.
void	setLocale(java.util.Locale locale) Sets the locale property for the current instance of this bean.
void	setPreserveContext(int mode) Sets the preserve context mode.
void	setResourceName(java.lang.String name) Sets the name of the resource to use with this bean.
void	setTimeout(long milliseconds) Sets the task timeout in milliseconds.
void	transferContext(ITask source) Transfers a context from one bean to another.

Field Detail

PRESERVE_NEVER

public static final int PRESERVE_NEVER

Do not preserve context after task execution (default)

See Also:

Constant Field Values

PRESERVE_ON_ERROR

public static final int PRESERVE_ON_ERROR

Preserve context on task execution errors only

See Also:

Constant Field Values

PRESERVE_ALWAYS

public static final int PRESERVE_ALWAYS

Always preserve context after task execution

See Also:

Constant Field Values

Method Detail

setPreserveContext

public void setPreserveContext(int mode)
                        throws java.lang.IllegalArgumentException

Sets the preserve context mode. An execution context is created automatically when the task bean executes. The execution context describes a link to the data source connection. The default behavior is to clear the context after execution. This property can be set at any time, however, the context disposition will proceed based on the mode setting that is in effect on completion of execute.

Parameters:

mode - one of the preserve context mode constants.

• PRESERVE_NEVER -- Do not preserve context after task execution (default)
• PRESERVE_ON_ERROR -- Preserve context on task execution errors only
• PRESERVE_ALWAYS -- Always preserve context after task execution

Throws:

java.lang.IllegalArgumentException - if mode is out of range

See Also:

getPreserveContext( ), transferContext( ITask ), copyContext( ITask ), clearContext( )

getPreserveContext

public int getPreserveContext()

Retrieves the current preserve context mode.

Returns:

the current preserve context mode or PRESERVE_NEVER if not set.

See Also:

setPreserveContext( int ), transferContext( ITask ), copyContext( ITask ), clearContext( )

transferContext

public void transferContext(ITask source)
                     throws ResourceInUseException

Transfers a context from one bean to another. Removes the context from the source bean. The following code fragment illustrates usage:

 bean1.execute( );                // context is auto-created
 bean2.transferContext( bean1 );  // transfer context from bean1 to bean2
 bean2.execute( );                // execute bean2
 

A task bean may get its context from another bean or may generate its own context. Typically, the context is automatically generated at when executeSync or executeAsync is called. Therefore this method may only be called following task execution.

Parameters:

source - the bean to transfer the context from

Throws:

ResourceInUseException - if another task is using the context

See Also:

copyContext( ITask ), setPreserveContext( int ), clearContext( )

copyContext

public void copyContext(ITask source)
                 throws UnsupportedOperationException

Copies a context from one bean to another. Does not remove the context from the source bean. Not supported by all resources or implementations.

A task bean may get its context from another bean or may generate its own context. Typically, the context is automatically generated at when executeSync or executeAsync is called. Therefore this method may only be called following task execution.

Parameters:

source - the bean to copy the context from

Throws:

UnsupportedOperationException - if the implementation does not support this method.

See Also:

transferContext( ITask ), setPreserveContext( int ), clearContext( )

clearContext

public void clearContext()
                  throws ResourceInUseException

Removes a context from a bean.

The context is cleared automatically after execution by default unless the preserve mode indicates otherwise. This method has no effect if context has not been created.

Implementation Notes:

1. When a context is not shared between task beans, the associated resources are also freed.
2. When a context is shared between multiple beans using copyContext, calling clearContext on a given task bean will end the use of the resources for that bean, but it should have no effect on other beans still using the context. The context should be completely reclaimed when clearContext is called on the last bean.
3. The implementation should not rely on automatic garbage collection to reclaim context resources.

Throws:

ResourceInUseException - if the task is using the context

See Also:

transferContext( ITask ), copyContext( ITask ), setPreserveContext( int )

setTimeout

public void setTimeout(long milliseconds)

Sets the task timeout in milliseconds. Controls the length of time a task can execute before firing a task status change event with a TASK_TIMEOUT completion status.

Parameters:

milliseconds - the maximum time to wait for task execution to complete. Default is Long.MAX_VALUE.

If a task does not complete within the specified timeout starting from the call to executeSync() or executeAsync() the task bean will attempt to cancel the task execution. Due to a race condition between the attempt to cancel and the completion of the task, the cancel attempt may not necessarily succeed.

See Also:

getTimeout( ), ITaskListener, TaskStatusChangeEvent

getStatus

public TaskStatusChangeEvent getStatus()

Returns the current task execution status. The event object contains the following task status information:

• event.status -- one of the event status constants defined in TaskStatusChangeEvent
• event.exception -- optional exception information. May be null.

Returns:

the last status change event that was fired, or an event with TASK_CREATED status if the task has never executed.

getTimeout

public long getTimeout()

Retrieves the current task timeout in milliseconds.

Returns:

the maximum time in milliseconds to wait for task execution to complete. Default is Long.MAX_VALUE.

If a task does not complete within the specified timeout starting from the call to executeSync() or executeAsync() the task bean will attempt to cancel the task execution. Due to a race condition between the attempt to cancel and the completion of the task, the cancel attempt may not necessarily succeed.

See Also:

setTimeout( long ), ITaskListener, TaskStatusChangeEvent

executeSync

public void executeSync()
                 throws ResourceInUseException

Synchronously executes the task using the current property settings. Fires task status change events to track the task execution progress. Does not return until the task completes, times out or is canceled. Uses the currently owned context, or creates one if none has been set.

Throws:

ResourceInUseException - if task is already executing

See Also:

executeAsync( ), cancel( ), ITaskListener, TaskStatusChangeEvent

executeAsync

public void executeAsync()
                  throws ResourceInUseException

Asynchronously executes the task using the current property settings. Starts a thread that calls executeSync. This method returns without waiting for the task to complete. Listeners will be notified of task progress and completion status via the task status change events. Uses the currently owned context, or creates one if none has been set.

Throws:

ResourceInUseException - if task is already executing

See Also:

executeSync( ), cancel( ), ITaskListener, TaskStatusChangeEvent

cancel

public void cancel()

Cancels the currently executing task and fires a task status change event with a TASK_CANCELED completion status.

Due to a race condition between the attempt to cancel and the completion of the task, the cancel attempt may not necessarily succeed.

Implementation Notes:

1. In synchronous execution, cancel must be able to interrupt executeSync.
2. Since executeSync blocks, cancel must be capable of being called from a separate thread.

See Also:

executeSync( ), executeAsync( ), ITaskListener, TaskStatusChangeEvent

addTaskListener

public void addTaskListener(ITaskListener listener)

Adds a new task listener to this bean.

Parameters:

listener - the new listener to add

removeTaskListener

public void removeTaskListener(ITaskListener listener)

Removes the specified task listener from this bean.

Parameters:

listener - the listener to remove

getVersion

public java.lang.String getVersion()

Retrieves the version of the user's development environment or other user-specified version information, such as a date code. This read-only property is a bean generator input parameter.

Returns:

version string or blank string if not set

setInstanceName

public void setInstanceName(java.lang.String name)

Sets a user-defined instance name, such as an identifier for the bean on a web page or other bean container. This name need not be unique.

A monitor or trace/log facility could display this string if lower level objects pass it through.

Parameters:

name - optional instance name

See Also:

getInstanceName( ), setResourceName( String ), setJobName( String )

getInstanceName

public java.lang.String getInstanceName()

Retrieves a user-defined instance name, such as an identifier for the bean on a web page or other bean container. This name may not be unique.

Returns:

instance name or a blank string if not set

See Also:

setInstanceName( String ), getResourceName( ), getJobName( )

setResourceName

public void setResourceName(java.lang.String name)

Sets the name of the resource to use with this bean. This name refers to the resource or resource configuration to be used with this task. The default ResourceName is the fully qualified class name.

Implementation Notes:

1. This property may be used by the system to look up a mapping to a resource, such as a server address, data source name, etc.
2. A monitor or tracing/log facility could display this string if lower level objects pass it through.

Parameters:

name - the name of the resource to use

See Also:

getResourceName( ), setInstanceName( String ), setJobName( String )

getResourceName

public java.lang.String getResourceName()

Retrieves the name of the resource configuration in use by this bean

Returns:

resource name or fully qualified class name if not set

See Also:

setResourceName( String ), getInstanceName( ), getJobName( )

setJobName

public void setJobName(java.lang.String name)

Sets a user-defined job name, such as a JSP web path. This name need not be unique.

A monitor or tracing/log facility could display this string if lower level objects will pass it on through.

Parameters:

name - user-defined job name

See Also:

getJobName( ), setInstanceName( String ), setResourceName( String )

getJobName

public java.lang.String getJobName()

Retrieves user-defined job name, such as a JSP web path. This name may not be unique.

Returns:

job name or a blank string if not set

See Also:

setJobName( String ), getInstanceName( ), getResourceName( )

setLocale

public void setLocale(java.util.Locale locale)

Sets the locale property for the current instance of this bean. Implementations can use locale information to select character set translation tables, number and date formatting, time zone calculations, etc. If not set, the task bean assumes the current default system locale. The locale setting can be changed at any time. The methods executeSync and executeAsync sample the locale on method entry, and will use that value for that invocation.

Parameters:

locale - the new locale setting

getLocale

public java.util.Locale getLocale()

Retrieves the locale property for the current instance of this bean. Implementations can use locale information to select character set translation tables, number and date formatting, time zone calculations, etc. If not set, the task bean assumes the current default system locale.

Returns:

the current locale setting, or the system default if not set