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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(Object agentAddress)` Tells if another address is the same.
    `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.
    `String` | `getSimpleAgentNetworkID()` Return a string representing a shorter version of the unique identifier of the binded agent over the network.
    `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 Detail

    - #### 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()`

Fabien Michel, Olivier Gutknecht, Jacques Ferber - February 12 2016