public class AbstractAgent extends Object implements Comparable<AbstractAgent>
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.
AgentAddress
for more information.withRole
version of all the messaging methods has been
added. See sendMessageWithRole(AgentAddress, Message, String)
for an example of such a method.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.getState()
method for detailed
information.getLogger()
method for more details.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.
|
Constructor and Description |
---|
AbstractAgent() |
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 no
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 Madkit |
executeThisAgent()
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.
|
AgentAddress |
getAgentAddressIn(String community,
String group,
String role)
Agent's address at this CGR location.
|
List<AgentAddress> |
getAgentsWithRole(String community,
String group,
String role)
A list containing other agents playing this role in the organization.
|
List<AgentAddress> |
getAgentsWithRole(String community,
String group,
String role,
boolean callerIncluded)
A list containing all the agents playing 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)
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()
The kernel's address on which this agent is running.
|
Message |
getLastReceivedMessage()
Gets the last received message.
|
Message |
getLastReceivedMessage(MessageFilter filter)
Gets the last received message according to a filter.
|
AgentLogger |
getLogger()
Returns the agent's logger.
|
MadkitProperties |
getMadkitConfig()
Returns the Properties object of this MaDKit session.
|
<E extends Enum<E>> |
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()
The agent's name.
|
String |
getNetworkID()
Return a string representing a unique identifier for the agent over the network.
|
LocalDateTime |
getNextEventDate()
Method which is used by discrete-event simulation activators for doing fine-grained simulations.
|
OrganizationSnapshot |
getOrganizationSnapShot(boolean global)
Returns a snapshot view of all the current organization for debugging purpose.
|
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.
|
Scheduler.SimulationTime |
getSimulationTime()
Returns the
Scheduler.SimulationTime of the current simulation. |
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>> |
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...) 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 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 oldest 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, in the order they were received.
|
<E extends Enum<E>> |
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)
Deprecated.
as of MaDKit 5.2,
AgentLogger.setLevel(Level) should now be used through getLogger() |
<E extends Enum<E>> |
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(AgentFrame frame)
Called when the default GUI mechanism is used upon agent creation.
|
String |
toString() |
public Scheduler.SimulationTime getSimulationTime()
Scheduler.SimulationTime
of the current simulation.
This is automatically initialized when the agent is associated with an activator for the first time.
So it stays null
if the agent is not related to a simulationpublic LocalDateTime getNextEventDate()
DiscreteEventAgentsActivator
,
DateBasedDiscreteEventActivator
public void createGUIOnStartUp()
public boolean hasGUI()
true
if this agent has a GUI built by the kernelpublic final int hashCode()
public final String getNetworkID()
public final String getSimpleNetworkID()
getNetworkID()
public boolean isAlive()
true
if the agent has been launched and is not ended nor killed.protected void activate()
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); } }
protected void end()
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"); } }
public AbstractAgent.ReturnCode launchAgent(AbstractAgent agent)
launchAgent(agent,Integer.MAX_VALUE,false)
agent
- the agent to launch. 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
methodlaunchAgent(AbstractAgent)
public AbstractAgent.ReturnCode launchAgent(AbstractAgent agent, int timeOutSeconds)
launchAgent(agent,timeOutSeconds,false)
agent
- the agent to launch.timeOutSeconds
- time to wait the end of the agent's activation until returning a TIMEOUT. 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
secondsAbstractAgent.ReturnCode.AGENT_CRASH
: If the agent crashed during its activate
methodpublic AbstractAgent.ReturnCode launchAgent(AbstractAgent agent, boolean createFrame)
launchAgent(agent,Integer.MAX_VALUE,withGUIManagedByTheBooter)
agent
- the agent to launch.createFrame
- if true
, the kernel will launch a JFrame for this agent. 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
methodlaunchAgent(AbstractAgent)
public AbstractAgent.ReturnCode launchAgent(AbstractAgent agent, int timeOutSeconds, boolean createFrame)
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:
setupFrame(AgentFrame)
and so setup the default JFrame as
willOutputPanel
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. 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
methodpublic AbstractAgent launchAgent(String agentClass)
launchAgent(agentClass, Integer.MAX_VALUE, false)
.agentClass
- the full class name of the agent to launchnull
if the operation times out or failed.public AbstractAgent launchAgent(String agentClass, int timeOutSeconds)
launchAgent(agentClass, timeOutSeconds, false)
.timeOutSeconds
- time to wait the end of the agent's activation until returning null
agentClass
- the full class name of the agent to launchnull
if the operation times out or failed.public AbstractAgent launchAgent(String agentClass, boolean createFrame)
launchAgent(agentClass, Integer.MAX_VALUE, defaultGUI)
.createFrame
- if true
a default GUI will be associated with the launched agentagentClass
- the full class name of the agent to launchnull
if the operation times out or failed.public AbstractAgent launchAgent(String agentClass, int timeOutSeconds, boolean createFrame)
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.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 agentagentClass
- the full class name of the agent to launchnull
if the operation times out or failed.public List<AbstractAgent> launchAgentBucket(String agentClass, int bucketSize, int cpuCoreNb, String... roles)
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.
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 agentsroles
- 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
.null
if the operation has failedpublic List<AbstractAgent> launchAgentBucket(String agentClass, int bucketSize, String... roles)
launchAgentBucket(agentClass, bucketSize, 1, roles)
.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"
null
if the operation has failedpublic void launchAgentBucket(List<? extends AbstractAgent> bucket, String... roles)
launchAgentBucket(bucket, 1, roles)
, That is only
one core will be used for the launch.bucket
- the list of agents to launchroles
- 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
public void launchAgentBucket(List<? extends AbstractAgent> bucket, int nbOfParallelTasks, String... roles)
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.bucket
- the list of agents to launchnbOfParallelTasks
- 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 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 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
public AbstractAgent.ReturnCode killAgent(AbstractAgent target)
killAgent(target,Integer.MAX_VALUE)
so that the
targeted agent has a lot of time to complete its end()
method.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 ;).killAgent(AbstractAgent, int)
public AbstractAgent.ReturnCode killAgent(AbstractAgent target, int timeOutSeconds)
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.
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.public String getName()
public void setName(String name)
name
- the name to display in logger info, GUI title and so on, default is "class name + internal ID"@Deprecated public void setLogLevel(Level newLevel)
AgentLogger.setLevel(Level)
should now be used through getLogger()
AgentLogger.setLevel(Level)
because this
also works when logger
is null
and allows to set it to null
to save cpu time.public AgentLogger getLogger()
getLogger()
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.AgentLogger
public int compareTo(AbstractAgent other)
compareTo
in interface Comparable<AbstractAgent>
other
- the agent to be compared.public AbstractAgent.ReturnCode createGroup(String community, String group)
createGroup(community, group, false, null)
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 groupAbstractAgent.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
rolescreateGroup(String, String, boolean, Gatekeeper)
public AbstractAgent.ReturnCode createGroup(String community, String group, boolean isDistributed)
createGroup(community, group, isDistributed, null)
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.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
rolescreateGroup(String, String, boolean, Gatekeeper)
public AbstractAgent.ReturnCode createGroup(String community, String group, boolean isDistributed, Gatekeeper keyMaster)
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".
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.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.Gatekeeper
,
AbstractAgent.ReturnCode
public AbstractAgent.ReturnCode bucketModeCreateGroup(String community, String group, boolean isDistributed, Gatekeeper keyMaster)
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...)
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.AbstractAgent.ReturnCode.SUCCESS
: If the group has been successfully created.
AbstractAgent.ReturnCode.ALREADY_GROUP
: If the operation failed because such a group already exists.Gatekeeper
,
AbstractAgent.ReturnCode
public boolean createGroupIfAbsent(String community, String group)
createGroupIfAbsent(community, group, false, null)
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.true
if the group has been created, false
if such a group already exists.createGroupIfAbsent(String, String, boolean, Gatekeeper)
public boolean createGroupIfAbsent(String community, String group, boolean isDistributed)
createGroupIfAbsent(community, group, isDistributed, null)
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
- if true
the new group will be distributed when multiple MaDKit kernels are connected.true
if the group has been created, false
if such a group already exists.createGroupIfAbsent(String, String, boolean, Gatekeeper)
public boolean createGroupIfAbsent(String community, String group, boolean isDistributed, Gatekeeper keyMaster)
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
- 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.true
if the group has been created, false
if such a group already exists.Gatekeeper
,
AbstractAgent.ReturnCode
public AbstractAgent.ReturnCode leaveGroup(String community, String group)
community
- the community namegroup
- the group nameAbstractAgent.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.AbstractAgent.ReturnCode
public AbstractAgent.ReturnCode requestRole(String community, String group, String role)
requestRole(community, group, role, null, false)
. So the passKey is null
and the group must
not be secured for this to succeed.community
- the group's community.group
- the targeted group.role
- the desired role.requestRole(String, String, String, Object)
public AbstractAgent.ReturnCode requestRole(String community, String group, String role, Object passKey)
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
.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.AbstractAgent.ReturnCode
,
Gatekeeper
public AbstractAgent.ReturnCode bucketModeRequestRole(String community, String group, String role, Object passKey)
launchAgentBucket
methods with no
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 built at runtime.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
.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
,
Gatekeeper
public AbstractAgent.ReturnCode leaveRole(String community, String group, String role)
community
- the community namegroup
- the group namerole
- the role nameAbstractAgent.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.AbstractAgent.ReturnCode
public AgentAddress getAgentAddressIn(String community, String group, String role)
community
- group
- role
- null
if this agent does not handle this role.public AgentAddress getAgentWithRole(String community, String group, String role)
AgentAddress
corresponding to an agent having this position in the organization. The caller is
excluded from the search.community
- the community namegroup
- the group namerole
- the role nameAgentAddress
corresponding to an agent handling this role or null
if such an agent
does not exist.public AgentAddress getDistantAgentWithRole(String community, String group, String role, KernelAddress from)
AgentAddress
corresponding to an agent having this position in the organization on a particular kernel. The
caller is excluded from the search.community
- the community namegroup
- the group namerole
- the role namefrom
- the kernel address on which the agent is runningAgentAddress
corresponding to an agent handling this role on the targeted kernel or
null
if such an agent does not exist.public List<AgentAddress> getAgentsWithRole(String community, String group, String role)
community
- the community namegroup
- the group namerole
- the role nameList
containing agents that handle this role or null
if no agent has been
found.public List<AgentAddress> getAgentsWithRole(String community, String group, String role, boolean callerIncluded)
community
- the community namegroup
- the group namerole
- the role namecallerIncluded
- if false
, the caller is removed from the list if it is in.List
containing agents that handle this role or null
if no agent has been
found.public Message nextMessage()
null
if the message box is empty.public Message nextMessage(MessageFilter filter)
null
if such message has not been found.public List<Message> nextMessages(MessageFilter filter)
filter
- if null
all the messages are returned and removed from the mailbox.public Message getLastReceivedMessage()
null
if the mailbox is empty.public Message getLastReceivedMessage(MessageFilter filter)
filter
- the message filter to usenull
if such message has not been found.public Message purgeMailbox()
null
if the mailbox is already empty.public boolean isMessageBoxEmpty()
true
if there is no message in the mailbox.public AbstractAgent.ReturnCode sendMessage(AgentAddress receiver, Message messageToSend)
sendMessageWithRole(receiver, messageToSend, null)
.receiver
- messageToSend
- 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.AbstractAgent.ReturnCode
,
AgentAddress
public AbstractAgent.ReturnCode sendMessageWithRole(AgentAddress receiver, Message message, String senderRole)
receiver
- the targeted agentmessage
- the message to sendAbstractAgent.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.AbstractAgent.ReturnCode
,
AgentAddress
public AbstractAgent.ReturnCode sendMessage(String community, String group, String role, Message message)
community
- the community namegroup
- the group namerole
- the role namemessage
- the message to sendAbstractAgent.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.AbstractAgent.ReturnCode
public AbstractAgent.ReturnCode sendMessageWithRole(String community, String group, String role, Message message, String senderRole)
sendMessageWithRole(community, group, role, messageToSend,null)
. If several agents match, the target is
chosen randomly. The sender is excluded from this search.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 sentAbstractAgent.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.AbstractAgent.ReturnCode
public AbstractAgent.ReturnCode broadcastMessage(String community, String group, String role, Message message)
community
- the community namegroup
- the group namerole
- the role namemessage
- 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.AbstractAgent.ReturnCode
public AbstractAgent.ReturnCode broadcastMessageWithRole(String community, String group, String role, Message messageToSend, String senderRole)
community
- the community namegroup
- the group namerole
- the role namemessageToSend
- senderRole
- the agent's role with which the message should be sentAbstractAgent.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.AbstractAgent.ReturnCode
public AbstractAgent.ReturnCode sendReplyWithRole(Message messageToReplyTo, Message reply, String senderRole)
messageToReplyTo
- the previously received message.reply
- the reply itself.senderRole
- the agent's role with which the message should be sentAbstractAgent.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.AbstractAgent.ReturnCode
public AbstractAgent.ReturnCode sendReply(Message messageToReplyTo, Message reply)
sendReplyWithRole(messageToReplyTo, reply, null)
.messageToReplyTo
- the previously received message.reply
- the reply itself.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.sendReplyWithRole(Message, Message, String)
public Message getReplyTo(Message originalMessage)
originalMessage
- the message to which a reply is searched.null
if no reply to this message has been received.public void receiveMessage(Message m)
m
- public final String getMadkitProperty(String key)
getMadkitConfig().getProperty(key)
key
- the name of the MaDKit propertynull
if there is no property with that key.setMadkitProperty(String, String)
,
Madkit
public <E extends Enum<E>> String getMadkitProperty(E option)
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.option
- the constant representing a MaDKit optionnull
if there is no property having the corresponding
name.LevelOption BooleanOption
public void setMadkitProperty(String key, String value)
key
- the name of the MaDKit propertygetMadkitProperty(String)
,
Madkit
public <E extends Enum<E>> void setMadkitProperty(E option, String value)
option
- the constant representing a MaDKit optiongetMadkitProperty(String)
,
Madkit
public <E extends Enum<E>> boolean isMadkitPropertyTrue(E option)
Boolean.parseBoolean(getMadkitProperty(option))
option
- the constant representing a runtime optiontrue
if the option has been set to true
public void setupFrame(AgentFrame frame)
frame.setContentPane(new OutputPanel(this));
. Default settings for the frame are:
MadkitMenu
, AgentMenu
and AgentLogLevelMenu
frame
- the default frame which has been created by MaDKit for this agent.OutputPanel
public OrganizationSnapshot getOrganizationSnapShot(boolean global)
global
- if true
this takes into account agents coming from other connected kernelspublic TreeSet<String> getExistingCommunities()
public TreeSet<String> getExistingGroups(String community)
community
- the community's namenull
if this community does not exist.public TreeSet<String> getMyGroups(String community)
community
- null
if this community does not
exist. This set could be empty.public TreeSet<String> getMyRoles(String community, String group)
community
- group
- null
if the
community or the group does not exist. This set could be empty.public TreeSet<String> getExistingRoles(String community, String group)
community
- the community's namegroup
- the group's namenull
if it does not exist.public boolean checkAgentAddress(AgentAddress agentAddress)
true
if the address still exists in the organization.public boolean isCommunity(String community)
community
- the name of the communitytrue
If a community with this name exists, false
otherwise.public boolean isGroup(String community, String group)
community
- the name of the community the group is ingroup
- the name of the grouptrue
If a group with this name exists in this community, false
otherwise.public boolean hasRole(String community, String group, String role)
community
- group
- role
- true
if the agent is playing this rolepublic boolean isRole(String community, String group, String role)
community
- the name of the community the group is ingroup
- the name of the grouprole
- the name of the roletrue
If a role with this name exists in this false
otherwise.public String toString()
public MadkitProperties getMadkitConfig()
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/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 |
LevelOption BooleanOption
public KernelAddress getKernelAddress()
public String getServerInfo()
public void destroyCommunity(String community)
community
- the community to destroypublic void destroyGroup(String community, String group)
community
- the communitygroup
- the group to destroypublic void destroyRole(String community, String group, String role)
community
- the communitygroup
- the grouprole
- the group to destroypublic AbstractAgent.ReturnCode launchXmlAgents(String xmlFile) throws SAXException, IOException, ParserConfigurationException
xmlFile
- the XML file to parseAbstractAgent.ReturnCode.SEVERE
if the launch failedParserConfigurationException
IOException
SAXException
public AbstractAgent.ReturnCode launchNode(Node agentXmlNode)
agentXmlNode
- the XML nodeAbstractAgent.ReturnCode.SEVERE
if the launch failedXMLUtilities
public AbstractAgent.State getState()
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.public void reload()
public <E extends Enum<E>> void proceedEnumMessage(EnumMessage<E> message)
EnumMessage
so that if it is correctly built, the agent will trigger its corresponding behavior
using the parameters of the message.message
- the message to proceedEnumMessage
public boolean isKernelOnline()
true
if the kernel is online.protected static Madkit executeThisAgent(int nbOfInstances, boolean createFrame, String... args)
AbstractAgent
:
public static void main(String[] args) {
executeThisAgent(args);
}
Still, the agent must have a default constructor for that to work.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());
}
Madkit.doAction(madkit.action.KernelAction, Object...)
BooleanOption LevelOption
protected static Madkit executeThisAgent(String... args)
executeThisAgent(1, true, args)
args
- MaDKit optionsMadkit.doAction(madkit.action.KernelAction, Object...)
executeThisAgent(int, boolean, String...)
protected static Madkit executeThisAgent()
executeThisAgent(null, 1, true)
Madkit.doAction(madkit.action.KernelAction, Object...)
executeThisAgent(int, boolean, String...)
Fabien Michel, Olivier Gutknecht, Jacques Ferber - February 17 2020