unsw.cse.mica.agent.transport
Class AbstractAgentProtocol

java.lang.Object
  extended by unsw.cse.mica.agent.transport.AbstractAgentProtocol
All Implemented Interfaces:
AgentActions, MessageHandler, AgentProtocol
Direct Known Subclasses:
XMLAgentProtocol

public abstract class AbstractAgentProtocol
extends java.lang.Object
implements AgentProtocol, MessageHandler

Provides support for some of the Protocol functionality that is shared between all protocols. This includes connection to AgentConnection and MessageHandler objects, and synchronization of actions and action replies. The inner class Reply is used as a description of the result of an action for this purpose.

Author:
jhw

Nested Class Summary
 class AbstractAgentProtocol.Reply
          An encapsulation of a reply from the blackboards in response to an action.
 
Constructor Summary
AbstractAgentProtocol()
           
 
Method Summary
 void deleteMob(java.lang.String mobName)
          Delete a mob from the blackboard.
 TypeManager getTypeManager()
          Request a Mob TypeManager.
 void handleDeletedMob(Mob mob)
          handle a deletedMob message.
 void handleNewMob(Mob mob)
          handle a new mob message.
 void handleReplacedMob(Mob oldMob, Mob newMob)
          handle a deletedMob message.
 void handleTypeManagerChanged()
          handle a typeManagerChanged message.
 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 setConnection(AgentConnection connection)
          Tell the protocol which underlying connection to use
 void setMessageHandler(MessageHandler messageHandler)
          Set the object to inform when new messages arrive from 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.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface unsw.cse.mica.agent.transport.AgentProtocol
isConnected
 
Methods inherited from interface unsw.cse.mica.agent.AgentActions
connect, disconnect
 

Constructor Detail

AbstractAgentProtocol

public AbstractAgentProtocol()
Method Detail

setMessageHandler

public void setMessageHandler(MessageHandler messageHandler)
Description copied from interface: AgentProtocol
Set the object to inform when new messages arrive from the blackboard

Specified by:
setMessageHandler in interface AgentProtocol

setConnection

public void setConnection(AgentConnection connection)
Description copied from interface: AgentProtocol
Tell the protocol which underlying connection to use

Specified by:
setConnection in interface AgentProtocol

getTypeManager

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

Specified by:
getTypeManager in interface AgentActions
Throws:
TransportException - if the agent was not connected

register

public void register(java.lang.String mobType)
              throws TransportException,
                     ActionException
Description copied from interface: AgentActions
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).

Specified by:
register in interface AgentActions
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

public void unregister(java.lang.String mobType)
                throws TransportException,
                       ActionException
Description copied from interface: AgentActions
Inform the blackboard that we are no longer interested in a particular type.

Specified by:
unregister in interface AgentActions
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.

readMob

public Mob readMob(java.lang.String mobName)
            throws TransportException,
                   ActionException
Description copied from interface: AgentActions
Retrieve a mob by its name.

Specified by:
readMob in interface AgentActions
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

writeMob

public java.lang.String writeMob(Mob mob)
                          throws TransportException
Description copied from interface: AgentActions
Write a mob to the blackboard.

Specified by:
writeMob in interface AgentActions
Returns:
The name that has been given to the mob.
Throws:
TransportException - if the agent was not connected

replaceMob

public void replaceMob(Mob mob)
                throws TransportException,
                       ActionException
Description copied from interface: AgentActions
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

Specified by:
replaceMob in interface AgentActions
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

deleteMob

public void deleteMob(java.lang.String mobName)
               throws TransportException,
                      ActionException
Description copied from interface: AgentActions
Delete a mob from the blackboard.

Specified by:
deleteMob in interface AgentActions
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

mobSearch

public java.util.List mobSearch(java.lang.String micaQuery)
                         throws TransportException,
                                ActionException
Description copied from interface: AgentActions
Finds all mobs meeting the criteria.

Specified by:
mobSearch in interface AgentActions
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

handleNewMob

public void handleNewMob(Mob mob)
handle a new mob message. Simply forwards the message to the specified handler

Specified by:
handleNewMob in interface MessageHandler
Parameters:
mob - the mob that has been written to the blackboard

handleDeletedMob

public void handleDeletedMob(Mob mob)
handle a deletedMob message. Simply forwards the message to the specified handler

Specified by:
handleDeletedMob in interface MessageHandler
Parameters:
mob - the mob that has been deleted

handleReplacedMob

public void handleReplacedMob(Mob oldMob,
                              Mob newMob)
handle a deletedMob message. Simply forwards the message to the specified handler

Specified by:
handleReplacedMob in interface MessageHandler
Parameters:
oldMob - the old value of the mob (where the name is cleared)
newMob - the new value of the mob

handleTypeManagerChanged

public void handleTypeManagerChanged()
handle a typeManagerChanged message. Simply forwards the message to the specified handler

Specified by:
handleTypeManagerChanged in interface MessageHandler