Class DynamicCompositeAgent

  • All Implemented Interfaces:
    Agent

    public class DynamicCompositeAgent
    extends java.lang.Object
    implements Agent
    Group several Agents into one composite, so they can be scheduled as a unit.

    Agents can be dynamically added and removed.

    Note: This class is threadsafe for add and remove.

    • Field Detail

      • EMPTY_AGENTS

        private static final Agent[] EMPTY_AGENTS
      • agentIndex

        private int agentIndex
      • agents

        private Agent[] agents
      • roleName

        private final java.lang.String roleName
      • addAgent

        private final java.util.concurrent.atomic.AtomicReference<Agent> addAgent
      • removeAgent

        private final java.util.concurrent.atomic.AtomicReference<Agent> removeAgent
    • Constructor Detail

      • DynamicCompositeAgent

        public DynamicCompositeAgent​(java.lang.String roleName)
        Construct a new composite that has no Agents to begin with.
        Parameters:
        roleName - to be given for Agent.roleName().
      • DynamicCompositeAgent

        public DynamicCompositeAgent​(java.lang.String roleName,
                                     java.util.List<? extends Agent> agents)
        Construct a new composite with a given list Agents to begin with.
        Parameters:
        roleName - to be given for Agent.roleName().
        agents - the parts of this composite, at least one agent and no null agents allowed.
        Throws:
        java.lang.NullPointerException - if the array or any element is null.
      • DynamicCompositeAgent

        public DynamicCompositeAgent​(java.lang.String roleName,
                                     Agent... agents)
        Construct a new composite with a given list Agents to begin with.
        Parameters:
        roleName - to be given for Agent.roleName().
        agents - the parts of this composite, at least one agent and no null agents allowed.
        Throws:
        java.lang.NullPointerException - if the array or any element is null.
    • Method Detail

      • onStart

        public void onStart()
        To be overridden by Agents that need to do resource init on start.

        This method will be called by the agent thread once on start.

        Note that one agent throwing an exception on start may result in other agents not being started.

        Specified by:
        onStart in interface Agent
      • doWork

        public int doWork()
                   throws java.lang.Exception
        An agent should implement this method to do its work.

        The return value is used for implementing a backoff strategy that can be employed when no work is currently available for the agent to process.

        If the Agent wished to terminate and close then a AgentTerminationException can be thrown.

        Specified by:
        doWork in interface Agent
        Returns:
        0 to indicate no work was currently available, a positive value otherwise.
        Throws:
        java.lang.Exception - if an error has occurred
      • onClose

        public void onClose()
        To be overridden by Agents that need to do resource cleanup on close.

        This method will be called after the agent thread has terminated or if the agent is closed before it runs.

        Note that one agent throwing an exception on close will not prevent other agents from being closed.

        Specified by:
        onClose in interface Agent
        Throws:
        java.lang.RuntimeException - if any sub-agent throws an exception onClose. The agents exceptions are collected as suppressed exceptions in the thrown exception.
      • roleName

        public java.lang.String roleName()
        Get the name of this agent's role.
        Specified by:
        roleName in interface Agent
        Returns:
        the name of this agent's role.
      • tryAdd

        public boolean tryAdd​(Agent agent)
        Try and add a new Agent to the composite. This method does not block and will return false if another concurrent attempt to add is in progress.

        The agent will be added during the next invocation of doWork() if this operation is successful. If the Agent.onStart() method throws an exception then it will not be added and Agent.onClose() will be called.

        Parameters:
        agent - to be added to the composite.
        Returns:
        true is a successful add request is pending otherwise false if another concurrent add request is in progress.
        See Also:
        hasAddAgentCompleted()
      • tryRemove

        public boolean tryRemove​(Agent agent)
        Try and remove an Agent from the composite. The agent is removed during the next doWork() duty cycle if this operation is successful. This method does not block and will return false if another concurrent attempt to remove is in progress.

        The Agent is removed by identity. Only the first found is removed.

        Parameters:
        agent - to be removed.
        Returns:
        true is a successful remove request is pending otherwise false if another concurrent remove request is in progress.
        See Also:
        hasRemoveAgentCompleted()
      • add

        private void add​(Agent agent)
      • remove

        private void remove​(Agent agent)