5 <title> OILS Messaging </title>
16 The OILS messaging system works on two different primary layers: the transport layer and the
17 application layer. The transport layer manages virtual connections between client and server,
18 while the application layer manages user/application level messages.
20 All messages must declare which protocol version they are requesting. The current protocol level
23 <h1> Transport Layer </h1>
26 There are currently three types of messages in the transport layer: <b>CONNECT, STATUS, </b> and
30 <b>STATUS</b> message provide general information to the transport layer are used in different
31 ways throughout the system. They are sent primarily by the server in response to client requests.
32 Each message comes with
33 a status and statusCode. The actual status part of the STATUS message is just a helpful message (mostly for debugging). The
34 statusCode is an integer representing the exact status this message represents. The status codes
35 are modeled after HTTP status codes. Currently used codes consist of the following:
37 <b> <pre style="border: solid thin blue; margin: 2% 10% 2% 10%; padding-left: 50px">
50 This list is likely to change at least a little.
54 The <b>CONNECT</b> message initiates the virtual connection for a client and expects a <b>STATUS</b>
55 in return. If the connection is successful, the statusCode for the <b>STATUS</b> message shall be
56 <b>STATUS_OK</b>. If the authentication fails or if there is not actual authentication information
57 within the message, the statusCode for the returned message shall be <b>STATUS_FORBIDDEN</b>.
60 If at any point the client sends a non-connect message to the server when the client is not connected or the
61 connection has timed out, the <b>STATUS</b> that is returned shall have statusCode <b>STATUS_EXPFAILED</b>.
64 The <b>DISCONNECT</b> message is sent by the client to the server to end the virtual session. The server
65 shall not respond to any disconnect messages.
68 <h1> Message Layer </h1>
71 There are currently two types of message layer messages: <b>REQUEST</b> and <b>RESULT</b>. <b>REQUEST</b>
72 messages represent application layer requests made by a client and <b>RESULT</b> messages are the servers
73 response to such <b>REQUEST</b>'s.
76 By design, all <b>CONNECT</b> and <b>REQUEST</b> messages sent by a client will be acknowledged by one or
77 more responses from the server. This is much like the SYN-ACK philosophy of TCP, however different in many
78 ways. The only guarantees made by the server are 1. you will know that we received your request and 2. you
79 will know the final outcome of your request. It is the responsibility of the actual application to send
80 the requested application data (e.g. RESULT messages, intermediate STATUS messages).
84 The server responses are matched to client requests by a <b>threadTrace</b>. A threadTrace is simply a
85 number and all application layer messages and STATUS messages are required to have one. (Note that the
86 threadTrace contained within a STATUS message sent in response to a CONNECT will be ignored). Currently,
87 there is no restriction on the number other than it shall be unique within a given virtual connection.
88 When the server receives a <b>REQUEST</b> message, it extracts the <b>threadTrace</b> from the message
89 and all responses to that request will contain the same <b>threadTrace</b>.
92 As mentioned above, every <b>CONNECT</b> message will be acknowledged by a single
93 <b>STATUS</b> message. <b>REQUEST</b>'s are a little more complex, however. A <b>REQUEST</b>
94 will receive one or more <b>RESULT</b>'s if the <b>REQUEST</b> warrants such a response. A <b>REQUEST</b>
95 may even receive one or more intermediate <b>STATUS</b>'s (e.g. <b>STATUS_CONTINUE</b>). (Consult the
96 documentation on the application request the client is requesting for more information on the number and
97 type of responses to that request). All <b>REQUEST</b>'s, however, regardless of other response types,
98 shall receieve as the last response a <b>STATUS</b> message with statusCode <b>STATUS_COMPLETE</b>. This
99 allows the client to wait for REQUEST "completeness" as opposed to waiting on or calculating individual
103 <h1> Client Pseudocode </h1>
105 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
111 if ( msg.statusCode == STATUS_OK )
115 if ( msg.statusCode == STATUS_FORBIDDEN )
117 handle authentication failure and attempt another connect if requested
119 while ( more requests ) {
121 /* you may send multiple requests before processing any responses. For the sake
122 of this example, we will only walk through a single client request */
124 send REQUEST with threadTrace X
126 while ( response = recv ) {
128 if ( response.threadTrace != X )
132 if ( response.type == STATUS )
134 if ( response.statusCode == STATUS_TIMEOUT or
135 response.statusCode == STATUS_REDIRECTED or
136 response.statusCode == STATUS_EXPFAILED)
138 resend the the request with threadTrace X because it was not honored.
140 if ( response.statusCode == STATUS_COMPLETE )
142 the request is now complete, nothing more to be done with this request
145 if ( response.typ == RESULT )
147 pass result to the application layer for processing
157 <h1> Server Pseudocode </h1>
159 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
161 while( message = recv() ) {
163 if( message.type != CONNECT )
165 return a STATUS with statusCode STATUS_EXPFAILED
168 if ( message.type == CONNECT and server is unable to authenticate the client )
170 return a STATUS with statusCode STATUS_FORBIDDEN
173 if ( message.type == CONNECT and server is able to authenticate user )
175 return STATUS with statusCode STATUS_OK and continue
177 while ( msg = recv() and virtual session is active ) {
180 if ( msg.type == REQUEST )
182 Record the threadTrace. Pass the REQUEST to the application layer for processing.
183 When the application layer has completed processing, respond to the client
184 with a STATUS message with statusCode STATUS_COMPLETE and threadTrace matching
185 the threadTrace of the REQUEST. Once the final STATUS_COMPLETE message is sent,
186 the session is over. Return to outer server loop.
188 /* Note: during REQUEST processing by the application layer, the application may
189 opt to send RESULT and/or STATUS messages to the client. The server side
190 transport mechanism is not concerned with these messages. The server only
191 needs to be notified when the REQUEST has been sucessfully completed. */
193 if( message.type == DISCONNECT )
195 Virtual session has ended. Return to outer loop.
200 } // Main server loop
208 <h1> XML Examples</h1>
212 <h2> Protocol Element </h2>
214 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
216 <oils:domainObjectAttr value="1" name="protocol"/>
220 <h2> threadTrace Element </h2>
222 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
224 <oils:domainObjectAttr value="1" name="threadTrace"/>
228 <h2> Type element </h2>
230 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
232 <oils:userAuth hashseed="237" secret="89dd8c65300d4af126cf467779ff1820" username="bill"/>
236 <h2> CONNECT Message </h2>
238 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
240 <oils:domainObjectAttr value="CONNECT" name="type"/>
241 <oils:userAuth hashseed="237" secret="89dd8c65300d4af126cf467779ff1820" username="bill"/>
242 <oils:domainObjectAttr value="1" name="threadTrace"/>
243 <oils:domainObjectAttr value="1" name="protocol"/>
244 </oils:domainObject>
249 <h2> DISCONNECT Message </h2>
251 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
253 <oils:domainObject name="oilsMessage">
254 <oils:domainObjectAttr value="DISCONNECT" name="type"/>
255 <oils:domainObjectAttr value="0" name="threadTrace"/>
256 <oils:domainObjectAttr value="1" name="protocol"/>
257 </oils:domainObject>
261 <h2> STATUS Message </h2>
263 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
265 <oils:domainObject name="oilsMessage">
266 <oils:domainObjectAttr value="STATUS" name="type"/>
267 <oils:domainObjectAttr value="0" name="threadTrace"/>
268 <oils:domainObjectAttr value="1" name="protocol"/>
269 <oils:domainObject name="oilsConnectStatus">
270 <oils:domainObjectAttr value="Connection Successful" name="status"/>
271 <oils:domainObjectAttr value="200" name="statusCode"/>
272 </oils:domainObject>
273 </oils:domainObject>
277 <h2> REQUEST Message </h2>
279 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
281 <oils:domainObject name="oilsMessage">
282 <oils:domainObjectAttr value="REQUEST" name="type"/>
283 <oils:domainObjectAttr value="4" name="threadTrace"/>
284 <oils:domainObjectAttr value="1" name="protocol"/>
285 <oils:domainObject name="oilsMethod">
286 <oils:domainObjectAttr value="mult" name="method"/>
288 <oils:param>1</oils:param>
289 <oils:param>2</oils:param>
291 </oils:domainObject>
292 </oils:domainObject>
296 <h2> RESULT Message </h2>
298 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
300 <oils:domainObject name="oilsMessage">
301 <oils:domainObjectAttr value="RESULT" name="type"/>
302 <oils:domainObjectAttr value="4" name="threadTrace"/>
303 <oils:domainObjectAttr value="1" name="protocol"/>
304 <oils:domainObject name="oilsResult">
305 <oils:domainObjectAttr value="OK" name="status"/>
306 <oils:domainObjectAttr value="200" name="statusCode"/>
307 <oils:domainObject name="oilsScalar">2</oils:domainObject>
308 </oils:domainObject>
309 </oils:domainObject>