Verastream Transaction Integrator 4.0

com.attachmate.tasks
Interface ITask

All Known Implementing Classes:
BaseTaskBean, BaseTxBean

public interface ITask

Contains method definitions to be implemented by all Task Beans.

Task Beans are standard Java beans that represent a particular client operation to be performed. A client operation 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 client operation 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 client operation
  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 client operations such as the Transaction Integrator for CICS and the Transaction Integrator for IMS. 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 client operation 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 client operation execution and freed up immediately after client operation 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 client operation 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 client operation and the various preserve modes as given in the following table.

Preserve Context ModeTASK_CREATEDTASK_STARTEDTASK_SUCCESSFULTASK_CANCELEDTASK_FAILEDTASK_TIMEOUT
PRESERVE_ALWAYSNoYesYesYesYesYes
PRESERVE_ON_ERRORNoYesNoNoYesYes
PRESERVE_NEVERNoYesNoNoNoNo
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 client operation. Different products may have other ways to do the remoting.
  3. Clients 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 // * .


Field Summary
static int PRESERVE_ALWAYS
          Always preserve context after client operation execution
static int PRESERVE_NEVER
          Do not preserve context after client operation execution (default)
static int PRESERVE_ON_ERROR
          Preserve context on client operation execution errors only
 
Method Summary
 void addTaskListener(ITaskListener listener)
          Adds a new task listener to this bean.
 void cancel()
          Cancels the currently executing client operation 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 client operation using the current property settings.
 void executeSync()
          Synchronously executes the client operation 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 client operation execution status.
 long getTimeout()
          Retrieves the current client operation 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 client operation timeout in milliseconds.
 void transferContext(ITask source)
          Transfers a context from one bean to another.
 

Field Detail

PRESERVE_NEVER

static final int PRESERVE_NEVER
Do not preserve context after client operation execution (default)

See Also:
Constant Field Values

PRESERVE_ON_ERROR

static final int PRESERVE_ON_ERROR
Preserve context on client operation execution errors only

See Also:
Constant Field Values

PRESERVE_ALWAYS

static final int PRESERVE_ALWAYS
Always preserve context after client operation execution

See Also:
Constant Field Values
Method Detail

setPreserveContext

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 client operation execution (default)
  • PRESERVE_ON_ERROR -- Preserve context on client operation execution errors only
  • PRESERVE_ALWAYS -- Always preserve context after client operation execution
Throws:
java.lang.IllegalArgumentException - if mode is out of range
See Also:
getPreserveContext( ), transferContext( ITask ), copyContext( ITask ), clearContext( )

getPreserveContext

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

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 client operation execution.

Parameters:
source - the bean to transfer the context from
Throws:
ResourceInUseException - if another client operation is using the context
See Also:
copyContext( ITask ), setPreserveContext( int ), clearContext( )

copyContext

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 client operation 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

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 client operation is using the context
See Also:
transferContext( ITask ), copyContext( ITask ), setPreserveContext( int )

setTimeout

void setTimeout(long milliseconds)
Sets the client operation timeout in milliseconds. Controls the length of time a client operation can execute before firing a task status change event with a TASK_TIMEOUT completion status.

Parameters:
milliseconds - the maximum time to wait for client operation execution to complete. Default is Long.MAX_VALUE.

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

See Also:
getTimeout( ), ITaskListener, TaskStatusChangeEvent

getStatus

TaskStatusChangeEvent getStatus()
Returns the current client operation execution status. The event object contains the following task status information:

Returns:
the last status change event that was fired, or an event with TASK_CREATED status if the client operation has never executed.

getTimeout

long getTimeout()
Retrieves the current client operation timeout in milliseconds.

Returns:
the maximum time in milliseconds to wait for client operation execution to complete. Default is Long.MAX_VALUE.

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

See Also:
setTimeout( long ), ITaskListener, TaskStatusChangeEvent

executeSync

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

Throws:
ResourceInUseException - if client operation is already executing
HostResponseFormatException - if client operation execution response from the Host contains content that cannot be successfully parsed using the copybook format specified as expected client operation output when the client operation was designed.
See Also:
executeAsync( ), cancel( ), ITaskListener, TaskStatusChangeEvent

executeAsync

void executeAsync()
                  throws ResourceInUseException,
                         HostResponseFormatException
Asynchronously executes the client operation using the current property settings. Starts a thread that calls executeSync. This method returns without waiting for the client operation to complete. Listeners will be notified of client operation 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 client operation is already executing
HostResponseFormatException - if client operation execution response from the Host contains content that cannot be successfully parsed using the copybook format specified as expected client operation output when the client operation was designed.
See Also:
executeSync( ), cancel( ), ITaskListener, TaskStatusChangeEvent

cancel

void cancel()
Cancels the currently executing client operation 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 client operation, 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

void addTaskListener(ITaskListener listener)
Adds a new task listener to this bean.

Parameters:
listener - the new listener to add

removeTaskListener

void removeTaskListener(ITaskListener listener)
Removes the specified task listener from this bean.

Parameters:
listener - the listener to remove

getVersion

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

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

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

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 client operation. 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

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

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

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

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

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

Verastream Transaction Integrator 4.0