madkit.kernel

## Class Agent

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

- All Implemented Interfaces:
    java.lang.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 and Description
    `Agent()`
    `Agent(boolean isDaemon)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.util.List<Message>` | `broadcastMessageWithRoleAndWaitForReplies(java.lang.String community, java.lang.String group, java.lang.String role, Message message, java.lang.String senderRole, java.lang.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(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` | `sendMessageAndWaitForReply(java.lang.String community, java.lang.String group, java.lang.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(java.lang.String community, java.lang.String group, java.lang.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` | `sendMessageWithRoleAndWaitForReply(AgentAddress receiver, Message messageToSend, java.lang.String senderRole)` Sends a message and waits for an answer to it.
    `Message` | `sendMessageWithRoleAndWaitForReply(AgentAddress receiver, Message messageToSend, java.lang.String senderRole, java.lang.Integer timeOutMilliSeconds)` Sends a message and waits for an answer to it.
    `Message` | `sendMessageWithRoleAndWaitForReply(java.lang.String community, java.lang.String group, java.lang.String role, Message messageToSend, java.lang.String senderRole)` Sends a message to an agent having this position in the organization and waits indefinitely for an answer to it.
    `Message` | `sendMessageWithRoleAndWaitForReply(java.lang.String community, java.lang.String group, java.lang.String role, Message messageToSend, java.lang.String senderRole, java.lang.Integer timeOutMilliSeconds)` Sends a message to an agent having this position in the organization 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, java.lang.String senderRole)` Sends a reply message and waits indefinitely for an answer to it.
    `Message` | `sendReplyWithRoleAndWaitForReply(Message messageToReplyTo, Message reply, java.lang.String senderRole, java.lang.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, java.lang.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(java.lang.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(long timeOutMilliseconds)` This method gets the next message of the mailbox or waits for a new incoming message considering 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, 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 Detail

    - #### Agent

          public Agent(boolean isDaemon)

    - #### Agent

          public Agent()

  - ### Method Detail

    - #### 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:
        `java.lang.IllegalArgumentException` - If the priority is not in the range `Thread.MIN_PRIORITY` to `Thread.MAX_PRIORITY`.
        `java.lang.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 the 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,
                                                            java.lang.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,
                                                            java.lang.String senderRole,
                                                            java.lang.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(java.lang.String community,
                                                    java.lang.String group,
                                                    java.lang.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(java.lang.String community,
                                                            java.lang.String group,
                                                            java.lang.String role,
                                                            Message messageToSend,
                                                            java.lang.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(java.lang.String community,
                                                    java.lang.String group,
                                                    java.lang.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(java.lang.String community,
                                                            java.lang.String group,
                                                            java.lang.String role,
                                                            Message messageToSend,
                                                            java.lang.String senderRole,
                                                            java.lang.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,
                                                          java.lang.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,
                                                          java.lang.String senderRole,
                                                          java.lang.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 java.util.List<Message> broadcastMessageWithRoleAndWaitForReplies(java.lang.String community,
                                                                                   java.lang.String group,
                                                                                   java.lang.String role,
                                                                                   Message message,
                                                                                   java.lang.String senderRole,
                                                                                   java.lang.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(java.lang.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,
                                    java.lang.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

Fabien Michel, Olivier Gutknecht, Jacques Ferber - September 9 2019