Awareness Protocol

Manuele Kirsch Pinheiro

Project CEMT (II-UFRGS / Opera-INRIA Cooperation)

Contents

1. Goal and structure
2. Methods
3. Data
4. Examples
5. Complete awareness protocol DTD

This document describes the awareness protocol defined for the Project CEMT. The document is divided in three sections : in the first section, the protocol's goal and structure are described; in the second, its methods are detailed and, in the third section, its data elements are described. The section 4 gives some usage examples of this protocol, and the section 5 present the complete DTD for this awareness protocol

1 Goal and structure

The main goal of this protocol is to exchange awareness informations between clients and a server. These awareness information include informations about the user (member of a group), his/her preferences (his/her profiles) and papers, and, of course, his/her activities, referenced here as events. The user produces the awareness information in the clients, which format and pass this information to the server using this protocol. The server, by its turn, is responsible for control and storage it in a reliable data base.

This awareness server is not a general purposes server. It should be designed to deal with a specific set of activities from a specific user group. For example, in Project CEMT, this server was designed to deal with an user group in an e-learning authoring activity, and the client used was modified to communicate the awareness informations generated during this process to the server.

This proposed awareness protocol is a application level protocol based in TCP sockets (see Figure 1). By using TCP as transfer protocol, this awareness protocol intents to be a connection oriented protocol, with all the guarantees from TCP to deal with duplicate or lost packets, and unordered delivery. It is also a request/response protocol: a client sends requests in XML format to the server, which also responds in XML format. These requests are referenced here as methods.

This awareness protocol includes 17 methods for manipulating these awareness informations and for control purposes (begin, end, beginevent, endevent, cancelevent, getevents, newuser, newprofile, newpaper, setuser, setprofile, setpaper, getuser, getprofile, getpaper, nop and response). These methods are describe in the section 2, and the informations manipulated by these methods (events, members, profiles and papers) are described in section 3. These methods, during a connection established between client and server, must obey a specific order. The client must send its requests respecting this order, showed below, and for each request, the server must respond using the "response" method.

All those methods (including the server response) use a XML syntax, which is presented in the next section. At the end of this document, the complete DTD for this protocol is presented.

2 Methods

The methods begin, end, response, getevents, beginevent, endevent and cancelevent must be always implemented. The other methods may be suppressed by the client implementation, but the resulting environment will be very limited.

All those methods use awareness information such as members and events. These information are also transmitted in a XML syntax, and their elements are describe in section 3.

2.1 Method "begin"

The first method in all connections between a client and the server in this awareness protocol must be the method begin. This method indicates that a session is begging and what user is responsible for this session.

<!ELEMENT begin (member) >

2.2 Method "end"

This is the last method to be called in a connection. It simply indicates the end of the session and, by consequence, the end of the communication between client and server.

<!ELEMENT end EMPTY >

2.3 Method "response"

The method response is used by the server to send the response to client's requests. It may includes awareness informations like events, members, profiles or papers, or a status line, which may contain an human readable message.

<!ELEMENT response ( status | event* | paper* | profile* | member* ) >
<!ATTLIST response type ( OK | NOK ) #REQUIRED >
<!ELEMENT status (#PCDATA)>

2.4 Methods "beginevent", "endevent" and "cancelevent"

Those methods intent to inform, respectively, the beginning, the conclusion and the cancellation of an activity (event) in the client side.

<!ELEMENT beginevent ( event ) >
<!ELEMENT endevent ( event ) >
<!ELEMENT cancelevent ( event )>

2.5 Method "getevents"

The method getevents is used by the client to request awareness informations from the server. The server must return the awareness informations that accord with the user's profiles. If no user is provided for the getevents method, the server must use the user's information supplied by the begin method.

<!ELEMENT getevents ( member+ ) >

2.6 Method "nop"

This method may be used by the client to indicates that it want to keep the connection with the server, despites the user is doing nothing. It can be used to prevent time-out in the connection when a user is not doing any activity that produces awareness informations.

<!ELEMENT nop EMPTY >

2.7 Methods "newuser" and "setuser"

These methods are used to, respectively, create a new user or set the informations of an existent one.

<!ELEMENT newuser ( member ) >
<!ELEMENT setuser ( member ) >

2.8 Methods "newprofile" and "setprofile"

These methods are used to, respectively, create a new profile or set the informations of an existent one.

<!ELEMENT newprofile ( profile ) >
<!ELEMENT setprofile ( profile ) >

2.9 Methods "newpaper" and "setpaper"

These methods are used to, respectively, create a new paper or set the informations of an existent one.

<!ELEMENT newpaper ( paper ) >
<!ELEMENT setpaper ( paper ) >

2.10 Methods "getuser", "getprofile" and "getpaper"

These methods are used by the client to request to the server informations about one or more users, profiles and papers, respectively. If no user, profile or paper information is passed in the request, the server must assume that the client wants the informations of all users, profiles or papers registered.

<!ELEMENT getuser ( member* ) >
<!ELEMENT getprofile ( profile* ) >
<!ELEMENT getpaper ( paper* ) >

3 Data

All methods from this protocol manipulate awareness informations. These informations represent activities (event), users (member), papers and profiles informations and they are also described in a XML syntax, which is showed below.

3.1 Event

An event represents an activity important for the group work. Each activity has a type and a name, and when an activity is executed, it is done by an user at a determinate interval of time, and it includes a description and some details about what have been made.

<!ELEMENT event (description?, details?, time?, member?, specialdata*) >
<!ATTLIST event type CDATA #REQUIRED
                name CDATA #IMPLIED >

<!ELEMENT description (#PCDATA | info)* >
<!ELEMENT details (#PCDATA | info)* >

<!-- small piece of information. Can be used to structure the description and details information -->
<!ELEMENT info (#PCDATA) >
<!ATTLIST info name CDATA #IMPLIED >


<!-- for expansion purposes -->
<!ELEMENT specialdata ANY >

3.2 Time

A time element represents a date/time interval, described as an initial and a final moment. These initial and final moments are represented in the time element as attributes (bg and ed attributes, respectively). Each of these attributes are described using the date/time description of the RFC1123 (also used in HTTP/1.1 and SMTP protocols), which updates RCF822. This date/time description used for these attributes is showed below :

The time element is describe as :

<!ELEMENT time EMPTY>
<!-- bg and ed attributes include date/time specification as describe in protocol specification -->
<!ATTLIST time bg CDATA #REQUIRED 
               ed CDATA #REQUIRED >

3.3 Member

A member represents an user in the group. Each user has a type, which identifies what kind of user he/she is, and also an id and a login, which identify he/she in an unique way. It includes also other useful informations about the user, as name, machine, mail and homepage, and a time interval of his/her last login in the system.

As any user in this protocol is seen as part of a group. This user may have roles (papers) to play in this group and he/she may have also his/her preferences about what activities, among the group activities, he/she should be notified. To represent these concepts, the member element includes the profile and paper lists, where a server or a client may describe those informations about the user.

<!ELEMENT member ( name?, mail?, homepage?, time?, machine?, proflist?, paperlist?, specialdata* )>
<!ATTLIST member type CDATA #IMPLIED
                 id   CDATA #IMPLIED
                 login CDATA #REQUIRED >
<!ELEMENT name (#PCDATA)>
<!ELEMENT mail (#PCDATA)>
<!ELEMENT homepage (#PCDATA)>
<!ELEMENT machine (#PCDATA)>
<!ELEMENT proflist ( profile* )>
<!ELEMENT paperlist ( paper* )>

3.4 Profile

An user may indicate what kind of awareness information he/she wants. A profile indicate what events (activities) are interesting for the user and the time interval in which they are interesting. A profile, according to its type, can be associated to a member, to a paper (representing the awareness informations that are absolutely necessary for playing this paper), or both (representing the awareness informations that a user wants when he/she is playing this paper).

<!ELEMENT profile ( time?, association?, event* )>
<!ATTLIST profile type CDATA #REQUIRED
                  id CDATA #IMPLIED
                  name CDATA #IMPLIED >

<!ELEMENT association ( member | paper | (member, paper) )>

3.5 Paper

A paper describes a role that can be played by the users.

<!ELEMENT paper ( description? )>
<!ATTLIST paper type CDATA #REQUIRED
                id CDATA #IMPLIED 
                level CDATA #IMPLIED
                name CDATA #IMPLIED >

4 Examples

In this section, an example is presented to illustrate the use of this awareness protocol.

As described in section 2, this protocol must obey an specific order. Any communication should begin with the method begin. So, this example will start with this method :

<begin>

    <member type='4' login='kirsch' id='1004'>

     </member>

</begin>

<response type="OK">

</response>

Here, the client requests the beginning of the communication with the server for a user already known by the server (user id '1004' and login 'kirsch' from the type '4'). The server respond with an "OK", which identifies that the request is correct and was accepted.

After this start, the client can initiate its activities. It may signal to the server, for example, that an event has began :

<beginevent>

   <event type='101' name='savedocument'>

   </event>

</beginevent>

<response type="OK">

</response>

In this example, the client signals to the server that a "savedocument" event (event type '104') has began, and the server indicates with its response "OK" that the request is correct and was accepted.

A few moments later, the user may conclude the activity that generates this event "savedocument". The client can request the end of this event to the server, and also pass to the server all informations about the finished event.

<endevent>

   <event type='101' name='savedocument'>

		     <description> The document Test.html has been saved/consolidated by the user </description>

       <details>

           <info name="machine"> gnome </info>

       </details>

       <time bg="Tue, 16 Oct 2001 15:23:00 GMT" ed="Tue, 16 Oct 2001 15:30:00 GMT" />

       <member type="4" login="kirsch" id="1004"> </member>

   </event>

</endevent>

<response type="OK">

</response>

In this communication, the client instructs the server that the last "savedocument" event has been concluded and passes the informations about this event : its descriptions, details, time interval and member. The info element is used to structure the details : here, it was used to inform that this event was executed in the machine named "gnome".

Anytime after the beginning of the communication, the user may also ask for awareness informations. This can be done using the method getevents :

<getevents>

<member type="4" login="kirsch" id="1004"> </member>

</getevents>

<response type="OK">

   <event type='101' name='savedocument'>

        <description> The document Test.html has been saved/consolidated by the user </description>

        <details>

            <info name="machine"> gnome </info>

        </details>

        <time bg="Tue, 16 Oct 2001 15:23:00 GMT" ed="Tue, 16 Oct 2001 15:30:00 GMT" />

        <member type="4" login="kirsch" id="1004">

             <name>Manuele Kirsch Pinheiro</name>

             <mail>Manuele.Kirsch_Pinheiro@inrialpes.fr</mail>

             <homepage> http://www.inf.ufrgs.br/~manuele/ </homepage>

        </member>

   </event>

   <event type='101' name='savedocument'>

        <description> The document index.html has been saved/consolidated by the user </description>

        <details>

             <info name="machine"> host </info>

        </details>

        <time bg="Tue, 10 Oct 2001 10:23:00 GMT" ed="Tue, 10 Oct 2001 10:30:00 GMT" />

        <member type="4" login="guest" id="1001">

              <name>Guest user</name>

        </member>

   </event>

</response>

In this example, the client asks for the awareness events produced that fits the user's profiles. The server accepted this request and responds with two events.

Besides these operations involving events, the user may require informations about other users (or about himself), as shown in the next example :

<getuser>

<member type="4" login="guest" id="1001"> </member>

</getuser>

<response type="OK">

    <member type="4" login="guest" id="1001">

          <name> Guest user </name>

          <mail> </mail>

          <homepage> </homepage>

          <time bg="Tue, 10 Oct 2001 10:23:00 GMT" ed="Tue, 10 Oct 2001 12:30:00 GMT" />

          <machine> host </machine>

          <proflist>

              <profile type="8" id="1002" name="personalprofile">

                  <time bg="Tue, 10 Oct 2001 12:30:00 GMT" ed="Tue, 31 Dec 2002 23:59:00 GMT" />

                  <association>

                       <member type="4" login="guest" id="1001"> </member>

                  </association>

              </profile>

              <profile type="9" id="1003" name="personalpaperprofile">

                  <time bg="Tue, 10 Oct 2001 12:30:00 GMT" ed="Tue, 31 Dec 2002 23:59:00 GMT" />

                  <association>

                        <member type="4" login="guest" id="1001"> </member>

                        <paper type="11" level="2" name="writer"></paper>

                  </association>

                  <event type="101" name="savedocument"> </event>

              </profile>

          </proflist>

          <paperlist>

              <paper type="11" level="2" name="writer" id="1005">

                   <description> Writer role </description>

              </paper>

         </paperlist>

     </member>

</response>

Here the server replies with the guest's informations, including he/she's last login (time element inside member element), profiles (one personal profile and other profile associated with the paper "writer") and papers (just the "writer" paper).

The user may wish to change the informations about him/herself or about other user (if the server allows it). It may do this by using the setuser method. In the next example, a user tries to change the informations of an non-existent user, causing a response "NOK" by the server :

<setuser>

     <member type="4" login="manu" id="2004"> 
          <name> Manuele Kirsch Estefanel </name>          
          <mail> mkirsch@terra.com.br </mail>          
          <homepage> </homepage>         
          <machine> darkness </machine>
     </member>

</setuser>

<response type="NOK">

   <status>

        Method Failed : User unknown

   </status>

</response>

Finally, to finish the communication (and the work), the client sends an end method to the server :

<end \>

<response type="OK">

</response>

5 Complete awareness protocol DTD

<!DOCTYPE awareness [

<!-- ================== XML ELEMENTS FROM AWARENESS PROTOCOL ==================== -->

<!-- =============== Methods ============== -->
<!-- start and finish the connection -->
<!ELEMENT begin (member) >
<!ELEMENT end EMPTY >

<!-- response from the server -->
<!ELEMENT response ( status | event* | paper* | profile* | member* ) >
<!ATTLIST response type ( OK | NOK ) #REQUIRED >
<!ELEMENT status (#PCDATA)>

<!-- begin,end and cancel an event -->
<!ELEMENT beginevent ( event ) >
<!ELEMENT endevent ( event ) >
<!ELEMENT cancelevent ( event )>

<!-- request the event from the server base  -->
<!ELEMENT getevents ( member+ ) >

<!-- for the client inform to the server that the user is doing nothing -->
<!ELEMENT nop EMPTY >

<!-- creating and setting users, papers and profiles -->
<!ELEMENT newuser ( member ) >
<!ELEMENT setuser ( member ) >
<!ELEMENT newprofile ( profile ) >
<!ELEMENT setprofile ( profile ) >
<!ELEMENT newpaper ( paper ) >
<!ELEMENT setpaper ( paper ) >

<!-- requesting user, paper or profile information -->
<!ELEMENT getuser ( member* ) >
<!ELEMENT getprofile ( profile* ) >
<!ELEMENT getpaper ( paper* ) >


<!-- =============== Data =============== -->
<!-- event definition -->
<!ELEMENT event (description?, details?, time?, member?, specialdata*) >
<!ATTLIST event type CDATA #REQUIRED
                name CDATA #IMPLIED >

<!ELEMENT description (#PCDATA | info)* >
<!ELEMENT details (#PCDATA | info)* >

<!-- small piece of information. Can be used to structure the description and details information -->
<!ELEMENT info (#PCDATA) >
<!ATTLIST info name CDATA #IMPLIED >

<!-- for expansion purposes -->
<!ELEMENT specialdata ANY >

<!-- date/time interval -->
<!ELEMENT time EMPTY>
<!-- bg and ed attributes include date/time specification as describe in protocol specification -->
<!ATTLIST time bg CDATA #REQUIRED 
               ed CDATA #REQUIRED >

<!-- user definition -->
<!ELEMENT member ( name?, mail?, homepage?, time?, machine?, proflist?, paperlist?, specialdata* )>
<!ATTLIST member type CDATA #IMPLIED
                 id   CDATA #IMPLIED
                 login CDATA #REQUIRED >
<!ELEMENT name (#PCDATA)>
<!ELEMENT mail (#PCDATA)>
<!ELEMENT homepage (#PCDATA)>
<!ELEMENT machine (#PCDATA)>

<!-- list of the user's profiles -->
<!ELEMENT proflist ( profile* )>

<!-- list of the user's roles -->
<!ELEMENT paperlist ( paper* )>

<!-- profile definition -->
<!ELEMENT profile ( time?, association?, event* )>
<!ATTLIST profile type CDATA #REQUIRED
                  id CDATA #IMPLIED
                  name CDATA #IMPLIED >

<!-- used to associate a profile to a user or a role, or both -->
<!ELEMENT association ( member | paper | (member, paper) )>

<!-- role definition -->
<!ELEMENT paper ( description? )>
<!ATTLIST paper type CDATA #REQUIRED
                id CDATA #IMPLIED 
                level CDATA #IMPLIED
                name CDATA #IMPLIED >

]>