Package madkit.kernel

# Class AgentAddress

java.lang.Object
madkit.kernel.AgentAddress

All Implemented Interfaces:
  `Serializable`

public class AgentAddress extends Object implements Serializable
Identifies an agent within the artificial society.

How this class works is very different from the previous versions of MaDKit. More precisely, it now corresponds to a CGR location (community;group;role) where the agent is in. So, an agent may have several AgentAddress as it could join many CGR locations.

Moreover, if the related agent leaves the corresponding CGR location, then an AgentAddress becomes invalid and no longer permits to reach this agent. For instance, a message sent using `AbstractAgent.sendMessage(AgentAddress, Message)` will not be delivered if the agent has leaved the related CGR location.

Since:
  MaDKit 1.0
Version:
  5.1
Author:
  Olivier Gutknecht, Fabien Michel
See Also:
  - Serialized Form

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `equals(Object agentAddress)`
  Tells if another address is the same.
  `final String`
  `getAgentNetworkID()`
  Return a string representing a unique identifier of the binded agent over the network.
  `String`
  `getCommunity()`
  Returns the community to which this agent address is binded to.
  `String`
  `getGroup()`
  Returns the group to which this agent address is binded to.
  `KernelAddress`
  `getKernelAddress()`
  `String`
  `getRole()`
  Returns the role to which this agent address is binded to.
  `final String`
  `getSimpleAgentNetworkID()`
  Return a string representing a shorter version of the unique identifier of the binded agent over the network.
  `final int`
  `hashCode()`
  The hash code of an agent address.
  `boolean`
  `isFrom(KernelAddress kernel)`
  Tells if the address is from a specific kernel.
  `String`
  `toString()`
  Returns a string representing this address.

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Method Details

  - ### getKernelAddress

    public KernelAddress getKernelAddress()
    Returns:
      the platform's kernelAddress to which this agent address comes from

  - ### getCommunity

    public String getCommunity()
    Returns the community to which this agent address is binded to.
    Returns:
      the name of the community to which this agent address belongs to
    Since:
      MaDKit 5

  - ### getGroup

    public String getGroup()
    Returns the group to which this agent address is binded to.
    Returns:
      the name of the group to which this agent address belongs to
    Since:
      MaDKit 5

  - ### getRole

    public String getRole()
    Returns the role to which this agent address is binded to.
    Returns:
      the role name to which this agent address belongs to
    Since:
      MaDKit 5

  - ### toString

    public String toString()
    Returns a string representing this address. This string contains the ID of the owner agent, the CGR location of this address and the `KernelAddress` to which this address belongs to.
    Overrides:
      `toString` in class `Object`
    Returns:
      a description of this address.

  - ### equals

    public boolean equals(Object agentAddress) throws ClassCastException
    Tells if another address is the same. If `true`, this means that both addresses refer to the same agent considering the same position in the artificial society.
    Overrides:
      `equals` in class `Object`
    Parameters:
      `agentAddress` - the address to compare.
    Throws:
      `ClassCastException` - On purpose, if the address is compared to an object with another type which is considered as a programming error.

  - ### hashCode

    public final int hashCode()
    The hash code of an agent address. It is the same as the underlying agent's. See `AbstractAgent.hashCode()`
    Overrides:
      `hashCode` in class `Object`

  - ### isFrom

    public boolean isFrom(KernelAddress kernel)
    Tells if the address is from a specific kernel. If `true`, This means that the agent to which this address belongs to is located on the tested kernel. So, it is just a shortcut for *

         return getKernelAddress().equals(kernel);

    for which this address has been created was running on the local kernel.
    Parameters:
      `kernel` - the kernel address against which this address should be tested.
    Returns:
      `true` if this address belongs to the corresponding kernel.
    Since:
      MaDKit 5.0.4

  - ### getAgentNetworkID

    public final String getAgentNetworkID()
    Return a string representing a unique identifier of the binded agent over the network.
    Returns:
      the agent's network identifier

  - ### getSimpleAgentNetworkID

    public final String getSimpleAgentNetworkID()
    Return a string representing a shorter version of the unique identifier of the binded agent over the network. As a simplified version, this string may not be unique.
    Returns:
      a simplified version of the binded agent's network identifier
    See Also:
      - `AbstractAgent.getSimpleNetworkID()`