matt protocol
[09/10/2008 21:42] marc allen
contents
introduction
protocol entities
protocol entity interfaces
ice implementation
mediator
examples
downloads
q&a
contact
links
introduction
The matt protocol describes a way to relay distreet messages between distributed network entities.
The matt protocol will be deployed in the final of the 18th annual Loebner Prize for Artifical Intelligence (Sunday October 12th).
protocol entities
There are three key entities in the matt protocol:
Mailbox
 handles message storage and retrieval.
Participant
 a network entity which requires the ability to send and receive messages with its peers.
Mediator
 handles the assignment of a
Mailbox
  to a
Participant
In order to start a matt session there must exist:
At least one
Mediator
At least two
Participants
At least one
Mailbox
 per
Participant
In order for network entities to communicate with each other:
Each
Participant
 must
registerParticipant
 with a
Mediator
A
Mediator
 must ensure that each registered
Participant
 is assigned a
Mailbox
Participants
 perform
read
 /
write
 /
listen
 operations on their respective
Mailboxes
protocol entity interfaces
The following outlines the operations that can be invoked on each of the entities describe above:
Mailbox
::empty()
: returns false if there are pending unread messages, otherwise true.
Mailbox
::active()
: returns true if mutable operations can be performed on the
Mailbox
Mailbox
::read()
: returns the first unread message in the
Mailbox
Mailbox
::write(
String
)
: writes a message to the
Mailbox
Mailbox
::addListener(
EventListner
)
: registers an
EventListner
  with the
Mailbox
Mailbox
::removeListener()
: unregisters all
EventListners
EventListener
::onEvent(
EventType
,
String
)
: invoked by a
Mailbox
 on each new event
Participant
::setMailbox(
Mailbox
)
: assigns a
Mailbox
 to a
Participant
Mediator
::registerParticipant(
Participant
)
: registers a
Participant
 with
Mediator
ice implementation
The following is the listing for a matt compliant api implemented using zeroc's ice:
#ifndef MATT_COMPONENTS_ICE_20080309_1545
#define MATT_COMPONENTS_ICE_20080309_1545

/**
 * This Ice file outlines the distributed components for a MATT session.
 *
 * TIG participants are required to implement the roles::Participant class,
 * which is expected to implement the setMailbox method.
 *
 * Participants then have the option to either implementing an eventListener
 * which requires an onEvent method to be implemented or to devise some method
 * by which they poll a mailbox for new messages.
 *
 * Generated code for C++, C#, Java, Python and Visual Basic will be provided
 * and arrangements to support other languages can be made.
 *
 * Sample code will also be provided for creating proxies to a Mediator.
 *
 * Usage:
 *
 * 1. Participant instances connect to a Mediator service
 *
 * 2. Once a sufficient number of Participants have register the Mediator will
 *    assign mailboxes to each
 *
 * 3. Once a Participant has a mailbox assigned they may begin:
 *    Read/Write Operations on that Mailbox until the Mailbox is closed.
 *    They may register an EventListener while the Mailbix is active.
 *
 *    NOTE: A Mailbox may close for the following reasons:
 *      a. The allotted Time To Live (TTL) has been reached
 *      b. A registered EventListener fails to be responsive(*)
 *
 * 4. Once the Mailbox is closed/deactivated it will not be reopened.
 *
 * 5. Participants will have to re-register with a Mediator service in order
 *    to obtain a new Mailbox
 *
 * Please contact Marc Allen for more information: matt@1bdi.co.uk
 */

module
matt {
/**
 * Exception base type
 */

exception
MattException {
/**
 * Description of the exception
 */

string
description;
};

/**
 * This exception is thrown when an RMI occurs on an inactive entity
 */

exception
MattNotActiveException
extends
MattException {
};

/**
 * This exception is thrown when an RMI fails because there are not pending messages
 */
exception
MattNoMessageException
extends
MattException {
};

/**
 * Base Listen Exception - something went trying to (add|remove) a listener
 */
exception
MattListenException
extends
MattException {
};

/**
 * Exception thrown because there is already an EventListener registered
 */
exception
MattAlreadyListeningException
extends
MattListenException {
};

/**
 * Exception thrown because there was no previous EventListener to unregister
 */
exception
MattNotListeningException
extends
MattListenException {
};

/**
 * This module handles communications between TIG participants
 */
module
messaging {
/**
 * Valid communication events
 */
enum
EventType {
Message,
Closed
};

/**
 * Participants may choose to have message pushed to them
 */
class
EventListener {
/**
 * Callback member function describing the event that triggered
 */
void
onEvent(EventType event,
string
message);
};

/**
 * Facilitates read/write operations on messages
 * The mailbox can be used in either a pull or push mode,
 * i.e. clients of the mailbox may register an event_listener
 * which will push new messages as they are received.
 * Alternatively clients may choose to poll the mailbox for
 * new messages.
 */
class
Mailbox {
/**
 * If the mailbox has pending messages this return false
 */
bool
empty();

/**
 * Returns true if mailbox is still in service
 */
bool
active();

/**
 * Returns the first unread message in the mailbox
 * Will throw an exception if (empty() == true)
 */
string
read()
  
throws

    MattNoMessageException,
    MattNotActiveException;

/**
 * Posts a message via the mailbox
 * May throw an exception if (active() == false)
 */
void
write(
string
message)
  
throws

    MattNotActiveException;

/**
 * Registers an event_listener with the mailbox
 *
 * The mailbox will trigger the on_event message of the
 * listener each time a new message is received with an
 * event_type of "message".
 *
 * If the mailbox is closed gracefully the listener will
 * also be informed with a "closed" event message.
 *
 * A mailbox will support no more than one event_listener
 * per client.
 *
 * If calling listener->on_event(...) fails the mailbox will
 * assume the client is no longer available and the mailbox will
 * close.
 */
void
addListener(EventListener * listener)
  
throws

    MattAlreadyListeningException,
    MattListenException,
    MattNotActiveException;

/**
 * Unregisters an EventListener
 */
void
removeListener()
  
throws

    MattNotListeningException,
    MattListenException,
    MattNotActiveException;
};
};

/**
 * There are two roles in TIG, this module encapsulates these
 */
module
roles {
/**
 * Participants communicate with one-another via their mailbox
 * which is assigned to them by the mediator once they have registered.
 */
class
Participant {
void
setMailbox(matt::messaging::Mailbox * mb);
};

/**
 * Assigns mailboxes to registered clients.
 */
class
Mediator {
void
registerParticipant(Participant * p);
};
};
};

#endif
/*MATT_COMPONENTS_ICE_20080309_1545*/
mediator
I will update this page with code for a mock
Mediator
 shortly
examples
In the downloads section below I have added a tar containing the matt.ice file, a sample server/client implementation in C++ and the necessary files/projects to build these on Windows, Linux and Mac OSx.
In addition to the code.tar.gz file you will need to ensure that your platform has: Boost 1.35, gcc (linux/mac) or visual studio 2003 and Ice 3.2.1.
Setting up your environment.

  • Ensure the required software packages are installed (Boost, Ice, compiler).
  • untar the files (this will create a directory called "code").
  • On linux or mac, cd to the code directory and type "make"
  • On windows, open the visual studio project under code/exmaples/vc7
    •

    Running the smaple apps... the code generates two identical binaries, differing only in name called server.tsk/client.tsk on linux/mac and server.exe/client.exe on windows.
    To run the server you must type:
    $ ./server.[tsk|exe] --Ice.Config="/code/examples/config/server.cfg"

    To run the client you must type:
    $ ./client.[tsk|exe] --Ice.Config="/code/examples/config/client.cfg"

    Note on linux/mac you can also cd in to the "exmaples/cpp" directory and type:
    $ make run

    This will start the server and client as required.

    The sample server is very basic merely echoing back to a client what has been sent to it, an echo server if you will. It is not very robust and is only intended as a tool to develope client apps.
    The sample client simply checks if there are any pending messages, if there are reads them, otherwise sends "hello".

    If you have any problems please contact me. I am happy to extend these smaple apps if you have any addition requirements.
    Please to not reply on the implementation of the sample server - it is a sample.
    downloads
    matt.ice interface file as specified above
    cpp.tar.gz C++ binding
    csharp.tar.gz C# binding
    html.tar.gz documentation generated from matt.ice
    java.tar.gz Java binding
    matt.tar.gz interface file and Makefile which will create all bindings found on this page
    python.tar.gz Python binding
    vb.tar.gz Visual Basic binding
    code.tar.gz Matt Implementation Code/Examples
    noboost.tar.gz Matt Implementation Code/Examples without Boost dependancy
    withJavaClient.tar.gz Matt Implementation Code/Examples with Java client
    withJavaServer.tar.gz Matt Implementation Code/Examples with Java client and Server
    matt.exe Matt Implementation of client/server applicatiopns
    FileRelayClient.exe Matt Implementation of FileRelay client/server applicatiopns
    matt_bug_fix.exe Matt Implementation of client/server applicatiopns with GUI bug fix
    q&a
    How do I install Ice?
    ZeroC do a pretty good job at answering this question ;-)
    Just take a look at their download page: http://www.zeroc.com/download.html
    What do I do with the generated files, they are completely meaningless?
    You need to extend the abstract class
    matt::Participant
     and implement the
    setMailbox
     member function.
    You could also implement a
    matt::messaging::EventListener
     to have messages pushed to you, but this is optional
    Can we have some comments in the code please?
    Please look at the html download [or this page] for documentation.
    I've got the API integrated, is there a
    matt::Mediator
     I can register with?
    Ahh... I've not implemented one yet, I will do a Mock soon!
    In the mean time you could repeat what you did for the
    matt::Mediator
     and
    matt::Mailbox

    Admittedly, there's a little more code to these... but for the sake of proof of concept/mock returning a static message or implementing an echo should be fine, no?
    contact
    If you have any questions please contact Marc Allen at: matt@1bdi.co.uk
    http://www.rdg.ac.uk/cirg/loebner/cirg-loebner-main.asp