unsw.cse.mica.agent
Class XMLOverTCPAgentTransport

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

public class XMLOverTCPAgentTransport
extends java.lang.Object
implements AgentTransport

This class encapsulates an XML protocol running over a TCP connection. At present this is the only available protocol and connection; this class provides a simple way of creating and using this transport setup. All of the methods simply delegate to an internal transport objects.

Author:
jhw

Constructor Summary
XMLOverTCPAgentTransport(Agent agent, java.lang.String host, int port)
          Create a new XML over TCP transport which will connect to a blackboard on the given host and port.
 
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.
 java.lang.String getHost()
           
 int getPort()
           
 TypeManager getTypeManager()
          Request a Mob TypeManager.
 boolean isConnected()
          Check whether the transport is connected to the blackboard or not.
 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 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

XMLOverTCPAgentTransport

public XMLOverTCPAgentTransport(Agent agent,
                                java.lang.String host,
                                int port)
Create a new XML over TCP transport which will connect to a blackboard on the given host and port.

Parameters:
agent - the agent that this transport is for
host - the machine on which the blackboard is running
port - the TCP port number on which the blackboard is listening.
Method Detail

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

getHost

public java.lang.String getHost()

getPort

public int getPort()

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

connect

public java.lang.String connect(java.lang.String agentName)
                         throws TransportException
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)
Throws:
TransportException

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

disconnect

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

Specified by:
disconnect in interface AgentActions
Throws:
TransportException

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

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

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

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.

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

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