Overview  Package   Class  Use  Deprecated  Index
Home >> All >> edu >> mit >> media >> hive >> [ agent overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---

edu.mit.media.hive.agent
Class AgentImpl  

java.lang.Object
  java.rmi.server.RemoteObject
      java.rmi.server.RemoteServer
          java.rmi.server.UnicastRemoteObject
              edu.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.

---

Overview  Package   Class  Use  Deprecated  Index
Home >> All >> edu >> mit >> media >> hive >> [ agent overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---