fipaos.agent.task
Class Task

java.lang.Object
  |
  +--fipaos.agent.task.Task
Direct Known Subclasses:
AgentManagementSystem.IdleTask, AgentMessagingTest.TestAgent.IdleTask, AMSDeregistrationTask, AMSRegistrationTask, AMSTask, DFDeregistrationTask, DFListenerTask, DFModifyTask, DFRegistrationTask, DFSearchTask, DFTask, DirectoryFacilitator.IdleTask, FIPAOSAgent.TopLevelHandlerTask, FIPAWrapperTask, MessageTimingAgent.IdleTask, MessageTimingAgent.MessageTestTask, MessageTimingAgent.TestingTask, PingAgent.IdleTask, SubscriptionHandlerTask, SubscriptionManagerTask, SynchronousTask, WaitTask

public abstract class Task
extends java.lang.Object

This class is an abstract representation of an agent task. It contains message dispatchers and dummy handling methods. To implement tasks in your agent, subclass this class and override the methods for the message types that you need to handle. For example, if your agent handles two conversations - one of type request and the other of contract net, then you would create two task classes that subclass this class. One that handles fipa-request protocol messages only, and on the handles fipa-contract-net messages only.

The Task-lifecycle is as follows:


Field Summary
protected  java.util.Set _children
          List of children of this task.
protected  java.lang.Object _lock
          Lock - ensures mutual exclusion between threads modifying this Task
protected  FIPAOSAgent _owner
          The agent that owns this task - should only be used for the purpose of updating/retreiving parent-Agent state information
protected  TaskManager _tm
          The task manager that manages this task object - useful for registering new tasks based on incoming conversations
 
Constructor Summary
Task()
          Constructs a Task object - to fully initialise a Task object, use the Task or TaskManager newTask() method
Task(FIPAOSAgent owner, TaskManager taskman)
          Deprecated. This constructor is no longer supported. Use the no-argument constructor from sub-classes, and initialise using the newTask() method of the parent Task or TaskManager.
Task(FIPAOSAgent owner, TaskManager taskman, java.lang.String id)
          Deprecated. This constructor is no longer supported. Use the no-argument constructor from sub-classes, and initialise using the newTask() method of the parent Task or TaskManager.
 
Method Summary
protected  void DFSearchResults(DFAgentDescription[] df_descs)
          Callback method that is used to signal to the task that the previously requestes DF search has now finished.
protected  void done()
          When invoked, parent task will have the appropriate doneX() method invoked
protected  void done(java.lang.Object result)
          When invoked, parent task will have the appropriate doneX(Object) method invoked
 void doneDFSearchTask(java.lang.Object result)
          Callback method to indicate that a DFSearchTask has completed.
 void errorDFSearchTask(Task t, java.lang.Throwable exception)
          Callback method to indicate that a DFSearchTask has failed.
protected  void forward(ACL acl)
          Sends an ACL message.
protected  void forward(Message msg)
          Sends a Message.
 java.lang.Object getContext()
          Gets a context object for this Task - allows a parent-Task to associate some arbritary "context" with a child-Task which it can pickup when the child completes/fails
protected  ACL getNewConversation(java.lang.String protocol)
          Returns a new ACL message object that is pre-filled for the specified protocol.
 TaskState getState()
          Returns the TaskState associated with this Task
 void handleAcceptProposal(Conversation c)
          Dummy method - please override implementation and DO NOT invoke
 void handleAgree(Conversation c)
          Dummy method - please override implementation and DO NOT invoke
 void handleCfp(Conversation c)
          Dummy method - please override implementation and DO NOT invoke
 void handleConfirm(Conversation c)
          Dummy method - please override implementation and DO NOT invoke
 void handleDisconfirm(Conversation c)
          Dummy method - please override implementation and DO NOT invoke
 void handleFailure(Conversation c)
          Dummy method - please override implementation and DO NOT invoke
 void handleInform(Conversation c)
          Dummy method - please override implementation and DO NOT invoke
 void handleInformIf(Conversation c)
          Dummy method - please override implementation and DO NOT invoke
 void handleInformRef(Conversation c)
          Dummy method - please override implementation and DO NOT invoke
 void handleLateMessage(Message msg)
          Please override implementation - by default sends a not-understood
 void handleNotUnderstood(Conversation c)
          Dummy method - please override implementation and DO NOT invoke
protected  void handleOther(Conversation conv)
          This method can be implemented to provide a mechanism for dealing with incoming messages for which there is no performative handler available in the task subclass.
 void handlePropagate(Conversation c)
          Dummy method - please override implementation and DO NOT invoke
 void handlePropose(Conversation c)
          Dummy method - please override implementation and DO NOT invoke
 void handleProxy(Conversation c)
          Dummy method - please override implementation and DO NOT invoke
 void handleQueryIf(Conversation c)
          Dummy method - please override implementation and DO NOT invoke
 void handleQueryRef(Conversation c)
          Dummy method - please override implementation and DO NOT invoke
 void handleRefuse(Conversation c)
          Dummy method - please override implementation and DO NOT invoke
 void handleRejectProposal(Conversation c)
          Dummy method - please override implementation and DO NOT invoke
 void handleRequest(Conversation c)
          Dummy method - please override implementation and DO NOT invoke
 void handleRequestWhen(Conversation c)
          Dummy method - please override implementation and DO NOT invoke
 void handleRequestWhenever(Conversation c)
          Dummy method - please override implementation and DO NOT invoke
 void handleSubscribe(Conversation c)
          Dummy method - please override implementation and DO NOT invoke
 void handleUndeliverableMessage(Message msg)
          Please override implementation to deal with undeliverable messages
protected  void newTask(java.lang.String name, Task task)
          Initialises the given task, and invokes its start() method
protected  void newTask(java.lang.String name, Task task, Conversation conv)
          Initialises the given task, and invokes its start() method
protected  void newTask(java.lang.String name, Task task, Conversation conv, long timeout)
          Initialises the given task, and invokes its start() method.
protected  void newTask(java.lang.String name, Task task, long timeout)
          Initialises the given task, and invokes its start() method.
protected  void newTask(Task task)
          Initialises the given task, and invokes its start() method.
protected  void newTask(Task task, Conversation conv)
          Initialises the given task, and invokes its start() method.
protected  void newTask(Task task, Conversation conv, long timeout)
          Initialises the given task, and invokes its start() method.
protected  void newTask(Task task, long timeout)
          Initialises the given task, and invokes its start() method.
 void notify(Conversation conv)
          Dispatches incoming messages to the correct message handling method.
protected  void notifyDone(Task child, java.lang.String method, java.lang.Object result)
          Default method invoked to dispatch done callbacks - override this with a method to dispatch the callback statically to improve efficiency :)
protected  void notifyError(Task child, java.lang.String method, java.lang.Throwable error)
          Default method invoked to dispatch error callbacks - override this with a method to dispatch the callback statically to improve efficiency :)
 void notifyMessageFailure(Message msg)
          Dispatches incoming messages that have bounced for some reason.
 void notifyMessageForEndedConversation(Message msg)
          Dispatches incoming message for ended conversation to the correct method.
protected  void notifyTimeout(Task child, java.lang.String method)
          Default method invoked to dispatch timeout callbacks - override this with a method to dispatch the callback statically to improve efficiency :)
protected  boolean searchDF(DFAgentDescription df_desc)
          Searches the local platform DF for any agents matching the specified DF description.
protected  boolean searchDF(DFAgentDescription df_desc, boolean federated)
          Searches the local platform DF for any agents matching the specified DF description.
protected  boolean searchDF(DFAgentDescription df_desc, SearchConstraints constraint)
          Searches the local platform DF for any agents matching the specified DF description using the specified search constraint.
protected  boolean searchDF(java.lang.String df, DFAgentDescription df_desc, boolean federated)
          Searches the specified DF for any agents matching the specified DF description.
protected  boolean searchDF(java.lang.String df, DFAgentDescription df_desc, SearchConstraints constraint, boolean federated)
          Searches the specified DF for any agents matching the specified DF description using the specified search contraint.
protected  boolean sendNotUnderstood(ACL orig_acl)
          Send a not-understood in response to the given ACL
 void setContext(java.lang.Object o)
          Sets a context object for this Task - allows a parent-Task to associate some arbritary "context" with a child-Task which it can pickup when the child completes/fails
protected  void startTask()
          Invoked immediately after the task has been initialised by newTask()
 void timeoutDFSearchTask(Task t)
          Callback method to indicate that a DFSearchTask has failed.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

_owner

protected FIPAOSAgent _owner
The agent that owns this task - should only be used for the purpose of updating/retreiving parent-Agent state information

_tm

protected TaskManager _tm
The task manager that manages this task object - useful for registering new tasks based on incoming conversations

_children

protected java.util.Set _children
List of children of this task.

_lock

protected java.lang.Object _lock
Lock - ensures mutual exclusion between threads modifying this Task
Constructor Detail

Task

public Task()
Constructs a Task object - to fully initialise a Task object, use the Task or TaskManager newTask() method

Task

public Task(FIPAOSAgent owner,
            TaskManager taskman)
Deprecated. This constructor is no longer supported. Use the no-argument constructor from sub-classes, and initialise using the newTask() method of the parent Task or TaskManager.

Constructs a Task object. You must construct tasks using a concrete subclass of this class.
Parameters:
owner - The agent that owns this task
taskman - Reference to parent TaskManager

Task

public Task(FIPAOSAgent owner,
            TaskManager taskman,
            java.lang.String id)
Deprecated. This constructor is no longer supported. Use the no-argument constructor from sub-classes, and initialise using the newTask() method of the parent Task or TaskManager.

Constructs a task object. You must construct tasks using a concrete subclass of this class.
Parameters:
owner - The agent that owns this task
taskman - The task manager managing this task
id - The unique id of the task
Method Detail

setContext

public void setContext(java.lang.Object o)
Sets a context object for this Task - allows a parent-Task to associate some arbritary "context" with a child-Task which it can pickup when the child completes/fails

getContext

public java.lang.Object getContext()
Gets a context object for this Task - allows a parent-Task to associate some arbritary "context" with a child-Task which it can pickup when the child completes/fails

getState

public TaskState getState()
Returns the TaskState associated with this Task
Returns:
The TaskState associated with this

notifyMessageForEndedConversation

public void notifyMessageForEndedConversation(Message msg)
Dispatches incoming message for ended conversation to the correct method.
Parameters:
msg - Message that has arrived after end of conversation

notifyMessageFailure

public void notifyMessageFailure(Message msg)
Dispatches incoming messages that have bounced for some reason.
Parameters:
conv - Conversation containing incoming message

notify

public void notify(Conversation conv)
Dispatches incoming messages to the correct message handling method.
Parameters:
conv - Conversation containing incoming message

handleInform

public void handleInform(Conversation c)
Dummy method - please override implementation and DO NOT invoke

handleRequest

public void handleRequest(Conversation c)
Dummy method - please override implementation and DO NOT invoke

handleFailure

public void handleFailure(Conversation c)
Dummy method - please override implementation and DO NOT invoke

handleNotUnderstood

public void handleNotUnderstood(Conversation c)
Dummy method - please override implementation and DO NOT invoke

handleRefuse

public void handleRefuse(Conversation c)
Dummy method - please override implementation and DO NOT invoke

handleSubscribe

public void handleSubscribe(Conversation c)
Dummy method - please override implementation and DO NOT invoke

handleAgree

public void handleAgree(Conversation c)
Dummy method - please override implementation and DO NOT invoke

handleAcceptProposal

public void handleAcceptProposal(Conversation c)
Dummy method - please override implementation and DO NOT invoke

handleCfp

public void handleCfp(Conversation c)
Dummy method - please override implementation and DO NOT invoke

handleConfirm

public void handleConfirm(Conversation c)
Dummy method - please override implementation and DO NOT invoke

handleDisconfirm

public void handleDisconfirm(Conversation c)
Dummy method - please override implementation and DO NOT invoke

handleInformIf

public void handleInformIf(Conversation c)
Dummy method - please override implementation and DO NOT invoke

handleInformRef

public void handleInformRef(Conversation c)
Dummy method - please override implementation and DO NOT invoke

handlePropagate

public void handlePropagate(Conversation c)
Dummy method - please override implementation and DO NOT invoke

handlePropose

public void handlePropose(Conversation c)
Dummy method - please override implementation and DO NOT invoke

handleProxy

public void handleProxy(Conversation c)
Dummy method - please override implementation and DO NOT invoke

handleQueryIf

public void handleQueryIf(Conversation c)
Dummy method - please override implementation and DO NOT invoke

handleQueryRef

public void handleQueryRef(Conversation c)
Dummy method - please override implementation and DO NOT invoke

handleRejectProposal

public void handleRejectProposal(Conversation c)
Dummy method - please override implementation and DO NOT invoke

handleRequestWhen

public void handleRequestWhen(Conversation c)
Dummy method - please override implementation and DO NOT invoke

handleRequestWhenever

public void handleRequestWhenever(Conversation c)
Dummy method - please override implementation and DO NOT invoke

handleUndeliverableMessage

public void handleUndeliverableMessage(Message msg)
Please override implementation to deal with undeliverable messages

NOTE: Not yet implemented


handleLateMessage

public void handleLateMessage(Message msg)
Please override implementation - by default sends a not-understood

searchDF

protected boolean searchDF(DFAgentDescription df_desc)
Searches the local platform DF for any agents matching the specified DF description. This method will use the following default search parameters:
Parameters:
df_desc - The DF description to search for
Returns:
False if the search could not be started, true otherwise - a return value of true does NOT mean that results were found

searchDF

protected boolean searchDF(DFAgentDescription df_desc,
                           SearchConstraints constraint)
Searches the local platform DF for any agents matching the specified DF description using the specified search constraint. This method will use the following default search parameters:
Parameters:
df_desc - The DF description to search for
constraint - The search constraint
Returns:
False if the search could not be started, true otherwise - a return value of true does NOT mean that results were found

searchDF

protected boolean searchDF(DFAgentDescription df_desc,
                           boolean federated)
Searches the local platform DF for any agents matching the specified DF description. The search is optionally federated across other DFs. This method will use the following default search parameters:
Parameters:
df_desc - The DF description to search for
federated - Flag to signal whether this search should be federated or not
Returns:
False if the search could not be started, true otherwise - a return value of true does NOT mean that results were found

searchDF

protected boolean searchDF(java.lang.String df,
                           DFAgentDescription df_desc,
                           boolean federated)
Searches the specified DF for any agents matching the specified DF description. The search is optionally federated across other DFs. This method will use the following default search parameters:
Parameters:
df - The DF to search
df_desc - The DF description to search for
federated - Flag to signal whether this search should be federated or not
Returns:
False if the search could not be started, true otherwise - a return value of true does NOT mean that results were found

searchDF

protected boolean searchDF(java.lang.String df,
                           DFAgentDescription df_desc,
                           SearchConstraints constraint,
                           boolean federated)
Searches the specified DF for any agents matching the specified DF description using the specified search contraint. The search is optionally federated across other DFs.
Parameters:
df - The DF to search
df_desc - The DF description to search for
constraint - The search constraint
federated - Flag to signal whether this search should be federated or not
Returns:
False if the search could not be started, true otherwise - a return value of true does NOT mean that results were found

DFSearchResults

protected void DFSearchResults(DFAgentDescription[] df_descs)
Callback method that is used to signal to the task that the previously requestes DF search has now finished. The results of the search are returned as an array of DF description objects. This method should be overridden in any concrete tasks to provide some functionality.
Parameters:
df_descs - An array of search results

doneDFSearchTask

public void doneDFSearchTask(java.lang.Object result)
Callback method to indicate that a DFSearchTask has completed. This simply invokes DFSearchResults unless it is overridden.
Parameters:
result - The result of the DF-search

errorDFSearchTask

public void errorDFSearchTask(Task t,
                              java.lang.Throwable exception)
Callback method to indicate that a DFSearchTask has failed. This simply invokes DFSearchResults unless it is overridden.

timeoutDFSearchTask

public void timeoutDFSearchTask(Task t)
Callback method to indicate that a DFSearchTask has failed. This simply invokes DFSearchResults unless it is overridden.
Parameters:
t - The DFSearchTask that has timed-out
exception -  

forward

protected void forward(ACL acl)
Sends an ACL message.
Parameters:
acl - The ACL message to send
Throws:
MessageSenderException - if the message could not be sent

forward

protected void forward(Message msg)
Sends a Message.
Parameters:
msg - The Message to send
Throws:
MessageSenderException - if the message could not be sent

sendNotUnderstood

protected boolean sendNotUnderstood(ACL orig_acl)
Send a not-understood in response to the given ACL

getNewConversation

protected ACL getNewConversation(java.lang.String protocol)
Returns a new ACL message object that is pre-filled for the specified protocol. This is the preferred way of constructing new messages (that are not part of an existing conversation) as this will generate a unique conversation ID.
Parameters:
protocol - The agent interaction protocol to use
Returns:
A new ACL message object

newTask

protected void newTask(Task task)
Initialises the given task, and invokes its start() method. The task name will become the name of the class by default.
Parameters:
task - The new Task to be initialised and added to the system

newTask

protected void newTask(Task task,
                       Conversation conv)
Initialises the given task, and invokes its start() method. The task name will become the name of the class by default.
Parameters:
task - The new Task to be initialised and added to the system
conv - Conversation to be associated with this Task

newTask

protected void newTask(java.lang.String name,
                       Task task)
Initialises the given task, and invokes its start() method
Parameters:
task - The new Task to be initialised and added to the system
name - The name to be used for this task

newTask

protected void newTask(java.lang.String name,
                       Task task,
                       Conversation conv)
Initialises the given task, and invokes its start() method
Parameters:
task - The new Task to be initialised and added to the system
conv - Conversation to be associated with this Task
name - The name to be associated with this task

newTask

protected void newTask(Task task,
                       long timeout)
Initialises the given task, and invokes its start() method. The task name will become the name of the class by default. If the task doesn't invoke done() in the given amount of time, a timeoutX() method will be invoked on the parent-Task, where X is the id of the task
Parameters:
timeout - The time in milliseconds to wait before timing out
task - The new Task to be initialised and added to the system

newTask

protected void newTask(Task task,
                       Conversation conv,
                       long timeout)
Initialises the given task, and invokes its start() method. The task name will become the name of the class by default. If the task doesn't invoke done() in the given amount of time, a timeoutX() method will be invoked on the parent-Task, where X is the id of the task
Parameters:
timeout - The time in milliseconds to wait before timing out
task - The new Task to be initialised and added to the system
conv - Conversation to be associated with this Task

newTask

protected void newTask(java.lang.String name,
                       Task task,
                       long timeout)
Initialises the given task, and invokes its start() method. If the task doesn't invoke done() in the given amount of time, a timeoutX() method will be invoked on the parent-Task, where X is the id of the task
Parameters:
timeout - The time in milliseconds to wait before timing out
task - The new Task to be initialised and added to the system
name - The name to be used for this task

newTask

protected void newTask(java.lang.String name,
                       Task task,
                       Conversation conv,
                       long timeout)
Initialises the given task, and invokes its start() method. If the task doesn't invoke done() in the given amount of time, a timeoutX() method will be invoked on the parent-Task, where X is the id of the task
Parameters:
timeout - The time in milliseconds to wait before timing out
task - The new Task to be initialised and added to the system
conv - Conversation to be associated with this Task
name - The name to be associated with this task

done

protected void done()
When invoked, parent task will have the appropriate doneX() method invoked

done

protected void done(java.lang.Object result)
When invoked, parent task will have the appropriate doneX(Object) method invoked
Parameters:
result - The Object to pass to parent task

startTask

protected void startTask()
Invoked immediately after the task has been initialised by newTask()

notifyError

protected void notifyError(Task child,
                           java.lang.String method,
                           java.lang.Throwable error)
Default method invoked to dispatch error callbacks - override this with a method to dispatch the callback statically to improve efficiency :)
Parameters:
child - Child-Task that has failed
method - Name of the method to invoke

notifyDone

protected void notifyDone(Task child,
                          java.lang.String method,
                          java.lang.Object result)
Default method invoked to dispatch done callbacks - override this with a method to dispatch the callback statically to improve efficiency :)
Parameters:
child - Child-Task that has completed
method - Name of the method to invoke
result - Result associated with the completion (null if no result given)

notifyTimeout

protected void notifyTimeout(Task child,
                             java.lang.String method)
Default method invoked to dispatch timeout callbacks - override this with a method to dispatch the callback statically to improve efficiency :)
Parameters:
child - Child-Task that has timed-out
method - Name of the method to invoke

handleOther

protected void handleOther(Conversation conv)
This method can be implemented to provide a mechanism for dealing with incoming messages for which there is no performative handler available in the task subclass. The default implementation is to send a not-understood message. Override this method if you wish to add different handling such as learning how to handle the performative.
Parameters:
conv - The conversation containing the message to handle