JACK——TeamsManual4 TeamPlans
4 TeamPlans
A teamplan specifies how a task is achieved in terms of one or more roles. It typically contains steps determining which of the sub-teams nominated to perform the roles in the role obligation structure will in fact perform each role (a process known as task team formation). It also dictates the steps directing each sub-team to achieve specific goals.
Teams provides additional constructs to support both activities (the establish() reasoning method and the @teamAchieve statement). The JACK @parallel statement supports non-sequential coordination of sub-team behaviour. As team behaviour (embodied in a teamplan) is specified in terms of roles, it is decoupled from the actual sub-team behaviour. Thus team behaviour can be specified and understood independently of sub-team behaviour.
4.1 TeamPlan Definition
TeamPlan definitions take the form shown below:
teamplan PlanType extends TeamPlan
{
#handles event EventType event_ref;
// possible declarations about required roles etc.
// Plan method definitions, reasoning methods
// and JACK Agent Language declarations describing
// relationships to other components etc.
// optional relevant method
static boolean relevant (EventType event_ref)
{
// code to determine if the plan
// is relevant
}
// optional context method
context()
{
// logical condition to determine which
// plan instances are applicable
}
// optional establish method
#reasoning method establish()
{
// code to establish the task team for the task
}
body()
{
// The plan body. This describes the actual steps
// an agent performs when it executes this plan.
// It includes Java code, JACK Agent Language
// @-statements, and in addition @teamAchieve
// statements for use within TeamPlans.
}
}
Each component of this definition is explained in the following table:
| Syntax Term |
Description |
| teamplan |
A Teams Language keyword used to introduce a TeamPlan definition. |
| PlanType |
The name of your derived TeamPlan class. |
| extends TeamPlan |
This part of the statement plays the same role as in Java – it indicates that the teamplan being defined inherits from a Teams Language base class called TeamPlan. The TeamPlan base class provides the generic plan processing implementation and the overridable stub for task team formation. |
| #handles event EventType event_ref |
Specifies the event type that this plan handles. The plan may place further constraints on its applicability via the relevant() and context() methods. |
| static boolean relevant(EventType event_ref) |
Code to determine if the plan is relevant for the instance of the event being handled. |
| context() |
Logical condition to determine which plan instances are applicable. |
| #reasoning method establish() |
Code to establish the task team for the plan. |
| body() |
Describes the actual work done by the team when the plan is executed. It is the plan's top-level reasoning method. If it succeeds the plan succeeds. If it fails the plan fails. |
Table 4-1: Components of a TeamPlan definition
4.2 TeamPlan Declarations
The teamplan can use any of the declarations that are available in JACK agent plans. In addition they can have declarations relating to the roles required to establish the task team for the plan and a declaration specifying the role for which the plan is applicable.
#requires role RoleType rolecontainer_ref as role_ref
This declaration states that the current plan requires an instance of the role RoleType. This declaration is used in the teamplans of the role tenderer, where the reference to the role container instance rolecontainer_ref can be used to access the role container to find an appropriate instance of the role RoleType to satisfy this role in the task team. This selection of the role instance occurs during the task team establishment phase. During this phase, role_ref will be set to refer to the selected performer and will subsequently be used as a reference to this role instance in the plan. role_ref is used to issue a @teamAchieve. This is because the team executing the plan needs a reference to the role filler (via the role reference) in order to issue the @teamAchieve.
The #requires role declarations are used instead of the #uses role declarations when the plan is to use the default establish reasoning method to select the role instance.
Events are posted to the role filler by the @teamAchieve statement via the role specification. As such, the programmer need not declare that the event being handled by the role filler is posted in the plan.
Each component of the #requires role declaration is explained in the following table:
| Component |
Meaning |
| #requires role |
Specifies that the plan makes use of this role. |
| RoleType |
The role type that is used by the plan. |
| rolecontainer_ref |
A local reference that is used to perform operations on the role container. |
| role_ref |
A local reference that is used to perform operations on the role instance. |
Table 4-2: Components of the #requires role declaration
#requires role RoleType rolecontainer_ref as role_ref (size)
This form of the #requires role declaration is the same as the previous version except that it specifies that the plan now needs size performers from the rolecontainer_ref. During the team establishment phase, the variable role_ref will be set to an array that contains the selected performers.
#uses role RoleType rolecontainer_ref as role_ref
This declaration states that the current plan makes use of an instance of the role RoleType. The declaration is used in the teamplans of the role tenderer, where the reference to the role container instance rolecontainer_ref can be used to access the role container to find an appropriate instance of the role RoleType to satisfy this role in the task team. role_ref will be used as a reference to this role instance in the plan. role_ref is used to issue a @teamAchieve. This is because the team executing the plan needs a reference to the role filler (via the role reference) in order to issue the @teamAchieve.
The #uses role declarations are used instead of the #requires role declarations when the plan overrides the default establish reasoning method to select the role instance.
Events are posted in the role filler by the @teamAchieve statement via the role specification. As such, the programmer need not declare that the event being handled by the role filler is posted in the plan.
| Component |
Meaning |
| #uses role |
Specifies that the plan makes use of this role. |
| RoleType |
The role type that is used by the plan. |
| rolecontainer_ref |
A local reference that is used to perform operations on the role container. |
| role_ref |
A local reference that is used to perform operations on the role instance. |
Table 4-3: Components of the #uses role declaration
#uses role RoleType rolecontainer_ref as role_ref (size)
This form of the #uses role declaration is the same as the previous version except that it specifies that the plan now needs size performers from the rolecontainer_ref. During the team establishment phase, the variable role_ref will be set to an array that contains the selected performers.
#uses role RoleType rolecontainer_ref
This last anonymous role usage declaration form provides direct access to the team's role container for reviewing and selecting performers, and for team-level manipulation of resources, such as assignment or revocation of roles. The container is referred to with its team reference name, i.e. rolecontainer_ref.
#applicable_for role RoleType roleinstance_ref
This declaration occurs in plans of the role filler. It indicates that the plan should not only react to the event it handles, it should also test for applicability based on the currently active role.
| Component |
Meaning |
| #applicable_for role |
Specifies that this plan is only applicable for certain roles. |
| RoleType |
The role type that this plan is applicable for. |
| roleinstance_ref |
A local reference that is used to perform operations on the role instance. |
Table 4-4: Components of the #applicable_for role declaration
#applicable_from role RoleType roleinstance_ref
This declaration occurs in plans of the role tenderer. It indicates that the plan should not only react to the event it handles, it should also test for applicability based on the role relationship it is currently acting under. This form of applicability declaration checks that it has a peer relationship with the team that initiated the @teamAchieve.
| Component |
Meaning |
| #applicable_from role |
Specifies that this plan is only applicable for certain peer role relationships. |
| RoleType |
The role type that this plan is applicable for. |
| roleinstance_ref |
A local reference that is used to perform operations on the role instance. |
Table 4-5: Components of the #applicable_from role declaration
4.3 Task Team Establishment
The task team establishment stage is an initial execution stage for a teamplan, for the purpose of establishing which particular role performers to use for the plan. Technically, the task team establishment stage is achieved by a reasoning method that is performed prior to the plan body when a plan is chosen for execution. Task team establishment may fail, in which case the plan fails.
The task team establishment method is defined in a teamplan as a reasoning method:
#reasoning method establish()
{
...
}
There is a default task team establishment method, defaultEstablish(), which fills all the #requires role usages with distinct performers. They are selected by repeatedly calling the nextFiller() method of the appropriate role containers. The default establishment only selects active role objects (discussed in the chapter on Team Formation), and requires all fillers to be distinct. The #uses role declarations are then left unfilled; for the plural case, the array is constructed though left unfilled.
An explicit establish() reasoning method will override the default task team establishment method and be solely responsible for identifying and assigning task team role fillers.
Alternatively, an application may override a role container's nextFiller() method by means of the #container method statement in the role definition.
4.4 TeamPlan Members and Methods
The TeamPlan has access to the same members and methods described in the chapter on JACK Agent plans in the Agent Manual. In addition, the TeamPlan has the #reasoning method establish() which was described in the section on Task Team Establishment.
4.5 Team Goal Handling
The Team Modelling Framework includes all JACK BDI programming facilities, and provides extra team goal handling support through the additional @teamAchieve statement.
The @teamAchieve statement is used in a teamplan to sub-task a goal for a team member. The statement may then succeed or fail depending on whether the team member succeeded or failed in reaching the goal. The infrastructure deals with the necessary inter-team coordination, and in particular, takes care of the required task control to deal with all cases of success, failure, or exception propagation.
The JACK @parallel statement is used in a teamplan as a program control structure to sub-task goals for several team members in parallel, or more precisely, to progress on several branches of activity in the teamplan in parallel. The success or failure of the statement depends on the successes and failures of the parallel branches involved. The programmer specifies whether all branches need to succeed or whether it is sufficient that at least one branch succeed. The programmer also specifies whether to wait for all branches to complete before the statement completes, or whether to complete the statement as soon as possible (e.g. with the first successful branch, if the success of one branch is sufficient).
The @parallel statement provides a very powerful mechanism for expressing teamplans. The implied task synchronisation reduces the effort of programming coordinated activity, in particular while focusing on the "success paths". Recovery procedures, contingency planning and their effect on coordination, require careful design and use of the task control statements available in JACK.
The underlying concept is that in failing a sub-task, a sub-team may qualify the failure, i.e. "fail for a reason", for which the teamplan might include a contingency. This is a slightly different execution model than BDI, where failing to complete a plan results in a reposting of the goal, to allow another plan to be used. For team tasks, the recovery on failure needs to be dealt with at the teamplan level as it, for instance, may involve re-tasking other sub-teams as well as the sub-team failing its task. At the same time, the recovery may also allow some other parallel tasks to progress without interrupts.
Further, the choice of which particular response to make at the team level in reaction to the failure of a sub-team to complete its task is a dynamic choice that may depend both on any partial success the sub-team has had towards its goal, and the more global situation at hand, including the current state of other sub-teams.
4.6 TeamPlan @-statements
The teamplan reasoning methods can use any of the @-statements that are available in JACK agent plans. In addition they can combine the @teamAchieve and JACK @parallel statements to coordinate and sub-task sub-teams that have been selected to perform particular roles as part of the teamplan's task team.
The @teamAchieve statement is described in more detail in the next sections.
4.6.1 The @teamAchieve Statement
The @teamAchieve declaration is used to activate a sub-team (role filler) by posting an event to the sub-team. The team that posted the @teamAchieve then waits until the event has been processed.
Note: @team_achieve has been deprecated in favour of @teamAchieve.
The @teamAchieve has the following form:
@teamAchieve(roleinstance_ref, EventInstance)
Each parameter of the above definition is described in the following table:
| Component |
Meaning |
| @teamAchieve |
Introduces the @teamAchieve statement, which issues a directive to a sub-team, via the role. |
| roleinstance_ref |
A local reference to the role object that defines the relationship between the team (role tenderer) and sub-team (role filler). The roleinstance_ref is obtained from one of the following statements; #uses role, #requires role, #applicable_for role or applicable_from role. |
| EventInstance |
EventInstance is a reference to an event derived from MessageEvent. It is declared and instantiated as for a normal JACK statement (see, for instance, @send). The event being sent to the sub-team (role filler) must be declared as being #handles event by the role. |
Table 4-6: Components of the @teamAchieve statement
The EventInstance used in the @teamAchieve is obtained by accessing the event declaration in the role that the plan uses. For example, a plan might contain the following lines:
teamplan Plan9 extends TeamPlan {
#requires role RoleA rolecontainer as role_ref;
body()
{
...
@teamAchieve(role_ref, role_ref.eventref.postingMethod());
...
}
}
This example would require that a role, RoleA, had declared an event with an event reference, eventref. The posting method of this event is called to generate an event instance inline.
Optionally, the event can be pre-constructed and a reference kept locally in the plan. This local reference to the event instance could be used to check the value of event members after the @teamAchieve has returned.
As mentioned previously, @teamAchieve suspends the execution of the containing teamplan until the event has been processed in the sub-team. A @teamAchieve terminates successfully if the event has been successfully handled by the sub-team, otherwise it fails.
The @teamAchieve statement can also be used to post events back to the peer of the team performing the plan, with the following syntax:
@teamAchieve(roleinstance_ref.peer, EventInstance)
4.6.1.1 Getting Return Values Through @teamAchieve
The technique for communicating the results of the processing of a @teamAchieve event to the commanding team is as follows:
The sub-team plan handling an event sub-tasked by a @teamAchieve can change the fields of its local copy of the event. When the plan succeeds, these fields are copied back into the event instance that was originally used in the teamplan executing the @teamAchieve. Thus, if a handle to that event instance is maintained, it is then possible to retrieve all fields that have been changed.
4.6.1.2 Exception Propagation for @teamAchieve
During the handling of an event sub-tasked with @teamAchieve, a team may throw a Java exception. If this is not caught by the handling plan, it is propagated back to the team that is executing the @teamAchieve statement in the following way:
- If the exception is a TeamException, then the same exception is thrown to the teamplan executing the @teamAchieve;
- If the original exception is not a TeamException, then a TeamError is thrown to the teamplan executing the @teamAchieve.
A @teamAchieve may also be interrupted by an exception thrown to it by a parallel execution branch in the teamplan. In this case, the infrastructure notifies the active sub-team so that a TeamAbort is thrown to the plan handling the @teamAchieve event.