AbstractAgent (MaDKit 5.0.4)

java.lang.Object
- madkit.kernel.AbstractAgent

All Implemented Interfaces:

Serializable, Comparable<AbstractAgent>

Direct Known Subclasses:

AbstractModel, Agent, ConsoleAgent, Watcher
```
public class AbstractAgent
extends Object
implements Comparable<AbstractAgent>, Serializable
```
The super class of all MaDKit 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.
The agent's behavior is intentionally not defined. It is up to the agent developer to choose an agent model or to develop his specific agent library on top of the facilities provided by the MaDKit API. However, all the launched agents share the same organizational view, and the basic messaging code, so integration of different agents is quite easy, even when they are coming from different developers or have heterogeneous models.
Agent-related methods (most of this API) is only effective after the agent has been launched and thus registered in the current Madkit session. Especially, that means that most of the API has no effect in the constructor method of an Agent and will only produce a warning if used.

MaDKit v.5 new features
- One of the big change that comes with version 5 is how agents are identified and localized within the artificial society. An agent is no longer binded to a single agent address but has as many agent addresses as holden positions in the artificial society. see AgentAddress for more information.
- With respect to the previous change, a withRole version of all the messaging methods has been added. See sendMessageWithRole(AgentAddress, Message, String) for an example of such a method.
- A replying mechanism has been introduced through SendReply methods. It enables the agent with the possibility of replying directly to a given message. Also, it is now possible to get the reply to a message, or to wait for a reply ( for Agent subclasses only as they are threaded) See sendReply(Message, Message) for more details.
- Agents now have a formal state during a MaDKit session. See the getState() method for detailed information.
- One of the most convenient improvement of v.5 is the logging mechanism which is provided. See the logger attribute for more details.
Version:

5.5

Author:

Fabien Michel, Olivier Gutknecht

See Also:
Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`AbstractAgent.ReturnCode` This class enumerates all the return codes which could be obtained with essential methods of the `AbstractAgent` and `Agent` classes.
`static class`	`AbstractAgent.State` An agent state.

Field Summary

Fields
Modifier and Type Field and Description

protected AgentLogger logger
logger should be used to print messages and trace the agent's life cycle.

Fields
Modifier and Type	Field and Description
`protected AgentLogger`	`logger` `logger` should be used to print messages and trace the agent's life cycle.

Constructor Summary

Constructors
Constructor and Description

AbstractAgent()

Constructors
Constructor and Description
`AbstractAgent()`

Method Summary

Methods
Modifier and Type	Method and Description
`protected void`	`activate()` This method corresponds to the first behavior which is called by the MaDKit kernel when an agent is launched.
`AbstractAgent.ReturnCode`	`broadcastMessage(String community, String group, String role, Message message)` Broadcasts a message to every agent having a role in a group in a community, but not to the sender.
`AbstractAgent.ReturnCode`	`broadcastMessageWithRole(String community, String group, String role, Message messageToSend, String senderRole)` Broadcasts a message to every agent having a role in a group in a community using a specific role for the sender.
`AbstractAgent.ReturnCode`	`bucketModeCreateGroup(String community, String group, boolean isDistributed, Gatekeeper keyMaster)` Creates a new Group within a community even if the agent has been launched using using one of the `launchAgentBucket` methods.
`AbstractAgent.ReturnCode`	`bucketModeRequestRole(String community, String group, String role, Object passKey)` Requests a role even if the agent has been launched using one of the `launchAgentBucket` methods with non `null` roles.
`boolean`	`checkAgentAddress(AgentAddress agentAddress)` Checks if this agent address is still valid.
`int`	`compareTo(AbstractAgent other)` Compares this agent with the specified agent for order with respect to instantiation time.
`AbstractAgent.ReturnCode`	`createGroup(String community, String group)` Creates a new Group within a community.
`AbstractAgent.ReturnCode`	`createGroup(String community, String group, boolean isDistributed)` Creates a new Group within a community.
`AbstractAgent.ReturnCode`	`createGroup(String community, String group, boolean isDistributed, Gatekeeper keyMaster)` Creates a new Group within a community.
`boolean`	`createGroupIfAbsent(String community, String group)` Creates a new Group within a community but does not produce any warning if the group already exists.
`boolean`	`createGroupIfAbsent(String community, String group, boolean isDistributed)` Creates a new Group within a community but does not produce any warning if the group already exists.
`boolean`	`createGroupIfAbsent(String community, String group, boolean isDistributed, Gatekeeper keyMaster)` Creates a new Group within a community but does not produce any warning if the group already exists.
`void`	`createGUIOnStartUp()` Activates the MaDKit GUI initialization when launching the agent whatever the launching parameters.
`void`	`destroyCommunity(String community)` Wipes out an entire community at once.
`void`	`destroyGroup(String community, String group)` Wipes out an entire group at once.
`void`	`destroyRole(String community, String group, String role)` Wipes out an entire role at once.
`protected void`	`end()` This method corresponds to the last behavior which is called by the MaDKit kernel.
`protected static void`	`executeThisAgent()` This offers a convenient way to create a main method that launches the agent class under development.
`protected static void`	`executeThisAgent(int nbOfInstances, boolean createFrame, String... args)` This offers a convenient way to create main a main method that launches the agent class under development.
`protected static void`	`executeThisAgent(String... args)` This offers a convenient way to create a main method that launches the agent class under development.
`AgentAddress`	`getAgentAddressIn(String community, String group, String role)` Returns the agent address of this agent at this CGR location.
`List<AgentAddress>`	`getAgentsWithRole(String community, String group, String role)` Returns an `List` containing agents that handle this role in the organization.
`List<AgentAddress>`	`getAgentsWithRole(String community, String group, String role, boolean callerIncluded)` Returns an `List` containing all the agents that handle this role in the organization.
`AgentAddress`	`getAgentWithRole(String community, String group, String role)` Returns an `AgentAddress` corresponding to an agent having this position in the organization.
`AgentAddress`	`getDistantAgentWithRole(String community, String group, String role, KernelAddress from)` Returns an `AgentAddress` corresponding to an agent having this position in the organization on a particular kernel.
`TreeSet<String>`	`getExistingCommunities()` returns the names of the communities that exist.
`TreeSet<String>`	`getExistingGroups(String community)` returns the names of the groups that exist in this community.
`TreeSet<String>`	`getExistingRoles(String community, String group)` returns the names of the roles that exist in this group.
`KernelAddress`	`getKernelAddress()` Returns the kernel address on which the agent is running.
`AgentLogger`	`getLogger()` Returns the agent's logger.
`MadkitProperties`	`getMadkitConfig()` Returns the Properties object of this MaDKit session.
`<E extends Enum<E>> String`	`getMadkitProperty(E option)` Shortcut for `getMadkitProperty(option.name())`.
`String`	`getMadkitProperty(String key)` Gets the MaDKit session property indicated by the specified key.
`TreeSet<String>`	`getMyGroups(String community)` Gets the names of the groups the agent is in according to a community
`TreeSet<String>`	`getMyRoles(String community, String group)` Gets the names of the roles that the agent has in a specific group
`String`	`getName()` Returns the agent's name.
`String`	`getNetworkID()` Return a string representing a unique identifier for the agent over the network.
`Map<String,Map<String,Map<String,Set<AgentAddress>>>>`	`getOrganizationSnapShot(boolean global)`
`Message`	`getReplyTo(Message originalMessage)` Gets the next message which is a reply to the originalMessage.
`String`	`getServerInfo()` Returns the server's info, IP and port, if the kernel is online.
`String`	`getSimpleNetworkID()` Return a string representing a shorter version of the unique identifier of the agent over the network.
`AbstractAgent.State`	`getState()` Returns the current state of the agent in the MaDKit platform.
`boolean`	`hasGUI()` Tells if this agent has a GUI automatically built by the kernel
`int`	`hashCode()` The ID of an agent.
`boolean`	`hasRole(String community, String group, String role)` Tells if the agent is currently playing a specific role.
`boolean`	`isAlive()` Returns `true` if the agent has been launched and is not ended nor killed.
`boolean`	`isCommunity(String community)` Tells if a community exists in the artificial society.
`boolean`	`isGroup(String community, String group)` Tells if a group exists in the artificial society.
`boolean`	`isKernelOnline()` Tells if the kernel on which this agent is running is online.
`<E extends Enum<E>> boolean`	`isMadkitPropertyTrue(E option)` Shortcut for `Boolean.parseBoolean(getMadkitProperty(option))`
`boolean`	`isMessageBoxEmpty()` Tells if there is a message in the mailbox
`boolean`	`isRole(String community, String group, String role)` Tells if a role exists in the artificial society.
`AbstractAgent.ReturnCode`	`killAgent(AbstractAgent target)` Kills the targeted agent.
`AbstractAgent.ReturnCode`	`killAgent(AbstractAgent target, int timeOutSeconds)` Kills the targeted agent.
`AbstractAgent.ReturnCode`	`launchAgent(AbstractAgent agent)` Launches a new agent in the MaDKit platform.
`AbstractAgent.ReturnCode`	`launchAgent(AbstractAgent agent, boolean createFrame)` Launches a new agent in the MaDKit platform.
`AbstractAgent.ReturnCode`	`launchAgent(AbstractAgent agent, int timeOutSeconds)` Launches a new agent in the MaDKit platform.
`AbstractAgent.ReturnCode`	`launchAgent(AbstractAgent agent, int timeOutSeconds, boolean createFrame)` Launches a new agent and returns when the agent has completed its `activate()` method or when `timeOutSeconds` seconds elapsed.
`AbstractAgent`	`launchAgent(String agentClass)` Launches a new agent using its full class name.
`AbstractAgent`	`launchAgent(String agentClass, boolean createFrame)` Launches a new agent using its full class name.
`AbstractAgent`	`launchAgent(String agentClass, int timeOutSeconds)` Launches a new agent using its full class name.
`AbstractAgent`	`launchAgent(String agentClass, int timeOutSeconds, boolean createFrame)` Launches a new agent using its full class name and returns when the launched agent has completed its `activate()` method or when the time out is elapsed.
`void`	`launchAgentBucket(List<? extends AbstractAgent> bucket, int nbOfParallelTasks, String... roles)` Similar to `launchAgentBucket(String, int, String...)`
`void`	`launchAgentBucket(List<? extends AbstractAgent> bucket, String... roles)` This call is equivalent to This has the same effect as `launchAgentBucket(bucket, 1, roles)`, That is only one core will be used for the launch.
`List<AbstractAgent>`	`launchAgentBucket(String agentClass, int bucketSize, int cpuCoreNb, String... roles)` Optimizes mass agent launching.
`List<AbstractAgent>`	`launchAgentBucket(String agentClass, int bucketSize, String... roles)` This has the same effect as `launchAgentBucket(agentClass, bucketSize, 1, roles)`.
`AbstractAgent.ReturnCode`	`launchNode(Node agentXmlNode)` Launch agents by parsing an XML node.
`AbstractAgent.ReturnCode`	`launchXmlAgents(String xmlFile)` launch all the agents defined in an xml configuration file
`AbstractAgent.ReturnCode`	`leaveGroup(String community, String group)` Makes this agent leaves the group of a particular community.
`AbstractAgent.ReturnCode`	`leaveRole(String community, String group, String role)` Abandons an handled role within a group of a particular community.
`Message`	`nextMessage()` Retrieves and removes the oldest received message contained in the mailbox.
`Message`	`nextMessage(MessageFilter filter)` Retrieves and removes the first message of the mailbox that matches the filter.
`List<Message>`	`nextMessages(MessageFilter filter)` Retrieves and removes all the messages of the mailbox that match the filter.
`<E extends Enum<E>> void`	`proceedEnumMessage(EnumMessage<E> message)` Proceeds an `EnumMessage` so that if it is correctly built, the agent will trigger its corresponding behavior using the parameters of the message.
`Message`	`purgeMailbox()` Purges the mailbox and returns the most recent received message at that time.
`void`	`receiveMessage(Message m)` This method offers a convenient way for regular object to send messages to Agents, especially threaded agents.
`void`	`reload()` Kills the caller and launches a new instance of this agent using the latest byte code available for the corresponding class.
`AbstractAgent.ReturnCode`	`requestRole(String community, String group, String role)` Requests a role within a group of a particular community.
`AbstractAgent.ReturnCode`	`requestRole(String community, String group, String role, Object passKey)` Requests a role within a group of a particular community using a passKey.
`AbstractAgent.ReturnCode`	`sendMessage(AgentAddress receiver, Message messageToSend)` Sends a message to an agent using an agent address.
`AbstractAgent.ReturnCode`	`sendMessage(String community, String group, String role, Message message)` Sends a message to an agent having this position in the organization, specifying explicitly the role used to send it.
`AbstractAgent.ReturnCode`	`sendMessageWithRole(AgentAddress receiver, Message message, String senderRole)` Sends a message, using an agent address, specifying explicitly the role used to send it.
`AbstractAgent.ReturnCode`	`sendMessageWithRole(String community, String group, String role, Message message, String senderRole)` Sends a message to an agent having this position in the organization.
`AbstractAgent.ReturnCode`	`sendReply(Message messageToReplyTo, Message reply)` Sends a message by replying to a previously received message.
`AbstractAgent.ReturnCode`	`sendReplyWithRole(Message messageToReplyTo, Message reply, String senderRole)` Sends a message by replying to a previously received message.
`void`	`setLogLevel(Level newLevel)` Sets the agent's log level.
`<E extends Enum<E>> void`	`setMadkitProperty(E option, String value)` Set the MaDKit session property indicated by the specified constant representing a MaDKit option.
`void`	`setMadkitProperty(String key, String value)` Set the MaDKit session property indicated by the specified key.
`void`	`setName(String name)` Changes the agent's name
`void`	`setupFrame(JFrame frame)` Called when the default GUI mechanism is used upon agent creation.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail
- logger
```
protected AgentLogger logger
```
  logger should be used to print messages and trace the agent's life cycle. According to a log level, the messages will be displayed in the console and/or the GUI and/or a file according to the settings. Thanks to the logging mechanism of the SDK, various log level could be used. The following idiom should be used because Logger is set to null when AgentLogger.setLevel(Level) is used with Level.OFF. This allows to efficiently optimize the runtime speed when they are a lot of agents (e.g. in a simulation mode). Indeed, thanks to this idiom, useless strings will not be built, thus saving a lot of time.
```
 if (logger != null)
        logger.info("info message");
 
```
  getLogger() should not be used here because it always returns a non null logger.
  See Also:
  Level, Logger

Constructor Detail
- AbstractAgent
```
public AbstractAgent()
```

Method Detail

createGUIOnStartUp
```
public void createGUIOnStartUp()
```
Activates the MaDKit GUI initialization when launching the agent whatever the launching parameters. By default agents are launched without a GUI but some of them always need one: This ensures that the agent will have one. This method should be used only in the constructor of the agent, otherwise it will be useless as it specifies a boot property of the agent.

hasGUI
```
public boolean hasGUI()
```
Tells if this agent has a GUI automatically built by the kernel

Returns:
true if this agent has a GUI built by the kernel

hashCode
```
public final int hashCode()
```
The ID of an agent. All the agents have different hashCode value in one kernel. Thus it can be used to identify one agent. In a networked environment, this value should be used in combination with the kernelAddress of the agent for unique identification. This also holds when multiple MaDKit kernels are launched within the same JVM.

Overrides:

hashCode in class Object

Returns:
the agent's unique ID in the MaDKit kernel

getNetworkID
```
public final String getNetworkID()
```
Return a string representing a unique identifier for the agent over the network.

Returns:
the agent's network identifier

getSimpleNetworkID
```
public final String getSimpleNetworkID()
```
Return a string representing a shorter version of the unique identifier of the agent over the network. As a simplified version, this string may not be unique.

Returns:
a simplified version of the agent's network identifier
See Also:
getNetworkID()

isAlive
```
public boolean isAlive()
```
Returns true if the agent has been launched and is not ended nor killed.

activate

protected void activate()

This method corresponds to the first behavior which is called by the MaDKit kernel when an agent is launched. Usually a good place to take a position in the organization of the artificial society.

Here is a typical example:

 @Override
 protected void activate()
 {
        AbstractAgent.ReturnCode returnCode = requestRole("a community", "a group", "my role");
        if (returnCode == AbstractAgent.ReturnCode.SUCCESS){
                if(logger != null)
                        logger.info("I am now playing my role in the artificial society");
        }
        else{
                if(logger != null)
                        logger.warning("something wrong, return code is "+returnCode);
        }
 }

end

protected void end()

This method corresponds to the last behavior which is called by the MaDKit kernel. This call occurs when a threaded agent normally exits its live method or when the agent is killed. Usually a good place to release taken resources or log what has to be logged. It has to be noted that the kernel automatically takes care of removing the agent from the organizations it is in. However, this cleaning is not logged by the agent. Therefore it could be of interest for the agent to do that itself.

Here is a typical example:

 @Override
 protected void end()
 {
        AbstractAgent.ReturnCode returnCode = leaveRole("a community", "a group", "my role");
        if (returnCode == AbstractAgent.ReturnCode.SUCCESS){
                if(logger != null)
                        logger.info("I am leaving the artificial society");
        }
        else{
                if(logger != null)
                        logger.warning("something wrong when ending, return code is "+returnCode);
        }
        if(logger != null)
                logger.info("I am done");
        }
 }

launchAgent
```
public AbstractAgent.ReturnCode launchAgent(AbstractAgent agent)
```
Launches a new agent in the MaDKit platform. This has the same effect as launchAgent(agent,Integer.MAX_VALUE,false)
Parameters:
agent - the agent to launch.

Returns:
- AbstractAgent.ReturnCode.SUCCESS : The launch has succeeded. This also means that the agent has successfully completed its activate method
- AbstractAgent.ReturnCode.ALREADY_LAUNCHED : If this agent has been already launched
- AbstractAgent.ReturnCode.TIMEOUT : If your agent is activating for more than 68 years Oo !
- AbstractAgent.ReturnCode.AGENT_CRASH : If the agent crashed during its activate method
Since:

MaDKit 5.0

See Also:
launchAgent(AbstractAgent)

launchAgent
```
public AbstractAgent.ReturnCode launchAgent(AbstractAgent agent,
                                   int timeOutSeconds)
```
Launches a new agent in the MaDKit platform. This has the same effect as launchAgent(agent,timeOutSeconds,false)
Parameters:
agent - the agent to launch.
timeOutSeconds - time to wait the end of the agent's activation until returning a TIMEOUT.

Returns:
- AbstractAgent.ReturnCode.SUCCESS : The launch has succeeded. This also means that the agent has successfully completed its activate method
- AbstractAgent.ReturnCode.ALREADY_LAUNCHED : If this agent has been already launched
- AbstractAgent.ReturnCode.TIMEOUT : If the activation time of the agent is greater than timeOutSeconds seconds
- AbstractAgent.ReturnCode.AGENT_CRASH: If the agent crashed during its activate method

launchAgent
```
public AbstractAgent.ReturnCode launchAgent(AbstractAgent agent,
                                   boolean createFrame)
```
Launches a new agent in the MaDKit platform. This has the same effect as launchAgent(agent,Integer.MAX_VALUE,withGUIManagedByTheBooter)
Parameters:
agent - the agent to launch.
createFrame - if true, the kernel will launch a JFrame for this agent.

Returns:
- AbstractAgent.ReturnCode.SUCCESS : The launch has succeeded. This also means that the agent has successfully completed its activate method
- AbstractAgent.ReturnCode.ALREADY_LAUNCHED : If this agent has been already launched
- AbstractAgent.ReturnCode.TIMEOUT : If your agent is activating for more than 68 years Oo !
- AbstractAgent.ReturnCode.AGENT_CRASH : If the agent crashed during its activate method
Since:

MaDKit 5.0

See Also:
launchAgent(AbstractAgent)

launchAgent
```
public AbstractAgent.ReturnCode launchAgent(AbstractAgent agent,
                                   int timeOutSeconds,
                                   boolean createFrame)
```
Launches a new agent and returns when the agent has completed its activate() method or when timeOutSeconds seconds elapsed. That is, the launched agent has not finished its activate() before the time out time elapsed. Additionally, if createFrame is true, it tells to MaDKit that an agent GUI should be managed by the Kernel. In such a case, the kernel takes the responsibility to assign a JFrame to the agent and to manage its life cycle (e.g. if the agent ends or is killed then the JFrame is closed) Using this feature there are two possibilities:
- 1. the agent overrides the method setupFrame(JFrame) and so setup the default JFrame as will
- 2. the agent does not override it so that MaDKit will setup the JFrame with the default Graphical component delivered by the MaDKit platform: OutputPanel
Parameters:
agent - the agent to launch.
timeOutSeconds - time to wait for the end of the agent's activation until returning a TIMEOUT.
createFrame - if true, the kernel will launch a JFrame for this agent.

Returns:
- AbstractAgent.ReturnCode.SUCCESS : The launch has succeeded. This also means that the agent has successfully completed its activate method
- AbstractAgent.ReturnCode.ALREADY_LAUNCHED : If this agent has been already launched
- AbstractAgent.ReturnCode.TIMEOUT : If the activation time of the agent is greater than timeOutSeconds seconds
- AbstractAgent.ReturnCode.AGENT_CRASH : If the agent crashed during its activate method
Since:

MaDKit 5.0

launchAgent
```
public AbstractAgent launchAgent(String agentClass)
```
Launches a new agent using its full class name.
This has the same effect as launchAgent(agentClass, Integer.MAX_VALUE, false).

Parameters:
agentClass - the full class name of the agent to launch

Returns:
the instance of the launched agent or null if the operation times out or failed.

launchAgent
```
public AbstractAgent launchAgent(String agentClass,
                        int timeOutSeconds)
```
Launches a new agent using its full class name.
This has the same effect as launchAgent(agentClass, timeOutSeconds, false).

Parameters:
timeOutSeconds - time to wait the end of the agent's activation until returning null
agentClass - the full class name of the agent to launch

Returns:
the instance of the launched agent or null if the operation times out or failed.

launchAgent
```
public AbstractAgent launchAgent(String agentClass,
                        boolean createFrame)
```
Launches a new agent using its full class name.
This has the same effect as launchAgent(agentClass, Integer.MAX_VALUE, defaultGUI).

Parameters:
createFrame - if true a default GUI will be associated with the launched agent
agentClass - the full class name of the agent to launch

Returns:
the instance of the launched agent or null if the operation times out or failed.

launchAgent
```
public AbstractAgent launchAgent(String agentClass,
                        int timeOutSeconds,
                        boolean createFrame)
```
Launches a new agent using its full class name and returns when the launched agent has completed its activate() method or when the time out is elapsed. This has the same effect as launchAgent(AbstractAgent, int, boolean) but allows to launch agent using a class name found reflexively. The targeted agent class should have a default constructor for this to work. Additionally, this method will launch the last compiled byte code of the corresponding class if it has been reloaded using MadkitClassLoader.reloadClass(String). Finally, if the launch timely succeeded, this method returns the instance of the created agent.

Parameters:
timeOutSeconds - time to wait the end of the agent's activation until returning null
createFrame - if true a default GUI will be associated with the launched agent
agentClass - the full class name of the agent to launch

Returns:
the instance of the launched agent or null if the operation times out or failed.

launchAgentBucket
```
public List<AbstractAgent> launchAgentBucket(String agentClass,
                                    int bucketSize,
                                    int cpuCoreNb,
                                    String... roles)
```
Optimizes mass agent launching. Launches bucketSize instances of agentClassName (an agent class) and put them in the artificial society at the locations defined by cgrLocations. Each string of the cgrLocations array defines a complete CGR location. So for example, cgrLocations could be defined and used with code such as :
```
 launchAgentBucketWithRoles("madkit.bees.Bee", 1000000, "community,group,role","anotherC,anotherG,anotherR")
 
```
In this example all the agents created by this process will have these two roles in the artificial society, even if they do not request them in their activate() method.
Additionally, in order to avoid to change the code of the agent considering how they will be launched (using the bucket mode or not). One should use the following alternative of the usual request methods : bucketModeCreateGroup(String, String, boolean, Gatekeeper), bucketModeRequestRole(String, String, String, Object): If used in activate(), these requests will be ignored when the bucket mode is used or normally proceeded otherwise.
If some of the corresponding groups do not exist before this call, the caller agent will automatically become the manager of these groups.
Parameters:
agentClass - the name of the class from which the agents should be built.
bucketSize - the desired number of instances.
cpuCoreNb - the number of parallel tasks to use. Beware that if cpuCoreNb is greater than 1, the agents' constructors and activate() methods will be called simultaneously so that one has to be careful if shared resources are accessed by the agents
roles - default locations in the artificial society for the launched agents. Each string of the cgrLocations array defines a complete CGR location by separating C, G and R with commas as follows: "community,group,role". It can be null.

Returns:
a list containing all the agents which have been launched, or null if the operation has failed
Since:

MaDKit 5.0.0.6

launchAgentBucket
```
public List<AbstractAgent> launchAgentBucket(String agentClass,
                                    int bucketSize,
                                    String... roles)
```
This has the same effect as launchAgentBucket(agentClass, bucketSize, 1, roles).

Parameters:
agentClass - the name of the class from which the agents should be built.
bucketSize - the desired number of instances.
roles - default locations in the artificial society for the launched agents. Each string of the cgrLocations array defines a complete CGR location by separating C, G and R with commas as follows: "community,group,role"

Returns:
a list containing all the agents which have been launched, or null if the operation has failed
Since:

MaDKit 5.0.2

launchAgentBucket
```
public void launchAgentBucket(List<? extends AbstractAgent> bucket,
                     String... roles)
```
This call is equivalent to This has the same effect as launchAgentBucket(bucket, 1, roles), That is only one core will be used for the launch.

Parameters:
bucket - the list of agents to launch
roles - default locations in the artificial society for the launched agents. Each string of the cgrLocations array defines a complete CGR location by separating C, G and R with commas as follows: "community,group,role". It can be null

launchAgentBucket
```
public void launchAgentBucket(List<? extends AbstractAgent> bucket,
                     int nbOfParallelTasks,
                     String... roles)
```
Similar to launchAgentBucket(String, int, String...) except that the list of agents to launch is given. Especially, this could be used when the agents have no default constructor.

Parameters:
bucket - the list of agents to launch
nbOfParallelTasks - the number of parallel tasks to use for launching the agents. Beware that if nbOfParallelTasks is greater than 1, the agents' activate() methods will be call simultaneously so that one has to be careful if shared resources are accessed
roles - default locations in the artificial society for the launched agents. Each string of the cgrLocations array defines a complete CGR location by separating C, G and R with commas as follows: "community,group,role". It can be null

killAgent
```
public AbstractAgent.ReturnCode killAgent(AbstractAgent target)
```
Kills the targeted agent. This has the same effect as killAgent(target,Integer.MAX_VALUE) so that the targeted agent has a lot of time to complete its end() method.
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 more than 2e31 seconds and has been brutally stopped: This unlikely happens ;).
Since:

MaDKit 5.0

See Also:
killAgent(AbstractAgent, int)

killAgent
```
public AbstractAgent.ReturnCode killAgent(AbstractAgent target,
                                 int timeOutSeconds)
```
Kills the targeted agent. The kill process stops the agent's life cycle but allows it to process its 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.
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.
Since:

MaDKit 5.0

getName
```
public String getName()
```
Returns the agent's name.

Returns:
the name to display in logger info, GUI title and so on. Default is "class name + internal ID"

setName
```
public void setName(String name)
```
Changes the agent's name

Parameters:
name - the name to display in logger info, GUI title and so on, default is "class name + internal ID"

setLogLevel
```
public void setLogLevel(Level newLevel)
```
Sets the agent's log level. This should be used instead of directly AgentLogger.setLevel(Level) because this also works when logger is null and allows to set it to null to save cpu time.

Parameters:
newLevel - The log level under which log messages are displayed. If Level.OFF is used then logger is set to null
See Also:
logger

getLogger
```
public final AgentLogger getLogger()
```
Returns the agent's logger.

Returns:
the agent's logger. It cannot be null as it will be created if necessary. But you can then still put logger to null for optimizing your code by using setLogLevel(Level) with Level.OFF.
Since:

MaDKit 5.0.0.6

See Also:
logger

compareTo
```
public int compareTo(AbstractAgent other)
```
Compares this agent with the specified agent for order with respect to instantiation time.

Specified by:

compareTo in interface Comparable<AbstractAgent>

Parameters:
other - the agent to be compared.

Returns:
a negative integer, a positive integer or zero as this agent has been instantiated before, after or is the same agent than the specified agent.
See Also:
Comparable.compareTo(java.lang.Object)

createGroup
```
public AbstractAgent.ReturnCode createGroup(String community,
                                   String group)
```
Creates a new Group within a community. This has the same effect as createGroup(community, group, false, null)
Parameters:
community - the community within which the group will be created. If this community does not exist it will be created.
group - the name of the new group

Returns:
- AbstractAgent.ReturnCode.SUCCESS: If the group has been successfully created.
- AbstractAgent.ReturnCode.ALREADY_GROUP: If the operation failed because such a group already exists.
- AbstractAgent.ReturnCode.IGNORED: If this method is used in activate and this agent has been launched using launchAgentBucket(List, String...) with non null roles
Since:

MaDKit 5.0

See Also:
createGroup(String, String, boolean, Gatekeeper)

createGroup
```
public AbstractAgent.ReturnCode createGroup(String community,
                                   String group,
                                   boolean isDistributed)
```
Creates a new Group within a community. This has the same effect as createGroup(community, group, isDistributed, null)
Parameters:
community - the community within which the group will be created. If this community does not exist it will be created.
group - the name of the new group.
isDistributed - if true the new group will be distributed when multiple MaDKit kernels are connected.

Returns:
- AbstractAgent.ReturnCode.SUCCESS: If the group has been successfully created.
- AbstractAgent.ReturnCode.ALREADY_GROUP: If the operation failed because such a group already exists.
- AbstractAgent.ReturnCode.IGNORED: If this method is used in activate and this agent has been launched using launchAgentBucket(List, String...) with non null roles
Since:

MaDKit 5.0

See Also:
createGroup(String, String, boolean, Gatekeeper)

createGroup
```
public AbstractAgent.ReturnCode createGroup(String community,
                                   String group,
                                   boolean isDistributed,
                                   Gatekeeper keyMaster)
```
Creates a new Group within a community.
If this operation succeed, the agent will automatically handle the role defined by Organization.GROUP_MANAGER_ROLE, which value is "manager", in this created group. Especially, if the agent leaves the role of "manager", it will also automatically leave the group and thus all the roles it has in this group.
Agents that want to enter the group may send messages to the "manager" using the role defined by Organization.GROUP_CANDIDATE_ROLE, which value is "candidate".
Parameters:
community - the community within which the group will be created. If this community does not exist it will be created.
group - the name of the new group.
isDistributed - if true the new group will be distributed when multiple MaDKit kernels are connected.
keyMaster - any object that implements the Gatekeeper interface. If not null, this object will be used to check if an agent can be admitted in the group. When this object is null, there is no group access control.

Returns:
- AbstractAgent.ReturnCode.SUCCESS: If the group has been successfully created.
- AbstractAgent.ReturnCode.ALREADY_GROUP: If the operation failed because such a group already exists.
- AbstractAgent.ReturnCode.IGNORED: If the agent has been launched using a launchAgentBucket method such as launchAgentBucket(List, String...) with non null roles. This for optimization purposes.
Since:

MaDKit 5.0

See Also:
Gatekeeper, AbstractAgent.ReturnCode

bucketModeCreateGroup
```
public AbstractAgent.ReturnCode bucketModeCreateGroup(String community,
                                             String group,
                                             boolean isDistributed,
                                             Gatekeeper keyMaster)
```
Creates a new Group within a community even if the agent has been launched using using one of the launchAgentBucket methods. This method is only useful when called within the activate() method.
For instance, this is useful if you launch one million of agents and when only some of them have to create a specific group, not defined in the parameters of launchAgentBucket(List, int, String...)
Parameters:
community - the community within which the group will be created. If this community does not exist it will be created.
group - the name of the new group.
isDistributed - if true the new group will be distributed when multiple MaDKit kernels are connected.
keyMaster - any object that implements the Gatekeeper interface. If not null, this object will be used to check if an agent can be admitted in the group. When this object is null, there is no group access control.

Returns:
- AbstractAgent.ReturnCode.SUCCESS: If the group has been successfully created.
- AbstractAgent.ReturnCode.ALREADY_GROUP: If the operation failed because such a group already exists.
Since:

MaDKit 5.0.2

See Also:
Gatekeeper, AbstractAgent.ReturnCode

createGroupIfAbsent
```
public boolean createGroupIfAbsent(String community,
                          String group)
```
Creates a new Group within a community but does not produce any warning if the group already exists. This has the same effect as createGroupIfAbsent(community, group, false, null)

Parameters:
community - the community within which the group will be created. If this community does not exist it will be created.
group - the name of the new group.

Returns:
true if the group has been created, false if such a group already exists.
Since:

MaDKit 5.0

See Also:
createGroupIfAbsent(String, String, boolean, Gatekeeper)

createGroupIfAbsent
```
public boolean createGroupIfAbsent(String community,
                          String group,
                          boolean isDistributed)
```
Creates a new Group within a community but does not produce any warning if the group already exists. This has the same effect as createGroupIfAbsent(community, group, isDistributed, null)

Parameters:
community - the community within which the group will be created. If this community does not exist it will be created.
group - the name of the new group
isDistributed - if true the new group will be distributed when multiple MaDKit kernels are connected.

Returns:
true if the group has been created, false if such a group already exists.
Since:

MaDKit 5.0

See Also:
createGroupIfAbsent(String, String, boolean, Gatekeeper)

createGroupIfAbsent
```
public boolean createGroupIfAbsent(String community,
                          String group,
                          boolean isDistributed,
                          Gatekeeper keyMaster)
```
Creates a new Group within a community but does not produce any warning if the group already exists. If this operation succeed, the agent will automatically handle the role of group manager in the created group.

Parameters:
community - the community within which the group will be created. If this community does not exist it will be created.
group - the name of the new group
isDistributed - if true the new group will be distributed when multiple MaDKit kernels are connected.
keyMaster - any object that implements the Gatekeeper interface. If not null, this object will be used to check if an agent can be admitted in the group. When this object is null, there is no group access control.

Returns:
true if the group has been created, false if such a group already exists.
Since:

MaDKit 5.0

See Also:
Gatekeeper, AbstractAgent.ReturnCode

leaveGroup
```
public AbstractAgent.ReturnCode leaveGroup(String community,
                                  String group)
```
Makes this agent leaves the group of a particular community.
Parameters:
community - the community name
group - the group name

Returns:
- AbstractAgent.ReturnCode.SUCCESS: If the operation has succeeded.
- AbstractAgent.ReturnCode.NOT_COMMUNITY: If the community does not exist.
- AbstractAgent.ReturnCode.NOT_GROUP: If the group does not exist.
- AbstractAgent.ReturnCode.NOT_IN_GROUP: If this agent is not a member of this group.
Since:

MaDKit 5.0

See Also:
AbstractAgent.ReturnCode

requestRole
```
public AbstractAgent.ReturnCode requestRole(String community,
                                   String group,
                                   String role)
```
Requests a role within a group of a particular community. This has the same effect as requestRole(community, group, role, null, false). So the passKey is null and the group must not be secured for this to succeed.

Parameters:
community - the group's community.
group - the targeted group.
role - the desired role.
Since:

MaDKit 5.0

See Also:
requestRole(String, String, String, Object)

requestRole
```
public AbstractAgent.ReturnCode requestRole(String community,
                                   String group,
                                   String role,
                                   Object passKey)
```
Requests a role within a group of a particular community using a passKey.
Parameters:
community - the group's community.
group - the targeted group.
role - the desired role.
passKey - the passKey to enter a secured group. It is generally delivered by the group's group manager. It could be null, which is sufficient to enter an unsecured group. Especially, requestRole(String, String, String) uses a null passKey.

Returns:
- AbstractAgent.ReturnCode.SUCCESS: If the operation has succeeded.
- AbstractAgent.ReturnCode.NOT_COMMUNITY: If the community does not exist.
- AbstractAgent.ReturnCode.NOT_GROUP: If the group does not exist.
- AbstractAgent.ReturnCode.ROLE_ALREADY_HANDLED: If this role is already handled by this agent.
- AbstractAgent.ReturnCode.ACCESS_DENIED: If the access denied by the manager of that secured group.
- AbstractAgent.ReturnCode.IGNORED: If the agent has been launched using a launchAgentBucket method such as launchAgentBucket(List, String...) with non null roles. This for optimization purposes.
Since:

MaDKit 5.0

See Also:
AbstractAgent.ReturnCode, Gatekeeper

bucketModeRequestRole
```
public AbstractAgent.ReturnCode bucketModeRequestRole(String community,
                                             String group,
                                             String role,
                                             Object passKey)
```
Requests a role even if the agent has been launched using one of the launchAgentBucket methods with non null roles. For instance, this is useful if you launch one million of agents and when only some of them have to take a specific role which cannot be defined in the parameters of launchAgentBucket(List, int, String...) because they are priorly unknown and build at runtime.
Parameters:
community - the group's community.
group - the targeted group.
role - the desired role.
passKey - the passKey to enter a secured group. It is generally delivered by the group's group manager. It could be null, which is sufficient to enter an unsecured group. Especially, requestRole(String, String, String) uses a null passKey.

Returns:
- AbstractAgent.ReturnCode.SUCCESS: If the operation has succeeded.
- AbstractAgent.ReturnCode.NOT_COMMUNITY: If the community does not exist.
- AbstractAgent.ReturnCode.NOT_GROUP: If the group does not exist.
- AbstractAgent.ReturnCode.ROLE_ALREADY_HANDLED: If this role is already handled by this agent.
- AbstractAgent.ReturnCode.ACCESS_DENIED: If the access denied by the manager of that secured group.
Since:

MaDKit 5.0

See Also:
AbstractAgent.ReturnCode, Gatekeeper

leaveRole
```
public AbstractAgent.ReturnCode leaveRole(String community,
                                 String group,
                                 String role)
```
Abandons an handled role within a group of a particular community.
Parameters:
community - the community name
group - the group name
role - the role name

Returns:
- AbstractAgent.ReturnCode.SUCCESS: If the operation has succeeded.
- AbstractAgent.ReturnCode.NOT_COMMUNITY: If the community does not exist.
- AbstractAgent.ReturnCode.NOT_GROUP: If the group does not exist.
- AbstractAgent.ReturnCode.ROLE_NOT_HANDLED: If this role is not handled by this agent.
Since:

MaDKit 5.0

See Also:
AbstractAgent.ReturnCode

getAgentAddressIn
```
public AgentAddress getAgentAddressIn(String community,
                             String group,
                             String role)
```
Returns the agent address of this agent at this CGR location.

Parameters:
community -
group -
role -

Returns:
the agent's address in this location or null if this agent does not handle this role.
Since:

MaDKit 5.0.0.15

getAgentWithRole
```
public AgentAddress getAgentWithRole(String community,
                            String group,
                            String role)
```
Returns an AgentAddress corresponding to an agent having this position in the organization. The caller is excluded from the search.

Parameters:
community - the community name
group - the group name
role - the role name

Returns:
an AgentAddress corresponding to an agent handling this role or null if such an agent does not exist.

getDistantAgentWithRole
```
public AgentAddress getDistantAgentWithRole(String community,
                                   String group,
                                   String role,
                                   KernelAddress from)
```
Returns an AgentAddress corresponding to an agent having this position in the organization on a particular kernel. The caller is excluded from the search.

Parameters:
community - the community name
group - the group name
role - the role name
from - the kernel address on which the agent is running

Returns:
an AgentAddress corresponding to an agent handling this role on the targeted kernel or null if such an agent does not exist.

getAgentsWithRole
```
public List<AgentAddress> getAgentsWithRole(String community,
                                   String group,
                                   String role)
```
Returns an List containing agents that handle this role in the organization. The caller is excluded from this list.

Parameters:
community - the community name
group - the group name
role - the role name

Returns:
a List containing agents that handle this role or null if no agent has been found.

getAgentsWithRole
```
public List<AgentAddress> getAgentsWithRole(String community,
                                   String group,
                                   String role,
                                   boolean callerIncluded)
```
Returns an List containing all the agents that handle this role in the organization.

Parameters:
community - the community name
group - the group name
role - the role name
callerIncluded - if false, the caller is removed from the list if it is in.

Returns:
a List containing agents that handle this role or null if no agent has been found.

nextMessage
```
public Message nextMessage()
```
Retrieves and removes the oldest received message contained in the mailbox.

Returns:
The next message or null if the message box is empty.

nextMessage
```
public Message nextMessage(MessageFilter filter)
```
Retrieves and removes the first message of the mailbox that matches the filter.

Returns:
The next acceptable message or null if no such message has been found.

nextMessages
```
public List<Message> nextMessages(MessageFilter filter)
```
Retrieves and removes all the messages of the mailbox that match the filter.

Parameters:
filter - if null all the messages are returned and removed from the mailbox.

Returns:
the ordered list of matching messages, or an empty list if none has been found.

purgeMailbox
```
public Message purgeMailbox()
```
Purges the mailbox and returns the most recent received message at that time.

Returns:
the most recent received message or null if the mailbox is already empty.

isMessageBoxEmpty
```
public boolean isMessageBoxEmpty()
```
Tells if there is a message in the mailbox

Returns:
true if there is no message in the mailbox.

sendMessage
```
public AbstractAgent.ReturnCode sendMessage(AgentAddress receiver,
                                   Message messageToSend)
```
Sends a message to an agent using an agent address. This has the same effect as sendMessageWithRole(receiver, messageToSend, null).
Parameters:
receiver -
messageToSend -

Returns:
- AbstractAgent.ReturnCode.SUCCESS: If the send has succeeded.
- AbstractAgent.ReturnCode.NOT_IN_GROUP: If this agent is not a member of the receiver's group.
- AbstractAgent.ReturnCode.INVALID_AGENT_ADDRESS: If the receiver address is no longer valid. This is the case when the corresponding agent has leaved the role corresponding to the receiver agent address.
See Also:
AbstractAgent.ReturnCode, AgentAddress

sendMessageWithRole
```
public AbstractAgent.ReturnCode sendMessageWithRole(AgentAddress receiver,
                                           Message message,
                                           String senderRole)
```
Sends a message, using an agent address, specifying explicitly the role used to send it.
Parameters:
receiver - the targeted agent
message - the message to send

Returns:
- AbstractAgent.ReturnCode.SUCCESS: If the send has succeeded.
- AbstractAgent.ReturnCode.NOT_IN_GROUP: If this agent is not a member of the receiver's group.
- AbstractAgent.ReturnCode.ROLE_NOT_HANDLED: If senderRole is not handled by this agent.
- AbstractAgent.ReturnCode.INVALID_AGENT_ADDRESS: If the receiver address is no longer valid. This is the case when the corresponding agent has leaved the role corresponding to the receiver agent address.
See Also:
AbstractAgent.ReturnCode, AgentAddress

sendMessage
```
public AbstractAgent.ReturnCode sendMessage(String community,
                                   String group,
                                   String role,
                                   Message message)
```
Sends a message to an agent having this position in the organization, specifying explicitly the role used to send it. This has the same effect as sendMessageWithRole(community, group, role, messageToSend,null). If several agents match, the target is chosen randomly. The sender is excluded from this search.
Parameters:
community - the community name
group - the group name
role - the role name
message - the message to send

Returns:
- AbstractAgent.ReturnCode.SUCCESS: If the send has succeeded.
- AbstractAgent.ReturnCode.NOT_COMMUNITY: If the community does not exist.
- AbstractAgent.ReturnCode.NOT_GROUP: If the group does not exist.
- AbstractAgent.ReturnCode.NOT_ROLE: If the role does not exist.
- AbstractAgent.ReturnCode.NOT_IN_GROUP: If this agent is not a member of the targeted group.
- AbstractAgent.ReturnCode.NO_RECIPIENT_FOUND: If no agent was found as recipient, i.e. the sender was the only agent having this role.
See Also:
AbstractAgent.ReturnCode

sendMessageWithRole
```
public AbstractAgent.ReturnCode sendMessageWithRole(String community,
                                           String group,
                                           String role,
                                           Message message,
                                           String senderRole)
```
Sends a message to an agent having this position in the organization. This has the same effect as sendMessageWithRole(community, group, role, messageToSend,null) . If several agents match, the target is chosen randomly. The sender is excluded from this search.
Parameters:
community - the community name
group - the group name
role - the role name
message - the message to send
senderRole - the agent's role with which the message has to be sent

Returns:
- AbstractAgent.ReturnCode.SUCCESS: If the send has succeeded.
- AbstractAgent.ReturnCode.NOT_COMMUNITY: If the community does not exist.
- AbstractAgent.ReturnCode.NOT_GROUP: If the group does not exist.
- AbstractAgent.ReturnCode.NOT_ROLE: If the role does not exist.
- AbstractAgent.ReturnCode.ROLE_NOT_HANDLED: If senderRole is not handled by this agent.
- AbstractAgent.ReturnCode.NOT_IN_GROUP: If this agent is not a member of the targeted group.
- AbstractAgent.ReturnCode.NO_RECIPIENT_FOUND: If no agent was found as recipient, i.e. the sender was the only agent having this role.
See Also:
AbstractAgent.ReturnCode

broadcastMessage
```
public AbstractAgent.ReturnCode broadcastMessage(String community,
                                        String group,
                                        String role,
                                        Message message)
```
Broadcasts a message to every agent having a role in a group in a community, but not to the sender.
Parameters:
community - the community name
group - the group name
role - the role name
message -

Returns:
- AbstractAgent.ReturnCode.SUCCESS: If the send has succeeded.
- AbstractAgent.ReturnCode.NOT_COMMUNITY: If the community does not exist.
- AbstractAgent.ReturnCode.NOT_GROUP: If the group does not exist.
- AbstractAgent.ReturnCode.NOT_ROLE: If the role does not exist.
- AbstractAgent.ReturnCode.NO_RECIPIENT_FOUND: If no agent was found as recipient, i.e. the sender was the only agent having this role.
- AbstractAgent.ReturnCode.NOT_IN_GROUP: If this agent is not a member of the targeted group.
See Also:
AbstractAgent.ReturnCode

broadcastMessageWithRole
```
public AbstractAgent.ReturnCode broadcastMessageWithRole(String community,
                                                String group,
                                                String role,
                                                Message messageToSend,
                                                String senderRole)
```
Broadcasts a message to every agent having a role in a group in a community using a specific role for the sender. The sender is excluded from the search.
Parameters:
community - the community name
group - the group name
role - the role name
messageToSend -
senderRole - the agent's role with which the message should be sent

Returns:
- AbstractAgent.ReturnCode.SUCCESS: If the send has succeeded.
- AbstractAgent.ReturnCode.NOT_COMMUNITY: If the community does not exist.
- AbstractAgent.ReturnCode.NOT_GROUP: If the group does not exist.
- AbstractAgent.ReturnCode.NOT_ROLE: If the role does not exist.
- AbstractAgent.ReturnCode.NOT_IN_GROUP: If this agent is not a member of the targeted group.
- AbstractAgent.ReturnCode.NO_RECIPIENT_FOUND: If no agent was found as recipient, i.e. the sender was the only agent having this role.
See Also:
AbstractAgent.ReturnCode

sendReplyWithRole
```
public AbstractAgent.ReturnCode sendReplyWithRole(Message messageToReplyTo,
                                         Message reply,
                                         String senderRole)
```
Sends a message by replying to a previously received message. The sender is excluded from this search.
Parameters:
messageToReplyTo - the previously received message.
reply - the reply itself.
senderRole - the agent's role with which the message should be sent

Returns:
- AbstractAgent.ReturnCode.SUCCESS: If the send has succeeded.
- AbstractAgent.ReturnCode.NOT_IN_GROUP: If this agent is no longer a member of the corresponding group.
- AbstractAgent.ReturnCode.ROLE_NOT_HANDLED: If senderRole is not handled by this agent.
- AbstractAgent.ReturnCode.INVALID_AGENT_ADDRESS: If the receiver address is no longer valid. This is the case when the corresponding agent has leaved the role corresponding to the receiver agent address.
See Also:
AbstractAgent.ReturnCode

sendReply
```
public AbstractAgent.ReturnCode sendReply(Message messageToReplyTo,
                                 Message reply)
```
Sends a message by replying to a previously received message. This has the same effect as sendReplyWithRole(messageToReplyTo, reply, null).
Parameters:
messageToReplyTo - the previously received message.
reply - the reply itself.

Returns:
- AbstractAgent.ReturnCode.SUCCESS: If the reply has succeeded.
- AbstractAgent.ReturnCode.NOT_IN_GROUP: If this agent is no longer a member of the corresponding group.
- AbstractAgent.ReturnCode.INVALID_AGENT_ADDRESS: If the receiver address is no longer valid. This is the case when the corresponding agent has leaved the role corresponding to the receiver agent address.
See Also:
sendReplyWithRole(Message, Message, String)

getReplyTo
```
public Message getReplyTo(Message originalMessage)
```
Gets the next message which is a reply to the originalMessage.

Parameters:
originalMessage - the message to which a reply is searched.

Returns:
a reply to the originalMessage or null if no reply to this message has been received.

receiveMessage
```
public void receiveMessage(Message m)
```
This method offers a convenient way for regular object to send messages to Agents, especially threaded agents. For instance when a GUI wants to discuss with its linked agent: This allows to enqueue work to do in their life cycle

Parameters:
m -

getMadkitProperty
```
public final String getMadkitProperty(String key)
```
Gets the MaDKit session property indicated by the specified key. This call is equivalent to getMadkitConfig().getProperty(key)

Parameters:
key - the name of the MaDKit property

Returns:
the string value of the MaDKit property, or null if there is no property with that key.
See Also:
setMadkitProperty(String, String), Madkit

getMadkitProperty
```
public <E extends Enum<E>> String getMadkitProperty(E option)
```
Shortcut for getMadkitProperty(option.name()). Runtime options could be represented using enumeration constants, as it is the case for MaDKit's, so this is a convenient method for retrieving the value of an option.

Parameters:
option - the constant representing a MaDKit option

Returns:
the corresponding value as a String, or null if there is no property having the corresponding name.
Since:

MaDKit 5.0.3

See Also:
LevelOption BooleanOption

setMadkitProperty
```
public void setMadkitProperty(String key,
                     String value)
```
Set the MaDKit session property indicated by the specified key.

Parameters:
key - the name of the MaDKit property
See Also:
getMadkitProperty(String), Madkit

setMadkitProperty
```
public <E extends Enum<E>> void setMadkitProperty(E option,
                                         String value)
```
Set the MaDKit session property indicated by the specified constant representing a MaDKit option.

Parameters:
option - the constant representing a MaDKit option
See Also:
getMadkitProperty(String), Madkit

isMadkitPropertyTrue
```
public <E extends Enum<E>> boolean isMadkitPropertyTrue(E option)
```
Shortcut for Boolean.parseBoolean(getMadkitProperty(option))

Parameters:
option - the constant representing a runtime option

Returns:
true if the option has been set to true
Since:

MadKit 5.0.3

setupFrame
```
public void setupFrame(JFrame frame)
```
Called when the default GUI mechanism is used upon agent creation. This provides an empty frame which will be used as GUI for the agent. The life cycle of the frame is automatically managed: the frame is disposed when the agent is terminated. Some menus are available by default. Default code is only one line: frame.add(new IOPanel(this));. Default settings for the frame are:
- width = 400
- height = 300
- location = center of the screen
- a JMenuBar with: MadkitMenu, AgentMenu and AgentLogLevelMenu
Parameters:
frame - the default frame which has been created by MaDKit for this agent.
Since:

MaDKit 5.0.0.8

See Also:
OutputPanel

getOrganizationSnapShot

public Map<String,Map<String,Map<String,Set<AgentAddress>>>> getOrganizationSnapShot(boolean global)

getExistingCommunities
```
public TreeSet<String> getExistingCommunities()
```
returns the names of the communities that exist.

Returns:
an alphanumerically ordered set containing the names of the communities which exist.
Since:

MaDKit 5.0.0.20

getExistingGroups
```
public TreeSet<String> getExistingGroups(String community)
```
returns the names of the groups that exist in this community.

Parameters:
community - the community's name

Returns:
an alphanumerically ordered set containing the names of the groups which exist in this community, or null if this community does not exist.
Since:

MaDKit 5.0.0.20

getMyGroups
```
public TreeSet<String> getMyGroups(String community)
```
Gets the names of the groups the agent is in according to a community

Parameters:
community -

Returns:
a set containing the names of the groups the agent is in, or null if this community does not exist. This set could be empty.

getMyRoles
```
public TreeSet<String> getMyRoles(String community,
                         String group)
```
Gets the names of the roles that the agent has in a specific group

Parameters:
community -
group -

Returns:
a sorted set containing the names of the roles the agent has in a group, or null if the community or the group does not exist. This set could be empty.

getExistingRoles
```
public TreeSet<String> getExistingRoles(String community,
                               String group)
```
returns the names of the roles that exist in this group.

Parameters:
community - the community's name
group - the group's name

Returns:
an alphanumerically ordered set containing the names of the roles which exist in this group, or null if it does not exist.
Since:

MaDKit 5.0.0.20

checkAgentAddress
```
public boolean checkAgentAddress(AgentAddress agentAddress)
```
Checks if this agent address is still valid. I.e. the corresponding agent is still playing this role.

Returns:
true if the address still exists in the organization.
Since:

MaDKit 5.0.4

isCommunity
```
public boolean isCommunity(String community)
```
Tells if a community exists in the artificial society.

Parameters:
community - the name of the community

Returns:
true If a community with this name exists, false otherwise.

isGroup
```
public boolean isGroup(String community,
              String group)
```
Tells if a group exists in the artificial society.

Parameters:
community - the name of the community the group is in
group - the name of the group

Returns:
true If a group with this name exists in this community, false otherwise.

hasRole
```
public boolean hasRole(String community,
              String group,
              String role)
```
Tells if the agent is currently playing a specific role.

Parameters:
community -
group -
role -

Returns:
true if the agent is playing this role
Since:

MaDKit 5.0.3

isRole
```
public boolean isRole(String community,
             String group,
             String role)
```
Tells if a role exists in the artificial society.

Parameters:
community - the name of the community the group is in
group - the name of the group
role - the name of the role

Returns:
true If a role with this name exists in this couple, false otherwise.

toString
```
public String toString()
```
Overrides:

toString in class Object

Returns:
a String giving the name and the current state of the agent

getMadkitConfig

public MadkitProperties getMadkitConfig()

Returns the Properties object of this MaDKit session. That is by default the parameter which has been used to launch the kernel the agent is running on. If the agent has not been launched yet, the Properties returned is the default MaDKit configuration. It can be programmatically modified to launch a new session with different parameters. It can also be used as a black board shared by all the agents of a kernel by adding new user defined properties at run time or via the command line. The default set of MaDKit properties includes values for the following keys:

Key	Description of Associated Value
`madkit.version`	MaDKit kernel version
`build.id`	MaDKit kernel build ID
`madkit.repository.url`	the agent repository for this version, usually http://www.madkit.net/repository/MaDKit-version
`desktop`	`true` or `false`: Launch the desktop during boot phase
`launchAgents`	The agents launched during the boot phase
`createLogFiles`	true or `false`: Create log files automatically for the new agents
`logDirectory`	The directory used for the log files (./logs by default)
`agentLogLevel`	the default log level for the new agents
`warningLogLevel`	the default warning log level for the new agents
`network`	`true` or `false`: Launch the network during boot phase

Returns:: the Properties object defining the values of each MaDKit options in the current session.
Since:: MaDKit 5.0.0.10
See Also:: LevelOption BooleanOption

getKernelAddress
```
public KernelAddress getKernelAddress()
```
Returns the kernel address on which the agent is running.

Returns:
the kernel address representing the MaDKit kernel on which the agent is running

getServerInfo
```
public String getServerInfo()
```
Returns the server's info, IP and port, if the kernel is online.

Returns:
server's info: e.g. /192.168.1.14:4444

destroyCommunity
```
public void destroyCommunity(String community)
```
Wipes out an entire community at once. Mostly useful when doing simulated systems. This greatly optimizes the time required to make all the agents leave a community.

Parameters:
community - the community to destroy
Since:

MaDKit 5.0.0.9

destroyGroup
```
public void destroyGroup(String community,
                String group)
```
Wipes out an entire group at once. Mostly useful when doing simulated systems. This greatly optimizes the time required to make all the agents leave a group.

Parameters:
community - the community
group - the group to destroy
Since:

MaDKit 5.0.0.10

destroyRole
```
public void destroyRole(String community,
               String group,
               String role)
```
Wipes out an entire role at once. Mostly useful when doing simulated systems. This greatly optimizes the time required to make all the agents leave a role.

Parameters:
community - the community
group - the group
role - the group to destroy
Since:

MaDKit 5.0.0.10

launchXmlAgents

public AbstractAgent.ReturnCode launchXmlAgents(String xmlFile)
                                         throws SAXException,
                                                IOException,
                                                ParserConfigurationException

launch all the agents defined in an xml configuration file

Parameters:: xmlFile - the XML file to parse
Returns:: AbstractAgent.ReturnCode.SEVERE if the launch failed
Throws:: ParserConfigurationException; IOException; SAXException

launchNode
```
public AbstractAgent.ReturnCode launchNode(Node agentXmlNode)
```
Launch agents by parsing an XML node. The method immediately returns without waiting the end of the agents' activation,

Parameters:
agentXmlNode - the XML node

Returns:
AbstractAgent.ReturnCode.SEVERE if the launch failed
See Also:
XMLUtilities

getState
```
public AbstractAgent.State getState()
```
Returns the current state of the agent in the MaDKit platform. This method provides a way of knowing what is the current state of the agent regarding its life cycle. This could be convenient when you design a method that could work differently depending on the actual state of the agent.
Returns:
the current state of the agent:
- AbstractAgent.State.NOT_LAUNCHED: the agent has not been launched yet. This especially means that most of the methods of this API still do not work for this agent as it has not been registered yet.
- AbstractAgent.State.INITIALIZING: the agent is being registered by the kernel but has not started its activate() method yet.
- AbstractAgent.State.ACTIVATED: the agent is processing its activate() method. This state is also the "running" state of AbstractAgent subclasses (i.e. when they have finished their activation) as they do not have a Agent.live() managed by the kernel in their life cycle. On the contrary to Agent subclasses which next state is AbstractAgent.State.LIVING.
- AbstractAgent.State.LIVING: returned when Agent subclasses are processing their Agent.live() method.
- AbstractAgent.State.ENDING: the agent is processing its end() method.
- AbstractAgent.State.TERMINATED: the agent has finished its life in the MaDKit platform. Especially, most of the methods of this API will no longer work for this agent.

reload
```
public void reload()
```
Kills the caller and launches a new instance of this agent using the latest byte code available for the corresponding class.

proceedEnumMessage
```
public <E extends Enum<E>> void proceedEnumMessage(EnumMessage<E> message)
```
Proceeds an EnumMessage so that if it is correctly built, the agent will trigger its corresponding behavior using the parameters of the message.

Parameters:
message - the message to proceed
Since:

MaDKit 5.0.0.14

See Also:
EnumMessage

isKernelOnline
```
public boolean isKernelOnline()
```
Tells if the kernel on which this agent is running is online.

Returns:
true if the kernel is online.

executeThisAgent
```
protected static void executeThisAgent(int nbOfInstances,
                    boolean createFrame,
                    String... args)
```
This offers a convenient way to create main a main method that launches the agent class under development. The agent is launched in a new instance MaDKit. This call only works in the main method of the agent. MaDKit. Here is an example of use that will work in any subclass of AbstractAgent:
```
 
 public static void main(String[] args) {
        executeThisAgent(args);
 }
 
 
```
Still, the agent must have a default constructor for that to work.
Parameters:
nbOfInstances - specify how many of this kind should be launched
createFrame -
args - MaDKit options. For example, this will launch the agent in desktop mode :
```
 
 public static void main(String[] args) {
        executeThisAgent(BooleanOption.desktop.toString());
 }
 
 
```
Since:

MaDKit 5.0.0.14

See Also:
BooleanOption LevelOption

executeThisAgent
```
protected static void executeThisAgent(String... args)
```
This offers a convenient way to create a main method that launches the agent class under development. This call only works in the main method of the agent. This call is equivalent to executeThisAgent(1, true, args)

Parameters:
args - MaDKit options
Since:

MaDKit 5.0.0.14

See Also:
executeThisAgent(int, boolean, String...)

executeThisAgent
```
protected static void executeThisAgent()
```
This offers a convenient way to create a main method that launches the agent class under development. This call only works in the main method of the agent. This call is equivalent to executeThisAgent(null, 1, true)

Since:

MaDKit 5.0.0.15

See Also:
executeThisAgent(int, boolean, String...)

Class AbstractAgent

MaDKit v.5 new features

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

logger

Constructor Detail

AbstractAgent

Method Detail

createGUIOnStartUp

hasGUI

hashCode

getNetworkID

getSimpleNetworkID

isAlive

activate

end

launchAgent

launchAgent

launchAgent

launchAgent

launchAgent

launchAgent

launchAgent

launchAgent

launchAgentBucket

launchAgentBucket

launchAgentBucket

launchAgentBucket

killAgent

killAgent

getName

setName

setLogLevel

getLogger

compareTo

createGroup

createGroup

createGroup

bucketModeCreateGroup

createGroupIfAbsent

createGroupIfAbsent

createGroupIfAbsent

leaveGroup

requestRole

requestRole

bucketModeRequestRole

leaveRole

getAgentAddressIn

getAgentWithRole

getDistantAgentWithRole

getAgentsWithRole

getAgentsWithRole

nextMessage

nextMessage

nextMessages

purgeMailbox

isMessageBoxEmpty

sendMessage

sendMessageWithRole

sendMessage

sendMessageWithRole

broadcastMessage

broadcastMessageWithRole

sendReplyWithRole

sendReply

getReplyTo

receiveMessage

getMadkitProperty

getMadkitProperty

setMadkitProperty

setMadkitProperty

isMadkitPropertyTrue

setupFrame

getOrganizationSnapShot

getExistingCommunities

getExistingGroups