fr.dyade.aaa.agent
Class Agent

java.lang.Object
  extended byfr.dyade.aaa.agent.Agent
All Implemented Interfaces:
AgentMBean, java.io.Serializable
Direct Known Subclasses:
AgentAdmin, Container, Destination, ProxyAgent, UserAgent

public abstract class Agent
extends java.lang.Object
implements AgentMBean, java.io.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, Serialized Form

Field Summary
protected  boolean fixed
          Some agents must be loaded at any time, this can be enforced by this member variable.
protected  org.objectweb.util.monolog.api.Logger logmon
           
 java.lang.String name
          Symbolic name of the agent
 
Constructor Summary
Agent()
          Allocates a new Agent object.
Agent(boolean fixed)
          Allocates a new Agent object.
Agent(short to)
          Allocates a new Agent object.
Agent(short to, boolean fixed)
          Allocates a new Agent object.
Agent(short to, java.lang.String name)
          Allocates a new Agent object.
Agent(short to, java.lang.String name, boolean fixed)
          Allocates a new Agent object.
Agent(java.lang.String name)
          Allocates a new Agent object.
Agent(java.lang.String name, boolean fixed)
          Allocates a new Agent object.
Agent(java.lang.String name, boolean fixed, int stamp)
          Constructor used to build Well Known Services agents.
 
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  java.lang.String getLogTopic()
          Returns default log topic for agents.
 java.lang.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(RoleMultiple role, Notification not)
          Sends a notification to all the agents registered in a role.
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 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.
 java.lang.String toString()
          Returns a string representation of this agent, including the agent's class, name, global identication, and fixed property.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

name

public transient java.lang.String name
Symbolic name of the agent


fixed

protected transient 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 transient org.objectweb.util.monolog.api.Logger logmon
Constructor Detail

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(short, java.lang.String, boolean), deploy()

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(java.lang.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(short, java.lang.String, boolean)

Agent

public Agent(java.lang.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(short, java.lang.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(short, java.lang.String, boolean)

Agent

public Agent(short to,
             java.lang.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(short, java.lang.String, boolean)

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(short, java.lang.String, boolean)

Agent

public Agent(short to,
             java.lang.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(java.lang.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
Method Detail

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.


needToBeCommited

protected final boolean needToBeCommited()

save

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

Throws:
java.io.IOException

getLogTopic

protected java.lang.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.


isDeployed

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


deploy

public final void deploy()
                  throws java.io.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:

In reaction, the factory agent builds the agent in the target server from the serialized image, and saves it into operational storage.

Throws:
java.io.IOException - unspecialized exception

deploy

public final void deploy(AgentId reply)
                  throws java.io.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
Throws:
java.io.IOException - unspecialized exception

getName

public java.lang.String getName()
Returns this Agent's name.

Specified by:
getName in interface AgentMBean
Returns:
this Agent's name.

toString

public java.lang.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.

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.

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

agentInitialize

protected void agentInitialize(boolean firstTime)
                        throws java.lang.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
Throws:
java.lang.Exception - unspecialized exception

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(fr.dyade.aaa.agent.AgentId, fr.dyade.aaa.agent.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.

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.

react

public void react(AgentId from,
                  Notification not)
           throws java.lang.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
Throws:
java.lang.Exception - unspecialized exception

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.


Copyright ? 2004 Scalagent - All rights reserved