Package fr.dyade.aaa.agent

Class Agent

  • All Implemented Interfaces:
    AgentMBean, Encodable, Serializable
    Direct Known Subclasses:
    AgentFactory, AMQPAgent, Container, Destination, SynchronousAgent, UserAgent
    public abstract class Agent
extends Object
implements AgentMBean, Serializable, Encodable
    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();
    See Also:
    Notification, Engine, Channel, Serialized Form

    • Field Detail

      • serialVersionUID

        static final long serialVersionUID
        Define serialVersionUID for interoperability.
        See Also:
        Constant Field Values

      • logmon

        protected transient Logger logmon

      • DEBUG

        protected static final boolean DEBUG

      • 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

      • agentProfiling

        public boolean agentProfiling
        Boolean value indicating if the agent profiling is on. If true, the cumulative time of reaction and commit is kept for this agent.

      • 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. Be careful, id is not part of persistent data, it must be initialized after transaction load.

      • name

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

      • last

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

      • 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​(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​(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,
             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,
             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​(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
        id - unique identifier

      • 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

    • Method Detail

      • getReactNb

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

      • incWorkInProgress

        public final void incWorkInProgress()
        Increments the tick counter that reflects activity in server.

      • getReactTime

        public long getReactTime()
        Description copied from interface: AgentMBean
        Returns the total reaction time calculated for this agent.
        Specified by:
        getReactTime in interface AgentMBean
        Returns:
        the reactTime

      • resetReactTime

        public void resetReactTime()
        reset the reactTime
        Specified by:
        resetReactTime in interface AgentMBean

      • getCommitTime

        public long getCommitTime()
        Description copied from interface: AgentMBean
        Returns the total commit time calculated for this agent.
        Specified by:
        getCommitTime in interface AgentMBean
        Returns:
        the commitTime

      • resetCommitTime

        public void resetCommitTime()
        reset the commitTime
        Specified by:
        resetCommitTime in interface AgentMBean

      • resetTimer

        public void resetTimer()
        Reset reactTime and commitTime
        Specified by:
        resetTimer in interface AgentMBean

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

      • isUpdated

        public boolean isUpdated()
        Indicates whether the agent has been updated or not.
        Returns:
        true if the agent has been updated.

      • needToBeCommited

        protected final boolean needToBeCommited()
        Indicates to the Engine component that a commit is needed.
        Returns:
        true if there is no error.

      • save

        protected final void save()
                   throws IOException
        Saves the agent state unless not requested.
        Throws:
        IOException - if any error occurs.

      • agentSave

        protected void agentSave()
                  throws IOException
        Enables the sub-classes to save their state.
        Throws:
        IOException - if any error occurs.

      • hasName

        public boolean hasName()

      • getName

        public 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​(String name)
        Sets this Agent's name.
        Parameters:
        name - the Agent's name.

      • 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.
        Returns:
        the default log topic for agents.

      • initState

        private void initState​(String name,
                       boolean fixed,
                       AgentId id)

      • isDeployed

        public boolean isDeployed()
        Returns if the currently Agent has already been deployed.
        Returns:
        true if the current agent has already been deployed.

      • 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.
        Throws:
        IOException - unspecialized exception

      • 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
        Throws:
        IOException - unspecialized exception

      • toString

        public 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 Object
        Returns:
        A string representation of this agent.

      • getAgentId

        public final 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 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:
        Exception - unspecialized exception

      • getA3MBeanName

        private final String getA3MBeanName()

      • 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,
                   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 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:
        Exception - unspecialized exception

      • doAdminSyncNotification

        protected void doAdminSyncNotification​(AgentId from,
                                       AdminSyncNotification not)
        Default handling of AdminSyncNotification. Currently there is no command defined at the Agent level, this method just logs a warning, and unlocks the caller.
        Parameters:
        from -
        not -

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

      • getEncodableClassId

        public int getEncodableClassId()
        Enables the sub classes not to implement this method.
        Specified by:
        getEncodableClassId in interface Encodable
        Returns:
        -1

      • getEncodedSize

        public int getEncodedSize()
                   throws Exception
        Returns the size of the encoded object.
        Specified by:
        getEncodedSize in interface Encodable
        Returns:
        the size of the encoded object
        Throws:
        Exception - if an error occurs

      • encode

        public void encode​(Encoder encoder)
            throws Exception
        Encodes the object.
        Specified by:
        encode in interface Encodable
        Parameters:
        encoder - the encoder
        Throws:
        Exception - if an error occurs

      • decode

        public void decode​(Decoder decoder)
            throws Exception
        Decodes the object.
        Specified by:
        decode in interface Encodable
        Parameters:
        decoder - the encoder
        Throws:
        Exception - if an error occurs