SSB Agent User Guide


To connect to the SSB, you need to follow a few simple steps:

  • Instantiate a “connector” instance.
  • Register handlers for any messages you want to receive in your application (see below).
  • Call the connector’s “connect” method.

The code to do this looks like:

  final ServiceBusConnector context = new ServiceBusConnector();
  // indicate which types of data you would like to receive
  final Set<MessageType> supportedMessageTypes = new HashSet<MessageType>();
  // add some listeners (see below for more details)
  context.addMessageListener(new IsMessageType(GooseMessageTypes.DATA_MATRIX), new DataMatrixMessageListener());
  context.addMessageListener(new IsMessageType(GooseMessageTypes.NETWORK), new NetworkMessageListener());
  // etc.

There are also some things about the context which you can optionally configure, if desired. See the JavaDoc for additional details.

The current version of the ServiceBusConnector connects to a server running on the local host. There isn’t yet support for automatically finding a server or starting a server if one isn’t found.


When your application is ready to exit, it should be a good SSB citizen and disconnect. A future version may detect when agents crash without disconnecting. But the current version doesn’t notice this situation. So if you fail to disconnect before exiting, your application will continue to appear on the list of active agents.

The disconnection procedure is very simple:


The context may be reused if you want to reconnect using the same context and the message listeners you registered earlier. If you want to register different message listeners, you need to create a new context instance, as there isn’t a way to unregister listeners.

Sending a Message

Send to a Single Agent

To send a message to a single agent, you need to:

  • identify the agent to receive the message
  • indicate what type of data the message contains
  • provide data to send

For example, if you want to send a data matrix to a specific agent, this is how you would do it:

    final DataMatrix matrix = createANewAndUsefulDataMatrx();
    context.sendAsync(destinationID, GooseMessageTypes.DATA_MATRIX, matrix);

The message is sent asynchronously and the send method may return before the message is actually delivered to the recipient.

Send to All Agents

You may also want to send a message to all agents who can receive a particular message type. This is accomplished similarly:

    final DataMatrix matrix = createANewAndUsefulDataMatrx();
    context.sendAsyncToAll(GooseMessageTypes.DATA_MATRIX, matrix);

The only difference is that, naturally, there is no need to identify the recipient agent in this case.

Custom Data Types

You may have some new type of data that you want to send but isn’t known to the SSB server. You don’t need to do anything special in this case aside from defining a new message type in your application. So, the steps for sending a custom message type are as follows:

    // define the message type
    public static final CUSTOM_GENE_DATA = new URIMessageType(URI.create(""));
    // as before...
    CustomGeneData data = createInterestingData();
    context.sendAsync(destinationID, CUSTOM_GENE_DATA, data);

The only things you need to worry about in this case are:

  • making sure that your message type is unique and no one else is using the same message type for some other purpose. This is made easier by using URIs as message types, so you can include information specific to your organization in the message type, which should reduce the likelihood of conflicts.
  • make sure that applications that want to receive your custom data know the message type URI to use.
  • make sure that your data can be sent over whatever transport your SSB instance is configured to use. The default is JMS, so any serializable data should be fine.

The service bus doesn’t care about the contents of your data, as the data is just serialized and passed from the sender to the recipient.

Receiving a Message

To receive messages, you need to define listener classes and register instances of them with the agent context.

Define a Listener

To receive a message, you need to provide a listener instance which the agent context can invoke when messages arrive. The listener interface has a single method in it. Here is a sample listener which handles data matrix messages:

     * Handles "data matrix" messages.
    private class DataMatrixMessageListener implements MessageListener
         * {@inheritDoc}
        public void handleMessage(final Message<?> message) 
            Validate.notNull(message, "null message");
            Validate.isTrue(message.getMessageType().equals(GooseMessageTypes.DATA_MATRIX), "unexpected message");
            doSomethingApplicationSpecificWithTheData(message.getSenderID().getID(), (DataMatrix) message.getData());

Register a Listener

Of course, you need to tell the agent context about your listener. You register listeners with the context, along with a filter object which determines which messages are actually delivered to this listener. There are a few predefined filters:

  • IsMessageType accepts only messages of a specific message type.
  • TruePredicate accepts all messages.

For example, if you want register a listener for only data matrix messages, you would do it like this:

  context.addMessageListener(new IsMessageType(GooseMessageTypes.DATA_MATRIX), new DataMatrixMessageListener());

And if you wanted one listener to handle all messages, you would do it like this:

  context.addMessageListener(new TruePredicate(), new LogAllMessagesListener());

It is fine to have more than one listener registered for a particular message. When a message arrives, all listeners whose predicates accept the message will receive the message.

agentuserguide.txt · Last modified: 2009/02/21 05:54 by etellman
Recent changes RSS feed Creative Commons License Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki