5 <title> OILS Messaging </title>
16 The OpenSRF 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> messages provide general information to the transport layer and 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
34 (mostly for debugging). The
35 statusCode is an integer representing the exact status this message represents. The status codes
36 are modeled after HTTP status codes. Currently used codes consist of the following:
38 <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
59 If at any point the client sends a non-connect message to the server when the client is not connected or the
60 connection has timed out, the <b>STATUS</b> that is returned shall have statusCode <b>STATUS_EXPFAILED</b>.
63 The <b>DISCONNECT</b> message is sent by the client to the server to end the virtual session. The server
64 shall not respond to any disconnect messages.
67 <h1> Message Layer </h1>
70 There are currently two types of message layer messages: <b>REQUEST</b> and <b>RESULT</b>. <b>REQUEST</b>
71 messages represent application layer requests made by a client and <b>RESULT</b> messages are the servers
72 response to such <b>REQUEST</b>'s.
75 By design, all <b>CONNECT</b> and <b>REQUEST</b> messages sent by a client will be acknowledged by one or
76 more responses from the server. This is much like the SYN-ACK philosophy of TCP, however different in many
77 ways. The only guarantees made by the server are 1. you will know that we received your request and 2. you
78 will know the final outcome of your request. It is the responsibility of the actual application to send
79 the requested application data (e.g. RESULT messages, intermediate STATUS messages).
83 The server responses are matched to client requests by a <b>threadTrace</b>. A threadTrace is simply a
84 number and all application layer messages and STATUS messages are required to have one. (Note that the
85 threadTrace contained within a STATUS message sent in response to a CONNECT will be ignored). Currently,
86 there is no restriction on the number other than it shall be unique within a given virtual connection.
87 When the server receives a <b>REQUEST</b> message, it extracts the <b>threadTrace</b> from the message
88 and all responses to that request will contain the same <b>threadTrace</b>.
91 As mentioned above, every <b>CONNECT</b> message will be acknowledged by a single
92 <b>STATUS</b> message. <b>REQUEST</b>'s are a little more complex, however. A <b>REQUEST</b>
93 will receive one or more <b>RESULT</b>'s if the <b>REQUEST</b> warrants such a response. A <b>REQUEST</b>
94 may even receive one or more intermediate <b>STATUS</b>'s (e.g. <b>STATUS_CONTINUE</b>). (Consult the
95 documentation on the application request the client is requesting for more information on the number and
96 type of responses to that request). All <b>REQUEST</b>'s, however, regardless of other response types,
97 shall receieve as the last response a <b>STATUS</b> message with statusCode <b>STATUS_COMPLETE</b>. This
98 allows the client to wait for REQUEST "completeness" as opposed to waiting on or calculating individual
102 <h1> Client Pseudocode </h1>
104 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
110 if ( msg.statusCode == STATUS_OK )
114 while ( more requests ) {
116 /* you may send multiple requests before processing any responses. For the sake
117 of this example, we will only walk through a single client request */
119 send REQUEST with threadTrace X
121 while ( response = recv ) {
123 if ( response.threadTrace != X )
127 if ( response.type == STATUS )
129 if ( response.statusCode == STATUS_TIMEOUT or
130 response.statusCode == STATUS_REDIRECTED or
131 response.statusCode == STATUS_EXPFAILED)
133 resend the the request with threadTrace X because it was not honored.
135 if ( response.statusCode == STATUS_COMPLETE )
137 the request is now complete, nothing more to be done with this request
140 if ( response.typ == RESULT )
142 pass result to the application layer for processing
152 <h1> Server Pseudocode </h1>
154 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
156 while( message = recv() ) {
158 if( message.type != CONNECT )
160 return a STATUS with statusCode STATUS_EXPFAILED
163 if ( message.type == CONNECT )
165 return STATUS with statusCode STATUS_OK and continue
167 while ( msg = recv() and virtual session is active ) {
170 if ( msg.type == REQUEST )
172 Record the threadTrace. Pass the REQUEST to the application layer for processing.
173 When the application layer has completed processing, respond to the client
174 with a STATUS message with statusCode STATUS_COMPLETE and threadTrace matching
175 the threadTrace of the REQUEST. Once the final STATUS_COMPLETE message is sent,
176 the session is over. Return to outer server loop.
178 /* Note: during REQUEST processing by the application layer, the application may
179 opt to send RESULT and/or STATUS messages to the client. The server side
180 transport mechanism is not concerned with these messages. The server only
181 needs to be notified when the REQUEST has been sucessfully completed. */
183 if( message.type == DISCONNECT )
185 Virtual session has ended. Return to outer loop.
190 } // Main server loop
198 <h1> XML Examples</h1>
202 <h2> Protocol Element </h2>
204 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
206 <oils:domainObjectAttr value="1" name="protocol"/>
210 <h2> threadTrace Element </h2>
212 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
214 <oils:domainObjectAttr value="1" name="threadTrace"/>
218 <h2> CONNECT Message </h2>
220 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
222 <oils:domainObject name="oilsMessage">
223 <oils:domainObjectAttr value="CONNECT" name="type"/>
224 <oils:domainObjectAttr value="1" name="threadTrace"/>
225 <oils:domainObjectAttr value="1" name="protocol"/>
226 </oils:domainObject>
231 <h2> DISCONNECT Message </h2>
233 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
235 <oils:domainObject name="oilsMessage">
236 <oils:domainObjectAttr value="DISCONNECT" name="type"/>
237 <oils:domainObjectAttr value="0" name="threadTrace"/>
238 <oils:domainObjectAttr value="1" name="protocol"/>
239 </oils:domainObject>
243 <h2> STATUS Message </h2>
245 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
247 <oils:domainObject name="oilsMessage">
248 <oils:domainObjectAttr value="STATUS" name="type"/>
249 <oils:domainObjectAttr value="0" name="threadTrace"/>
250 <oils:domainObjectAttr value="1" name="protocol"/>
251 <oils:domainObject name="oilsConnectStatus">
252 <oils:domainObjectAttr value="Connection Successful" name="status"/>
253 <oils:domainObjectAttr value="200" name="statusCode"/>
254 </oils:domainObject>
255 </oils:domainObject>
259 <h2> REQUEST Message </h2>
261 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
263 <oils:domainObject name="oilsMessage">
264 <oils:domainObjectAttr value="REQUEST" name="type"/>
265 <oils:domainObjectAttr value="4" name="threadTrace"/>
266 <oils:domainObjectAttr value="1" name="protocol"/>
267 <oils:domainObject name="oilsMethod">
268 <oils:domainObjectAttr value="mult" name="method"/>
269 <oils:params>[1, 2]</oils:params>
270 </oils:domainObject>
271 </oils:domainObject>
275 <h2> RESULT Message </h2>
277 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
279 <oils:domainObject name="oilsMessage">
280 <oils:domainObjectAttr value="RESULT" name="type"/>
281 <oils:domainObjectAttr value="4" name="threadTrace"/>
282 <oils:domainObjectAttr value="1" name="protocol"/>
283 <oils:domainObject name="oilsResult">
284 <oils:domainObjectAttr value="OK" name="status"/>
285 <oils:domainObjectAttr value="200" name="statusCode"/>
286 <oils:domainObject name="oilsScalar">2</oils:domainObject>
287 </oils:domainObject>
288 </oils:domainObject>