Package madkit.kernel

# Class Agent

java.lang.Object
madkit.kernel.AbstractAgent
madkit.kernel.Agent

All Implemented Interfaces:
  `Comparable<AbstractAgent>`

Direct Known Subclasses:
  `Scheduler`

public class Agent extends AbstractAgent
The super class of all MaDKit threaded agents, v 5. It provides support for

- Agent's Life cycle, logging, and naming.
- Agent launching and killing.
- Artificial society creation and management.
- Messaging.
- Minimal graphical interface management.

Since:
  MaDKit 1.0
Version:
  5.0.2
Author:
  Fabien Michel, Olivier Gutknecht

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class madkit.kernel.AbstractAgent

  `AbstractAgent.ReturnCode, AbstractAgent.State`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Agent()`
  `Agent(boolean isDaemon)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `List<Message>`
  `broadcastMessageWithRoleAndWaitForReplies(String community, String group, String role, Message message, String senderRole, Integer timeOutMilliSeconds)`
  Broadcasts a message and wait for answers considering a timeout duration.
  `int`
  `getThreadPriority()`
  Returns this thread's priority.
  `boolean`
  `isDaemon()`
  Tells if the agent is a daemon.
  `AbstractAgent.ReturnCode`
  `killAgent(AbstractAgent target, int timeOutSeconds)`
  Kills the targeted agent.
  `protected void`
  `live()`
  This method corresponds to the second behavior which is called by the MaDKit kernel when a threaded agent is launched (i.e. an agent which subclasses this class).
  `protected void`
  `pause(int milliSeconds)`
  Stops the agent's process for a while.
  `Message`
  `sendMessageAndWaitForReply(String community, String group, String role, Message messageToSend)`
  Sends a message to an agent having this position in the organization and waits indefinitely for an answer to it.
  `Message`
  `sendMessageAndWaitForReply(String community, String group, String role, Message messageToSend, int timeOutMilliSeconds)`
  Sends a message to an agent having this position in the organization and waits for an answer to it.
  `Message`
  `sendMessageAndWaitForReply(AgentAddress receiver, Message messageToSend)`
  Sends a message and waits indefinitely for an answer to it.
  `Message`
  `sendMessageAndWaitForReply(AgentAddress receiver, Message messageToSend, int timeOutMilliSeconds)`
  Sends a message and waits for an answer to it.
  `Message`
  `sendMessageWithRoleAndWaitForReply(String community, String group, String role, Message messageToSend, String senderRole)`
  Sends a message to an agent having this position in the organization and waits indefinitely for an answer to it.
  `Message`
  `sendMessageWithRoleAndWaitForReply(String community, String group, String role, Message messageToSend, String senderRole, Integer timeOutMilliSeconds)`
  Sends a message to an agent having this position in the organization and waits for an answer to it.
  `Message`
  `sendMessageWithRoleAndWaitForReply(AgentAddress receiver, Message messageToSend, String senderRole)`
  Sends a message and waits for an answer to it.
  `Message`
  `sendMessageWithRoleAndWaitForReply(AgentAddress receiver, Message messageToSend, String senderRole, Integer timeOutMilliSeconds)`
  Sends a message and waits for an answer to it.
  `Message`
  `sendReplyAndWaitForReply(Message messageToReplyTo, Message reply)`
  Sends a reply message and waits indefinitely for an answer to it.
  `Message`
  `sendReplyAndWaitForReply(Message messageToReplyTo, Message reply, int timeOutMilliSeconds)`
  Sends a reply message and waits for an answer to it.
  `Message`
  `sendReplyWithRoleAndWaitForReply(Message messageToReplyTo, Message reply, String senderRole)`
  Sends a reply message and waits indefinitely for an answer to it.
  `Message`
  `sendReplyWithRoleAndWaitForReply(Message messageToReplyTo, Message reply, String senderRole, Integer timeOutMilliSeconds)`
  Sends a reply message and waits for an answer to it.
  `void`
  `setThreadPriority(int newPriority)`
  Changes the priority of the agent's thread.
  `Message`
  `waitAnswer(Message query)`
  Retrieves and removes the next message that is a reply to the query message, waiting for ever if necessary until a matching reply becomes available.
  `Message`
  `waitAnswer(Message query, Integer timeOutMilliSeconds)`
  Retrieves and removes the next message that is a reply to the query message, waiting for ever if necessary until a matching reply becomes available.
  `Message`
  `waitNextMessage()`
  This method is the blocking version of nextMessage().
  `Message`
  `waitNextMessage(long timeOutMilliseconds)`
  This method gets the next message of the mailbox or waits for a new incoming message considering a certain delay.
  `Message`
  `waitNextMessage(Integer timeOutMilliseconds, MessageFilter filter)`
  This method gets the next message of the mailbox or waits for a new incoming acceptable message up to a certain delay.
  `Message`
  `waitNextMessage(MessageFilter filter)`
  Retrieves and removes the next message that complies with the filter, waiting for ever if necessary until a matching message becomes available.

  ### Methods inherited from class madkit.kernel.AbstractAgent

  `activate, broadcastMessage, broadcastMessageWithRole, bucketModeCreateGroup, bucketModeRequestRole, checkAgentAddress, compareTo, createGroup, createGroup, createGroup, createGroupIfAbsent, createGroupIfAbsent, createGroupIfAbsent, createGUIOnStartUp, destroyCommunity, destroyGroup, destroyRole, end, executeThisAgent, executeThisAgent, executeThisAgent, getAgentAddressIn, getAgentsWithRole, getAgentsWithRole, getAgentWithRole, getDistantAgentWithRole, getExistingCommunities, getExistingGroups, getExistingRoles, getKernelAddress, getLastReceivedMessage, getLastReceivedMessage, getLogger, getMadkitConfig, getMadkitProperty, getMadkitProperty, getMyGroups, getMyRoles, getName, getNetworkID, getNextEventDate, getOrganizationSnapShot, getReplyTo, getServerInfo, getSimpleNetworkID, getSimulationTime, getState, hasGUI, hashCode, hasRole, isAlive, isCommunity, isGroup, isKernelOnline, isMadkitPropertyTrue, isMessageBoxEmpty, isRole, killAgent, launchAgent, launchAgent, launchAgent, launchAgent, launchAgent, launchAgent, launchAgent, launchAgent, launchAgentBucket, launchAgentBucket, launchAgentBucket, launchAgentBucket, launchNode, launchXmlAgents, leaveGroup, leaveRole, nextMessage, nextMessage, nextMessages, proceedEnumMessage, purgeMailbox, receiveMessage, reload, requestRole, requestRole, sendMessage, sendMessage, sendMessageWithRole, sendMessageWithRole, sendReply, sendReplyWithRole, setLogLevel, setMadkitProperty, setMadkitProperty, setName, setupFrame, toString`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### Agent

    public Agent(boolean isDaemon)

  - ### Agent

    public Agent()

- ## Method Details

  - ### setThreadPriority

    public void setThreadPriority(int newPriority)
    Changes the priority of the agent's thread. This should be used only starting from the `AbstractAgent.activate()` to have a concrete effect. Default priority is set to `Thread.NORM_PRIORITY` - 1 to ensure swing responsiveness.
    Parameters:
      `newPriority` - priority to set this thread to
    Throws:
      `IllegalArgumentException` - If the priority is not in the range `Thread.MIN_PRIORITY` to `Thread.MAX_PRIORITY`.
      `SecurityException` - if the current thread cannot modify this thread.
    Since:
      MadKit 5.0.1
    See Also:
      - `Thread`

  - ### getThreadPriority

    public int getThreadPriority()
    Returns this thread's priority.
    Returns:
      this thread's priority for this agent.
    Since:
      MadKit 5.0.1
    See Also:
      - `Thread`

  - ### isDaemon

    public boolean isDaemon()
    Tells if the agent is a daemon.
    Returns:
      `true` if the agent is a Daemon
    Since:
      MaDKit 5.0.0.9

  - ### live

    protected void live()
    This method corresponds to the second behavior which is called by the MaDKit kernel when a threaded agent is launched (i.e. an agent which subclasses this class). Usually, this is the place where all the agent's work lies. Most of the time, this work is about waiting for a message and thus treat it as it should be.

    Here is a typical example:

                @Override
                protected void live()
                {
                        while(true){
                                Message m = waitNextMessage();
                                handleMessage(m); //a private method that does the appropriate job
                }
                }

  - ### killAgent

    public AbstractAgent.ReturnCode killAgent(AbstractAgent target, int timeOutSeconds)
    Description copied from class: `AbstractAgent`
    Kills the targeted agent. The kill process stops the agent's life cycle but allows it to process its `AbstractAgent.end()` method until the time out elapsed.

    If the target is in the activate or live method (Agent subclasses), it will be brutally stop and then proceed its end method.

    The method returns only when the targeted agent actually ends its life. So if the target contains a infinite loop, the caller can be blocked. Using a timeout thus ensures that the caller will be blocked only a certain amount of time. Using 0 as timeout will stop the target as soon as possible, eventually brutally stop its life cycle. In such a case, if its end method has not been started, it will never run.

    Overrides:
      `killAgent` in class `AbstractAgent`
    Returns:
      - ``AbstractAgent.ReturnCode.SUCCESS``: If the target's end method has completed normally.
      - ``AbstractAgent.ReturnCode.ALREADY_KILLED``: If the target has been already killed.
      - ``AbstractAgent.ReturnCode.NOT_YET_LAUNCHED`` : If the target has not been launched.
      - ``AbstractAgent.ReturnCode.TIMEOUT``: If the target's end method took too much time and has been brutally stopped.

  - ### sendMessageAndWaitForReply

    public Message sendMessageAndWaitForReply(AgentAddress receiver, Message messageToSend)
    Sends a message and waits indefinitely for an answer to it. This has the same effect as `sendMessageWithRoleAndWaitForReply(receiver, messageToSend, null, null)`
    Parameters:
      `receiver` - the targeted agent by the send.
      `messageToSend` - the message to send.
    Returns:
      the reply received as soon as available, or `null` if there was an error when sending the message.
    Since:
      MaDKit 5
    See Also:
      - `sendMessageWithRoleAndWaitForReply(AgentAddress, Message, String, Integer)`

  - ### sendMessageAndWaitForReply

    public Message sendMessageAndWaitForReply(AgentAddress receiver, Message messageToSend, int timeOutMilliSeconds)
    Sends a message and waits for an answer to it. This has the same effect as `sendMessageWithRoleAndWaitForReply(receiver, messageToSend, null, timeOutMilliSeconds)`
    Parameters:
      `receiver` - the targeted agent by the send.
      `messageToSend` - the message to send.
      `timeOutMilliSeconds` - the maximum time to wait. If `null` the agent will wait indefinitely.
    Returns:
      the reply received as soon as available, or `null` if the time out has elapsed or if there was an error when sending the message.
    Since:
      MaDKit 5
    See Also:
      - `sendMessageWithRoleAndWaitForReply(AgentAddress, Message, String, Integer)`

  - ### sendMessageWithRoleAndWaitForReply

    public Message sendMessageWithRoleAndWaitForReply(AgentAddress receiver, Message messageToSend, String senderRole)
    Sends a message and waits for an answer to it. This has the same effect as `sendMessageWithRoleAndWaitForReply(receiver, messageToSend, senderRole, null)`
    Parameters:
      `receiver` - the targeted agent by the send.
      `messageToSend` - the message to send.
      `senderRole` - the role with which the sending is done.
    Returns:
      the reply received as soon as available, or `null` if the time out has elapsed or if there was an error when sending the message.
    Since:
      MaDKit 5
    See Also:
      - `sendMessageWithRoleAndWaitForReply(AgentAddress, Message, String, Integer)`

  - ### sendMessageWithRoleAndWaitForReply

    public Message sendMessageWithRoleAndWaitForReply(AgentAddress receiver, Message messageToSend, String senderRole, Integer timeOutMilliSeconds)
    Sends a message and waits for an answer to it. Additionally, the sending is done using a specific role for the sender.
    Parameters:
      `receiver` - the targeted agent by the send.
      `messageToSend` - the message to send.
      `senderRole` - the role with which the sending is done.
      `timeOutMilliSeconds` - the maximum time to wait. If `null` the agent will wait indefinitely.
    Returns:
      the reply received as soon as available, or `null` if the time out has elapsed or if there was an error when sending the message, that is any `AbstractAgent.ReturnCode` different from `AbstractAgent.ReturnCode.SUCCESS` (see `AbstractAgent.sendMessageWithRole(AgentAddress, Message, String)`).
    Since:
      MaDKit 5
    See Also:
      - `AbstractAgent.sendMessageWithRole(AgentAddress, Message, String)`
      - `AbstractAgent.ReturnCode`

  - ### sendMessageAndWaitForReply

    public Message sendMessageAndWaitForReply(String community, String group, String role, Message messageToSend)
    Sends a message to an agent having this position in the organization and waits indefinitely for an answer to it. This has the same effect as `sendMessageWithRoleAndWaitForReply(community, group, role, messageToSend, null, null)`
    Parameters:
      `community` - the community name
      `group` - the group name
      `role` - the role name
      `messageToSend` - the message to send. If `null` the agent will wait indefinitely.
    Returns:
      the reply received as soon as available, or `null` if there was an error when sending the message.
    Since:
      MaDKit 5
    See Also:
      - `sendMessageWithRoleAndWaitForReply(String, String, String, Message, String, Integer)`

  - ### sendMessageWithRoleAndWaitForReply

    public Message sendMessageWithRoleAndWaitForReply(String community, String group, String role, Message messageToSend, String senderRole)
    Sends a message to an agent having this position in the organization and waits indefinitely for an answer to it. This has the same effect as `sendMessageWithRoleAndWaitForReply(community, group, role, messageToSend, senderRole, null)`
    Parameters:
      `community` - the community name
      `group` - the group name
      `role` - the role name
      `messageToSend` - the message to send.
      `senderRole` - the role with which the sending is done. If `null` the agent will wait indefinitely.
    Returns:
      the reply received as soon as available, or `null` if there was an error when sending the message.
    Since:
      MaDKit 5
    See Also:
      - `sendMessageWithRoleAndWaitForReply(String, String, String, Message, String, Integer)`

  - ### sendMessageAndWaitForReply

    public Message sendMessageAndWaitForReply(String community, String group, String role, Message messageToSend, int timeOutMilliSeconds)
    Sends a message to an agent having this position in the organization and waits for an answer to it. This has the same effect as `sendMessageWithRoleAndWaitForReply(community, group, role, messageToSend, null, timeOutMilliSeconds)`
    Parameters:
      `community` - the community name
      `group` - the group name
      `role` - the role name
      `messageToSend` - the message to send.
      `timeOutMilliSeconds` - the maximum time to wait. If `null` the agent will wait indefinitely.
    Returns:
      the reply received as soon as available, or `null` if the time out has elapsed or if there was an error when sending the message.
    Since:
      MaDKit 5
    See Also:
      - `sendMessageWithRoleAndWaitForReply(String, String, String, Message, String, Integer)`

  - ### sendMessageWithRoleAndWaitForReply

    public Message sendMessageWithRoleAndWaitForReply(String community, String group, String role, Message messageToSend, String senderRole, Integer timeOutMilliSeconds)
    Sends a message to an agent having this position in the organization and waits for an answer to it. The targeted agent is selected randomly among matched agents. The sender is excluded from this search.
    Parameters:
      `community` - the community name
      `group` - the group name
      `role` - the role name
      `messageToSend` - the message to send.
      `senderRole` - the role with which the sending is done.
      `timeOutMilliSeconds` - the maximum time to wait. If `null` the agent will wait indefinitely.
    Returns:
      the reply received as soon as available, or `null` if the time out has elapsed or if there was an error when sending the message.
    Since:
      MaDKit 5

  - ### sendReplyAndWaitForReply

    public Message sendReplyAndWaitForReply(Message messageToReplyTo, Message reply)
    Sends a reply message and waits indefinitely for an answer to it. This has the same effect as `sendReplyWithRoleAndWaitForReply(messageToReplyTo, reply, null, null)`.
    Parameters:
      `messageToReplyTo` - the original message previously received.
      `reply` - the new message.
    Returns:
      the reply received as soon as available.
    Since:
      MaDKit 5
    See Also:
      - `sendReplyWithRoleAndWaitForReply(Message, Message, String, Integer)`

  - ### sendReplyAndWaitForReply

    public Message sendReplyAndWaitForReply(Message messageToReplyTo, Message reply, int timeOutMilliSeconds)
    Sends a reply message and waits for an answer to it. This has the same effect as `sendReplyWithRoleAndWaitForReply(messageToReplyTo, reply, null, timeOutMilliSeconds)`.
    Parameters:
      `messageToReplyTo` - the original message previously received
      `reply` - the new message
    Returns:
      the reply received as soon as available
    Since:
      MaDKit 5
    See Also:
      - `sendReplyWithRoleAndWaitForReply(Message, Message, String, Integer)`

  - ### sendReplyWithRoleAndWaitForReply

    public Message sendReplyWithRoleAndWaitForReply(Message messageToReplyTo, Message reply, String senderRole)
    Sends a reply message and waits indefinitely for an answer to it. This has the same effect as `sendReplyWithRoleAndWaitForReply(messageToReplyTo, reply, senderRole, null)`.
    Parameters:
      `messageToReplyTo` - the original message previously received
      `reply` - the new message
    Returns:
      the reply received as soon as available
    Since:
      MaDKit 5
    See Also:
      - `sendReplyWithRoleAndWaitForReply(Message, Message, String, Integer)`

  - ### sendReplyWithRoleAndWaitForReply

    public Message sendReplyWithRoleAndWaitForReply(Message messageToReplyTo, Message reply, String senderRole, Integer timeOutMilliSeconds)
    Sends a reply message and waits for an answer to it. Additionally, the reply is done using a specific role for the sender.
    Parameters:
      `messageToReplyTo` - the original message previously received
      `reply` - the reply message.
      `senderRole` - the role with which the reply is sent.
      `timeOutMilliSeconds` - the maximum time to wait. If `null` the agent will wait indefinitely.
    Returns:
      the reply received as soon as available, or `null` if the time out has elapsed or if there was an error when sending the reply, that is any `AbstractAgent.ReturnCode` different from `AbstractAgent.ReturnCode.SUCCESS` (see `AbstractAgent.sendReplyWithRole(Message, Message, String)`).
    Since:
      MaDKit 5
    See Also:
      - `AbstractAgent.sendReplyWithRole(Message, Message, String)`
      - `AbstractAgent.ReturnCode`

  - ### broadcastMessageWithRoleAndWaitForReplies

    public List<Message> broadcastMessageWithRoleAndWaitForReplies(String community, String group, String role, Message message, String senderRole, Integer timeOutMilliSeconds)
    Broadcasts a message and wait for answers considering a timeout duration.
    Parameters:
      `community` -
      `group` -
      `role` -
      `message` -
      `senderRole` -
      `timeOutMilliSeconds` -
    Returns:
      a list of messages which are answers to the `message` which has been broadcasted.

  - ### waitNextMessage

    public Message waitNextMessage()
    This method is the blocking version of nextMessage(). If there is no message in the mailbox, it suspends the agent life until a message is received
    Returns:
      the first received message
    See Also:
      - `waitNextMessage(long)`

  - ### waitNextMessage

    public Message waitNextMessage(long timeOutMilliseconds)
    This method gets the next message of the mailbox or waits for a new incoming message considering a certain delay.
    Parameters:
      `timeOutMilliseconds` - the maximum time to wait, in milliseconds.
    Returns:
      the first message in the mailbox, or `null` if no message has been received before the time out delay is elapsed

  - ### waitNextMessage

    public Message waitNextMessage(MessageFilter filter)
    Retrieves and removes the next message that complies with the filter, waiting for ever if necessary until a matching message becomes available.
    Parameters:
      `filter` -
    Returns:
      the first received message that matches the filter

  - ### waitNextMessage

    public Message waitNextMessage(Integer timeOutMilliseconds, MessageFilter filter)
    This method gets the next message of the mailbox or waits for a new incoming acceptable message up to a certain delay.
    Parameters:
      `timeOutMilliseconds` - the maximum time to wait, in milliseconds.
      `filter` -
    Returns:
      a message that matches or `null` otherwise.

  - ### pause

    protected void pause(int milliSeconds)
    Stops the agent's process for a while.
    Parameters:
      `milliSeconds` - the number of milliseconds for which the agent should pause.

  - ### waitAnswer

    public Message waitAnswer(Message query)
    Retrieves and removes the next message that is a reply to the query message, waiting for ever if necessary until a matching reply becomes available.
    Parameters:
      `query` - the message for which a reply is waited for
    Returns:
      the first reply to the query message
    Since:
      MadKit 5.0.4

  - ### waitAnswer

    public Message waitAnswer(Message query, Integer timeOutMilliSeconds)
    Retrieves and removes the next message that is a reply to the query message, waiting for ever if necessary until a matching reply becomes available.
    Parameters:
      `query` - the message for which a reply is waited for
      `timeOutMilliSeconds` - the maximum time to wait, in milliseconds.
    Returns:
      the first reply to the query message
    Since:
      MadKit 5.0.4