fr.dyade.aaa.agent
Class Agent
- AgentMBean, Serializable
public abstract class Agent
extends java.lang.Object
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:
- locally creating the object in memory (via constructor),
- configure it (for example via get/set methods),
- the deploy it .
The following code would then create a simple agent and deploy it:
Agent ag = new Agent();
ag.deploy();
Notification
, Engine
, Channel
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
|
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.
|
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.
|
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
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)
.
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)
.
name
- symbolic name
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)
.
name
- symbolic namefixed
- if true
agent is pinned in memory
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.
name
- symbolic namefixed
- if true
agent is pinned in memorystamp
- 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)
.
fixed
- if true
agent is pinned in memory
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)
.
to
- Identication of target agent server
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)
.
to
- Identication of target agent servername
- symbolic name
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.
to
- Identication of target agent servername
- symbolic namefixed
- if true
agent is pinned in memory
deploy()
Agent
public Agent(short to,
boolean fixed)
Allocates a new Agent object. This constructor has the same effect
as Agent(to, null, fixed)
.
to
- Identication of target agent serverfixed
- if true
agent is pinned in memory
Agent.Agent(short, java.lang.String, boolean)
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.
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.
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.
- 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.
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.
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.
- getId in interface AgentMBean
- 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.
- getName in interface AgentMBean
- 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.
- isFixed in interface AgentMBean
- true if this agent is a pinned in memory; false otherwise.
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.
from
- agent sending notificationnot
- 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.
to
- the unique id. of destination Agent
.not
- the notification to send.
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.
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.
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.
- toString in interface AgentMBean
- A string representation of this agent.
Copyright B) 2004 Scalagent - All rights reserved