fr.dyade.aaa.agent
Class Agent

java.lang.Object
  extended by fr.dyade.aaa.agent.Agent
All Implemented Interfaces:
AgentMBean, java.io.Serializable
Direct Known Subclasses:
AgentFactory, Container, Destination, 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
(package private)  long commitTime
           
(package private)  boolean deployed
          Determines if the current Agent has already been deployed.
static java.lang.String emptyString
           
protected  boolean fixed
          Some agents must be loaded at any time, this can be enforced by this member variable.
(package private)  AgentId id
          Global unique identifier of the agent.
(package private)  long last
          the last variable contains the virtual time of the last access.
protected  org.objectweb.util.monolog.api.Logger logmon
           
(package private)  java.lang.String name
          Symbolic name of the agent
(package private)  int reactNb
           
(package private)  long reactTime
           
(package private) static long serialVersionUID
          Define serialVersionUID for interoperability.
private  boolean updated
          true if the agent state has changed.
 
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, AgentId id)
          Constructor used to build "system" agents like AgentFactory.
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 resources 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 itself.
 void delete(AgentId agent)
          Permits this agent to destroy itself.
 void delete(AgentId agent, java.lang.Object extraInformation)
          Permits this agent to destroy itself.
 void deploy()
          Deploys a new agent.
 void deploy(AgentId reply)
          Deploys a new agent.
 java.lang.String getAgentId()
          Returns String format of the global unique identifier of the agent.
 long getCommitTime()
           
 AgentId getId()
          Returns the global unique identifier of the agent.
protected  java.lang.String getLogTopic()
          Returns default log topic for agents.
private  java.lang.String getMBeanName()
           
 java.lang.String getName()
          Returns this Agent's name.
 int getReactNb()
           
 long getReactTime()
           
private  void initState(java.lang.String name, boolean fixed, AgentId id)
           
 boolean isDeployed()
          Returns if the currently Agent has already been deployed.
 boolean isFixed()
          Tests if the agent is pinned in memory.
(package private) static Agent load(AgentId id)
          Restores the object state from the persistent storage.
protected  boolean needToBeCommited()
          Indicates to the Engine component that a commit is needed.
 void react(AgentId from, Notification not)
          Defines the reaction of the agent when receiving a notification.
private  void readObject(java.io.ObjectInputStream in)
           
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.
 void setName(java.lang.String name)
          Sets this Agent's name.
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.
protected  void setSave()
          Sets the updated field to true so that the agent state is saved after the current reaction.
 java.lang.String toString()
          Returns a string representation of this agent, including the agent's class, name, global identification, and fixed property.
private  void writeObject(java.io.ObjectOutputStream out)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

serialVersionUID

static final long serialVersionUID
Define serialVersionUID for interoperability.

See Also:
Constant Field Values

updated

private transient boolean updated
true if the agent state has changed.

This field value is initialized as true, so that by default the agent state is saved after a reaction.


reactNb

transient int reactNb

reactTime

transient long reactTime

commitTime

transient long commitTime

id

transient AgentId id
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.


name

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

last

transient long last
the last variable contains the virtual time of the last access. It is used by swap-out policy.

See Also:
garbage

emptyString

public static final java.lang.String emptyString
See Also:
Constant Field Values

deployed

transient boolean deployed
Determines if the current Agent has already been deployed.

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 - Identification 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 - Identification 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 - Identification 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 - Identification of target agent server
name - symbolic name
fixed - if true agent is pinned in memory
See Also:
deploy()

Agent

Agent(java.lang.String name,
      boolean fixed,
      AgentId id)
Constructor used to build "system" agents like AgentFactory. System agents are created from the agent package. This constructor takes the agent id as a parameter instead of building it.

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

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

getReactNb

public int getReactNb()
Specified by:
getReactNb in interface AgentMBean
Returns:
the reactNb

getReactTime

public long getReactTime()
Specified by:
getReactTime in interface AgentMBean
Returns:
the reactTime

getCommitTime

public long getCommitTime()
Specified by:
getCommitTime in interface AgentMBean
Returns:
the commitTime

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.


setSave

protected void setSave()
Sets the updated field to true so that the agent state is saved after the current reaction.


needToBeCommited

protected final boolean needToBeCommited()
Indicates to the Engine component that a commit is needed.


save

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

Throws:
java.io.IOException

load

static final Agent load(AgentId id)
                 throws java.io.IOException,
                        java.lang.ClassNotFoundException
Restores the object state from the persistent storage.

Throws:
java.io.IOException - when accessing the stored image
java.lang.ClassNotFoundException - if the stored image class may not be found

getName

public java.lang.String getName()
Returns this Agent's name. If the name is not set returns the string representation of its unique id.

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

setName

public void setName(java.lang.String name)
Sets this Agent's name.

Parameters:
name - the Agent's name.

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.


writeObject

private void writeObject(java.io.ObjectOutputStream out)
                  throws java.io.IOException
Throws:
java.io.IOException

readObject

private void readObject(java.io.ObjectInputStream in)
                 throws java.io.IOException,
                        java.lang.ClassNotFoundException
Throws:
java.lang.ClassNotFoundException
java.io.IOException

initState

private void initState(java.lang.String name,
                       boolean fixed,
                       AgentId id)

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

toString

public java.lang.String toString()
Returns a string representation of this agent, including the agent's class, name, global identification, and fixed property.

Specified by:
toString in interface AgentMBean
Overrides:
toString in class java.lang.Object
Returns:
A string representation of this agent.

getAgentId

public final java.lang.String getAgentId()
Returns String format of the global unique identifier of the agent.

Specified by:
getAgentId in interface AgentMBean
Returns:
the global unique identifier of the 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.

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.

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 just registers the JMS MBean.

Parameters:
firstTime - true when first called by the factory
Throws:
java.lang.Exception - unspecialized exception

getMBeanName

private java.lang.String getMBeanName()

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 immediately 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 itself. If necessary, this method should be overloaded to work properly.

Specified by:
delete in interface AgentMBean

delete

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

Parameters:
agent - Id of agent to notify.

delete

public void delete(AgentId agent,
                   java.lang.Object extraInformation)
Permits this agent to destroy itself. If necessary, this method should be overloaded to work properly.

Parameters:
agent - Id of agent to notify.
extraInformation - extra information added when notifying the agent.

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 resources 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.

Be careful, the notification sending is not allowed in this method.

The implementation of this method provided by the Agent class just unregister the JMX MBean if needed.

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


Copyright © 2010 ScalAgent D.T.. All Rights Reserved.