Defining custom contact networks / links

Every agent that lives in environment has visual non-removable element  connections that defines the contact network for this agent defined by the environment.

However, you may need to define more contact networks or single links. 

For example, if a person has parents, spouse and children, then the corresponding agent can have these references:

Person father
Person mother
Multiple link Person children

You may want your agent to communicate only with those agents that are among this agent connections. Links may be single or multiple, unidirectional or bidirectional.

Unidirectional and bidirectional links

You can establish contact links using the element  Link to agents.

 To create a new link to agents

  1. Drag the Link to agents element from the  Agent pallete onto the agent's diagram.
  2. Go to the properties of the link and specify the name of the link in the Name field. e.g. father
  3. Choose whether this link is Single (Single link option), or Multiple (Collection of links option). You may notice that the link icon changes when you change the link type.
  4. You may display links connecting your agents on the model animation. To show links on the animation, open the Animation section of the link's properties, and select the option Draw line connecting agents. Then configure the visual appearance of the link using the properties below: choose whether you want to draw the link behind agents, or on top of them, and set the link's line color, width, style (solid, dotted, or dashed), and choose the arrow position (end or center).

Properties

General

Name – The name of the link.

Show name – If selected, the link name is displayed on the agent diagram.

Ignore – If selected, the link is excluded from the model.

Visible – If selected, the link icon is visible on the animation at the model runtime.

Agent type – Choose here the type of the agent .

Collection of links  – If selected, the link is multiple - it connects the agent with several other agents.

Single link  – If selected, the link is single - it connects the agent with just one agent.

Make bidirectional/unidirectional – Click the button if you want to make the link bidirectional/unidirectional. Example of a bidirectional link: friend. Example of a unidirectional link: mother.

Communication

Message type –  Specify the type of the messages that will be received by these connections. You may need this to simplify access to the message fields in the On message received action,

You can choose one of the most-used types (int, double, boolean, String) using the corresponding option to the right. However, if your messages are of some other Java class, choose the Other option and specify the message type in the control to the right.

On message received  – Code to be executed when the agent receives a message from some another agent (possibly, from itself). Message sender is available in the code as sender, and the just received message as msg.

Forward message to – Here you can choose the message recipient statechart(s) that you want to process the received messages. To enable processing messages in some statechart, select the checkbox corresponding to this statechart in the given table.

Animation

You may display links connecting your agents on the model animation. To show links on the animation, select the option  Draw line connecting agents. Then configure the visual appearance of the link using the properties below: choose whether you want to draw the link behind agents, or on top of them, and set the link's line color, width, style (solid, dotted, or dashed), and choose the arrow position (end or center).

Managing the connections dynamically

Having created the contact link, you should make this link the reference to the required agent(s).

These references can be set when the agents are created or dynamically during simulation. The connections can be managed manually via agent functions, please refer here for the details. 

Here is the API you may use to change the connections at runtime. It differs depending on the type of the link (single or multiple):

Single link:

Agent getConnectedAgent() - returns the connected agent

connectTo( Agent a ) - adds a given agent to the connections of this agent and vice versa

boolean disconnect() - disconnects this agent from the currently connected agent

Collection of links:

LinkedList<Agent> getConnections() - returns the list of all connected agents

int getConnectionsNumber() - returns the number of connected agents

boolean isConnectedTo( Agent a ) - tests if this agent is connected to a given agent

Agent getConnectedAgent( int index ) - returns the connected agent with the given index

Agent getRandomConnectedAgent() - returns the randomly chosen connected agent

connectTo( Agent a ) - adds a given agent to the connections of this agent and vice versa

boolean disconnectFrom( Agent a ) - disconnects this agent from a given other agent

disconnectFromAll() - disconnects the agent from all other agents

Example:

father.connectTo(people(0));

Sending messages via link

Having created and initialized the link, you can send messages to the connected agent.

Single link:

send(Object msg) – sends the message to the connected agent

Collection of links:

send(Object msg, Agent dest) – sends the message to the specified connection

sendToAllConnected(Object msg)– sends the message to all connections

sendToRandomConnected(Object msg)– sends the message to a randomly chosen connection

Example:

For example, to send a message "Hi!" to the link named father, call father.send("Hi!")