unsw.cse.mica.agent
Interface AgentActions

All Known Subinterfaces:
AgentProtocol, AgentTransport, SynchronizedAgentActions
All Known Implementing Classes:
AbstractAgentProtocol, CompoundAgentTransport, LocalAgentTransport, NullAgentTransport, SecureXMLAgentProtocol, SecureXMLOverSSLAgentTransport, SecureXMLOverTCPAgentTransport, SynchronizedTransport, XMLAgentProtocol, XMLOverSSLAgentTransport, XMLOverTCPAgentTransport

public interface AgentActions

This interface represents the actions that an agent can perform.

The AgentActions is an abstraction of all the things that an agent can ask the blackboard to do. An agent uses its transport to perform these tasks.

Author:
Waleed Kadous

Method Summary
 java.lang.String connect(java.lang.String agentName)
          Connect to the blackboard.
 void deleteMob(java.lang.String mobName)
          Delete a mob from the blackboard.
 void disconnect()
          Disconnect from the Blackboard
 TypeManager getTypeManager()
          Request a Mob TypeManager.
 java.util.List mobSearch(java.lang.String micaQuery)
          Finds all mobs meeting the criteria.
 Mob readMob(java.lang.String mobName)
          Retrieve a mob by its name.
 void register(java.lang.String mobType)
          Allows the agent to register for events of a particular mobType.
 void replaceMob(Mob mob)
          Replace a mob on the blackboard.
 void unregister(java.lang.String mobType)
          Inform the blackboard that we are no longer interested in a particular type.
 java.lang.String writeMob(Mob mob)
          Write a mob to the blackboard.
 

Method Detail

connect

java.lang.String connect(java.lang.String agentName)
                         throws TransportException
Connect to the blackboard. This should be the first action performed by an agent.

Parameters:
agentName - The agent name proposed by the agent.
Returns:
The actual agent name (usually the requested name with a suffix)
Throws:
ConnectionException - if an exception occured while attempting to connect
ActionException - if the agent was already connected
TransportException

disconnect

void disconnect()
                throws TransportException
Disconnect from the Blackboard

Throws:
ActionException - if the agent was not connected.
TransportException

getTypeManager

TypeManager getTypeManager()
                           throws TransportException
Request a Mob TypeManager. In general this would be obtained from the blackboard but it could be cached or "faked" using local files.

Throws:
TransportException - if the agent was not connected

register

void register(java.lang.String mobType)
              throws TransportException,
                     ActionException
Allows the agent to register for events of a particular mobType.

Registration tells the blackboard that the agent is interested in mobs of a particular type. If the securirty policy allows, the agent will be informed when mobs of this type are written to the blackboard (via its handleNewMob method) or when mobs of this type are deleted from the blackboard (via its handleDeletedMob method).

Parameters:
mobType - The type we are interested in
Throws:
TransportException - if the agent was not connected
ActionException - if the requested type is not known.

unregister

void unregister(java.lang.String mobType)
                throws TransportException,
                       ActionException
Inform the blackboard that we are no longer interested in a particular type.

Parameters:
mobType - The type that the agent is no longer interested in hearing about.
Throws:
TransportException - if the agent was not connected
ActionException - if the agent was not connected or if the requested type is not known.

writeMob

java.lang.String writeMob(Mob mob)
                          throws TransportException
Write a mob to the blackboard.

Parameters:
mob -
Returns:
The name that has been given to the mob.
Throws:
TransportException - if the agent was not connected

deleteMob

void deleteMob(java.lang.String mobName)
               throws TransportException,
                      ActionException
Delete a mob from the blackboard.

Parameters:
mobName - the name of the mob to remove.
Throws:
TransportException - if the agent was not connected
ActionException - if the requested mob doesn't exist

readMob

Mob readMob(java.lang.String mobName)
            throws TransportException,
                   ActionException
Retrieve a mob by its name.

Parameters:
mobName - the name of the Mob to retrieve.
Returns:
The requested mob
Throws:
TransportException - if the agent was not connected
ActionException - if the requested mob doesn't exist

replaceMob

void replaceMob(Mob mob)
                throws TransportException,
                       ActionException
Replace a mob on the blackboard. If a mob exists on the blackboard whose name is the same as the name of the mob given, the old mob is replaced by the new mob. This is effectively an atomic delete-write action with the new mobs name and type being set as the old mobs name and type

Parameters:
mob - the mob to be written. The mob's name must be specified and indicates the name of the mob that will be replaced. The mob's type is ignored as the previous type will be carried over.
Throws:
TransportException - if the agent was not connected
ActionException - if no mob existed with the given name

mobSearch

java.util.List mobSearch(java.lang.String micaQuery)
                         throws TransportException,
                                ActionException
Finds all mobs meeting the criteria.

Parameters:
micaQuery - A query in the MicaQL query language.
Returns:
A list of Mobs, in the appropriate order.
Throws:
TransportException - if the agent was not connected
ActionException - if the query was invalid