madkit.kernel
Class AbstractAgent

java.lang.Object
  extended by madkit.kernel.AbstractAgent
All Implemented Interfaces:
java.io.Serializable
Direct Known Subclasses:
AbstractBee, AbstractPredator, Agent, Brain, Prey, SynchroScheduler, Turtle, TurtleEnvironment, WarbotEnvironment, Watcher

public class AbstractAgent
extends java.lang.Object
implements java.io.Serializable

The main MadKit AbstractAgent class. It provides support for agent's

The agent's behavior is intentionnaly 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 MadKit. However, all agent share the same organizational view, and the basic messaging code, so integration of agent coming from different developer and having heterogeneous models is quite easy.

Agent-related methods (almost everything here) can be invoked only after registration in the kernel (i.e. after the activate method has been invoked on this agent). That means that you should not use any of the agent methods in constructor

Version:
3.4 4/02/2002
Author:
Olivier Gutknecht, Fabien Michel
See Also:
Serialized Form

Constructor Summary
AbstractAgent()
          Default no-args constructor, which just set-up internal structures
 
Method Summary
 void activate()
          This method is initially called when the micro-kernel registers the agent.
 void broadcastMessage(java.lang.String groupName, java.lang.String roleName, Message m)
           
 void broadcastMessage(java.lang.String communityName, java.lang.String groupName, java.lang.String roleName, Message m)
          Broadcast a message to every agent having a role in a group.
 boolean connectedWithCommunity(java.lang.String communityName)
          returns true if the community is shared on the network
 int createGroup(boolean distributed, java.lang.String groupName, java.lang.String description, GroupIdentifier theIdentifier)
          Creates a new Group within the default community public
 int createGroup(boolean distributed, java.lang.String communityName, java.lang.String groupName, java.lang.String description, GroupIdentifier theIdentifier)
          Creates a new Group.
 void debug(java.lang.String s)
          Print out debug information only if the debug flag is on
 void disposeMyGUI()
          hide the graphical component that represents the Agent in some higher interface
 void end()
          This method is called by the agent micro-kernel at the end of the agent lifecycle.
 void foundGroup(java.lang.String groupName)
          Deprecated. As of MadKit 3.0. replaced by createGroup(boolean,String,String,String,GroupIdentifier).

This call is now equivalent to createGroup(true, groupName, null, null).

 AgentAddress getAddress()
          Gets the agent's own agent address
 AgentInformation getAgentInformation()
          Gets the agent's own information
 AgentAddress[] getAgentsWithRole(java.lang.String groupName, java.lang.String roleName)
           
 AgentAddress[] getAgentsWithRole(java.lang.String communityName, java.lang.String groupName, java.lang.String roleName)
          Gets the addresses of all agents (including this agent if present) that handle this role within this group
 AgentAddress getAgentWithRole(java.lang.String groupName, java.lang.String roleName)
           
 AgentAddress getAgentWithRole(java.lang.String communityName, java.lang.String groupName, java.lang.String roleName)
          Gets an agent that handle a given role within a group, chosen randomly
 java.lang.String[] getAvailableCommunities()
          returns the available communities
 java.lang.Object getBean()
          Deprecated. As of MadKit 2.0. replaced by getGUIObject()
 Controller getController()
          Return the current controller of the agent if there is one
 KernelAddress getCurrentKernelAddress()
          Returns the kernelAddress of the agency where this agent is situated...
 boolean getDebug()
           
 java.lang.String[] getExistingGroups()
          return the names of the groups that exist within the default community
 java.lang.String[] getExistingGroups(java.lang.String communityName)
          return the names of the groups that exist in this community
 java.lang.String[] getExistingRoles(java.lang.String groupName)
          return the names of the roles that exist within this group in the default community
 java.lang.String[] getExistingRoles(java.lang.String communityName, java.lang.String groupName)
          return the names of the roles that exist in this (community,group) couple
 java.util.Vector getGroups()
          Deprecated. As of MadKit 3.0. replaced by getExistingGroups(String)
 java.lang.Object getGUIObject()
          Gets the graphic component representing the agent.
 int getMessageBoxSize()
          Get the number of messages in the message box
 java.lang.String[] getMyGroups()
           
 java.lang.String[] getMyGroups(java.lang.String communityName)
          Gets the name of the groups the agent joined in this community.
 java.lang.String[] getMyRoles(java.lang.String groupName)
          Gets roles currently handled within a group of the default community
 java.lang.String[] getMyRoles(java.lang.String communityName, java.lang.String groupName)
          Gets roles currently handled within a group of this community
 java.lang.String getName()
          Gets the current agent patronymic name
 java.lang.String[] getRoles(java.lang.String groupName)
          Deprecated. As of MadKit 3.0. replaced by getExistingRoles(String,String)
 boolean hasGUI()
          Check if a bean is running in GUI mode.
 void initGUI()
          This method is called by the specific external graphic system (as the G-Box) to ask the agent to prepare a graphical interface.
 boolean isBelongingToGroup(AgentAddress address, java.lang.String groupName)
          Tell if an agent is a member of a specific group in the default community
 boolean isBelongingToGroup(AgentAddress address, java.lang.String communityName, java.lang.String groupName)
          Tell if the agent is a member of a specific group in a given community
 boolean isCommunity(java.lang.String communityName)
          Determines if this group already exists in this community
 boolean isGroup(java.lang.String groupName)
          Determines if this group already exists in the default community
 boolean isGroup(java.lang.String communityName, java.lang.String groupName)
          Determines if this group already exists in this community
 boolean isMemberOf(java.lang.String groupName)
          Tell if the agent is a member of a specific group in the default community
 boolean isMemberOf(java.lang.String communityName, java.lang.String groupName)
          Tell if the agent is a member of a specific group in a given community
 boolean isMessageBoxEmpty()
          Is there any message left to be read ?
 boolean isRole(java.lang.String groupName, java.lang.String roleName)
           
 boolean isRole(java.lang.String communityName, java.lang.String groupName, java.lang.String roleName)
           
 void joinGroup(java.lang.String groupName)
          Deprecated. As of MadKit 3.0. replaced by createGroup(boolean,String,String,String,GroupIdentifier).

This call is now equivalent to createGroup(true, groupName, null, null) if the group does not exist or requestRole(groupName, "member", null) otherwise.

 void killAgent(AbstractAgent agent)
          Kill another agent.
 void launchAgent(AbstractAgent agent, java.lang.String name, boolean gui)
          This method is called in order to launch an agent from another agent.
 void launchAgent(AbstractAgent agent, java.lang.String name, java.awt.Point position, java.awt.Dimension dim)
          This method try to launch an agent with a GUI with the specified coordinates and dimension
 boolean leaveGroup(java.lang.String groupName)
           
 boolean leaveGroup(java.lang.String communityName, java.lang.String groupName)
          Make the agent leave the group.
 boolean leaveRole(java.lang.String groupName, java.lang.String roleName)
           
 boolean leaveRole(java.lang.String communityName, java.lang.String groupName, java.lang.String roleName)
          Abandon an handled role within a group.
 Message nextMessage()
          Gets the first message in the queue.
 void print(java.lang.String theString)
          Prints text information in a environment-independant way (GUI, console, ...)
 void println(java.lang.String theString)
          Prints text information in a environment-independant way (GUI, console, ...)
 void receiveMessage(Message m)
          kernel use
 void redisplayMyGUI()
          try to restore the graphical component that represents the Agent in some higher interface
 void requestRole(java.lang.String groupName, java.lang.String roleName)
          Deprecated. As of MadKit 3.0. replaced by requestRole(String,String,Object).

This call is now equivalent to requestRole(groupName, roleName, null).

 int requestRole(java.lang.String groupName, java.lang.String roleName, java.lang.Object memberCard)
          Request a role within a group of the default community
 int requestRole(java.lang.String communityName, java.lang.String groupName, java.lang.String roleName, java.lang.Object memberCard)
          Request a role within a group.
 void restoreAgent(AbstractAgent agent)
          experimental
 void sendMessage(AgentAddress a, Message m)
          Send a message to another agent.
 void sendMessage(java.lang.String groupName, java.lang.String roleName, Message m)
           
 void sendMessage(java.lang.String communityName, java.lang.String groupName, java.lang.String roleName, Message m)
          Send a message to an agent having a specific role in a group.
 void setBean(java.lang.Object theBean)
          Deprecated. As of MadKit 2.0. replaced by setGUIObject(Object)
 void setController(Controller c)
          Assign a controller which will be in charge of the control of the agent's behavior
 void setDebug(boolean b)
          Set the debug flag
 void setGUIObject(java.lang.Object theBean)
          This method set the bean that will be used to represent the agent in a graphical environment, the agent is also registered as running in GUI mode
 void setName(java.lang.String theName)
          Change the current agent patronymic name.
 void setOutput(java.io.Writer o)
          Deprecated. As of MadKit 2.0. replaced by setOutputWriter(Writer)
 void setOutputWriter(java.io.Writer o)
          Reassigns the "standard" agent text output stream (used by method println).
 void windowClosing(java.awt.AWTEvent we)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AbstractAgent

public AbstractAgent()
Default no-args constructor, which just set-up internal structures

Method Detail

getController

public Controller getController()
Return the current controller of the agent if there is one


setController

public void setController(Controller c)
Assign a controller which will be in charge of the control of the agent's behavior


activate

public void activate()
This method is initially called when the micro-kernel registers the agent. Usually a good place to set up some initial groups and roles.


end

public void end()
This method is called by the agent micro-kernel at the end of the agent lifecycle. If the the agent is killed from the outside, it is the last opportunity for the agent to cleanly shutdown its operations.


createGroup

public int createGroup(boolean distributed,
                       java.lang.String communityName,
                       java.lang.String groupName,
                       java.lang.String description,
                       GroupIdentifier theIdentifier)
Creates a new Group. If operation succeed, the agent will automaticaly handle two roles: member and group manager.

Parameters:
distributed - if true the new group will be distributed when multiple MadKit kernels are connected
communityName - the community within the group will be created. If this community does not exist it will be created.
groupName - the name of the new group
description - can be null (thus the description will be the name of the group)
theIdentifier - an object that implements the GroupIdentifer Interface. When null, there is no group access control
Returns:
1 if operation succeed; -1 if the group already exists.
Since:
MadKit 3.0
See Also:
GroupIdentifier

createGroup

public int createGroup(boolean distributed,
                       java.lang.String groupName,
                       java.lang.String description,
                       GroupIdentifier theIdentifier)
Creates a new Group within the default community public


requestRole

public int requestRole(java.lang.String communityName,
                       java.lang.String groupName,
                       java.lang.String roleName,
                       java.lang.Object memberCard)
Request a role within a group.

Parameters:
communityName - the group's community.
groupName - the desired group.
roleName - the desired role.
memberCard - the passKey to enter a group. If needed, it is generally delivered by the group's group manager to nice agents :) It can be null when the desired group has no security (i.e. was created using null for theIdentifier parameter).
Returns:
1 : operation success; -1 : access denied; -2 : the role is already handled by this agent; -3 : the group does not exist; -4 : the community does not exist.
Since:
MadKit 3.0

requestRole

public int requestRole(java.lang.String groupName,
                       java.lang.String roleName,
                       java.lang.Object memberCard)
Request a role within a group of the default community


leaveRole

public boolean leaveRole(java.lang.String communityName,
                         java.lang.String groupName,
                         java.lang.String roleName)
Abandon an handled role within a group.

Returns:
true if operation is done; false otherwise.
Since:
MadKit 3.0

leaveRole

public boolean leaveRole(java.lang.String groupName,
                         java.lang.String roleName)

leaveGroup

public boolean leaveGroup(java.lang.String communityName,
                          java.lang.String groupName)
Make the agent leave the group.

Returns:
true if operation is done; false otherwise.
Since:
MadKit 3.0

leaveGroup

public boolean leaveGroup(java.lang.String groupName)

joinGroup

public void joinGroup(java.lang.String groupName)
Deprecated. As of MadKit 3.0. replaced by createGroup(boolean,String,String,String,GroupIdentifier).

This call is now equivalent to createGroup(true, groupName, null, null) if the group does not exist or requestRole(groupName, "member", null) otherwise.


requestRole

public void requestRole(java.lang.String groupName,
                        java.lang.String roleName)
Deprecated. As of MadKit 3.0. replaced by requestRole(String,String,Object).

This call is now equivalent to requestRole(groupName, roleName, null).


foundGroup

public void foundGroup(java.lang.String groupName)
Deprecated. As of MadKit 3.0. replaced by createGroup(boolean,String,String,String,GroupIdentifier).

This call is now equivalent to createGroup(true, groupName, null, null).


getAgentsWithRole

public AgentAddress[] getAgentsWithRole(java.lang.String communityName,
                                        java.lang.String groupName,
                                        java.lang.String roleName)
Gets the addresses of all agents (including this agent if present) that handle this role within this group


getAgentsWithRole

public AgentAddress[] getAgentsWithRole(java.lang.String groupName,
                                        java.lang.String roleName)

getAgentWithRole

public AgentAddress getAgentWithRole(java.lang.String communityName,
                                     java.lang.String groupName,
                                     java.lang.String roleName)
Gets an agent that handle a given role within a group, chosen randomly

Parameters:
groupName - group name
roleName - role name
Returns:
the agent address.

getAgentWithRole

public AgentAddress getAgentWithRole(java.lang.String groupName,
                                     java.lang.String roleName)

getMyGroups

public java.lang.String[] getMyGroups(java.lang.String communityName)
Gets the name of the groups the agent joined in this community.

Parameters:
communityName - a string holding a community name
Since:
MadKit 3.0

getMyGroups

public java.lang.String[] getMyGroups()
Returns:
an array of group names

getExistingGroups

public java.lang.String[] getExistingGroups(java.lang.String communityName)
return the names of the groups that exist in this community


getExistingGroups

public java.lang.String[] getExistingGroups()
return the names of the groups that exist within the default community


isMemberOf

public boolean isMemberOf(java.lang.String communityName,
                          java.lang.String groupName)
Tell if the agent is a member of a specific group in a given community

Returns:
true if the agent is member of a group

isMemberOf

public boolean isMemberOf(java.lang.String groupName)
Tell if the agent is a member of a specific group in the default community

Returns:
true if the agent is member of a group

isBelongingToGroup

public boolean isBelongingToGroup(AgentAddress address,
                                  java.lang.String communityName,
                                  java.lang.String groupName)
Tell if the agent is a member of a specific group in a given community

Returns:
true if the agent is member of a group

isBelongingToGroup

public boolean isBelongingToGroup(AgentAddress address,
                                  java.lang.String groupName)
Tell if an agent is a member of a specific group in the default community

Returns:
true if the agent is member of a group

getMyRoles

public java.lang.String[] getMyRoles(java.lang.String communityName,
                                     java.lang.String groupName)
Gets roles currently handled within a group of this community


getMyRoles

public java.lang.String[] getMyRoles(java.lang.String groupName)
Gets roles currently handled within a group of the default community


getExistingRoles

public java.lang.String[] getExistingRoles(java.lang.String communityName,
                                           java.lang.String groupName)
return the names of the roles that exist in this (community,group) couple


getExistingRoles

public java.lang.String[] getExistingRoles(java.lang.String groupName)
return the names of the roles that exist within this group in the default community


getRoles

public java.lang.String[] getRoles(java.lang.String groupName)
Deprecated. As of MadKit 3.0. replaced by getExistingRoles(String,String)


isRole

public boolean isRole(java.lang.String communityName,
                      java.lang.String groupName,
                      java.lang.String roleName)
Returns:
true if the role exists (i.e. there is at least one agent with this role); false otherwise.

isRole

public boolean isRole(java.lang.String groupName,
                      java.lang.String roleName)
Returns:
true if the role exists (i.e. there is at least one agent with this role); false otherwise.

getGroups

public java.util.Vector getGroups()
Deprecated. As of MadKit 3.0. replaced by getExistingGroups(String)


isGroup

public boolean isGroup(java.lang.String communityName,
                       java.lang.String groupName)
Determines if this group already exists in this community


isGroup

public boolean isGroup(java.lang.String groupName)
Determines if this group already exists in the default community


isCommunity

public boolean isCommunity(java.lang.String communityName)
Determines if this group already exists in this community

Since:
MadKit 3.0

getAvailableCommunities

public java.lang.String[] getAvailableCommunities()
returns the available communities

Since:
MadKit 3.0

connectedWithCommunity

public boolean connectedWithCommunity(java.lang.String communityName)
returns true if the community is shared on the network

Since:
MadKit 3.0

isMessageBoxEmpty

public boolean isMessageBoxEmpty()
Is there any message left to be read ?


getMessageBoxSize

public int getMessageBoxSize()
Get the number of messages in the message box


nextMessage

public Message nextMessage()
Gets the first message in the queue.

Returns:
the first item in the message queue, or null if there is no message available

receiveMessage

public void receiveMessage(Message m)
kernel use


sendMessage

public void sendMessage(AgentAddress a,
                        Message m)
Send a message to another agent.

Parameters:
a - AgentAddress of the receiver
m - Message to be sent

sendMessage

public void sendMessage(java.lang.String communityName,
                        java.lang.String groupName,
                        java.lang.String roleName,
                        Message m)
Send a message to an agent having a specific role in a group. The corresponding AgentAddress is selected with a getAgentWithRole(..) method call.

Parameters:
communityName - community in which the group is defined
groupName - group in which the role is defined
roleName - Role of the receiver
m - Message to be sent

sendMessage

public void sendMessage(java.lang.String groupName,
                        java.lang.String roleName,
                        Message m)

broadcastMessage

public void broadcastMessage(java.lang.String communityName,
                             java.lang.String groupName,
                             java.lang.String roleName,
                             Message m)
Broadcast a message to every agent having a role in a group. You must assume that the message might not be cloned when sent to local agents


broadcastMessage

public void broadcastMessage(java.lang.String groupName,
                             java.lang.String roleName,
                             Message m)

launchAgent

public void launchAgent(AbstractAgent agent,
                        java.lang.String name,
                        boolean gui)
This method is called in order to launch an agent from another agent.

Parameters:
agent - The new (already instanciated) agent.
name - The "usual" name
gui - Should we setup the agent GUI if possible ?

launchAgent

public void launchAgent(AbstractAgent agent,
                        java.lang.String name,
                        java.awt.Point position,
                        java.awt.Dimension dim)
This method try to launch an agent with a GUI with the specified coordinates and dimension


restoreAgent

public void restoreAgent(AbstractAgent agent)
experimental


killAgent

public void killAgent(AbstractAgent agent)
Kill another agent. This is only possible if the caller launched the target agent itself and still owns a reference to the potential victim


getAddress

public AgentAddress getAddress()
Gets the agent's own agent address


getAgentInformation

public AgentInformation getAgentInformation()
Gets the agent's own information


setName

public void setName(java.lang.String theName)
Change the current agent patronymic name. This name does not need to be unique, and is provided only as a facility


getName

public java.lang.String getName()
Gets the current agent patronymic name


getCurrentKernelAddress

public KernelAddress getCurrentKernelAddress()
Returns the kernelAddress of the agency where this agent is situated... Generally this value is equal to getAddress().getKernel() but when an agent migrate, this value may change. This method is used to get the real value of the current kernel address.

Returns:
the current kernelAddress

hasGUI

public boolean hasGUI()
Check if a bean is running in GUI mode. Usually verified by the Kernel or the host application to setup or not a default graphical interface

Returns:
true if a GUI has been instanciated

initGUI

public void initGUI()
This method is called by the specific external graphic system (as the G-Box) to ask the agent to prepare a graphical interface. The agent developper should use a setGUIObject(...) within this method, as well as other necessary initializations. If the developper does not overload this method, a vanilla text output might be used as the default interface.


setBean

public void setBean(java.lang.Object theBean)
Deprecated. As of MadKit 2.0. replaced by setGUIObject(Object)


getBean

public java.lang.Object getBean()
Deprecated. As of MadKit 2.0. replaced by getGUIObject()


setGUIObject

public void setGUIObject(java.lang.Object theBean)
This method set the bean that will be used to represent the agent in a graphical environment, the agent is also registered as running in GUI mode

Parameters:
theBean - an allocated graphic component
Since:
MadKit 2.0

getGUIObject

public java.lang.Object getGUIObject()
Gets the graphic component representing the agent. Usually called by the host application

Since:
MadKit 2.0

debug

public void debug(java.lang.String s)
Print out debug information only if the debug flag is on


setDebug

public void setDebug(boolean b)
Set the debug flag


getDebug

public boolean getDebug()
Returns:
true if debug is on

println

public void println(java.lang.String theString)
Prints text information in a environment-independant way (GUI, console, ...)


print

public void print(java.lang.String theString)
Prints text information in a environment-independant way (GUI, console, ...)


setOutput

public void setOutput(java.io.Writer o)
Deprecated. As of MadKit 2.0. replaced by setOutputWriter(Writer)


setOutputWriter

public void setOutputWriter(java.io.Writer o)
Reassigns the "standard" agent text output stream (used by method println).


disposeMyGUI

public void disposeMyGUI()
hide the graphical component that represents the Agent in some higher interface

Since:
MadKit 3.0

redisplayMyGUI

public void redisplayMyGUI()
try to restore the graphical component that represents the Agent in some higher interface

Since:
MadKit 3.0

windowClosing

public void windowClosing(java.awt.AWTEvent we)


Copyright © Madkit Team (O. Gutknecht, J. Ferber, F. Michel et al.) All Rights Reserved.