doc/OpenSRF-Messaging-Protocol.html

   1 <html>
   2
   3         <head>
   4
   5                 <title> OILS Messaging </title>
   6
   7         </head>
   8
   9         <body>
  10
  11
  12                 <h1> Abstract </h1>
  13
  14                 <p>
  15
  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.
  19
  20                 All messages must declare which protocol version they are requesting.  The current protocol level
  21                 is 1.
  22
  23                 <h1> Transport Layer </h1>
  24
  25                 <p>
  26                 There are currently three types of messages in the transport layer: <b>CONNECT, STATUS, </b> and
  27                 <b>DISCONNECT</b>.
  28
  29                 <p>
  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:
  37
  38                 <b> <pre style="border: solid thin blue; margin: 2% 10% 2% 10%; padding-left: 50px">
  39                 100     STATUS_CONTINUE
  40                 200     STATUS_OK
  41                 205     STATUS_COMPLETE
  42                 307     STATUS_REDIRECTED
  43                 400     STATUS_BADREQUEST
  44                 404     STATUS_NOTFOUND
  45                 408     STATUS_TIMEOUT
  46                 417     STATUS_EXPFAILED
  47                 </pre> </b>
  48
  49                 <p>
  50                 This list is likely to change at least a little.
  51
  52
  53                 <p>
  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>.
  57
  58                 <p>
  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>.
  61
  62                 <p>
  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.
  65
  66
  67                 <h1> Message Layer </h1>
  68
  69                 <p>
  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.
  73
  74                 <p>
  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).
  80
  81
  82                 <p>
  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>.
  89
  90                 <p>
  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
  99                 responses.
 100
 101
 102                 <h1> Client Pseudocode </h1>
 103
 104                 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
 105
 106 send CONNECT
 107
 108 msg = recv()
 109
 110 if ( msg.statusCode == STATUS_OK )
 111
 112         OK. continue
 113
 114 while ( more requests ) {
 115
 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 */
 118
 119         send REQUEST with threadTrace X
 120
 121         while ( response = recv ) {
 122
 123                 if (  response.threadTrace != X )
 124
 125                         continue/ignore
 126
 127                 if ( response.type == STATUS )
 128
 129                         if (  response.statusCode == STATUS_TIMEOUT             or
 130                                         response.statusCode == STATUS_REDIRECTED        or
 131                                         response.statusCode == STATUS_EXPFAILED)
 132
 133                                 resend the the request with threadTrace X because it was not honored.
 134
 135                         if ( response.statusCode == STATUS_COMPLETE )
 136
 137                                 the request is now complete, nothing more to be done with this request
 138                                 break out of loop
 139
 140                 if ( response.typ == RESULT )
 141
 142                         pass result to the application layer for processing
 143
 144         } // receiving
 145
 146 } // sending
 147
 148
 149                 </pre>
 150
 151                 <br>
 152                 <h1> Server Pseudocode </h1>
 153
 154                 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
 155
 156 while( message = recv() ) {
 157
 158         if( message.type != CONNECT )
 159
 160                 return a STATUS with statusCode STATUS_EXPFAILED
 161                 start loop over
 162
 163         if ( message.type == CONNECT )
 164
 165                 return STATUS with statusCode STATUS_OK and continue
 166
 167         while ( msg = recv() and virtual session is active ) {
 168
 169
 170                 if ( msg.type == REQUEST )
 171
 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.
 177
 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. */
 182
 183                 if( message.type == DISCONNECT )
 184
 185                         Virtual session has ended. Return to outer loop.
 186
 187
 188         } // Sessin loop
 189
 190 } // Main server loop
 191
 192
 193
 194                 </pre>
 195
 196
 197                 <br>
 198                 <h1> XML Examples</h1>
 199                 <br>
 200
 201
 202                 <h2> Protocol Element </h2>
 203
 204                 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
 205
 206 &lt;oils:domainObjectAttr value="1" name="protocol"/>
 207
 208                 </pre>
 209
 210                 <h2> threadTrace Element </h2>
 211
 212                 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
 213
 214 &lt;oils:domainObjectAttr value="1" name="threadTrace"/>
 215
 216                 </pre>
 217
 218                 <h2> CONNECT Message </h2>
 219
 220                 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
 221
 222 &lt;oils:domainObject name="oilsMessage">
 223         &lt;oils:domainObjectAttr value="CONNECT" name="type"/>
 224         &lt;oils:domainObjectAttr value="1" name="threadTrace"/>
 225         &lt;oils:domainObjectAttr value="1" name="protocol"/>
 226 &lt;/oils:domainObject>
 227
 228                 </pre>
 229
 230
 231                 <h2> DISCONNECT Message </h2>
 232
 233                 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
 234
 235 &lt;oils:domainObject name="oilsMessage">
 236         &lt;oils:domainObjectAttr value="DISCONNECT" name="type"/>
 237         &lt;oils:domainObjectAttr value="0" name="threadTrace"/>
 238         &lt;oils:domainObjectAttr value="1" name="protocol"/>
 239 &lt;/oils:domainObject>
 240
 241                 </pre>
 242
 243                 <h2> STATUS Message </h2>
 244
 245                 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
 246
 247 &lt;oils:domainObject name="oilsMessage">
 248         &lt;oils:domainObjectAttr value="STATUS" name="type"/>
 249         &lt;oils:domainObjectAttr value="0" name="threadTrace"/>
 250         &lt;oils:domainObjectAttr value="1" name="protocol"/>
 251         &lt;oils:domainObject name="oilsConnectStatus">
 252                 &lt;oils:domainObjectAttr value="Connection Successful" name="status"/>
 253                 &lt;oils:domainObjectAttr value="200" name="statusCode"/>
 254         &lt;/oils:domainObject>
 255 &lt;/oils:domainObject>
 256
 257                 </pre>
 258
 259                 <h2> REQUEST Message </h2>
 260
 261                 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
 262
 263 &lt;oils:domainObject name="oilsMessage">
 264         &lt;oils:domainObjectAttr value="REQUEST" name="type"/>
 265         &lt;oils:domainObjectAttr value="4" name="threadTrace"/>
 266         &lt;oils:domainObjectAttr value="1" name="protocol"/>
 267         &lt;oils:domainObject name="oilsMethod">
 268                 &lt;oils:domainObjectAttr value="mult" name="method"/>
 269                 &lt;oils:params>[1, 2]&lt;/oils:params>
 270         &lt;/oils:domainObject>
 271 &lt;/oils:domainObject>
 272
 273                 </pre>
 274
 275                 <h2> RESULT Message </h2>
 276
 277                 <pre style="border: solid thin blue; margin: 0% 10% 0% 10%; padding-left: 50px">
 278
 279 &lt;oils:domainObject name="oilsMessage">
 280         &lt;oils:domainObjectAttr value="RESULT" name="type"/>
 281         &lt;oils:domainObjectAttr value="4" name="threadTrace"/>
 282         &lt;oils:domainObjectAttr value="1" name="protocol"/>
 283         &lt;oils:domainObject name="oilsResult">
 284                 &lt;oils:domainObjectAttr value="OK" name="status"/>
 285                 &lt;oils:domainObjectAttr value="200" name="statusCode"/>
 286                 &lt;oils:domainObject name="oilsScalar">2&lt;/oils:domainObject>
 287         &lt;/oils:domainObject>
 288 &lt;/oils:domainObject>
 289
 290                 </pre>
 291
 292
 293         </body>
 294
 295 </html>
 296
 297