Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep

edu.mit.media.hive.agent
Class AgentImpl  view AgentImpl download AgentImpl.java

java.lang.Object
  extended byjava.rmi.server.RemoteObject
      extended byjava.rmi.server.RemoteServer
          extended byjava.rmi.server.UnicastRemoteObject
              extended byedu.mit.media.hive.agent.AgentImpl
All Implemented Interfaces:
Agent, edu.mit.media.hive.rdf.Describable, java.rmi.Remote, java.io.Serializable
Direct Known Subclasses:
CameraDemoAgentImpl, EventReceivingAgentImpl, EventSendingAgentImpl

public abstract class AgentImpl
extends java.rmi.server.UnicastRemoteObject
implements Agent, java.io.Serializable

Base class for Hive agent implementations. An agent has a life cycle.

  1. Once in its lifetime, the agent is constructed by the no argument constructor.
  2. The agent arrives on a server; its doLocalSetup() method is called. This happens whenever it first comes to a server, whether created by Cell.createNewAgent(Class) or when it moves to the server.
  3. The agent's doBehavior() method is called. This method is the agent's main loop, where it's behavior is implemented. The agent is free to do what it wants, but should respect timeToStop. The agent sould never exit this method, a convienience method waitUntilDeath is provided for this purpose.
  4. When an agent is being killed, the notification onDying method is called. The onMoving is called for the notification for moving
  5. onLocalCleanup is called to ask the agent to free all its local resources. The reason for agent death can be discovered by looking at the value of stopCode if cleanup is dependant on the "type" of agent death
An agent might travel to another server, either by moving itself or being moved by someone authorized. The moveTo() method initiates the move: when the agent arrives at the remote server, arriveAt() and doBehaviour() will be called again. All agents have a notion of a list of "connections", which agents they talk to. It is up to the agent to define the semantics of what a connect means. Agents also have an icon that represents them: by default this icon is loaded from icons/AgentClassName.ppm.

Version:
$Revision: 2.1 $ ,

Field Summary
static int AGENTKILLED
          The different possible stop codes for the agents
static int AGENTMOVED
           
protected  java.lang.ThreadGroup agentThreadGroup
          Pointer to the thread group for this agent -- ell behaved agents, if they need to spawn separate threads, will make those threads members of this agents thread group.
protected  java.util.Vector commandList
          Hashtable of CommandObjects
protected  java.util.Hashtable commands
          Hashtable and list for the popup menu items or their non-graphical equivalents.
protected  edu.mit.media.hive.rdf.Description description
          Pointer to my RDF description.
protected  edu.mit.media.hive.support.SerializableImage icon
          The icon that represents this agent.
protected  java.lang.String iconName
           
protected  edu.mit.media.hive.cell.Cell myCell
          Pointer to the server I am currently on.
protected  boolean readyFlag
          Just describing whether or not this agent is ready for operation or not
protected  int stopCode
          Variable describing the reason why an agent was asked to stop
protected  boolean timeToStop
          Variable indicating this agent should die soon.
 
Fields inherited from class java.rmi.server.UnicastRemoteObject
 
Fields inherited from class java.rmi.server.RemoteObject
ref
 
Constructor Summary
AgentImpl()
          Basic constructor for agents.
 
Method Summary
 void addActionCommand(ActionCommand com)
          Add a popup menu item or non-graphical equivalent to the agent's behavior.
 void blockUntilReady()
          this method should block until the agent is ready -- it just sits in the wait method until it gets notified from the setIsReady method
 void configure(org.w3c.dom.Document doc)
          Tells the agent to configure itself from the DOM Node doc.
 boolean connectTo(Agent otherAgent)
          Tell this agent to connect to some other agent.
 void diePlease()
          Ask the agent to politely die -- by default, the agent just relays the call to the server and asks it tkill itself
 void disconnectFrom(Agent otherAgent)
          Disconnects this agent from the specified other agent.
 void disconnectFromAll()
          Disconnects this agent from all agents.
abstract  void doBehavior()
          Do the basic behavior for an agent, the agent's main loop.
 void doBehaviour()
          Deprecated.  
 void doLocalCleanup()
          Command the agent to free its local resources here.
 void doLocalSetup()
          Handle the setup when an agent arrives on a host -- it is appropriate to allocate system resources (file descriptors, etc) here and even to locate other agents that this agent needs to communicate with.
 java.util.Vector getActionCommands()
          Get the names of the ActionCommands this agent uses in the order in which they were entered.
 edu.mit.media.hive.cell.RemoteCell getCell()
          Return the server I'm living on.
 edu.mit.media.hive.shadow.cell.ComponentManagerShadow getComponentManagerShadow()
          A convenience method to return the ComponentManagerShadow or throws an exception if one is not present.
 edu.mit.media.hive.rdf.Description getDescription()
          Return the semantic description of this agent.
 edu.mit.media.hive.support.SerializableImage getIcon()
          Return the SerializableImage object that is the agent's icon.
 java.lang.String getIconName()
          Get the value of iconName.
 java.lang.String getName()
          get a name for this agent.
 java.lang.ThreadGroup getThreadGroup()
          Return the thread group that we are in
 boolean invokeActionCommand(java.lang.String com)
          Invoke an action command by name.
 boolean isReady()
          this flag tells another object whether this agent is ready to do its stuff.
 boolean isTimeToStop()
          Tell if the agent been told to stop.
 java.util.Vector listAllIncomingConnections()
          Return a vector of all the agents that are connected to me
 java.util.Vector listAllOutgoingConnections()
          Return a vector of all that agents that i am connected to
protected  void loadIcon()
          Load the icon for an agent off of disk.
 void moveTo(edu.mit.media.hive.support.CellAddress address)
          Move this agent to a new host.
 void onDying()
          Used to notify the agent that it is about to be killed
 void onMoving()
          Used to notify the agent that it is about to be moved
private  void readObject(java.io.ObjectInputStream in)
          Handle deserialization
 void setCell(edu.mit.media.hive.cell.Cell s)
          Set the server flag on the agent.
 void setDescription(edu.mit.media.hive.rdf.Description desc)
          Set the semantic deescription of this agent.
 void setIconName(java.lang.String v)
          Set the value of iconName.
 void setIsReady(boolean flag)
          be careful when overriding thismethod.
 void setThreadGroup(java.lang.ThreadGroup tg)
          Set the thread group of this agent.
 void setTimeToStop(int flag)
          Sets the time to stop flag
protected  void waitUntilDeath()
          Used at the end of the doBehavior method.
private  void writeObject(java.io.ObjectOutputStream out)
          Handle serialization requests.
 
Methods inherited from class java.rmi.server.UnicastRemoteObject
clone, exportObject, exportObject, exportObject, unexportObject
 
Methods inherited from class java.rmi.server.RemoteServer
getClientHost, getLog, setLog
 
Methods inherited from class java.rmi.server.RemoteObject
equals, getRef, hashCode, toString, toStub
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

myCell

protected transient edu.mit.media.hive.cell.Cell myCell
Pointer to the server I am currently on.


agentThreadGroup

protected transient java.lang.ThreadGroup agentThreadGroup
Pointer to the thread group for this agent -- ell behaved agents, if they need to spawn separate threads, will make those threads members of this agents thread group. There is no way, unfortunately, for Hive to enforce this though


description

protected edu.mit.media.hive.rdf.Description description
Pointer to my RDF description.


readyFlag

protected transient boolean readyFlag
Just describing whether or not this agent is ready for operation or not


timeToStop

protected transient boolean timeToStop
Variable indicating this agent should die soon. This is set asynchronously, typically by the server. Agents should inspect this in their main loop.

See Also:
doBehavior

stopCode

protected transient int stopCode
Variable describing the reason why an agent was asked to stop


AGENTKILLED

public static final int AGENTKILLED
The different possible stop codes for the agents

See Also:
Constant Field Values

AGENTMOVED

public static final int AGENTMOVED
See Also:
Constant Field Values

icon

protected edu.mit.media.hive.support.SerializableImage icon
The icon that represents this agent. Should be loaded at create time.


iconName

protected java.lang.String iconName

commands

protected java.util.Hashtable commands
Hashtable and list for the popup menu items or their non-graphical equivalents.


commandList

protected java.util.Vector commandList
Hashtable of CommandObjects

Constructor Detail

AgentImpl

public AgentImpl()
          throws java.rmi.RemoteException
Basic constructor for agents. This only gets called once in an agent's lifetime, when it is first created. It is not called when the agent arrives at a new host.

Method Detail

getDescription

public edu.mit.media.hive.rdf.Description getDescription()
Return the semantic description of this agent.

Specified by:
getDescription in interface Agent

setDescription

public void setDescription(edu.mit.media.hive.rdf.Description desc)
Set the semantic deescription of this agent.

Specified by:
setDescription in interface edu.mit.media.hive.rdf.Describable

getIconName

public java.lang.String getIconName()
Get the value of iconName.


setIconName

public void setIconName(java.lang.String v)
Set the value of iconName.


getName

public java.lang.String getName()
Description copied from interface: Agent
get a name for this agent.

Specified by:
getName in interface Agent

connectTo

public boolean connectTo(Agent otherAgent)
Tell this agent to connect to some other agent. It is up to the agent to define the semantics of what this means. By default, AgentImpl just prints an error message and returns false.

Specified by:
connectTo in interface Agent

disconnectFromAll

public void disconnectFromAll()
Disconnects this agent from all agents.

Specified by:
disconnectFromAll in interface Agent

disconnectFrom

public void disconnectFrom(Agent otherAgent)
Disconnects this agent from the specified other agent.

Specified by:
disconnectFrom in interface Agent

doLocalSetup

public void doLocalSetup()
Handle the setup when an agent arrives on a host -- it is appropriate to allocate system resources (file descriptors, etc) here and even to locate other agents that this agent needs to communicate with. This method replaces arriveAt


setCell

public void setCell(edu.mit.media.hive.cell.Cell s)
Set the server flag on the agent. Normally user code should not call this - creation code in the server should handle this


setThreadGroup

public void setThreadGroup(java.lang.ThreadGroup tg)
Set the thread group of this agent. Normally user code should not call this -- the creation methods in the server will set this properly


doBehavior

public abstract void doBehavior()
Do the basic behavior for an agent, the agent's main loop. Override this to provide your particular agent's behavior. Note: the doBehavior loop should not exit. Please call waitUntilDeath() at the end of this method, this will prevent the Cell from believing this agent prematurely exited.


doBehaviour

public void doBehaviour()
Deprecated.  

This is a silly hack to prevent any of us from repeating the silliest and most aggravating error of all time. In America, behavior has no 'u'


waitUntilDeath

protected void waitUntilDeath()
Used at the end of the doBehavior method. Simply wait until the timeToStop flag has been set and the notify method has been called so we can exit properly,


onMoving

public void onMoving()
Used to notify the agent that it is about to be moved


moveTo

public void moveTo(edu.mit.media.hive.support.CellAddress address)
            throws edu.mit.media.hive.cell.AgentDeliveryException
Move this agent to a new host.


doLocalCleanup

public void doLocalCleanup()
Command the agent to free its local resources here. It may or may not equal what happens when the agent is supposed to die -- but here would be the appropriate place to free File descriptors, and stop threads, but do not do anything related to the agent community -- do not notify them that this agent is about to die. When this method terminates, this agent should be ready to be killed


onDying

public void onDying()
Used to notify the agent that it is about to be killed


diePlease

public void diePlease()
Ask the agent to politely die -- by default, the agent just relays the call to the server and asks it tkill itself

Specified by:
diePlease in interface Agent

setTimeToStop

public final void setTimeToStop(int flag)
Sets the time to stop flag


loadIcon

protected void loadIcon()
Load the icon for an agent off of disk. If the agent is class edu.mit.media.hive.FooAgent then this looks for edu.mit.media.hive/icons/FooAgent.ppm in the class path or Jar file. If that doesn't exist, then a default is substituted.


getIcon

public edu.mit.media.hive.support.SerializableImage getIcon()
Return the SerializableImage object that is the agent's icon.

Specified by:
getIcon in interface Agent

getCell

public edu.mit.media.hive.cell.RemoteCell getCell()
Return the server I'm living on.

Specified by:
getCell in interface Agent

getThreadGroup

public java.lang.ThreadGroup getThreadGroup()
Return the thread group that we are in


listAllIncomingConnections

public java.util.Vector listAllIncomingConnections()
Return a vector of all the agents that are connected to me

Specified by:
listAllIncomingConnections in interface Agent

listAllOutgoingConnections

public java.util.Vector listAllOutgoingConnections()
Return a vector of all that agents that i am connected to

Specified by:
listAllOutgoingConnections in interface Agent

configure

public void configure(org.w3c.dom.Document doc)
               throws java.rmi.RemoteException
Tells the agent to configure itself from the DOM Node doc. Override this function to configure an agentfrom an XML file. This method is called by Hive if the agent was created through The user's ~/.hive/agentConfig file. If you want to load a configuration by hand, see Global.getConfigAsXMLDocument().

Specified by:
configure in interface Agent

addActionCommand

public void addActionCommand(ActionCommand com)
Add a popup menu item or non-graphical equivalent to the agent's behavior.


invokeActionCommand

public boolean invokeActionCommand(java.lang.String com)
Invoke an action command by name. Currently, this will only be called in a baseUICanvas or its non-graphical equivalent.

Specified by:
invokeActionCommand in interface Agent

getActionCommands

public java.util.Vector getActionCommands()
Get the names of the ActionCommands this agent uses in the order in which they were entered.

Specified by:
getActionCommands in interface Agent

getComponentManagerShadow

public edu.mit.media.hive.shadow.cell.ComponentManagerShadow getComponentManagerShadow()
                                                                                throws edu.mit.media.hive.shadow.ShadowNotFoundException
A convenience method to return the ComponentManagerShadow or throws an exception if one is not present.


writeObject

private void writeObject(java.io.ObjectOutputStream out)
                  throws java.io.IOException
Handle serialization requests.


readObject

private void readObject(java.io.ObjectInputStream in)
                 throws java.io.IOException,
                        java.lang.ClassNotFoundException
Handle deserialization


setIsReady

public final void setIsReady(boolean flag)
be careful when overriding thismethod. deciding when an agent is ready is up to the agent's author, however the agent should -not- report that it is ready until after the setIsReady( true ) has been called on it -- when that method call has occured, it means that the agent has been listed in the server's "directory"


isReady

public boolean isReady()
this flag tells another object whether this agent is ready to do its stuff. the semantics of being ready are left up to the agent's author, however the only restriction is that the agent should -not- report that it is ready until the server calls setIsReady( true ) on this agent

Specified by:
isReady in interface Agent

blockUntilReady

public void blockUntilReady()
this method should block until the agent is ready -- it just sits in the wait method until it gets notified from the setIsReady method

Specified by:
blockUntilReady in interface Agent

isTimeToStop

public boolean isTimeToStop()
Tell if the agent been told to stop.