Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## madkit.kernel
Class AbstractAgent

    java.lang.Object
      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

- Lifecycle
- Group and roles management
- Messaging
- Graphical interface
- Agent informations

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)

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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