The methods of the Hive lifecycle
There are six methods in the Hive lifecycle. These methods are all defined in the base class are derived from the base AgentImpl -- some of these methods are abstract and they must be overridden, some are written in AgentImpl as placeholders for the agent author's code. When overriding lifecycle methods, it is important that the programmer remember to call the superclass method as well.
AgentImpl()
The first method in the agent's lifecycle is its constructor. Every agent must define its own constructor, if nothing else than to state that it throws java.rmi.RemoteException. The only item that should be placed inside an agent's constructor are to initialize any complex, non-transient data structures that the agent requires for its operation. It is important to remember that the agent's constructor will only be called once during the agent's lifecycle, it will not be called when an agent arrives on another server. It is rare that anything will need to be put inside the constructor at all.
AgentImpl.doLocalSetup()
The second method that is called in an agent's life is doLocalSetup(). This method should contain any that should be executed when an agent "arrives" at a new server, either when it is first born or when it has just moved. Typical actions for local setup are gaining access to a shadow or finding another agent to talk to.
One obvious example is for any agent which is simple repeating events from a shadow. These agents (usually derivatives of GenericSignalPassthroughAgentImpl) find the shadow they need to talk to in their doLocalSetup() code and add themselves as a signal listener. If they cannot find the shadow they need, they often commit suicide by calling this.diePlease().
AgentImpl.doBehavior()
doBehavior() is the most important method in the agent's lifecycle, the place where an agent gets to do its own thing. Unlike other methods in the lifecycle, Hive does not expect doBehavior() to exit - indeed, if it does exit Hive assumes the agent has died.
When Hive wants an agent to die, it will call diePlease() on it, resulting on its "timeToStop" flag being set to true. An agent should inspect this flag in the doBehavior() method and exit if appropriate. The common way to do this is to wrap the agent's behavior in a while loop that is testing timeToStop ((while !timeToStop) { //... }. For agents that do not need anything in their doBehavior() loops, authors should call waitUntilDeath() inside the method. waitUntilDeath() is an efficient way to block until the timeToStop variable is set to true.
When timeToStop is actually set, then a variable named stopCode is also set to indicate why the agent should stop. This flag will either be set to AgentImpl.AGENTKILLED or AgentImpl.AGENTMOVED depending which one is appropriate. The agent can use this information to decide, for example, to move to another cell if it is about to be killed.
A final comment about timeToStop - when it is set, notify() is also called on the agent object. Agents that are waiting to die (for example, in the waitUntilDeath() method) can call wait() on themselves if they just want to wait until they are told to die. Programmers of simple agents do not need to be aware of this interaction.
AgentImp.onDying()
The onDying() method is called by the server just before the agent is killed. Agents can override this method to take their own action on being killed, or they can defer this work to doLocalCleanup().
AgentImpl.onMoving()
The onMoving() method is called by the server just before the agent is moved. Agents can override this method to take their own action on being moved, or they can defer this work to doLocalCleanup().
AgentImpl.doLocalCleanup()
The last part of an agent's life is doLocalCleanup(), the counterpart to doLocalSetup(). Here, the agent should remove all access to resources it has used. For example, this is the place that a GenericSignalPassthroughAgentImpl removes the agent as a listener from the shadow when this method is called.
If an agent is dying, it can try to notify any agents it has a relationship with in doLocalCleanup(). If the agent is only moving, it could be a bit more complicated. Hive does not currently support message forwarding of any sort, and so moving often looks like dying to other agents. If you want to do something for moving agents, contact the Hive team for ideas.