Sharing Information Among Agents

In this Lesson

In this lesson you will learn how information can be shared among agents.

Concepts

Let’s begin with a brief review of the Agent Introduction lesson.

Agents live a hermit’s life because they run in seclusion from all other agents – even agents in their own session. Agents are unaware of the existence of other agents and therefore cannot communicate directly with them. Agents do interact directly with the Pump and it is the Pump’s responsibility to stitch the services (agents) together towards a common goal.

This service isolation combined with automated coordination provides very loose coupling without the disadvantages it typically brings. As a result you are encouraged to design highly cohesive services resulting in reduced module complexity, increased system maintainability, increased module reusability, and faster delivery of your product.



Agent’s may be hermit’s but they generally share information in common with other agents. There are 4 ways which agents may share information from within their little hermit-cave.

  1. Shared Storage
  2. Session Context
  3. Session Storage
  4. Connection Storage

This lesson describes each of these options. Let’s begin with a picture illustrating where these storage options are in relation to agents



Shared Storage

Shared storage is something you provide as part of your solution. A relational database is one example. Since all agents have access to the shared storage they are able to share the information it contains. For example, you could have one agent that maintains a configuration profile for your solution and all other agents read the configuration information that applies to them.

They also share the information contained in the solution’s data model. For example, if you were providing a solution to manage your sports car collection you would have multiple agents – each sharing some portion of the data model for cars.

Session Context

The purpose of session context is to provide real-time notification between agents using a publish / subscribe model.

Key Values
One use of context is to control the topic of conversation. Keys representing entities in your data model are shared among agents to keep them focused on a specific set of information. For example, your sports car collection solution would have some agents which publish the key for a specific car and other agents which display detailed information about the selected car. In this way all agents in the conversation remain ‘focused’ on the same car.

Non-key values
Another use of context is to share non-key values of interest to other agents. Imagine two agents – the first agent collects various attributes about cars (color, make, model, year, number of doors, etc.). The second agent displays a list of cars matching the attributes. The first agent could publish the car attributes into context and the second agent would be notified when any of them changed and respond by updating the list of cars to match the selected attributes. These context values are not keys representing an entity in your object model. They are simply shared values which require a real-time notification among agents.

Event-Style Values
Imagine the same two agents. The first agent collects the car attributes and places them in shared storage and simply publishes a value used to indicate the attributes have changed. The second agent subscribes to this ‘event-style’ value and when it is notified of a change it looks up the attributes from shared storage and updates the list of cars.

Important
Context should contain the minimum set of information required to coordinate activity among agents.
Danger
Do not use context to share non-key information about an entity. For example, the agent which published the car key should NOT also publish other information about the car such as description, color, etc. in an effort to make it easier for subscribers to obtain and display those additional attributes. Agents which display entity information should always use a key to read the current entity attributes from the shared storage (i.e. the database). Why? Solutions are multi-user systems. Other users may be changing attributes about your entities.

Session context is only guaranteed to remain available during the life-cycle of a single scene. Values can be removed from context after a scene closes. For example, the default implement of Soiree’s menu navigation will clear non-global context values from context before starting a scene.

Tip
If you want to ensure context values remain in a session across scene boundaries then you should define them as Global Context in the product definition.

Session Storage

Agents may share information by storing it on the session. Information stored on the session will remain available until the session is closed.

Session storage is managed as a collection of name / value pairs. You may remove information from session storage by associating a named value with null.

Objects
The following com.seronix.pump.Pump methods are used to manage session storage

  • public static Serializable putSessionObject(Conversation conv, String key, Serializable value)
    This method stores the specified value and associates it with the named key in the conversation’s active session. The method returns the object previously associated with the key or null if no value is associated with the key.
  • public static Serializable putSessionObject(Agent agent, String key, Serializable value)
    This method will store the object in the agent’s session.
  • public static Serializable getSessionObject(Conversation conv, String key)
    This method returns the object associated with the key in the conversation’s active session or null if no value is associated with the key.
  • public static Serializable getSessionObject(Agent agent, String key)
    Get the object from the agent’s session.

Strings
The com.seronix.pump.Pump class also provides convenience methods which can be used to easily put and get String values.

  • public static String putSessionValue(Conversation conv, String key, String value)
    This method stores the specified String value and associates it with the named key in the conversation’s active session. The method returns any String previously associated with the key. If the key is associated with a non-String value then calling this method will cause an Exception to be thrown.
  • public static String putSessionValue(Agent agent, String key, String value)
    This method will store the value in the agent’s session.
  • public static String getSessionValue(Conversation conv, String key)
    This method returns the String associated with the key or null if no value is associated with the key. If the key is associated with a non-String value then calling this method will cause an Exception to be thrown.
  • public static String getSessionValue(Agent agent, String key)
    This method returns the value from the agent’s session.

Connection Storage

Agents may share information by storing it on the client connection. Information stored on the connection will remain available until the connection is closed by the client or timed out via the connection manager.

Connection storage is managed as a collection of name / value pairs. You may remove information from connection storage by associating a named value with null.

Objects
The following com.seronix.pump.Pump methods are used to manage connection storage

  • public static Serializable putConnectionObject(Conversation conv, String key, Serializable value)
    This method stores the specified value and associates it with the named key. The method returns the object previously associated with the key or null if no value is associated with the key.
  • public static Serializable getConnectionObject(Conversation conv, String key)
    This method returns the object associated with the key or null if no value is associated with the key.

Strings
The com.seronix.pump.Pump class also provides convenience methods which can be used to easily put and get String values.

  • public static String putConnectionValue(Conversation conv, String key, String value)
    This method stores the specified String value and associates it with the named key. The method returns any String previously associated with the key. If the key is associated with a non-String value then calling this method will cause an Exception to be thrown.
  • public static String getConnectionValue(Conversation conv, String key)
    This method returns the String associated with the key or null if no value is associated with the key. If the key is associated with a non-String value then calling this method will cause an Exception to be thrown.

That concludes this lesson.