Class AbstractAgent
- All Implemented Interfaces:
Comparable<AbstractAgent>
- Direct Known Subclasses:
AbstractModel
,Agent
,ConsoleAgent
,Watcher
- 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. SeesendMessageWithRole(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 ( forAgent
subclasses only as they are threaded) SeesendReply(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
getLogger()
method for more details.
- Version:
- 5.8
- Author:
- Fabien Michel, Olivier Gutknecht
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic enum
This class enumerates all the return codes which could be obtained with essential methods of theAbstractAgent
andAgent
classes.static enum
An agent state. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprotected void
activate()
This method corresponds to the first behavior which is called by the MaDKit kernel when an agent is launched.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.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.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 thelaunchAgentBucket
methods.bucketModeRequestRole
(String community, String group, String role, Object passKey) Requests a role even if the agent has been launched using one of thelaunchAgentBucket
methods with nonull
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.createGroup
(String community, String group) Creates a new Group within a community.createGroup
(String community, String group, boolean isDistributed) Creates a new Group within a community.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
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 Madkit
This offers a convenient way to create a main method that launches the agent class under development.protected static Madkit
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 Madkit
executeThisAgent
(String... args) This offers a convenient way to create a main method that launches the agent class under development.getAgentAddressIn
(String community, String group, String role) Agent's address at this CGR location.getAgentsWithRole
(String community, String group, String role) A list containing other agents playing this role in the organization.getAgentsWithRole
(String community, String group, String role, boolean callerIncluded) A list containing all the agents playing this role in the organization.getAgentWithRole
(String community, String group, String role) Returns anAgentAddress
corresponding to an agent having this position in the organization.getDistantAgentWithRole
(String community, String group, String role, KernelAddress from) AgentAddress
corresponding to an agent having this position in the organization on a particular kernel.Returns the names of the communities that exist.getExistingGroups
(String community) Returns the names of the groups that exist in this community.getExistingRoles
(String community, String group) Returns the names of the roles that exist in this group.The kernel's address on which this agent is running.Gets the last received message.getLastReceivedMessage
(MessageFilter filter) Gets the last received message according to a filter.Returns the agent's logger.Returns the Properties object of this MaDKit session.getMadkitProperty
(E option) Shortcut forgetMadkitProperty(option.name())
.final String
getMadkitProperty
(String key) Gets the MaDKit session property indicated by the specified key.getMyGroups
(String community) Gets the names of the groups the agent is in according to a communitygetMyRoles
(String community, String group) Gets the names of the roles that the agent has in a specific groupgetName()
The agent's name.final String
Return a string representing a unique identifier for the agent over the network.Method which is used by discrete-event simulation activators for doing fine-grained simulations.getOrganizationSnapShot
(boolean global) Returns a snapshot view of all the current organization for debugging purpose.getReplyTo
(Message originalMessage) Gets the next message which is a reply to the originalMessage.Returns the server's info, IP and port, if the kernel is online.final String
Return a string representing a shorter version of the unique identifier of the agent over the network.Returns theScheduler.SimulationTime
of the current simulation.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 kernelfinal int
hashCode()
The ID of an agent.boolean
Tells if the agent is currently playing a specific role.boolean
isAlive()
Returnstrue
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
Tells if a group exists in the artificial society.boolean
Tells if the kernel on which this agent is running is online.<E extends Enum<E>>
booleanisMadkitPropertyTrue
(E option) Shortcut forBoolean.parseBoolean(getMadkitProperty(option))
boolean
Tells if there is a message in the mailboxboolean
Tells if a role exists in the artificial society.killAgent
(AbstractAgent target) Kills the targeted agent.killAgent
(AbstractAgent target, int timeOutSeconds) Kills the targeted agent.launchAgent
(String agentClass) Launches a new agent using its full class name.launchAgent
(String agentClass, boolean createFrame) Launches a new agent using its full class name.launchAgent
(String agentClass, int timeOutSeconds) Launches a new agent using its full class name.launchAgent
(String agentClass, int timeOutSeconds, boolean createFrame) Launches a new agent using its full class name and returns when the launched agent has completed itsactivate()
method or when the time out is elapsed.launchAgent
(AbstractAgent agent) Launches a new agent in the MaDKit platform.launchAgent
(AbstractAgent agent, boolean createFrame) Launches a new agent in the MaDKit platform.launchAgent
(AbstractAgent agent, int timeOutSeconds) Launches a new agent in the MaDKit platform.launchAgent
(AbstractAgent agent, int timeOutSeconds, boolean createFrame) Launches a new agent and returns when the agent has completed itsactivate()
method or whentimeOutSeconds
seconds elapsed.launchAgentBucket
(String agentClass, int bucketSize, int cpuCoreNb, String... roles) Optimizes mass agent launching.launchAgentBucket
(String agentClass, int bucketSize, String... roles) This has the same effect aslaunchAgentBucket(agentClass, bucketSize, 1, roles)
.void
launchAgentBucket
(List<? extends AbstractAgent> bucket, int nbOfParallelTasks, String... roles) Similar tolaunchAgentBucket(String, int, String...)
except that the list of agents to launch is given.void
launchAgentBucket
(List<? extends AbstractAgent> bucket, String... roles) This call is equivalent to This has the same effect aslaunchAgentBucket(bucket, 1, roles)
, That is only one core will be used for the launch.launchNode
(Node agentXmlNode) Launch agents by parsing an XML node.launchXmlAgents
(String xmlFile) launch all the agents defined in an xml configuration fileleaveGroup
(String community, String group) Makes this agent leaves the group of a particular community.Abandons an handled role within a group of a particular community.Retrieves and removes the oldest received message contained in the mailbox.nextMessage
(MessageFilter filter) Retrieves and removes the first oldest message of the mailbox that matches the filter.nextMessages
(MessageFilter filter) Retrieves and removes all the messages of the mailbox that match the filter, in the order they were received.<E extends Enum<E>>
voidproceedEnumMessage
(EnumMessage<E> message) Proceeds anEnumMessage
so that if it is correctly built, the agent will trigger its corresponding behavior using the parameters of the message.Purges the mailbox and returns the most recent received message at that time.void
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.requestRole
(String community, String group, String role) Requests a role within a group of a particular community.requestRole
(String community, String group, String role, Object passKey) Requests a role within a group of a particular community using a passKey.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.sendMessage
(AgentAddress receiver, Message messageToSend) Sends a message to an agent using an agent address.sendMessageWithRole
(String community, String group, String role, Message message, String senderRole) Sends a message to an agent having this position in the organization.sendMessageWithRole
(AgentAddress receiver, Message message, String senderRole) Sends a message, using an agent address, specifying explicitly the role used to send it.Sends a message by replying to a previously received message.sendReplyWithRole
(Message messageToReplyTo, Message reply, String senderRole) Sends a message by replying to a previously received message.void
setLogLevel
(Level newLevel) Deprecated.<E extends Enum<E>>
voidsetMadkitProperty
(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
Changes the agent's namevoid
setupFrame
(AgentFrame frame) Called when the default GUI mechanism is used upon agent creation.toString()
-
Constructor Details
-
AbstractAgent
public AbstractAgent()
-
-
Method Details
-
getSimulationTime
Returns theScheduler.SimulationTime
of the current simulation. This is automatically initialized when the agent is associated with an activator for the first time. So it staysnull
if the agent is not related to a simulation- Returns:
- the simulationTime of the simulation in which the agent participates
-
getNextEventDate
Method which is used by discrete-event simulation activators for doing fine-grained simulations. By default, this method returns an event which is one second ahead of the current date of the simulation. So, this method can be overridden to fulfil the simulation requirement- Returns:
- the date of the next event for this agent.
- See Also:
-
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. -
getNetworkID
Return a string representing a unique identifier for the agent over the network.- Returns:
- the agent's network identifier
-
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:
-
isAlive
public boolean isAlive()Returnstrue
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
Launches a new agent in the MaDKit platform. This has the same effect aslaunchAgent(agent,Integer.MAX_VALUE,false)
- Parameters:
agent
- the agent to launch.- Returns:
AbstractAgent.ReturnCode.SUCCESS
activate
methodAbstractAgent.ReturnCode.ALREADY_LAUNCHED
AbstractAgent.ReturnCode.TIMEOUT
AbstractAgent.ReturnCode.AGENT_CRASH
activate
method
- Since:
- MaDKit 5.0
- See Also:
-
launchAgent
Launches a new agent in the MaDKit platform. This has the same effect aslaunchAgent(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
activate
methodAbstractAgent.ReturnCode.ALREADY_LAUNCHED
AbstractAgent.ReturnCode.TIMEOUT
timeOutSeconds
seconds
: If the agent crashed during itsAbstractAgent.ReturnCode.AGENT_CRASH
activate
method
-
launchAgent
Launches a new agent in the MaDKit platform. This has the same effect aslaunchAgent(agent,Integer.MAX_VALUE,withGUIManagedByTheBooter)
- Parameters:
agent
- the agent to launch.createFrame
- iftrue
, the kernel will launch a JFrame for this agent.- Returns:
AbstractAgent.ReturnCode.SUCCESS
activate
methodAbstractAgent.ReturnCode.ALREADY_LAUNCHED
AbstractAgent.ReturnCode.TIMEOUT
AbstractAgent.ReturnCode.AGENT_CRASH
activate
method
- Since:
- MaDKit 5.0
- See Also:
-
launchAgent
public AbstractAgent.ReturnCode launchAgent(AbstractAgent agent, int timeOutSeconds, boolean createFrame) Launches a new agent and returns when the agent has completed itsactivate()
method or whentimeOutSeconds
seconds elapsed. That is, the launched agent has not finished itsactivate()
before the time out time elapsed. Additionally, ifcreateFrame
istrue
, 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(AgentFrame)
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
- iftrue
, the kernel will launch a JFrame for this agent.- Returns:
AbstractAgent.ReturnCode.SUCCESS
activate
methodAbstractAgent.ReturnCode.ALREADY_LAUNCHED
AbstractAgent.ReturnCode.TIMEOUT
timeOutSeconds
secondsAbstractAgent.ReturnCode.AGENT_CRASH
activate
method
- Since:
- MaDKit 5.0
- 1. the agent overrides the method
-
launchAgent
Launches a new agent using its full class name.
This has the same effect aslaunchAgent(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
Launches a new agent using its full class name.
This has the same effect aslaunchAgent(agentClass, timeOutSeconds, false)
.- Parameters:
timeOutSeconds
- time to wait the end of the agent's activation until returningnull
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
Launches a new agent using its full class name.
This has the same effect aslaunchAgent(agentClass, Integer.MAX_VALUE, defaultGUI)
.- Parameters:
createFrame
- iftrue
a default GUI will be associated with the launched agentagentClass
- 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
Launches a new agent using its full class name and returns when the launched agent has completed itsactivate()
method or when the time out is elapsed. This has the same effect aslaunchAgent(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 usingMadkitClassLoader.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 returningnull
createFrame
- iftrue
a default GUI will be associated with the launched agentagentClass
- 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. LaunchesbucketSize
instances ofagentClassName
(an agent class) and put them in the artificial society at the locations defined bycgrLocations
. Each string of thecgrLocations
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 theiractivate()
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 inactivate()
, 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 andactivate()
methods will be called simultaneously so that one has to be careful if shared resources are accessed by the agentsroles
- default locations in the artificial society for the launched agents. Each string of thecgrLocations
array defines a complete CGR location by separating C, G and R with commas as follows:"community,group,role"
. It can benull
.- 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
This has the same effect aslaunchAgentBucket(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 thecgrLocations
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
This call is equivalent to This has the same effect aslaunchAgentBucket(bucket, 1, roles)
, That is only one core will be used for the launch.- Parameters:
bucket
- the list of agents to launchroles
- default locations in the artificial society for the launched agents. Each string of thecgrLocations
array defines a complete CGR location by separating C, G and R with commas as follows:"community,group,role"
. It can benull
-
launchAgentBucket
public void launchAgentBucket(List<? extends AbstractAgent> bucket, int nbOfParallelTasks, String... roles) Similar tolaunchAgentBucket(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 launchnbOfParallelTasks
- the number of parallel tasks to use for launching the agents. Beware that ifnbOfParallelTasks
is greater than 1, the agents'activate()
methods will be called simultaneously so that one has to be careful if shared resources are accessedroles
- default locations in the artificial society for the launched agents. Each string of thecgrLocations
array defines a complete CGR location by separating C, G and R with commas as follows:"community,group,role"
. It can benull
-
killAgent
Kills the targeted agent. This has the same effect askillAgent(target,Integer.MAX_VALUE)
so that the targeted agent has a lot of time to complete itsend()
method.- Returns:
: If the target's end method has completed normally.AbstractAgent.ReturnCode.SUCCESS
: If the target has been already killed.AbstractAgent.ReturnCode.ALREADY_KILLED
: If the target has not been launched.AbstractAgent.ReturnCode.NOT_YET_LAUNCHED
: If the target's end method took more than 2e31 seconds and has been brutally stopped: This unlikely happens ;).AbstractAgent.ReturnCode.TIMEOUT
- Since:
- MaDKit 5.0
- See Also:
-
killAgent
Kills the targeted agent. The kill process stops the agent's life cycle but allows it to process itsend()
method until the time out elapsed.If the target is in the activate or live method (Agent subclasses), it will be brutally stop and then proceed its end method.
The method returns only when the targeted agent actually ends its life. So if the target contains a infinite loop, the caller can be blocked. Using a timeout thus ensures that the caller will be blocked only a certain amount of time. Using 0 as timeout will stop the target as soon as possible, eventually brutally stop its life cycle. In such a case, if its end method has not been started, it will never run.
- Returns:
: If the target's end method has completed normally.AbstractAgent.ReturnCode.SUCCESS
AbstractAgent.ReturnCode.ALREADY_KILLED
: If the target has not been launched.AbstractAgent.ReturnCode.NOT_YET_LAUNCHED
AbstractAgent.ReturnCode.TIMEOUT
- Since:
- MaDKit 5.0
-
getName
The agent's name.- Returns:
- the name to display in logger info, GUI title and so on. Default is "class name + internal ID"
-
setName
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
Deprecated.as of MaDKit 5.2,AgentLogger.setLevel(Level)
should now be used throughgetLogger()
Sets the agent's log level. This should be used instead of directlyAgentLogger.setLevel(Level)
because this also works whenlogger
isnull
and allows to set it tonull
to save cpu time.- Parameters:
newLevel
- The log level under which log messages are displayed. IfLevel.OFF
is used thenlogger
is set tonull
- See Also:
-
logger
-
getLogger
Returns the agent's logger. It is lazily created so that ifgetLogger()
is not used, there is no memory foot print at all, which could be crucial when working with thousands of abstract agents in simulation mode.- Returns:
- the agent's logger.
- Since:
- MaDKit 5.0.0.6
- See Also:
-
compareTo
Compares this agent with the specified agent for order with respect to instantiation time.- Specified by:
compareTo
in interfaceComparable<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.
-
createGroup
Creates a new Group within a community. This has the same effect ascreateGroup(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:
: If the group has been successfully created.AbstractAgent.ReturnCode.SUCCESS
: If the operation failed because such a group already exists.AbstractAgent.ReturnCode.ALREADY_GROUP
AbstractAgent.ReturnCode.IGNORED
launchAgentBucket(List, String...)
with nonnull
roles
- Since:
- MaDKit 5.0
- See Also:
-
createGroup
Creates a new Group within a community. This has the same effect ascreateGroup(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
- iftrue
the new group will be distributed when multiple MaDKit kernels are connected.- Returns:
: If the group has been successfully created.AbstractAgent.ReturnCode.SUCCESS
: If the operation failed because such a group already exists.AbstractAgent.ReturnCode.ALREADY_GROUP
AbstractAgent.ReturnCode.IGNORED
launchAgentBucket(List, String...)
with nonnull
roles
- Since:
- MaDKit 5.0
- See Also:
-
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
DefaultMaDKitRoles.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
DefaultMaDKitRoles.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
- iftrue
the new group will be distributed when multiple MaDKit kernels are connected.keyMaster
- any object that implements theGatekeeper
interface. If notnull
, 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:
: If the group has been successfully created.AbstractAgent.ReturnCode.SUCCESS
AbstractAgent.ReturnCode.ALREADY_GROUP
: If the agent has been launched using aAbstractAgent.ReturnCode.IGNORED
launchAgentBucket
method such aslaunchAgentBucket(List, String...)
with nonnull
roles. This for optimization purposes.
- Since:
- MaDKit 5.0
- See Also:
-
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 thelaunchAgentBucket
methods. This method is only useful when called within theactivate()
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
- iftrue
the new group will be distributed when multiple MaDKit kernels are connected.keyMaster
- any object that implements theGatekeeper
interface. If notnull
, 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:
: If the group has been successfully created.AbstractAgent.ReturnCode.SUCCESS
AbstractAgent.ReturnCode.ALREADY_GROUP
- Since:
- MaDKit 5.0.2
- See Also:
-
-
createGroupIfAbsent
Creates a new Group within a community but does not produce any warning if the group already exists. This has the same effect ascreateGroupIfAbsent(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
Creates a new Group within a community but does not produce any warning if the group already exists. This has the same effect ascreateGroupIfAbsent(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 groupisDistributed
- iftrue
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
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 groupisDistributed
- iftrue
the new group will be distributed when multiple MaDKit kernels are connected.keyMaster
- any object that implements theGatekeeper
interface. If notnull
, 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:
-
leaveGroup
Makes this agent leaves the group of a particular community.- Parameters:
community
- the community namegroup
- the group name- Returns:
: If the operation has succeeded.AbstractAgent.ReturnCode.SUCCESS
: If the community does not exist.AbstractAgent.ReturnCode.NOT_COMMUNITY
: If the group does not exist.AbstractAgent.ReturnCode.NOT_GROUP
: If this agent is not a member of this group.AbstractAgent.ReturnCode.NOT_IN_GROUP
- Since:
- MaDKit 5.0
- See Also:
-
requestRole
Requests a role within a group of a particular community. This has the same effect asrequestRole(community, group, role, null, false)
. So the passKey isnull
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
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
- thepassKey
to enter a secured group. It is generally delivered by the group's group manager. It could benull
, which is sufficient to enter an unsecured group. Especially,requestRole(String, String, String)
uses anull
passKey
.- Returns:
: If the operation has succeeded.AbstractAgent.ReturnCode.SUCCESS
: If the community does not exist.AbstractAgent.ReturnCode.NOT_COMMUNITY
: If the group does not exist.AbstractAgent.ReturnCode.NOT_GROUP
: If this role is already handled by this agent.AbstractAgent.ReturnCode.ROLE_ALREADY_HANDLED
: If the access denied by the manager of that secured group.AbstractAgent.ReturnCode.ACCESS_DENIED
: If the agent has been launched using aAbstractAgent.ReturnCode.IGNORED
launchAgentBucket
method such aslaunchAgentBucket(List, String...)
with nonnull
roles. This for optimization purposes.
- Since:
- MaDKit 5.0
- See Also:
-
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 thelaunchAgentBucket
methods with nonull
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 oflaunchAgentBucket(List, int, String...)
because they are priorly unknown and built at runtime.- Parameters:
community
- the group's community.group
- the targeted group.role
- the desired role.passKey
- thepassKey
to enter a secured group. It is generally delivered by the group's group manager. It could benull
, which is sufficient to enter an unsecured group. Especially,requestRole(String, String, String)
uses anull
passKey
.- Returns:
: If the operation has succeeded.AbstractAgent.ReturnCode.SUCCESS
: If the community does not exist.AbstractAgent.ReturnCode.NOT_COMMUNITY
: If the group does not exist.AbstractAgent.ReturnCode.NOT_GROUP
: If this role is already handled by this agent.AbstractAgent.ReturnCode.ROLE_ALREADY_HANDLED
: If the access denied by the manager of that secured group.AbstractAgent.ReturnCode.ACCESS_DENIED
leaveRole
- Parameters:
community
- the community namegroup
- the group namerole
- the role name- Returns:
: If the operation has succeeded.AbstractAgent.ReturnCode.SUCCESS
: If the community does not exist.AbstractAgent.ReturnCode.NOT_COMMUNITY
: If the group does not exist.AbstractAgent.ReturnCode.NOT_GROUP
: If this role is not handled by this agent.AbstractAgent.ReturnCode.ROLE_NOT_HANDLED
- Since:
- MaDKit 5.0
- See Also:
getAgentAddressIn
- 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
AgentAddress
corresponding to an agent having this
position in the organization. The caller is excluded from the search.- Parameters:
community
- the community namegroup
- the group namerole
- the role name- Returns:
- an
AgentAddress
corresponding to an agent handling this role ornull
if such an agent does not exist.
getDistantAgentWithRole
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 namegroup
- the group namerole
- the role namefrom
- the kernel address on which the agent is running- Returns:
- an
AgentAddress
corresponding to an agent handling this role on the targeted kernel ornull
if such an agent does not exist.
getAgentsWithRole
- Parameters:
community
- the community namegroup
- the group namerole
- the role name- Returns:
- a
List
containing agents that handle this role ornull
if no agent has been found.
getAgentsWithRole
- Parameters:
community
- the community namegroup
- the group namerole
- the role namecallerIncluded
- iffalse
, the caller is removed from the list if it is in.- Returns:
- a
List
containing agents that handle this role ornull
if no agent has been found.
nextMessage
- Returns:
- The next message or
null
if the message box is empty.
nextMessage
- Returns:
- The next acceptable message or
null
if such message has not been found.
nextMessages
- Parameters:
filter
- ifnull
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.
getLastReceivedMessage
- Returns:
- the last received message or
null
if the mailbox is empty.
getLastReceivedMessage
- Parameters:
filter
- the message filter to use- Returns:
- the last received message that matches the filter or
null
if such message has not been found.
purgeMailbox
- Returns:
- the most recent received message or
null
if the mailbox is already empty.
isMessageBoxEmpty
- Returns:
true
if there is no message in the mailbox.
sendMessage
sendMessageWithRole(receiver, messageToSend, null)
.- Parameters:
receiver
-messageToSend
-- Returns:
: If the send has succeeded.AbstractAgent.ReturnCode.SUCCESS
: If this agent is not a member of the receiver's group.AbstractAgent.ReturnCode.NOT_IN_GROUP
: 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.AbstractAgent.ReturnCode.INVALID_AGENT_ADDRESS
- See Also:
sendMessageWithRole
- Parameters:
receiver
- the targeted agentmessage
- the message to send- Returns:
: If the send has succeeded.AbstractAgent.ReturnCode.SUCCESS
: If this agent is not a member of the receiver's group.AbstractAgent.ReturnCode.NOT_IN_GROUP
: IfAbstractAgent.ReturnCode.ROLE_NOT_HANDLED
senderRole
is not handled by this agent.
: 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.AbstractAgent.ReturnCode.INVALID_AGENT_ADDRESS
- See Also:
sendMessage
- Parameters:
community
- the community namegroup
- the group namerole
- the role namemessage
- the message to send- Returns:
: If the send has succeeded.AbstractAgent.ReturnCode.SUCCESS
: If the community does not exist.AbstractAgent.ReturnCode.NOT_COMMUNITY
: If the group does not exist.AbstractAgent.ReturnCode.NOT_GROUP
: If the role does not exist.AbstractAgent.ReturnCode.NOT_ROLE
: If this agent is not a member of the targeted group.AbstractAgent.ReturnCode.NOT_IN_GROUP
: If no agent was found as recipient, i.e. the sender was the only agent having this role.AbstractAgent.ReturnCode.NO_RECIPIENT_FOUND
- See Also:
sendMessageWithRole
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 namegroup
- the group namerole
- the role namemessage
- the message to sendsenderRole
- the agent's role with which the message has to be sent- Returns:
: If the send has succeeded.AbstractAgent.ReturnCode.SUCCESS
: If the community does not exist.AbstractAgent.ReturnCode.NOT_COMMUNITY
: If the group does not exist.AbstractAgent.ReturnCode.NOT_GROUP
: If the role does not exist.AbstractAgent.ReturnCode.NOT_ROLE
: IfAbstractAgent.ReturnCode.ROLE_NOT_HANDLED
senderRole
is not handled by this agent.
: If this agent is not a member of the targeted group.AbstractAgent.ReturnCode.NOT_IN_GROUP
: If no agent was found as recipient, i.e. the sender was the only agent having this role.AbstractAgent.ReturnCode.NO_RECIPIENT_FOUND
- See Also:
broadcastMessage
- Parameters:
community
- the community namegroup
- the group namerole
- the role namemessage
-- Returns:
: If the send has succeeded.AbstractAgent.ReturnCode.SUCCESS
: If the community does not exist.AbstractAgent.ReturnCode.NOT_COMMUNITY
: If the group does not exist.AbstractAgent.ReturnCode.NOT_GROUP
: If the role does not exist.AbstractAgent.ReturnCode.NOT_ROLE
: If no agent was found as recipient, i.e. the sender was the only agent having this role.AbstractAgent.ReturnCode.NO_RECIPIENT_FOUND
: If this agent is not a member of the targeted group.AbstractAgent.ReturnCode.NOT_IN_GROUP
- See Also:
broadcastMessageWithRole
- Parameters:
community
- the community namegroup
- the group namerole
- the role namemessageToSend
-senderRole
- the agent's role with which the message should be sent- Returns:
: If the send has succeeded.AbstractAgent.ReturnCode.SUCCESS
: If the community does not exist.AbstractAgent.ReturnCode.NOT_COMMUNITY
: If the group does not exist.AbstractAgent.ReturnCode.NOT_GROUP
: If the role does not exist.AbstractAgent.ReturnCode.NOT_ROLE
: If this agent is not a member of the targeted group.AbstractAgent.ReturnCode.NOT_IN_GROUP
: If no agent was found as recipient, i.e. the sender was the only agent having this role.AbstractAgent.ReturnCode.NO_RECIPIENT_FOUND
- See Also:
sendReplyWithRole
- Parameters:
messageToReplyTo
- the previously received message.reply
- the reply itself.senderRole
- the agent's role with which the message should be sent- Returns:
: If the send has succeeded.AbstractAgent.ReturnCode.SUCCESS
: If this agent is no longer a member of the corresponding group.AbstractAgent.ReturnCode.NOT_IN_GROUP
: IfAbstractAgent.ReturnCode.ROLE_NOT_HANDLED
senderRole
is not handled by this agent.
: 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.AbstractAgent.ReturnCode.INVALID_AGENT_ADDRESS
- See Also:
sendReply
sendReplyWithRole(messageToReplyTo, reply, null)
.- Parameters:
messageToReplyTo
- the previously received message.reply
- the reply itself.- Returns:
: If the reply has succeeded.AbstractAgent.ReturnCode.SUCCESS
: If this agent is no longer a member of the corresponding group.AbstractAgent.ReturnCode.NOT_IN_GROUP
: 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.AbstractAgent.ReturnCode.INVALID_AGENT_ADDRESS
- See Also:
getReplyTo
- 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
- Parameters:
m
-
getMadkitProperty
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:
getMadkitProperty
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:
setMadkitProperty
- Parameters:
key
- the name of the MaDKit property- See Also:
setMadkitProperty
- Parameters:
option
- the constant representing a MaDKit option- See Also:
isMadkitPropertyTrue
Boolean.parseBoolean(getMadkitProperty(option))
- Parameters:
option
- the constant representing a runtime option- Returns:
true
if the option has been set totrue
- Since:
- MadKit 5.0.3
setupFrame
frame.setContentPane(new OutputPanel(this));
.
Default settings for the frame are:
- width = 400
- height = 300
- location = center of the screen
- a JMenuBar with:
MadkitMenu
,AgentMenu
andAgentLogLevelMenu
- Parameters:
frame
- the default frame which has been created by MaDKit for this agent.- Since:
- MaDKit 5.1.1
- See Also:
getOrganizationSnapShot
- Parameters:
global
- iftrue
this takes into account agents coming from other connected kernels- Returns:
- a data containing all the organization structure
getExistingCommunities
- Returns:
- an alphanumerically ordered set containing the names of the communities which exist.
- Since:
- MaDKit 5.0.0.20
getExistingGroups
- 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
- 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
- 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
- Parameters:
community
- the community's namegroup
- 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
- Returns:
true
if the address still exists in the organization.- Since:
- MaDKit 5.0.4
isCommunity
- Parameters:
community
- the name of the community- Returns:
true
If a community with this name exists,false
otherwise.
isGroup
- Parameters:
community
- the name of the community the group is ingroup
- the name of the group- Returns:
true
If a group with this name exists in this community,false
otherwise.
hasRole
- Parameters:
community
-group
-role
-- Returns:
true
if the agent is playing this role- Since:
- MaDKit 5.0.3
isRole
- Parameters:
community
- the name of the community the group is ingroup
- the name of the grouprole
- the name of the role- Returns:
true
If a role with this name exists in this <community;group> couple,false
otherwise.
toString
getMadkitConfig
Key | Description of Associated Value |
---|---|
madkit.version |
MaDKit kernel version |
build.id |
MaDKit kernel build ID | </tr
madkit.repository.url |
the agent repository for this version, usually http://www.madkit.net/madkit/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:
getKernelAddress
- Returns:
- the kernel address representing the MaDKit kernel on which the agent is running
getServerInfo
- Returns:
- server's info: e.g. /192.168.1.14:4444
destroyCommunity
- Parameters:
community
- the community to destroy- Since:
- MaDKit 5.0.0.9
destroyGroup
- Parameters:
community
- the communitygroup
- the group to destroy- Since:
- MaDKit 5.0.0.10
destroyRole
- Parameters:
community
- the communitygroup
- the grouprole
- the group to destroy- Since:
- MaDKit 5.0.0.10
launchXmlAgents
- Parameters:
xmlFile
- the XML file to parse- Returns:
AbstractAgent.ReturnCode.SEVERE
if the launch failed- Throws:
ParserConfigurationException
IOException
SAXException
launchNode
- Parameters:
agentXmlNode
- the XML node- Returns:
AbstractAgent.ReturnCode.SEVERE
if the launch failed- See Also:
getState
- Returns:
- the current state of the agent:
: 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.NOT_LAUNCHED
: the agent is being registered by the kernel but has not started itsAbstractAgent.State.INITIALIZING
activate()
method yet.
: the agent is processing itsAbstractAgent.State.ACTIVATED
activate()
method. This state is also the "running" state ofAbstractAgent
subclasses (i.e. when they have finished their activation) as they do not have aAgent.live()
managed by the kernel in their life cycle. On the contrary toAgent
subclasses which next state isAbstractAgent.State.LIVING
.
: returned whenAbstractAgent.State.LIVING
Agent
subclasses are processing theirAgent.live()
method.
: the agent is processing itsAbstractAgent.State.ENDING
end()
method.
: 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.AbstractAgent.State.TERMINATED
reload
proceedEnumMessage
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:
isKernelOnline
- Returns:
true
if the kernel is online.
executeThisAgent
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 launchedcreateFrame
-args
- MaDKit options. For example, this will launch the agent in desktop mode :public static void main(String[] args) { executeThisAgent(BooleanOption.desktop.toString()); }
- Returns:
- the kernel instance that actually launches this agent, so that it is
possible to do other actions after the launch using
Madkit.doAction(madkit.action.KernelAction, Object...)
- Since:
- MaDKit 5.0.0.14
- See Also:
executeThisAgent
executeThisAgent(1, true, args)
- Parameters:
args
- MaDKit options- Returns:
- the kernel instance that actually launches this agent, so that it is
possible to do other actions after the launch using
Madkit.doAction(madkit.action.KernelAction, Object...)
- Since:
- MaDKit 5.0.0.14
- See Also:
executeThisAgent
executeThisAgent(null, 1, true)
- Returns:
- the kernel instance that actually launches this agent, so that it is
possible to do other actions after the launch using
Madkit.doAction(madkit.action.KernelAction, Object...)
- Since:
- MaDKit 5.0.0.15
- See Also:
AgentLogger.setLevel(Level)
should now be used throughgetLogger()