Defining the Flash RAD / RoomWare Server messages framework

Posted on October 16, 2009

1


Basics: The RoomWare Messages

There are four types of messages:

  1. event: contains data. Recieves no response
  2. action: contains data. Recieves a response
  3. request: contains data. Recieves a response
  4. response: contains data. Is sent as a result of an action (feedback) or a request.

APPROACH

Connecting to the RoomWare server

The RoomWare server is by default listening to port 8000 on your computer or on a web server. When you connect to the RoomWare server, you first have to transmit a “hello” to the RoomWare server. This “hello” contains the basic settings regarding your RoomWare client. These consists of two parts:

  1. The Application Key: this defines which cluster of RoomWare applications you want to join. Compare the key to a name of a chat-room you can join. You will only see/receive the messages sent within that room.
  2. The items you want to subscribe to: the subscribeto list acts like a filter with one ore more comma-separated search items. When someone sends a message with one of these stated items in their “broadcast” header: you will revieve that message.

Setup of the “helloRoomWare” message:

String helloRoomWare=
// Header
"subscribeto:evenName1,eventName2;applicationkey:myapplicaitonkey;"
+ (char)04; // Marker: End of transmission 
socket.sendMessage(helloRoomWare)

RoomWare Messages

RoomWare messages consists of two parts: 

  1. The RoomWare message header: telling the RoomWare server to which listeners the message should be broadcasted. 
  2. The RoomWare message body: with any type of content you choose. If you use XML, put at least a <message></message> tag as the XML body.

For each message you sent, the following rules are in place:

  1. The RoomWare message header is separated from the RoomWare message body by a ASCII code: 02 (char(02) or (char)02). The RoomWare server literally splits your message in two, using the ASCII 02 code as the separator. It is chosen for it’s fast and simple use.
  2. You close your message with a ASCII code 04 (“end of transmission”). When the RoomWare server, or any of your clients, listens to the byte-streams byte per byte, they will be able to separate one message from the other.

Setup of a RoomWare message (example)

String myMessage=
// Header
"broadcastto:eventName1,eventName2;type:event;"
+ (char)02 // Marker: Begin of text
+ "<message><body>mybody</body></message>" // Message body
+ (char)04; // Marker: End of transmission
socket.sendMessage(myMessage)

FLASH RAD FRAMEWORK

Types of RoomWare instructions in the Flash RAD framework

In the Flash RAD framework, most objects are embedded in forms. These forms can contain data. As an event fired via rw_event in most cases is meant to fire events in another Flash RAD application, there are two types of events: with form-data and without form-data.

  1. rw_event: an event. No form-data is sent, only the actions defined in the rw_event instruction. No response is sent back
  2. rw_dataevent: an event with data attached. This data is the form-data of the form the object is in. No response is sent back
  3. rw_action: the same as an event, but WITH a response. 
  4. rw_request: a request for something (data in most cases) from another source. A response is sent back.
  5. rw_response: the response on a request. Is sent by the Flash RAD framework.

BODY #2: Sending a RW message from the Flash RAD framework

There are two types: 

  1. Actions: these are the most simple type of messages and can be sent from any object that has an on{eventname} event-handler
  2. Data: these are sent from a Form. 

How to shape a RoomWare action

The RoomWare action consists of three parts: 

  1. The RoomWare reference: onClick=”rw_event *.myRoomWareConnector: rwListeners, rwActions;”
  2. The list of listeners who subscribed to this action: rwListeners=”submitPersonData,submitData
  3. The actual actions to be performed at the other side: rwActions=”reload *.itemlist:personID=[personID];

The RoomWare actions and listeners are separated from other actions as they refer to remote applications. In general you do not want to send and execute these actions locally.

How to setup a RoomWare Connector

A RoomWare Connector is a standard item in the flash RAD environment. This is how you set it up:

<roomwareconnector
name=”myRoomWareConnector
src=”http://myRoomWareServer.com:8080
applicationkey=”myApplicationKey
subscribeto=”bluetoothUpdate,remoteControlActions,submitPersonData>

The RoomWare Connector requires four parameters:

  1. name: the name of the connector, for reference by other objects in your Flash RAD application. 
  2. src: the URL to the RoomWare server. The semi-colon with the number is required and states the port-number to which the RoomWare server application is listening.
  3. applicationkey: the RoomWare Server can run multiple application clusters. The application key separates your application cluster from other application clusters.
  4. subscribeto: a list of the subjects of events / messages sent from other applications and devices in the RoomWare Application cluster

rw_dataevent: Posting complex data / form data to the RoomWare Server

You use a form to send complex data to the RoomWare server (or to any other form in your application). Like this:

onClick=”rw_dataevent *.myRoomWareConnector:rwListenersrwActions;”

The setup is exactly the same as the previous case. The difference is in what happens behind the screens: data from the form is inserted into the message.

Posting complex data from a form by another object

To post complex data from a form by a button-click-event, you use the customizable onCall_<eventname> event handler.

<form name=”myForm” onCall_myEventName=”“>

This is not implemented yet.

Basics: The RoomWare Message format

Within the Flash RAD Framework, messages can be sent to– and received from the RoomWare Server. To do this, a socket connection is used. The basic setup of a RoomWare message is this:

  1. the RoomWare message header contains the following parameters:
    1. broadcastto: This contains a comma separated list of all subscribers of your RoomWare application
    2. type: being either an action,  an event, a request or a response.
    3. slotid: the reference to the one who is expecting a response from a request or call for action
    4. clientid: the unique ID of the client
  2. the RoomWare message body which can contain any kind of text

The Flash RAD framework RoomWareMessage class

the Flar RAD framework RoomWareMessage class deals with constructing and parsing the RoomWare Server messages. It splits the data into two compartments:

  1. The RoomWare message header
  2. The RoomWare message body

It reflects the following RoomWare Message variables:

  1. broadcastto
  2. type
  3. slotid
  4. clientid
  5. body: which is the raw message body

The RoomWareMessage class does no further parsing of the data it receives or sends.

BODY #1: The setup of a Flash RAD framework message

A Flash RAD framework message contains all the data for internal processing. These are two parts:

  1. <actions>: this contains the actions to be performed on the receiving part. These actions are similar to the actions stated in the onClick, onChange and on{anything} events in the XHTML description of a panel.
  2. <body>: this contains the body of the Flash RAD framework message.

The XML looks like this:

<message>
 <actions></actions>
 <body>
 </body>
</message>;

With content from a from post it can look like this:

<message>
 <actions>reload *.itemlist:personID=2;setvalue *.myimage:http://myimages.com/face23.jpg;</actions>
 <body>
   <data>
     <firstName>John</firstname>
     <lastName>Doe</lastName>
     <personID>2</personID> 
   </data> 
 </body>
</message>;
Advertisements