fr.dyade.aaa.agent
Class Engine

java.lang.Object
  extended by fr.dyade.aaa.agent.Engine
All Implemented Interfaces:
EngineMBean, MessageConsumer, java.lang.Runnable
Direct Known Subclasses:
HAEngine

 class Engine
extends java.lang.Object
implements java.lang.Runnable, MessageConsumer, EngineMBean

The Engine class provides multiprogramming of agents. It realizes the program loop which successively gets the notifications from the message queue and calls the relevant reaction function member of the target agent. The engine's basic behaviour is:

 While (true) {
   // get next message in channel
   Message msg = qin.get();
   // get the agent to process event
   Agent agent = load(msg.to);
   // execute relevant reaction, all notification sent during this
   // reaction is inserted into persistent queue in order to processed
   // by the channel.
   agent.react(msg.from, msg.not);
   // save changes, then commit.
   <BEGIN TRANSACTION>
   qin.pop();
   channel.dispatch();
   agent.save();
   <COMMIT TRANSACTION>
 }
 

The Engine class ensures the atomic handling of an agent reacting to a notification:


Handling errors.

Two types of errors may occur: errors of first type are detected in the source code and signaled by an Exception; serious errors lead to an Error being raised then the engine exits. In the first case the exception may be handled at any level, even partially. Most of them are signaled up to the engine loop. Two cases are then distinguished depending on the recovery policy:


Nested Class Summary
(package private)  class Engine.EngineAverageLoadTask
           
 
Field Summary
(package private)  Agent agent
          The current agent running.
 boolean agentProfiling
           
(package private)  java.util.Hashtable agents
          This table is used to maintain a list of agents already in memory using the AgentId as primary key.
(package private)  Engine.EngineAverageLoadTask averageLoadTask
           
protected  boolean canStop
          Boolean variable used to stop the engine properly.
private  long commitTime
          Time consumned during reaction commit.
(package private)  java.util.Vector fixedAgentIdList
          Vector containing id's of all fixed agents.
protected  boolean isRunning
          Boolean variable used to stop the engine properly.
protected  org.objectweb.util.monolog.api.Logger logmon
           
private  boolean modified
          True if the timestamp is modified since last save.
protected  Queue mq
           
(package private)  Message msg
          The message in progress.
private  java.lang.String name
           
(package private)  int NbMaxAgents
          Maximum number of memory loaded agents.
protected  boolean needToBeCommited
           
(package private)  long now
          Virtual time counter use in FIFO swap-in/swap-out mechanisms.
protected  MessageQueue qin
          Queue of messages to be delivered to local agents.
private  long reactTime
          Time consumned during agent's reaction.
(package private)  int recoveryPolicy
          recovery policy in case of exception in agent specific code.
(package private) static int RP_EXC_NOT
          Send ExceptionNotification notification in case of exception in agent specific code.
(package private) static int RP_EXIT
          Stop agent server in case of exception in agent specific code.
(package private) static java.lang.String[] rpStrings
          String representations of RP_* constant values for the recoveryPolicy variable.
private  int stamp
          Logical timestamp information for messages in "local" domain.
private  byte[] stampBuf
          Buffer used to optimize
(package private)  EngineThread thread
          The active component of this engine.
protected  long timeout
           
 
Constructor Summary
protected Engine()
          Initializes a new Engine object (can only be used by subclasses).
 
Method Summary
(package private)  void abort(java.lang.Exception exc)
          Abort the agent reaction in case of error during execution.
(package private)  void addFixedAgentId(AgentId id)
          Adds an AgentId in the fixedAgentIdList Vector.
(package private)  void clean()
          Cleans the Channel queue of all pushed notifications.
(package private)  void commit()
          Commit the agent reaction in case of right termination: suppress the processed notification from message queue, then deletes it ; push all new notifications in qin and qout, and saves them ; saves the agent state ; then commit the transaction to validate all changes.
(package private)  void createAgent(Agent agent)
          Creates and initializes an agent.
(package private)  void createAgent(AgentId id, Agent agent)
          Creates and initializes an agent.
 void delete()
          This operation always throws an IllegalStateException.
(package private)  void deleteAgent(AgentId from)
          Deletes an agent.
(package private)  void dispatch()
          Dispatch messages between the MessageConsumer: Engine component and Network components.
 java.lang.String dumpAgent(AgentId id)
          Returns a string representation of the specified agent.
 java.lang.String dumpAgent(java.lang.String id)
          Returns a string representation of the specified agent.
(package private)  void garbage()
          The garbage method should be called regularly , to swap out from memory all the agents which have not been accessed for a time.
 float getAverageLoad1()
          Returns the load averages for the last minute.
 float getAverageLoad15()
          Returns the load averages for the past 15 minutes.
 float getAverageLoad5()
          Returns the load averages for the past 5 minutes.
 long getCommitTime()
           
 java.lang.String getDomainName()
          Returns the corresponding domain's name.
(package private)  AgentId[] getLoadedAgentIdlist()
          Method used for debug and monitoring.
 java.lang.String getName()
          Returns this Engine's name.
 int getNbAgents()
          Returns the number of agents actually loaded in memory.
 int getNbFixedAgents()
          Returns the number of fixed agents.
 int getNbMaxAgents()
          Returns the maximum number of agents loaded in memory.
 int getNbMessages()
          Gets the number of messages posted to this engine since creation.
 long getNbReactions()
          Returns the number of agent's reaction since last boot.
 int getNbWaitingMessages()
          Gets the number of waiting messages in this engine.
 MessageQueue getQueue()
          Get this engine's MessageQueue qin.
 long getReactTime()
           
protected  int getStamp()
           
(package private)  void init()
           
 void insert(Message msg)
          Insert a message in the MessageQueue.
 boolean isAgentProfiling()
           
 boolean isRunning()
          Tests if the engine is alive.
(package private)  Agent load(AgentId id)
          The load method return the Agent object designed by the AgentId parameter.
(package private) static Engine newInstance()
          Creates a new instance of Engine (real class depends of server type).
protected  void onTimeOut()
           
 void post(Message msg)
          Adds a message in "ready to deliver" list.
(package private)  void push(AgentId from, AgentId to, Notification not)
          Push a new message in temporary queue until the end of current reaction.
(package private)  Agent reload(AgentId id)
          The reload method return the Agent object loaded from the storage.
(package private)  void removeFixedAgentId(AgentId id)
          Removes an AgentId in the fixedAgentIdList Vector.
 void restore()
          Restores logical clock information from persistent storage.
 void run()
          Main loop of agent server Engine.
 void save()
          Saves logical clock information to persistent storage.
 void setAgentProfiling(boolean agentProfiling)
           
 void setNbMaxAgents(int NbMaxAgents)
          Sets the maximum number of agents that can be loaded simultaneously in memory.
protected  void setStamp(int stamp)
           
protected  void stamp(Message msg)
           
 void start()
          Causes this engine to begin execution.
 void stop()
          Forces the engine to stop executing.
(package private)  void terminate()
           
 java.lang.String toString()
          Returns a string representation of this engine.
 void validate()
          Validates all messages pushed in queue during transaction session.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

qin

protected MessageQueue qin
Queue of messages to be delivered to local agents.


isRunning

protected volatile boolean isRunning
Boolean variable used to stop the engine properly. The engine tests this variable between each reaction, and stops if it is false.


canStop

protected volatile boolean canStop
Boolean variable used to stop the engine properly. If this variable is true then the engine is waiting and it can interrupted, else it handles a notification and it will exit after (the engine tests the isRunning variable between each reaction)


stamp

private int stamp
Logical timestamp information for messages in "local" domain.


stampBuf

private byte[] stampBuf
Buffer used to optimize


modified

private boolean modified
True if the timestamp is modified since last save.


agents

java.util.Hashtable agents
This table is used to maintain a list of agents already in memory using the AgentId as primary key.


now

long now
Virtual time counter use in FIFO swap-in/swap-out mechanisms.


NbMaxAgents

int NbMaxAgents
Maximum number of memory loaded agents.


fixedAgentIdList

java.util.Vector fixedAgentIdList
Vector containing id's of all fixed agents.


agent

Agent agent
The current agent running.


msg

Message msg
The message in progress.


thread

EngineThread thread
The active component of this engine.


RP_EXC_NOT

static final int RP_EXC_NOT
Send ExceptionNotification notification in case of exception in agent specific code. Constant value for the recoveryPolicy variable.

See Also:
Constant Field Values

RP_EXIT

static final int RP_EXIT
Stop agent server in case of exception in agent specific code. Constant value for the recoveryPolicy variable.

See Also:
Constant Field Values

rpStrings

static final java.lang.String[] rpStrings
String representations of RP_* constant values for the recoveryPolicy variable.


recoveryPolicy

int recoveryPolicy
recovery policy in case of exception in agent specific code. Default value is RP_EXC_NOT.


name

private java.lang.String name

mq

protected Queue mq

logmon

protected org.objectweb.util.monolog.api.Logger logmon

needToBeCommited

protected boolean needToBeCommited

timeout

protected long timeout

agentProfiling

public boolean agentProfiling

reactTime

private long reactTime
Time consumned during agent's reaction.


commitTime

private long commitTime
Time consumned during reaction commit.


averageLoadTask

Engine.EngineAverageLoadTask averageLoadTask
Constructor Detail

Engine

protected Engine()
          throws java.lang.Exception
Initializes a new Engine object (can only be used by subclasses).

Throws:
java.lang.Exception
Method Detail

getNbReactions

public long getNbReactions()
Returns the number of agent's reaction since last boot.

Specified by:
getNbReactions in interface EngineMBean
Returns:
the number of agent's reaction since last boot

getNbMaxAgents

public int getNbMaxAgents()
Returns the maximum number of agents loaded in memory.

Specified by:
getNbMaxAgents in interface EngineMBean
Returns:
the maximum number of agents loaded in memory

setNbMaxAgents

public void setNbMaxAgents(int NbMaxAgents)
Sets the maximum number of agents that can be loaded simultaneously in memory.

Specified by:
setNbMaxAgents in interface EngineMBean
Parameters:
NbMaxAgents - the maximum number of agents

getNbAgents

public int getNbAgents()
Returns the number of agents actually loaded in memory.

Specified by:
getNbAgents in interface EngineMBean
Returns:
the maximum number of agents actually loaded in memory

getNbMessages

public int getNbMessages()
Gets the number of messages posted to this engine since creation. return the number of messages.

Specified by:
getNbMessages in interface EngineMBean

getNbWaitingMessages

public int getNbWaitingMessages()
Gets the number of waiting messages in this engine. return the number of waiting messages.

Specified by:
getNbWaitingMessages in interface EngineMBean

getNbFixedAgents

public int getNbFixedAgents()
Returns the number of fixed agents.

Specified by:
getNbFixedAgents in interface EngineMBean
Returns:
the number of fixed agents

getName

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

Specified by:
getName in interface EngineMBean
Specified by:
getName in interface MessageConsumer
Returns:
this Engine's name.

getDomainName

public final java.lang.String getDomainName()
Returns the corresponding domain's name.

Specified by:
getDomainName in interface MessageConsumer
Returns:
this domain's name.

newInstance

static Engine newInstance()
                   throws java.lang.Exception
Creates a new instance of Engine (real class depends of server type).

Returns:
the corresponding engine's instance.
Throws:
java.lang.Exception

push

final void push(AgentId from,
                AgentId to,
                Notification not)
Push a new message in temporary queue until the end of current reaction. As this method is only called by engine's thread it does not need to be synchronized.


dispatch

final void dispatch()
             throws java.lang.Exception
Dispatch messages between the MessageConsumer: Engine component and Network components.

Handle persistent information in respect with engine transaction.


Be careful, this method must only be used during a transaction in order to ensure the mutual exclusion.

Throws:
java.io.IOException - error when accessing the local persistent storage.
java.lang.Exception

clean

final void clean()
Cleans the Channel queue of all pushed notifications.


Be careful, this method must only be used during a transaction in order to ensure the mutual exclusion.


init

void init()
    throws java.lang.Exception
Throws:
java.lang.Exception

terminate

void terminate()

createAgent

final void createAgent(AgentId id,
                       Agent agent)
                throws java.lang.Exception
Creates and initializes an agent.

Parameters:
agent - agent object to create
Throws:
java.lang.Exception - unspecialized exception

createAgent

final void createAgent(Agent agent)
                throws java.lang.Exception
Creates and initializes an agent.

Parameters:
agent - agent object to create
Throws:
java.lang.Exception - unspecialized exception

deleteAgent

void deleteAgent(AgentId from)
           throws java.lang.Exception
Deletes an agent.

Parameters:
agent - agent to delete
Throws:
java.lang.Exception

garbage

void garbage()
The garbage method should be called regularly , to swap out from memory all the agents which have not been accessed for a time.


removeFixedAgentId

void removeFixedAgentId(AgentId id)
                  throws java.io.IOException
Removes an AgentId in the fixedAgentIdList Vector.

Parameters:
id - the AgentId of no more used fixed agent.
Throws:
java.io.IOException

addFixedAgentId

void addFixedAgentId(AgentId id)
               throws java.io.IOException
Adds an AgentId in the fixedAgentIdList Vector.

Parameters:
id - the AgentId of new fixed agent.
Throws:
java.io.IOException

getLoadedAgentIdlist

AgentId[] getLoadedAgentIdlist()
Method used for debug and monitoring. It returns an enumeration of all agents loaded in memory.


dumpAgent

public java.lang.String dumpAgent(java.lang.String id)
                           throws java.lang.Exception
Returns a string representation of the specified agent.

Specified by:
dumpAgent in interface EngineMBean
Parameters:
id - The string representation of the agent's unique identification.
Returns:
A string representation of the specified agent.
Throws:
java.lang.Exception
See Also:
dumpAgent(AgentId)

dumpAgent

public java.lang.String dumpAgent(AgentId id)
                           throws java.io.IOException,
                                  java.lang.ClassNotFoundException
Returns a string representation of the specified agent. If the agent is not present it is loaded in memory, be careful it is not initialized (agentInitialize) nor cached in agents vector.

Parameters:
id - The agent's unique identification.
Returns:
A string representation of specified agent.
Throws:
java.io.IOException
java.lang.ClassNotFoundException

load

final Agent load(AgentId id)
          throws java.io.IOException,
                 java.lang.ClassNotFoundException,
                 java.lang.Exception
The load method return the Agent object designed by the AgentId parameter. If the Agent object is not already present in the server memory, it is loaded from the storage. Be careful, if the save method can be overloaded to optimize the save process, the load procedure used by engine is always load.

Parameters:
id - The agent identification.
Returns:
The corresponding agent.
Throws:
java.io.IOException - If an I/O error occurs.
java.lang.ClassNotFoundException - Should never happen (the agent has already been loaded in deploy).
UnknownAgentException - There is no corresponding agent on secondary storage.
java.lang.Exception - when executing class specific initialization

reload

final Agent reload(AgentId id)
            throws java.io.IOException,
                   java.lang.ClassNotFoundException,
                   java.lang.Exception
The reload method return the Agent object loaded from the storage.

Parameters:
id - The agent identification.
Returns:
The corresponding agent.
Throws:
java.io.IOException - when accessing the stored image
java.lang.ClassNotFoundException - if the stored image class may not be found
java.lang.Exception - unspecialized exception

insert

public void insert(Message msg)
Insert a message in the MessageQueue. This method is used during initialization to restore the component state from persistent storage.

Specified by:
insert in interface MessageConsumer
Parameters:
msg - the message

validate

public void validate()
Validates all messages pushed in queue during transaction session.

Specified by:
validate in interface MessageConsumer

start

public void start()
Causes this engine to begin execution.

Specified by:
start in interface EngineMBean
Specified by:
start in interface MessageConsumer
See Also:
stop

stop

public void stop()
Forces the engine to stop executing.

Specified by:
stop in interface EngineMBean
Specified by:
stop in interface MessageConsumer
See Also:
start

getQueue

public MessageQueue getQueue()
Get this engine's MessageQueue qin.

Specified by:
getQueue in interface MessageConsumer
Returns:
this Engine's queue.

isRunning

public boolean isRunning()
Tests if the engine is alive.

Specified by:
isRunning in interface EngineMBean
Specified by:
isRunning in interface MessageConsumer
Returns:
true if this MessageConsumer is alive; false otherwise.

save

public void save()
          throws java.io.IOException
Saves logical clock information to persistent storage.

Specified by:
save in interface MessageConsumer
Throws:
java.io.IOException

restore

public void restore()
             throws java.lang.Exception
Restores logical clock information from persistent storage.

Specified by:
restore in interface MessageConsumer
Throws:
java.lang.Exception

delete

public void delete()
            throws java.lang.IllegalStateException
This operation always throws an IllegalStateException.

Specified by:
delete in interface MessageConsumer
Throws:
java.lang.IllegalStateException
See Also:
Transaction

getStamp

protected final int getStamp()

setStamp

protected final void setStamp(int stamp)

stamp

protected final void stamp(Message msg)

post

public void post(Message msg)
          throws java.lang.Exception
Adds a message in "ready to deliver" list. This method allocates a new time stamp to the message ; be Careful, changing the stamp imply the filename change too.

Specified by:
post in interface MessageConsumer
Throws:
java.lang.Exception

isAgentProfiling

public boolean isAgentProfiling()
Specified by:
isAgentProfiling in interface EngineMBean

setAgentProfiling

public void setAgentProfiling(boolean agentProfiling)
Specified by:
setAgentProfiling in interface EngineMBean

getReactTime

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

getCommitTime

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

onTimeOut

protected void onTimeOut()
                  throws java.lang.Exception
Throws:
java.lang.Exception

run

public void run()
Main loop of agent server Engine.

Specified by:
run in interface java.lang.Runnable

commit

void commit()
      throws java.lang.Exception
Commit the agent reaction in case of right termination:

Throws:
java.lang.Exception

abort

void abort(java.lang.Exception exc)
     throws java.lang.Exception
Abort the agent reaction in case of error during execution. In case of unrecoverable error during the reaction we have to rollback:

Throws:
java.lang.Exception

getAverageLoad1

public float getAverageLoad1()
Returns the load averages for the last minute.

Specified by:
getAverageLoad1 in interface EngineMBean
Specified by:
getAverageLoad1 in interface MessageConsumer
Returns:
the load averages for the last minute.

getAverageLoad5

public float getAverageLoad5()
Returns the load averages for the past 5 minutes.

Specified by:
getAverageLoad5 in interface EngineMBean
Specified by:
getAverageLoad5 in interface MessageConsumer
Returns:
the load averages for the past 5 minutes.

getAverageLoad15

public float getAverageLoad15()
Returns the load averages for the past 15 minutes.

Specified by:
getAverageLoad15 in interface EngineMBean
Specified by:
getAverageLoad15 in interface MessageConsumer
Returns:
the load averages for the past 15 minutes.

toString

public java.lang.String toString()
Returns a string representation of this engine.

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


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