fipaos.agent
Class FIPAOSAgent

java.lang.Object
  |
  +--fipaos.agent.FIPAOSAgent
All Implemented Interfaces:
ConversationListener
Direct Known Subclasses:
AgentManagementSystem, AgentMessagingTest.TestAgent, DFGUIAgent, DirectoryFacilitator, IOTestAgent, JessAgent, MessageTimingAgent, PingAgent

public abstract class FIPAOSAgent
extends java.lang.Object
implements ConversationListener

Base FIPA-OS agent class implementing FIPA-OS specifics for agent to agent communication. Override

notify()
deal with updated Conversations directly in the underlying Agent implementation, or use the
setListenerTask()
to set a default Task if you wish to use the TaskManager to implement the Agent.


Inner Class Summary
 class FIPAOSAgent.TopLevelHandlerTask
           
 
Field Summary
protected  DatabaseProfile _database_profile
          Database Profile
 java.util.List _registered_with
          List of Agents that this Agent is registered with
 java.lang.String _state
          Agent states: unknown, waiting, suspended, transit, initiated, active
protected  TaskManager _tm
          Task manager.
 
Constructor Summary
FIPAOSAgent(PlatformProfile platform_profile, AgentProfile agent_profile, java.lang.String agent_name, java.lang.String ownership, boolean using_task_manager)
          Constructor method to initialise an Agent.
FIPAOSAgent(PlatformProfile platform_profile, AgentProfile agent_profile, java.lang.String agent_name, java.lang.String ownership, boolean using_task_manager, FIPAOSAgentComponentFactory factory)
          Constructor method to initialise an Agent.
FIPAOSAgent(java.lang.String platform_profile_location, java.lang.String agent_name, java.lang.String ownership)
          Constructor method to initialise an Agent.
FIPAOSAgent(java.lang.String platform_profile_location, java.lang.String agent_name, java.lang.String ownership, boolean using_task_manager)
          Constructor method to initialise an Agent.
 
Method Summary
 void activate()
          This method should be overriden by the FIPAOSAgent - it is invoked when the user of the local machine wishes it to do something (usually display a GUI)
protected  boolean addNewProtocol(java.lang.String protocol_name, java.lang.String protocol_defn)
          Adds a newly downloaded protocol definition to the conversation manager to make it available for use.
protected  void deregisterWithAMS()
          Deregisters this agent with the DF.
protected  void deregisterWithDF()
          Deregisters this agent with the DF.
 void forward(ACL acl)
          Forward an acl message out via the ConversationManagerImpl
 void forward(Message msg)
          Forward an message out via the ConversationManager
 AgentID getAID()
          Gets the AgentID of this Agent
protected  ConversationManager getCM()
          Provides a reference to this Agent's ConversationManager implementation
 Conversation getCurrentConversation(java.lang.String conv)
          Method to retreive a conversation from the active list
 java.lang.String getHAP()
          Gets the local HAP name
 java.lang.String getLocalAMS()
          Returns the agent AID of the local platform AMS.
 AgentID getLocalAMSAID()
          Returns the agent AID of the local platform AMS.
 java.lang.String getLocalDF()
          Returns the agent AID of the local platform DF.
 AgentID getLocalDFAID()
          Returns the agent AID of the local platform DF.
 Conversation getNewConversation(java.lang.String protocol)
          Method to get a new Conversation object from the conversation manager given the protocol specified
 java.lang.String getOwnership()
          Returns the ownership id of the agent.
 PlatformProfile getPlatformProfile()
          Gets the platform profile for this Agent
 AgentProfile getProfile()
          Gets the profile for this Agent
 java.lang.String getState()
          Returns the state of the agent Currently, only 2 states might be returned: "unknown" and "active"
 boolean isShutdown()
          Indicates if this Agent has been shutdown
protected  boolean knowsProtocol(java.lang.String protocol_name)
          Indicates if the agent is aware of the protocol specified.
 void notify(Conversation conv)
          Conversation listener method to deal with conversations being sent by the planner scheduler.
 void notify(java.util.Enumeration enum)
          Deals with multiple conversations at once - just calls notify( Conversation ) for each one.
 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 :)
 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 notifyMessageInEndedConversation(Message msg)
          Indicates that the given Message arrived for a completed Conversation - override to deal with this if a TaskManager is not in use
 void notifyMessageUndeliverable(Message msg)
          Indicates that the given Message was not deliverable - override to deal with this if a TaskManager is not in use
 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 registeredWith(AgentID agent)
          Indicates if this agent is registered with the platform agent specified.
protected  boolean registeredWithAMS()
          Indicates if this agent is registered with the local AMS.
protected  boolean registeredWithDF()
          Indicates if this agent is registered with the local DF.
protected  void registerWithAMS()
          Registers this agent with the local platform AMS.
protected  void registerWithAMS(AgentID ams)
          Registers this agent with the AMS specified.
protected  void registerWithAMS(AgentID ams, java.lang.String state)
          Registers this agent with the AMS specified.
protected  void registerWithAMS(AMSRegistrationTask ams_task)
          Registers this agent using the AMS registration task specified.
protected  void registerWithDF(AgentID df, DFAgentDescription df_desc)
          Registers this agent with the DF specified.
protected  void registerWithDF(AgentID df, java.lang.String agent_type)
          Registers this agent with the DF specified.
protected  void registerWithDF(DFRegistrationTask df_task)
          Registers this agent using the DF registration task specified.
protected  void registerWithDF(java.lang.String agent_type)
          Registers this agent with the local platform DF.
 boolean sendNotUnderstood(ACL orig_acl)
          Send a not understood message in response to the given ACL message
 boolean sendNotUnderstood(ACL orig_acl, java.lang.String reason)
          Send a not understood message in response to the given ACL message
protected  boolean setListenerTask(Task idle_task)
          Sets the agent's idle task - this method MUST be used if you are using the task manager as it defines which task object should handle incoming messages that we have not previously seen.
 void setMessageSender(MessageSender ms)
          Sets the MessageSender for this
 void shutdown()
          Shutdown the Agent safely
protected  void startPushing()
          When using the push model or ConversationManagement, this method should be invoked in order to allow pushing to start
 void waitForPushLock()
          Blocks until the Agent is ready to receive messages/conversations
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

_tm

protected TaskManager _tm
Task manager.

_database_profile

protected DatabaseProfile _database_profile
Database Profile

_state

public java.lang.String _state
Agent states: unknown, waiting, suspended, transit, initiated, active

_registered_with

public java.util.List _registered_with
List of Agents that this Agent is registered with
Constructor Detail

FIPAOSAgent

public FIPAOSAgent(java.lang.String platform_profile_location,
                   java.lang.String agent_name,
                   java.lang.String ownership)
Constructor method to initialise an Agent. This loads the AgentProfile and creates an AgentComms instance for the Agent with the required CommsTransports. This constructor creates an agent that uses the Task Manager by default. This is going to be the required way of creating an agent in future versions of FIPA-OS, so this constructor should provide forward compatability. It will initialise the agent to use the Conversation Manager as well (as this is required for use of the Task Manager).
Parameters:
platform_profile_location - The location of the platform.profile (a fully qualified file name)
agent_name - globally unique identifier for the agent
ownership - the ownership of the agent

FIPAOSAgent

public FIPAOSAgent(java.lang.String platform_profile_location,
                   java.lang.String agent_name,
                   java.lang.String ownership,
                   boolean using_task_manager)
Constructor method to initialise an Agent. This loads the AgentProfile and creates an AgentComms instance for the Agent with the required CommsTransports. Can optionally create a Task Manager in the agent. If you are using the task manager then you must also call setListenerTask( Task ) in your constructor code in order to set up the default task. This default task handles all incoming messages that are new (i.e. that are not replies to message that we have previously sent). If you do not register a default task then incoming messages will be ignored.
Parameters:
platform_profile_location - The location of the platform.profile (a fully qualified file name)
agent_name - unique name of the Agent within its platform
ownership - the ownership of the agent
using_task_manager - Selected if a task manager is to be used

FIPAOSAgent

public FIPAOSAgent(PlatformProfile platform_profile,
                   AgentProfile agent_profile,
                   java.lang.String agent_name,
                   java.lang.String ownership,
                   boolean using_task_manager)
Constructor method to initialise an Agent. This uses the given AgentProfile and creates an MTS instance for the Agent with the required MTP's. Can optionally create a Task Manager in the agent. If you are using the task manager then you must also call setListenerTask( Task ) in your constructor code in order to set up the default task. This default task handles all incoming messages that are new (i.e. that are not replies to message that we have previously sent). If you do not register a default task then incoming messages will be ignored.
Parameters:
platform_profile - Representation of the Platform's profile
agent_profile - Representation of the Agent's profile
agent_name - unique name of the Agent within its platform
ownership - the ownership of the agent
using_task_manager - Selected if a task manager is to be used

FIPAOSAgent

public FIPAOSAgent(PlatformProfile platform_profile,
                   AgentProfile agent_profile,
                   java.lang.String agent_name,
                   java.lang.String ownership,
                   boolean using_task_manager,
                   FIPAOSAgentComponentFactory factory)
Constructor method to initialise an Agent. This uses the given AgentProfile and creates an MTS instance for the Agent with the required MTP's. Can optionally create a Task Manager in the agent. If you are using the task manager then you must also call setListenerTask( Task ) in your constructor code in order to set up the default task. This default task handles all incoming messages that are new (i.e. that are not replies to message that we have previously sent). If you do not register a default task then incoming messages will be ignored.
Parameters:
platform_profile - Representation of the Platform's profile
agent_profile - Representation of the Agent's profile
agent_name - unique name of the Agent within its platform
ownership - the ownership of the agent
using_task_manager - Selected if a task manager is to be used
factory - Factory to be used to generate Agent components
Method Detail

forward

public void forward(ACL acl)
Forward an acl message out via the ConversationManagerImpl
Parameters:
acl - ACL containing an agent communication language (acl) message

forward

public void forward(Message msg)
Forward an message out via the ConversationManager
Parameters:
msg - Message containing an agent communication language (acl) message and its associated envelope

waitForPushLock

public void waitForPushLock()
Blocks until the Agent is ready to receive messages/conversations

shutdown

public void shutdown()
Shutdown the Agent safely

isShutdown

public boolean isShutdown()
Indicates if this Agent has been shutdown

getOwnership

public java.lang.String getOwnership()
Returns the ownership id of the agent.

getProfile

public AgentProfile getProfile()
Gets the profile for this Agent

getPlatformProfile

public PlatformProfile getPlatformProfile()
Gets the platform profile for this Agent

getAID

public AgentID getAID()
Gets the AgentID of this Agent

getHAP

public java.lang.String getHAP()
Gets the local HAP name

activate

public void activate()
This method should be overriden by the FIPAOSAgent - it is invoked when the user of the local machine wishes it to do something (usually display a GUI)

By default it does nothing


getCurrentConversation

public Conversation getCurrentConversation(java.lang.String conv)
                                    throws InvalidConversationIDException
Method to retreive a conversation from the active list
Parameters:
conv - The conversation id of the Conversation object to retreive

getLocalAMS

public java.lang.String getLocalAMS()
Returns the agent AID of the local platform AMS.
Returns:
The local AMS GUID

getLocalAMSAID

public AgentID getLocalAMSAID()
Returns the agent AID of the local platform AMS.
Returns:
The local AMS GUID

getLocalDF

public java.lang.String getLocalDF()
Returns the agent AID of the local platform DF.
Returns:
The local DF GUID

getLocalDFAID

public AgentID getLocalDFAID()
Returns the agent AID of the local platform DF.
Returns:
The local DF GUID

getState

public java.lang.String getState()
Returns the state of the agent Currently, only 2 states might be returned: "unknown" and "active"

setListenerTask

protected boolean setListenerTask(Task idle_task)
Sets the agent's idle task - this method MUST be used if you are using the task manager as it defines which task object should handle incoming messages that we have not previously seen.
Parameters:
idle_task - The task object that should be used when the agent is idling e.g. the task object that handles incoming messages that are not replies
Returns:
True if the IDLE task was set, false otherwise

startPushing

protected void startPushing()
When using the push model or ConversationManagement, this method should be invoked in order to allow pushing to start

addNewProtocol

protected boolean addNewProtocol(java.lang.String protocol_name,
                                 java.lang.String protocol_defn)
Adds a newly downloaded protocol definition to the conversation manager to make it available for use.
Parameters:
protocol_name - The name of the protocol to add (e.g. fipa-new-protocol)
protocol_defn - The RDF definition of the protocol
Returns:
True if the protocol was added to the CM, false otherwise

knowsProtocol

protected boolean knowsProtocol(java.lang.String protocol_name)
Indicates if the agent is aware of the protocol specified.
Parameters:
protocol_name - The name of the protocol (e.g. fipa-new-protocol)
Returns:
True if the agents knows the protocol and can use it without throwing an exception, false otherwise

getNewConversation

public Conversation getNewConversation(java.lang.String protocol)
                                throws UnknownProtocolException
Method to get a new Conversation object from the conversation manager given the protocol specified

getCM

protected ConversationManager getCM()
Provides a reference to this Agent's ConversationManager implementation

notify

public void notify(Conversation conv)
Conversation listener method to deal with conversations being sent by the planner scheduler. These should be overriden as default by the sub-class if necessary
Specified by:
notify in interface ConversationListener
Parameters:
conv - The updated conversation to deal with

notify

public void notify(java.util.Enumeration enum)
Deals with multiple conversations at once - just calls notify( Conversation ) for each one. Override in sub class to replace this behavior. ( NOTE: When overriding this method, it should be noted that care should be taken because this method could be invoked at any time after the FIPAOSAgent() constructor had been used. Normally this method doesn't do anything until after startPushing() is invoked).
Specified by:
notify in interface ConversationListener
Parameters:
enum - An enumeration of updated conversations to deal with

notifyMessageInEndedConversation

public void notifyMessageInEndedConversation(Message msg)
Indicates that the given Message arrived for a completed Conversation - override to deal with this if a TaskManager is not in use
Specified by:
notifyMessageInEndedConversation in interface ConversationListener

notifyMessageUndeliverable

public void notifyMessageUndeliverable(Message msg)
Indicates that the given Message was not deliverable - override to deal with this if a TaskManager is not in use
Specified by:
notifyMessageUndeliverable in interface ConversationListener

setMessageSender

public void setMessageSender(MessageSender ms)
Sets the MessageSender for this
Specified by:
setMessageSender in interface ConversationListener

sendNotUnderstood

public boolean sendNotUnderstood(ACL orig_acl)
Send a not understood message in response to the given ACL message
Parameters:
acl - The ACL object to reply to

sendNotUnderstood

public boolean sendNotUnderstood(ACL orig_acl,
                                 java.lang.String reason)
Send a not understood message in response to the given ACL message
Parameters:
acl - The ACL object to reply to
reason - The reason for not-understanding

registeredWith

protected boolean registeredWith(AgentID agent)
Indicates if this agent is registered with the platform agent specified. This does not have to be a local platform agent. To test registration task of the local platform agents you should use the registeredWithX() methods of this class.
Returns:
True if this agent is registered with the platform agent specified, false otherwise

registeredWithAMS

protected boolean registeredWithAMS()
Indicates if this agent is registered with the local AMS.
Returns:
True if this agent is registered with the local AMS, false otherwise

registeredWithDF

protected boolean registeredWithDF()
Indicates if this agent is registered with the local DF.
Returns:
True if this agent is registered with the local DF, false otherwise

registerWithAMS

protected void registerWithAMS()
                        throws AMSRegistrationException
Registers this agent with the local platform AMS. The platform state of the agent is automatically set to ACTIVE.

registerWithAMS

protected void registerWithAMS(AgentID ams)
                        throws AMSRegistrationException
Registers this agent with the AMS specified. The platform state of the agent is automatically set to ACTIVE.
Parameters:
ams - The AID of the AMS to register with

registerWithAMS

protected void registerWithAMS(AgentID ams,
                               java.lang.String state)
                        throws AMSRegistrationException
Registers this agent with the AMS specified. The platform state of the agent is set to the state specified.
Parameters:
ams - The AID of the AMS to register with
state - The platform state of the agent (e.g. ACTIVE - see FIPA spec for details)

registerWithAMS

protected void registerWithAMS(AMSRegistrationTask ams_task)
                        throws AMSRegistrationException
Registers this agent using the AMS registration task specified.
Parameters:
ams_task - The AMSRegistrationTask to register with

registerWithDF

protected void registerWithDF(java.lang.String agent_type)
                       throws DFRegistrationException
Registers this agent with the local platform DF. The DF state of the agent is automatically set to ACTIVE. The agent type is set to that specified.
Parameters:
agent_type - The type of this agent, e.g. fipa-agent, fipa-arb etc

registerWithDF

protected void registerWithDF(AgentID df,
                              DFAgentDescription df_desc)
                       throws DFRegistrationException
Registers this agent with the DF specified. The DF details of the agent are extracted from the DF Description object specified.
Parameters:
df - The AID of the AMS to register with
df_desc - A DF description that describes this agent

registerWithDF

protected void registerWithDF(AgentID df,
                              java.lang.String agent_type)
                       throws DFRegistrationException
Registers this agent with the DF specified. The DF state of the agent is automatically set to ACTIVE. The agent type is set to that specified.
Parameters:
df - The GUID/AID of the DF to register with
agent_type - The type of this agent, e.g. fipa-agent, fipa-arb etc

registerWithDF

protected void registerWithDF(DFRegistrationTask df_task)
                       throws DFRegistrationException
Registers this agent using the DF registration task specified.
Parameters:
df_task - The ADFRegistrationTask to register with

deregisterWithDF

protected void deregisterWithDF()
                         throws DFRegistrationException
Deregisters this agent with the DF.

deregisterWithAMS

protected void deregisterWithAMS()
                          throws AMSRegistrationException
Deregisters this agent with the DF.

notifyDone

public 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

public 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

notifyError

public 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