fr.dyade.aaa.agent

Class Agent

Implemented Interfaces:
AgentMBean, Serializable
Known Direct Subclasses:
AgentAdmin, Container, Destination, ProxyAgent, UserAgent

public abstract class Agent
extends java.lang.Object
implements AgentMBean, Serializable

The Agent class represents the basic component in our model. agents are "reactive" objects which behave according to "event -> reaction"model: an event embodies a significant state change which one or many agents may react to.

Class Agent defines the generic interface and the common behavior for all agents; every agent is an object of a class deriving from class Agent. Agents are the elementary programming and execution entities; they only communicate using notifications through the message bus, and are controlled by the execution engine.

The reactive behavior is implemented by function member React, which defines the reaction of the agent when receiving a notification; this function member is called by the execution engine.

Agents are persistent objects, and the Agent class realizes a "swap-in/swap-out" mechanism which allows loading (or finding) in main memory the agents to activate, and unloading the agents idle since a while.


Agents must be created in two steps:

The following code would then create a simple agent and deploy it:

     Agent ag = new Agent();
     ag.deploy();
 

See Also:
Notification, Engine, Channel

Field Summary

protected boolean
fixed
Some agents must be loaded at any time, this can be enforced by this member variable.
protected Logger
logmon
String
name
Symbolic name of the agent

Constructor Summary

Agent()
Allocates a new Agent object.
Agent(String name)
Allocates a new Agent object.
Agent(String name, boolean fixed)
Allocates a new Agent object.
Agent(String name, boolean fixed, int stamp)
Constructor used to build Well Known Services agents.
Agent(boolean fixed)
Allocates a new Agent object.
Agent(short to)
Allocates a new Agent object.
Agent(short to, String name)
Allocates a new Agent object.
Agent(short to, String name, boolean fixed)
Allocates a new Agent object.
Agent(short to, boolean fixed)
Allocates a new Agent object.

Method Summary

void
agentFinalize(boolean lastTime)
Called to inform this agent that it is garbaged and that it should free any active ressources that it has allocated.
protected void
agentInitialize(boolean firstTime)
Gives this agent an opportunity to initialize after having been deployed, and each time it is loaded into memory.
void
delete()
Permits this agent to destroy it.
void
delete(AgentId agent)
Permits this agent to destroy it.
void
deploy()
Deploys a new agent.
void
deploy(AgentId reply)
Deploys a new agent.
AgentId
getId()
Returns the global unique identifier of the agent.
protected String
getLogTopic()
Returns default log topic for agents.
String
getName()
Returns this Agent's name.
boolean
isDeployed()
Returns if the currently Agent has already been deployed.
boolean
isFixed()
Tests if the agent is pinned in memory.
protected boolean
needToBeCommited()
void
react(AgentId from, Notification not)
Defines the reaction of the agent when receiving a notification.
protected void
save()
Saves the agent state unless not requested.
protected void
sendTo(AgentId to, Notification not)
This method sends a notification to the agent which id is given in parameter.
protected void
sendTo(Role role, Notification not)
This method sends a notification to the agent which id is wrapped in the specified role.
protected void
sendTo(RoleMultiple role, Notification not)
Sends a notification to all the agents registered in a role.
protected void
setNoSave()
Sets the updated field to false so that the agent state is not saved after the current reaction; the field is set back to true for the next reaction.
String
toString()
Returns a string representation of this agent, including the agent's class, name, global identication, and fixed property.

Field Details

fixed

protected boolean fixed
Some agents must be loaded at any time, this can be enforced by this member variable. If true agent is pinned in memory.


logmon

protected Logger logmon


name

public String name
Symbolic name of the agent

Constructor Details

Agent

public Agent()
Allocates a new Agent object. The resulting object is not an agent; before it can react to a notification you must deploy it. This constructor has the same effect as Agent(AgentServer.getServerId(), null, false).

See Also:
Agent.Agent(short, java.lang.String, boolean), deploy()


Agent

public Agent(String name)
Allocates a new Agent object. This constructor has the same effect as Agent(AgentServer.getServerId(), name, false).

Parameters:
name - symbolic name

See Also:
Agent.Agent(short, java.lang.String, boolean)


Agent

public Agent(String name,
             boolean fixed)
Allocates a new Agent object. This constructor has the same effect as Agent(AgentServer.getServerId(), name, fixed).

Parameters:
name - symbolic name
fixed - if true agent is pinned in memory

See Also:
Agent.Agent(short, java.lang.String, boolean)


Agent

public Agent(String name,
             boolean fixed,
             int stamp)
Constructor used to build Well Known Services agents.

System agents are created from the agent package. WKS agents are similar to system agents, except that they may be defined in separate packages, and they do not necessarily exist on all agent servers. Their creation is controlled from the configuration file of the agent server.

This constructor takes the agent id as a parameter instead of building it. Since the constructor has been made public, the consistency of agent ids allocation must be enforced. This is done by the constructor checking that the id stamp is comprised in the AgentId.MinWKSIdStamp - AgentId.MaxWKSIdStamp interval.

Parameters:
name - symbolic name
fixed - if true agent is pinned in memory
stamp - well known stamp


Agent

public Agent(boolean fixed)
Allocates a new Agent object. This constructor has the same effect as Agent(AgentServer.getServerId(), null, fixed).

Parameters:
fixed - if true agent is pinned in memory

See Also:
Agent(short,String,boolean)


Agent

public Agent(short to)
Allocates a new Agent object. This constructor has the same effect as Agent(to, null, false).

Parameters:
to - Identication of target agent server

See Also:
Agent.Agent(short, java.lang.String, boolean)


Agent

public Agent(short to,
             String name)
Allocates a new Agent object. This constructor has the same effect as Agent(to, name, false).

Parameters:
to - Identication of target agent server
name - symbolic name

See Also:
Agent.Agent(short, java.lang.String, boolean)


Agent

public Agent(short to,
             String name,
             boolean fixed)
Allocates a new Agent object. The resulting object is not an agent; before it can react to a notification you must deploy it.

Parameters:
to - Identication of target agent server
name - symbolic name
fixed - if true agent is pinned in memory

See Also:
deploy()


Agent

public Agent(short to,
             boolean fixed)
Allocates a new Agent object. This constructor has the same effect as Agent(to, null, fixed).

Parameters:
to - Identication of target agent server
fixed - if true agent is pinned in memory

See Also:
Agent.Agent(short, java.lang.String, boolean)

Method Details

agentFinalize

public void agentFinalize(boolean lastTime)
Called to inform this agent that it is garbaged and that it should free any active ressources that it has allocated. A subclass of Agent should override this method if it has any operation that it wants to perform before it is garbaged. For example, an agent with threads (a ProxyAgent for example) would use the initialize method to create the threads and the agentFinalize method to stop them. The implementation of this method provided by the Agent class does nothing.

Parameters:
lastTime - true when last called by the factory on agent deletion.


agentInitialize

protected void agentInitialize(boolean firstTime)
            throws Exception
Gives this agent an opportunity to initialize after having been deployed, and each time it is loaded into memory.

This function is first called by the factory agent, just after it deploys the agent.

This function is used by agents with a fixed field set to true to initialize their transient variables, as it is called each time the agent server is restarted.

This function is not declared final so that derived classes may change their reload policy. The implementation of this method provided by the Agent class does nothing.

Parameters:
firstTime - true when first called by the factory


delete

public void delete()
Permits this agent to destroy it. If necessary, its method should be overloaded to work properly.
Specified by:
delete in interface AgentMBean


delete

public void delete(AgentId agent)
Permits this agent to destroy it. If necessary, its method should be overloaded to work properly.

Parameters:
agent - Id of agent to notify.


deploy

public final void deploy()
            throws IOException
Deploys a new agent. It works by sending a notification to a special agent, of class Factory, running on the target agent server. The notification asks for a remote creation of the agent. This solution presents the advantage of reusing the standard communication mechanisms of the agent machine.

The whole process involves then the following steps:

  • serializing the object state,
  • building an AgentCreateRequest notification with the resulting bytes stream,
  • sending it to the target Factory agent.
In reaction, the factory agent builds the agent in the target server from the serialized image, and saves it into operational storage.


deploy

public final void deploy(AgentId reply)
            throws IOException
Deploys a new agent. It works as deploy() method above; after the agent creation, the Factory agent sends an AgentCreateReply notification.

Parameters:
reply - agent to reply to


getId

public final AgentId getId()
Returns the global unique identifier of the agent. Each agent is identified by a unique identifier allowing the agent to be found. The identifiers format is detailed in AgentId class.
Specified by:
getId in interface AgentMBean

Returns:
the global unique identifier of the agent.


getLogTopic

protected String getLogTopic()
Returns default log topic for agents. Its method should be overridden in subclass in order to permit fine configuration of logging system. By default it returns Debug.A3Agent.


getName

public String getName()
Returns this Agent's name.
Specified by:
getName in interface AgentMBean

Returns:
this Agent's name.


isDeployed

public boolean isDeployed()
Returns if the currently Agent has already been deployed.


isFixed

public final boolean isFixed()
Tests if the agent is pinned in memory.
Specified by:
isFixed in interface AgentMBean

Returns:
true if this agent is a pinned in memory; false otherwise.

See Also:
fixed


needToBeCommited

protected final boolean needToBeCommited()


react

public void react(AgentId from,
                  Notification not)
            throws Exception
Defines the reaction of the agent when receiving a notification. This member function implements the common reactive behavior of an agent, it is called by the execution engine (see Engine class).

If there is no corresponding reaction, the agent send an UnknownNotification notification to the sender.

Parameters:
from - agent sending notification
not - notification to react to


save

protected final void save()
            throws IOException
Saves the agent state unless not requested.


sendTo

protected final void sendTo(AgentId to,
                            Notification not)
This method sends a notification to the agent which id is given in parameter. During an agent reaction alls notifications sent are buffered until reaction commit.

Be careful if you use this method outside of an agent reaction, its behavior is slightly different: each notification is immediatly sent using a local transaction.

Parameters:
to - the unique id. of destination Agent.
not - the notification to send.

See Also:
Channel.sendTo(AgentId,Notification)


sendTo

protected final void sendTo(Role role,
                            Notification not)
This method sends a notification to the agent which id is wrapped in the specified role.

Parameters:
role - the destination Role.
not - the notification to send.


sendTo

protected final void sendTo(RoleMultiple role,
                            Notification not)
Sends a notification to all the agents registered in a role.

Parameters:
role - the destination MultiplRole.
not - the notification to send.


setNoSave

protected void setNoSave()
Sets the updated field to false so that the agent state is not saved after the current reaction; the field is set back to true for the next reaction.


toString

public String toString()
Returns a string representation of this agent, including the agent's class, name, global identication, and fixed property.
Specified by:
toString in interface AgentMBean

Returns:
A string representation of this agent.


Copyright B) 2004 Scalagent - All rights reserved