Task definition file - Appistry EAF v3.7

The task definition file identifies the module file, implementation, and all the tasks and methods defined in the module. Below is the basic syntax of a task definition file.

<?xml version='1.0'?>
<!DOCTYPE task SYSTEM 'ModuleDefinition.dtd'>
<module file='library, assembly, jar or class filename' implementation='DLL or Java or .NET' className='Java or .NET class name'>
  <task name='actual method_function_name' type='unlimited'/>
  <task name='alias_name' type='unlimited'>
    <method>actual_method_function_name</method>
    <onStartup>onStartup_method_function_name</onStartup>
    <onShutdown>onShutdown_method_function_name</onShutdown>
    <isAvailable>isAvailable_method_function_name</isAvailable>
  </task>
  <affinity-task name='actual_method_function_name'/>
  <affinity-task name='alias_name'>
    <method>actual_method_function_name</method>
  </affinity-task>
  <task name='alias_name' type='limited' min='number' max='number' percentage='percentage'>
    <method>actual_method_function_name</method>
    <onStartup>onStartup_method_function_name</onStartup>
    <onShutdown>onShutdown_method_function_name</onShutdown>
  </task>
  <task name='alias_name' type='exclusive' busy-wait-time='milliseconds'>
    <method>actual_method_function_name</method>
    <onStartup>onStartup_method_function_name</onStartup>
    <onShutdown>onShutdown_method_function_name</onShutdown>
  </task>
  <task name='alias_name' type='background' instances='number' retryDelay='milliseconds'>
    <method>actual_method_function_name</method>
  </task>
  <task name='alias_name' type='background' percentage='percentage' retryDelay='milliseconds'>
    <method>actual_method_function_name</method>
  </task>
</module>

Module element

The module element has three attributes: file, implementation, and className. The file attribute contains the compiled code file name and is case sensitive.

The implementation attribute identifies the tasks' run-time environment. This attribute has three possible values.

.NET Create the task to the application fabric task interface using a .NET-managed language and compile. The task handler calls classes in the assembly.
DLL Create the task to the fabric task interface and compile a Linux C shared object or Windows C DLL. The task handler calls the functions.
Java Create the task to the fabric task interface and compile in Java. The task handler loads the Java environment and calls the Java byte code.

The className attribute is required if the implementation is .NET or Java. This attribute is ignored if the implementation equals DLL. Below is an example of a module element with a DLL implementation.

<module file='tutorial_tasks.so' implementation='DLL' >

In .NET and Java, the className identifies the class containing the task implementation. The className value is the fully-qualified name of the class including namespace.

<module file='VBdotnet.dll' implementation='.NET' className='Acme.VBTask'>

In Java, the className identifies the location of the Java class file. The className value is the fully-qualified name of the class including package.

<module file='JavaTask.class' implementation='Java' className='com.acme.tasks.JavaTask'>

In the following Java example the task class is inside a jar.

<module file='acme.jar' implementation='Java' className='com.acme.tasks.JavaTask'>

Task element

The task element has at least two attributes: name, type. Additional attributes are available based on the task type.

The name attribute is the name of the task and must be identical to the task name used in the process flow. The name may be the exact name of the function or method to be called, or it may be an alias. If the name is an alias, then a cooresponding method element (see below) must be used. This attribute is case sensitive.

The type attribute indicates if the task is unlimited, limited, exclusive, or background. If the type attribute is not included, the task is considered unlimited.
The Unlimited task type does not have additional attributes. The limited task type has min, max, and percentage attributes. The background task type has percentage or instances, and retryDelay attributes. The exclusive task type has the busy-wait-timeout attribute.

The fabric is capable of running multiple, concurrent instances of a task on a worker or CPU. However, this is not always desirable. Appistry EAF allows you to configure a task by classifying it as one of four types and adding parameters based on the task type. The table below provides a basic overview of the four task types. For in depth explanations, refer to the appropriate task's tutorial.

Task Type	Characteristics	Configuration	Tutorial
Unlimited	No restrictions Multiple instances may run concurrently on multiple workers in the fabric Multiple requests for the task are serviced concurrently depending on available memory and CPU	Task XML file	Hello World with Process Flows and tasks
Limited	Only a specified number of instances may run concurrently in the fabric (for example, a limited task may be configured to run on 2 out of 10 workers) A worker may run multiple instances of the task Multiple requests for the task are serviced concurrently depending on configuration, available memory, and CPU	Task XML file
Exclusive	Only a specified number of instances may run concurrently per worker or per CPU (for example, an exclusive task will run on every worker but be restricted to only one instance at a time based on worker or CPU) The fabric performs load control to balance requests for exclusive tasks across the fabric When multiple requests for an exclusive task arrive on a single worker, the requests are executed in a gated fashion. For example, if exclusive tasks are configured to allow two concurrent per worker, then two requests are serviced at a time while other requests wait their turn. Good for long running tasks (several seconds or more) or CPU intensive	Task XML file and fabric.cfg	Computing Pi using Exclusive Tasks tutorial
Background	Runs constantly waiting for work (like a unix daemon or Windows service) Background tasks are not called from a process flow as part of a client request, but rather get "work" as defined by the task implementer. For example, the background task might monitor a queue in fabric accessible memory (FAM), read from a socket. or poll a service external to the fabric. Since it is not part of a fabric request, background tasks do not have the same inherent reliability as the other task types	Task XML file

Unlimited Tasks
The unlimited task type does not have additional attributes beyond the mentioned name and type.

Please note the first uses the exact name of the method to be called, and the second uses an alias.

<task name='calculateShipmentDate' type='unlimited'/>

or

<task name='calcShipDate' type='unlimited'>
    <method>calculateShipmentDate</method>
</task>

Limited Tasks
Limited tasks define the following additional attributes:

The min attribute indicates the minimum number of instances this task can run at one time. This attribute must be greater than zero.
The max attribute indicates the maximum number of instances this task can run at one time. This attribute must be greater than the minimum value.
The percentage attribute indicates the percentage of workers that can run one instance of the task.

For limited tasks, the percentage attribute must be greater than zero and less than or equal to 100. The min and max values override this value. For example, if an application fabric consists of 100 workers and a limited task has a percentage value of 10, a min value of 2 and a max value of 5, only 5 instances of this task can run at the same time.

<task name='enterOrderToDB' type='limited' min='5' max='20' percentage='25'>

Exclusive Tasks
Exclusive tasks define the following additional attribute:

The busy-wait-timeout attribute indicates the amount of time, in seconds, the fabric waits for an available worker when workers running exclusive tasks are busy. This attribute is only available if the task type is exclusive. A value of INFINITE means that the fabric will wait indefinitely.

<task name='computePi' type='exclusive' busy-wait-timeout='2'>

Background Tasks
Background tasks define the following additional attributes:

The percentage attribute indicates the percentage of workers that can run one instance of the task. If a background task includes the instances attribute, the percentage attribute is not available.
The instances attribute indicates the total number of instances of the task running in the fabric at one time. This number may be greater than the number of workers in the fabric. If a background task includes the percentage attribute, the instances attribute is not available.
The retryDelay attribute indicates the amount of time, in milliseconds, the fabric waits before attempting to rerun the execute method. This delay applies only if an error occurs when the fabric is trying to rerun the execute method. Background tasks that complete successfully immediately begin processing the next task.

For background tasks, the percentage attribute must be greater than zero and may be greater than 100. For example, if an application fabric consists of 100 workers and a background task has a percentage value of 150, 150 instances of this task can run at the same time.

<task name='processVendorFeedEvents' type='background' percentage='10' retryDelay='10000'>

or

<task name='processVendorFeedEvents' type='background' instances='1' retryDelay='10000'>

Affinity-task element

The affinity-task element identifies a method or function whose purpose is to help the fabric direct work to a worker with the needed capacity, resource, etc. for a specific piece of work requested by a process flow state. The affinity-task is specified in one or more process flow definitions, and a corresponding entry in the Task definition file is required.

The name attribute is the name of the affinity task and must be identical to the affinity task name used in the process flow. The name may be the exact name of the function or method to be called, or it may be an alias. If the name is an alias, then a cooresponding method element (see below) must be used. This attribute is case sensitive.

<affinity-task name='isDataInLocalCache'/>

or

<affinity-task name='checkCache'>
    <method>isDataInLocalCache</method>
</affinity-task>

Method element

The method element identifies a task's actual execute function or method. This element is a child of the task and affinity-task elements and is only required when the name attribute of the parent element is an alias for the actual function or method name. Below is an example of a method element.
Please note the first uses the exact name of the method to be called, and the second uses an alias.

<task name='calculateShipmentDate' type='unlimited'/>
<task name='calcDelivery' type='unlimited'>
    <method>calculateDeliveryDate</method>
</task>

onStartup element

The onStartup element names a function that accepts no input values. This function allows you to setup a task for processing. Each fabric application is hosted by a task service. The onStartup function of a given task is called once and only once when the task service starts up. An example of an onStartup function is opening a connection to a database. This is an optional element, and a child of the task element, and must follow the method element. Below is an example of an onStartup element.

<onStartup>openConnection</onStartup>

onShutdown element

The onShutdown element names a function that accepts no input values. This function allows you to cleanup a task before shutdown. Each fabric application is hosted by a task service. The onShutdown function of a given task is called once and only once when the task service shuts down. An example of an onStartup function is closing a database connection. This is an optional element, and a child of the task element, and must follow the onStartup element. Below is an example of an onShutdown element.

<onShutdown>closeConnection</onShutdown>

isAvailable method

Deprecated: You can use affinity tasks for this functionality and more.

The isAvailable element names a boolean method or function that accepts no input values. This method or function returns true or false to indicate if the worker is available to perform a function at that time. For example, if the worker loses the database connection, the isAvailable returns false until the connection is restored and the worker does not accept work that requires this function. This is an optional element, and a child of the task element, and must follow the onShutdown element. The actual method or function must be implemented by the fabric task developer.

<isAvailable>myIsAvailableMethod</isAvailable>

Example task definition files

Unlimited task

<?xml version='1.0'?>
<!DOCTYPE task SYSTEM 'ModuleDefinition.dtd'>
<module file='tutorial_tasks.dll' implementation='DLL' >
  <task name='releaseHold_task'/>
  <affinity-task name='name'>
    <method>method_function_name</method>
  </affinity-task>
</module>

Limited task

<?xml version='1.0'?>
<!DOCTYPE task SYSTEM 'ModuleDefinition.dtd'>
<module file='tutorial_tasks.dll' implementation='DLL' >
  <task name='enterOrderToDB' type='limited' min='5' max='20' percentage='25'>
    <method>enterOrderToDB</method>
    <onStartup>openConnection</onStartup>
    <onShutdown>closeConnection</onShutdown>
  </task>
</module>

Exclusive task

<?xml version='1.0'?>
<!DOCTYPE task SYSTEM 'ModuleDefinition.dtd'>
<module file='tutorial_tasks.dll' implementation='DLL'>
  <task name='itemPurchase_task' type='exclusive'/>
</module>

Background tasks

<?xml version='1.0'?>
<!DOCTYPE task SYSTEM 'ModuleDefinition.dtd'>
<module file='tutorial_tasks.dll' implementation='DLL'>
  <task name='myBackgroundTask' type='background' instances='5' retryDelay='1000'>
    <method>queue_pushPop</method>
  </task>
</module>