unsw.cse.mica.agent
Class LocalAgentTransport

java.lang.Object
  extended by unsw.cse.mica.agent.LocalAgentTransport
All Implemented Interfaces:
AgentActions, AgentTransport, MessageHandler

public class LocalAgentTransport
extends java.lang.Object
implements AgentTransport, MessageHandler

The local agent transport is used to communicate between agents that run within the same JVM. For now, it should be considered a little under-tested; the XMLNetAgentTransport is far more thoroughly tested.

Author:
waleed

Constructor Summary
LocalAgentTransport(Agent agent, LocalBBTransport trans)
          This creates an Agent transport.
 
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
 java.lang.String getAgentName()
          Get the name that was provided for this agent at connection.
 TypeManager getTypeManager()
          Request a Mob TypeManager.
 void handleDeletedMob(Mob m)
          This method is called whenever a non-transient MICA object is deleted from the blackboard that the agent has registered interest it.
 void handleNewMob(Mob m)
          This method is called when a new MICA object has arrived.
 void handleReplacedMob(Mob oldMob, Mob newMob)
          This method is called whenever a mob is replaced on the blackboard with a type for which the agent has registered interest.
 void handleTypeManagerChanged()
          Called by the AgentTransport whenever the blackboard's type manager has changed.
 boolean isConnected()
          Check whether the transport is connected to the blackboard or not.
 java.util.List mobSearch(java.lang.String prologQuery)
          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 setMessageHandler(MessageHandler handler)
          Tell the transport to use a new message handler.
 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
 

Constructor Detail

LocalAgentTransport

public LocalAgentTransport(Agent agent,
                           LocalBBTransport trans)
This creates an Agent transport. Immediately after initialisation, the agent is likely to call connect().

Method Detail

setMessageHandler

public void setMessageHandler(MessageHandler handler)
Description copied from interface: AgentTransport
Tell the transport to use a new message handler. WARNING: Use of this method can break the agent-transport connection. In general, AgentTransports are given an agent in their constructor and this method will not need to be called. It is is provided primarily to allow the creation of more complex transports such as the SynchronizedTransport whose functionality is built on top of an underlying transport.

Specified by:
setMessageHandler in interface AgentTransport
Parameters:
handler - the new message handler for the transport

getTypeManager

public TypeManager getTypeManager()
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

handleNewMob

public void handleNewMob(Mob m)
Description copied from interface: MessageHandler
This method is called when a new MICA object has arrived.

Whenever a mob is written to the blackboard that the agent has registered an interest in the handleNewMob is called. It is passed the new Mob (MICA object) as a parameter so it can decide any further actions.

Note: The handleNewMob is called asynchronously. You should not make any assumptions about its synchronizations.

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

handleDeletedMob

public void handleDeletedMob(Mob m)
Description copied from interface: MessageHandler
This method is called whenever a non-transient MICA object is deleted from the blackboard that the agent has registered interest it.

Whenever a mob is deleted from the blackboard that the agent has registered an interest in the handleDeletedMob method is called.

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

handleReplacedMob

public void handleReplacedMob(Mob oldMob,
                              Mob newMob)
Description copied from interface: MessageHandler
This method is called whenever a mob is replaced on the blackboard with a type for which the agent has registered interest.

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()
Description copied from interface: MessageHandler
Called by the AgentTransport whenever the blackboard's type manager has changed. If the agent does not need type information, this method can simply be implemented as an empty function. If the agent requires an up-to-date type manager, the use of a RemoteTypeManager is suggested.

Specified by:
handleTypeManagerChanged in interface MessageHandler

deleteMob

public void deleteMob(java.lang.String mobName)
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 delete

readMob

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

Specified by:
readMob in interface AgentActions
Parameters:
mobName - the nae of the mob to be read
Returns:
The requested mob

writeMob

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

Specified by:
writeMob in interface AgentActions
Parameters:
mob - the mob to be written
Returns:
The name that has been given to the mob.

replaceMob

public void replaceMob(Mob mob)
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.

mobSearch

public java.util.List mobSearch(java.lang.String prologQuery)
Description copied from interface: AgentActions
Finds all mobs meeting the criteria.

Specified by:
mobSearch in interface AgentActions
Parameters:
prologQuery -
Returns:
A list of Mobs, in the appropriate order.

connect

public java.lang.String connect(java.lang.String agentName)
Description copied from interface: AgentActions
Connect to the blackboard. This should be the first action performed by an agent.

Specified by:
connect in interface AgentActions
Parameters:
agentName - The agent name proposed by the agent.
Returns:
The actual agent name (usually the requested name with a suffix)
See Also:
AgentActions.connect(java.lang.String)

isConnected

public boolean isConnected()
Description copied from interface: AgentTransport
Check whether the transport is connected to the blackboard or not.

Specified by:
isConnected in interface AgentTransport
Returns:
true if the agent is connect to the blackboard, false otherwise

getAgentName

public java.lang.String getAgentName()
Description copied from interface: AgentTransport
Get the name that was provided for this agent at connection.

Specified by:
getAgentName in interface AgentTransport
Returns:
the agents name on the blackboard, or null if the transport is not connected

disconnect

public void disconnect()
Description copied from interface: AgentActions
Disconnect from the Blackboard

Specified by:
disconnect in interface AgentActions
See Also:
AgentActions.disconnect()

register

public void register(java.lang.String mobType)
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
See Also:
AgentActions.register(java.lang.String)

unregister

public void unregister(java.lang.String mobType)
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.
See Also:
AgentActions.unregister(java.lang.String)