Create a new class of Agent

This tutorial explains how to create a new class of Agent.

In the SkyData concept, there are three kinds of agents:

• Harbour managers: each one manages a harbour (represented by the class SKHM)
• SKD: each SKD has data (images, text, articles, etc.) and a family (a group of replicas) (represented by the class SKD)
• SkyWorker: Each one is created by an SKD and has a specific task.

This tutorial will explain how to create a basic version class of SkyWorker that does not exist in the prototype.

What is a SkyWorker

As previously mentioned, a SkyWorker is an agent created by an SKD to perform a specific task.

For example, the task could be:

• Migrate to a specific Harbour
• Stay at a specific Harbour to act as a relay
• Migrate to all Harbours
• And so on

Therefore, a SkyWorker does not have data ; rather, it has a parent (the SKD creator) and a list of specific behaviours.

Code of the SKAgent

To create a new agent, we must inherit the SKAgent class.

To do so, let's create the class SKW:

public class SKW extends SKAgent {

    /**
     * The list of the specific behaviours
     */
    private Map<String, Object> harbour = new HashMap<>();

    /**
     * ID of the SKD creator
     */
    private SKAID parent = null;

    /**
     * Construct a new SKW
     */
    public SKW() {
        super();
    }
    /**
     * Initialize a SKW
     */
    @SuppressWarnings({ "unchecked", "unused" })
    @Override
    protected void setup() {
        super.setup();

        /*
        Add some logic here. For example: 
        - Communicating regularly with the parent
        - Verify if the goal is accomplished and delete itself if needed
        - and so on
        */
    }
}

Deploy the new agent

According to the Usage section, to use this new agent in the Harbour configuration, you must compile the agent class to create a JAR and copy it in the folder jarManager (see How to run an experiment).

To do that, you can use the following command (directly in the build directory (for example in skd/build/classes/java/main/)):

jar cvf skydata_internal_agents_SKD.jar skydata/*

Internal update

In order to react to any special internal events, a callback mechanism is implemented in the prototype.

The idea is simple:

1. The agents define the name of events (strings)
2. The behaviours add callbacks to some events (by using the function addInternalUpdate)
3. When the event occurs, the agents execute all callbacks listening on this event (by using the function internalUpdate)

Some events can execute callbacks with parameters (for example the event FAMILY_UPDATE) by passing it to internalUpdate.

Currently, the list of the events is:

• AFTER_MIGRATION: throw when the migration is finished
• AFTER_REPLICATION: throw when the replication is finished
• WANT_MIGRATE: throw when an agent wants to migrate (pass the destination as parameter)
• DELETION: throw when an agent wants to delete itself
• FAMILY_UPDATE: throw when we update the position of a family member (pass its identity as parameter)
• FAMILY_ADDED: throw when we add a family member
• FAMILY_REMOVED: throw when we remove a family member

Some useful functions to code a new agent

This section lists useful functions for a new agent and references their documentation links:

General functions:

• setup: use at the creation of the first agent (not called after a replication)
• reset: called at each initialization of the agent (creation and after a replication)

To send or receive messages:

• skSendNormal: send a message to another agent without using the reliable sending protocol. (See here)
• skSendReliable: send a message to another agent using the reliable sending protocol. (See here)
• broadcast: broadcast a message to a list of agents (you can specify if you want to use reliable sending protocol) (See here)
• skReceive: receive a message matching a message template (See here)

To store permanently an object in the memory of migration (even after a replication):

• createStorageObject: take a key and an object and store this object referenced by the key (See here)
• getStorageObject: get an object referenced by a specific key (See here)
• hasStorageObject: verify if an object is stored (See here)

Manage the migration:

• afterMove: called just after a migration (See here)
• doMove: called during the migration process (See here)
• beforeMove: called just before the migration process (See here)
• blockMigrate: block the migration temporarily (See here)
• unblockMigrate: unblock the migration (See here)
• canMigrate: verify if the agent can migrate (See here)
• migrate: initiate a migration process on a specific Harbour (See here)

Manage the replication:

• afterClone: called just after a replication (See here)
• doClone: called during the replication process (See here)
• beforeClone: called just before the replication process
• blockReplicate: block the replication temporarily (See here)
• unblockReplicate: unblock the replication (See here)
• canReplicate: verify if the agent can replicate (See here)
• clone: initiate a replication process on a specific Harbour (See here)

All function documentation is available here.