Table of Contents

Blackboard Service

The blackboard service provides a means for agents to exchange information in two important ways: publish-subscribe (push) and querying.

Publish-subscribe (push)

The data is organized into particular areas identified by a readable string, also called topics. The use of topics works very similar to a message queue. Agents can subscribe to topics to be notified of new items and agents can register themselves with a callback interface to be called automatically as these data items come in. Such a method for passing data is often called a 'push' message box, as the data is pushed as soon as possible from the blackboard to the agent. The topics are also persisted, so that agents that connect at later times can find out what has been published so far. At the moment, the topics are persisted in memory only, so care should be taken by agent developers not to exhaust the memory resources.

Blackboard Querying

Even though data is passed to other currently subscribed agents immediately, the data is kept in memory until an agent removes it. Any agent can remove any piece of data, but it must pass the universally unique identifier that is assigned to the blackboard data item to do so, or use a generic blackboard query to remove a range of data items. While the data has not yet been removed, agents can query the data using a BlackboardQuery. This allows agents to retrieve particular data items that satisfy the query criteria. These criteria are currently specified by adding predicates to the BlackboardQuery instance. The blackboard will then execute these predicates on the server side and find all blackboard items that qualify. It is not possible to query data across topics, so an agent can only search in one topic at a time.


The interface to the blackboard is available from the source code. Below is the explanation what each method does:

public interface BlackboardService extends Service {
        // This is the callback interface that agents should implement to be notified. See the blackboard-example
        // on how this should be used.
	interface IBlackboardNotification extends ServiceListener {
		public void onData( BlackboardItem data );
	 * Publishes a data item on the blackboard. Data items *must* inherit from BlackboardItem.
	public DataHandle publish( String dataDomainName, BlackboardItem data ) 
		throws BlackboardException;
	 * Subscribes to a data domain, returning an identifier for the subscription
	public String subscribe( BlackboardQuery query, IBlackboardNotification notify ) 
		throws BlackboardException;
	 * Unsubscribes from a data domain using the sub key from the subscription call
	public void unsubscribe( String domainName, String subIdentifier ) 
		throws BlackboardException;
	 * Queries data domain for matching data items.
	public List<BlackboardItem> query( BlackboardQuery query ) 
		throws BlackboardException;
	 * Removes a particular data item from the data domain
	public void remove( DataHandle handle ) 
		throws BlackboardException;
	 * Removes a (number of) particular data item(s) from the data domain by running a query.
	public void removeByQuery( BlackboardQuery query ) 
		throws BlackboardException;
	 * This counts the messages within a particular data domain
	public int count( String dataDomainName ) 
		throws BlackboardException;

To import the org.iids.aos.blackboardservice.* classes in your agent, either

  1. manually add blackboard-service-interface-2.0-m4.jar (found in your $AGENTSCAPE_HOME$/lib/shared dir) to your agent jar's class-path (without leading path), or
  2. add the following dependency to your agent's Maven project file (pom.xml) for automated linking by your Maven-enabled IDE:


The topics have a predefined format to enable automatic selection of persistence and relay requirements. The topic names must be separated by a dot '.' and start with the purpose of the data items, followed by the scope of the data items. Application developers usually only need to specify the App purpose qualifier (but are free to listen on the Platform topics).

The following purpose qualifiers exist:

Purpose qualifier Description
App Application use. This is where data items are stored that belong to a particular application running on the agentscape platform.
Platform Platform use. This is where data items may be stored for services running on the platform.

The scope qualifiers are explained as follows:

Scope qualifier Description
Global The global scope will propagate data items to any other agentscape platform that is connected to the underlying distributed storage scheme. In this version of blackboard, there is no propagation.
Cluster The cluster scope will propagate data items within a cluster of agentscape hosts.
Local The local scope will not propagate data items from the host to any other.

Some examples for valid topic names:

  • App.Global.MyApplication.Sensordata
  • Platform.Global.Heartbeat
  • App.Local.MyApplication.SensorExchange

Please refer to the blackboard agent example in the source code tree for more information on blackboard usage and a programming example FIXME.

development/service/blackboard_service.txt · Last modified: 2012/05/15 14:17 by reinier