Protocol

Eve defines an interaction protocol between agents. This protocol consists of a common RPC language and some expected behavioral patterns. In this section of the documentation this interaction protocol is described:

• Communication Protocol describes the RPC language for the agents.
• Required methods describes the standard methods of an agent.
• Management methods describes optional methods that an implementation should make available to administrators and developers.
• Interaction patterns describes common behavior that implementations should provide to agents, with associated methods.
• Documentation links to resources related to the JSON-RPC protocol.

Communication Protocol

Eve agents communicate with each other using the JSON-RPC protocol. This is a simple and readable protocol, using JSON to format requests and responses. JSON (JavaScript Object Notation) is a lightweight, flexible data-interchange format. It is easy for humans to read and write, and easy for machines to parse and generate. JSON-RPC version 2.0 is the minimally required version, because Eve uses named parameters.

A request from Agent X to agent Y can look as follows:
Agent X addresses method add from agent Y, and provides two values as parameters. Agent Y executes the method with the provided parameters, and returns the result.

http://myserver.com/agents/agent_y

{
    "jsonrpc":"2.0",
    "id": 1,
    "method": "add",
    "params": {
        "a": 2.2,
        "b": 4.5
    }
}

{
    "jsonrpc":"2.0",
    "id": 1,
    "result": 6.7,
    "error": null
}

Required methods

MethodDescription

The method getMethods of Eve agents returns an array with method descriptions. The method descriptions have the following structure:

For example a method add(a,b) can be described as:

{
        "result": {
            "type": "Double"
        },
        "method": "add",
        "params": [
            {
                "name": "a",
                "required": true,
                "type": "Double"
            },
            {
                "name": "b",
                "required": true,
                "type": "Double"
            }
        ]
    }

Management methods

• scheduler.getTasks()

Interaction patterns

This part of the protocol description defines expected capabilities of Eve agents. These capabilities are optional, but are highly advisable as they offer better system-wide robustness and usability. It may be expected from the various Eve implementations to provide these out-of-the-box. Currently the following patterns are described: - Publish-subscribe model - Result monitor model

Publish-subscribe model

Description

Through the event subscription model, agents can request to be informed when a certain event is triggered. The two agents involved (subscriber and publisher) should share a common list of events. When the publisher triggers the event, it will call the provided callback method of the subscriber.

Public methods

Result monitor model

Description

The result monitor model offers robust, unidirectional synchronization of data. It basically allows an agent to keep up-to-date with the result value of a remote method. Traditionally this is achieved through an event subscription, indicating changed data, followed by a call to the specific method. Care must be taken to make sure the event is delivered to the agent, even in potentially unreliable network environments. A more robust, but less efficient solution would be to poll the method at a fixed interval. The result monitor model combines these solutions into one framework: it allows polling, event subscription and requesting a remote agent to push the result value at a fixed interval. Effectively it makes use of the time autonomy of the agents, making each responsible for trying to keep the data synchronized.

Agent behavior

To participate in the result monitor model, the agent should be able to repetitive request a remote method (poll), repetitively push the result of the method to another agent, push the result at a specific event (see publish-subscribe model) and potentially cache the result locally for future reference. Implementations are advised to bundle these three elements in one monitor API. As the polling and caching are locally organized, the only public methods are related to requesting the push behavior. The internal interface of this model will be documented in the implementation specific sections.

Public methods

Push configuration

The function monitor.registerPush requires a push configuration object PushConfig to configure a push monitor. The PushConfig object contains the following parameters:

Documentation

Documentation on the JSON-RPC protocol can be found via the following links:

• http://www.json.org
• http://json-rpc.org
• http://jsonrpc.org
• http://en.wikipedia.org/wiki/Json
• http://en.wikipedia.org/wiki/JSON_RPC