ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/i-scream/projects/cms/documentation/specification/protocols.txt
(Generate patch)

Comparing projects/cms/documentation/specification/protocols.txt (file contents):
Revision 1.1 by ajm, Sun Jan 28 18:35:31 2001 UTC vs.
Revision 1.6 by tdb, Sun Jan 28 22:01:14 2001 UTC

# Line 16 | Line 16 | Conventions
16   -----------
17   All protocols in this document assume a valid connection of
18   the appropriate type has been made, and that data streams
19 < already available.  All strings should and will be
19 > are already available.  All strings should, and will be,
20   terminated with a \n (newline character) to indicate the end
21   of the message.  All messages are sent as ASCII Strings.
22  
23   Fixed protocol messages will appear in [] brackets, if there
24 < is a variety of options they will be seperated with the |
24 > is a variety of options they will be separated with the |
25   character.  For example:
26  
27      [OK|ERROR]
28 <    
28 >  
29   Indicates that the message "OK" OR the message "ERROR" will
30   be sent depending on the result of the last action.
31  
# Line 35 | Line 35 | of data that will be returned.  For example:
35  
36      {lastmodified}
37  
38 < Indicates that data indicating for use as last modified will
39 < be returned.    
38 > Indicates that data for use as 'last modified' will be
39 > returned.  
40  
41 < If ever [ERROR] is sent back at any time, this indicates
42 < that all communication is over. EXCEPT where specified!
41 > If [ERROR] is sent back at any time, this indicates that all
42 > communication is over. EXCEPT where otherwise specified!
43  
44   Host Connection Protocol
45   ------------------------
46   The initial connection of a host to the i-scream server is
47   through the FilterManager.  A Host gets its configuration
48 < and then gets assigned a filter to connect to and start
48 > and then gets assigned a Filter to connect to and start
49   sending data.
50  
51 < The port number of the filter manager is fully configurable,
51 > The port number of the FilterManager is fully configurable,
52   however the default at this time is 4567.
53  
54   Host         (direction) Server         Comment
# Line 56 | Line 56 | Host         (direction) Server         Comment
56   [STARTCONFIG]---------->                Requests to start
57                                          receiving config
58                                          information
59 <            
59 >          
60               <---------- [OK|ERROR]     If the server ok's
61                                          the request or not
62  
63   [LASTMODIFIED]---------->               Asks when the config
64                                          was last modified
65                                          (used when checking
66 <                                        if the config has
66 >                                        if the config has
67                                          changed)
68 <            
68 >          
69               <---------- [{lastmodified}Returns a long int
70 <                         |ERROR]        time since epoc
70 >                         |ERROR]        time since epoch
71                                          eg, 123456789
72 <
72 >                                        To indicate what
73 >                                        format this is in,
74 >                                        I quote from the
75 >                                        Java 1.3 JDK API
76 >                                        "measured in milli
77 >                                        -seconds since the
78 >                                        epoch"
79 >                                      
80   [FILELIST]   ---------->                Asks the server for
81                                          the list of files
82                                          that were used to
# Line 77 | Line 84 | Host         (direction) Server         Comment
84                                          (used when checking
85                                          if the config has
86                                          changed)
87 <        
87 >      
88               <---------- [{filelist}    Returns a semi-colon
89 <                         |ERROR]        seperated list of
89 >                         |ERROR]        separated list of
90                                          filenames
91                                          eg,
92                                          a.conf;b.conf;c.conf
# Line 93 | Line 100 | Host         (direction) Server         Comment
100                                          retrieved from the
101                                          config file
102                                          eg, UDPUpdateTime
103 <            
103 >          
104               <---------- [{value}|ERROR]Returns the value of
105                                          the requested config
106                                          property
107                                          eg, 120
108                                          If it is unable to
109 <                                        find the requested
109 >                                        find the requested
110                                          property it returns
111                                          ERROR to indicate
112 <                                        that fact
113 <                                        
112 >                                        that fact, but
113 >                                        communication still
114 >                                        proceeds
115 >                                      
116               ********** LOOP UNTIL **********
117               The loop continues until the host
118               sends the following message
119 <            
120 < [ENDCONFIG]  ---------->                Indicates that the
119 >          
120 > [ENDCONFIG]  ---------->                Indicates that the
121                                          host requires no
122                                          more config
123 <            
123 >          
124               ********** LOOP  END **********
125               Communication continues
126 <            
126 >          
127               <---------- [OK]           Indicates that the
128                                          server is ready to
129                                          proceed
130 <                                        
130 >                                      
131   [FILTER]     ---------->                Asks the server to
132                                          send it the host
133 <                                        information of a
133 >                                        information of a
134                                          filter that it
135                                          should connect to
136 <                                        
136 >                                      
137               <---------- {filter}       Returns a semi-colon
138 <                                        seperated list of
138 >                                        separated list of
139                                          FQDN hostname, UDP
140                                          port number and TCP
141 <                                        port number that a
141 >                                        port number that a
142                                          configured Filter is
143                                          running on and
144 <                                        assigned to the
144 >                                        assigned to the
145                                          calling host
146                                          eg,
147                                          raptor.ukc.ac.uk;
# Line 142 | Line 151 | Host         (direction) Server         Comment
151                                          server that the host
152                                          has finished an will
153                                          disconnect
154 <            
154 >          
155               <---------- [OK|ERROR]     Indicates that the
156                                          server is either ok
157                                          or that it thought
158                                          there was an error
159 <        
159 > ------------------------------------------------------------
160 >      
161   Host Heartbeat Protocol
162   -----------------------
163   When a host is configured after it has connected it should
164   obtain a property TCPUpdateTime.  This indicates how often
165 < a host should send a "Heart Beat" which is a pro-active
165 > a host should send a "Heart Beat", which is a pro-active
166   connection to the server by the host to indicate that it is
167   still alive.  This "Heart Beat" also allows a host to see
168 < its configuration has changed and act accordingly.  In a
168 > its configuration has changed and act accordingly.  In a
169   well written host this should just be a case of dropping out
170   of a loop and heading back to the start (connecting to the
171   filter manager).
# Line 165 | Line 175 | Host            (direction) Server      Comment
175   [HEARTBEAT]     ---------->             Starts the
176                                          heartbeat protocol
177                                          off
178 <                                        
178 >                                      
179                  <---------- [OK|ERROR]  Indicates that the
180                                          server is ok or not
181  
# Line 177 | Line 187 | Host            (direction) Server      Comment
187                                          server is ok or not
188  
189   [{filelist}]    ---------->             Send a semi-colon
190 <                                        seperated list of
190 >                                        separated list of
191                                          filenames
192                                          eg,
193                                          a.conf;b.conf;c.conf
194                                          This should be
195                                          identical to the one
196 <                                        recieved in the
196 >                                        received in the
197                                          connection protocol
198  
199                  <---------- [OK]        Indicates that the
200                                          server is ok
201  
202   [{lastmodified}]---------->             Returns a long int
203 <                                        time since epoc
203 >                                        time since epoch
204                                          eg, 123456789
205                                          This should be
206                                          identical to the one
207 <                                        recieved in the
207 >                                        received in the
208                                          connection protocol
209 +                                        To indicate what
210 +                                        format this is in,
211 +                                        I quote from the
212 +                                        Java 1.3 JDK API
213 +                                        "measured in milli
214 +                                        -seconds since the
215 +                                        epoch"
216  
217                  <---------- [OK|ERROR]  The server then
218                                          checks all the files
# Line 203 | Line 220 | Host            (direction) Server      Comment
220                                          see if they have
221                                          been modified more
222                                          recently than the
223 <                                        lastmodified value
224 <                                        if they HAVE that
223 >                                        lastmodified value.
224 >                                        If they HAVE that
225                                          indicates that the
226                                          configuration has
227                                          changed and the host
# Line 221 | Line 238 | Host            (direction) Server      Comment
238                                          server that the host
239                                          has finished an will
240                                          disconnect
241 <                
241 >              
242                  <---------- [OK|ERROR]  Indicates that the
243                                          server is either ok
244                                          or that it thought
245                                          there was an error
246 + ------------------------------------------------------------
247  
248   Host Data Protocol
249   ------------------
# Line 238 | Line 256 | http://www.i-scream.org.uk/cgi-bin/docs.cgi?doc=specif
256   Client Control Protocol
257   -----------------------
258  
259 < <TODO>
259 > The client control protocol channel is opened by the client
260 > and allows a variety of actions to be carried out by the
261 > client at anytime.  Unlike previous protocols, this is NOT
262 > sequential, all of the requests can be carried out in
263 > any order.
264  
265 + All client protocols are backwards compatible, and the
266 + version is shown by the protocol identifier.
267 +
268 + There are three sections to this protocol.
269 +
270 + 1) Initialise (sent only at start)
271 + 2) Send command(s) - unlimited number in any order
272 + 3) Disconnect (sent only at end)
273 +
274 + If at anytime the client sends something the server does
275 + not understand, an [ERROR] will be sent
276 +
277 + All are indicated with <> brackets.
278 +
279 + v1.0 - Protocol identifier: "PROTOCOL 1.0" (without quotes)
280 +       Supported commands:
281 +            STARTCONFIG
282 +            STARTDATA
283 +            STOPDATA
284 +
285 + Host         (direction) Server         Comment
286 + ------------------------------------------------------------
287 + <initialise>
288 + [CONNECT]    ---------->                Starts off the
289 +                                        client protocol
290 +            
291 +             <---------- [{protocol}]   The server sends the
292 +                                        protocol identifier
293 +                                      
294 + [{name}]     ---------->                The client sends its
295 +                                        "name".  This name
296 +                                        is used to identify
297 +                                        the type of client
298 +                                        to the system and
299 +                                        obtain its config
300 +                                        eg, Conient
301 +            
302 +             <---------- [OK]           Indicates the server
303 +                                        is ok to proceed
304 +                      
305 +
306 + <command #1> (allows client to obtain its configuration)
307 + [STARTCONFIG]---------->                Tell the server we
308 +                                        want to start this
309 +                                        command
310 +            
311 +             <---------- [OK]           Indicates the server
312 +                                        is ok to proceed
313 +            
314 +             ********** LOOP START **********
315 +             This loop reads configuration
316 +             properties from the config
317 +
318 + [{property}] ---------->                Sends the name of a
319 +                                        property to be
320 +                                        retrieved from the
321 +                                        config file
322 +                                        Clients can obtain
323 +                                        host information
324 +                                        eg,
325 +                                        Host.UDPUpdateTime
326 +                                        Otherwise it must
327 +                                        prefix requests
328 +                                        with "Client."
329 +                                        All other requests
330 +                                        will be ignored as
331 +                                        if it was unable to
332 +                                        retrieve the
333 +                                        property
334 +                                      
335 +             <---------- [{value}|ERROR]Returns the value of
336 +                                        the requested config
337 +                                        property
338 +                                        eg, 120
339 +                                        If it is unable to
340 +                                        find the requested
341 +                                        property it returns
342 +                                        ERROR to indicate
343 +                                        that fact
344 +                                      
345 +             ********** LOOP UNTIL **********
346 +             The loop continues until the client
347 +             sends the following message
348 +            
349 + [ENDCONFIG]  ---------->                Indicates that the
350 +                                        client requires no
351 +                                        more config
352 +            
353 +             ********** LOOP  END **********
354 +             Communication continues
355 +            
356 +             <---------- [OK]           Indicates that the
357 +                                        server is ready to
358 +                                        proceed
359 +
360 + <command #2> (tells the server to start the data link)
361 + [STARTDATA]  ---------->                Tell the server we
362 +                                        want to start this
363 +                                        command
364 +          
365 +             <---------- [{portnumber}  The server then sets
366 +                         |ERROR]        itself listening for
367 +                                        a connection on its
368 +                                        data link socket for
369 +                                        this client.  It
370 +                                        returns the port no.
371 +                                        that it is listening
372 +                                        on eg, 12367
373 +                                        If the data link is
374 +                                        already started the
375 +                                        server will return
376 +                                        ERROR
377 +            
378 +             <---------- [OK]           Indicates the client
379 +                                        has successfully
380 +                                        connected to the
381 +                                        data socket.
382 +
383 + <command #3> (tells the server to stop the data link)
384 + [STOPDATA]   ---------->                Tell the server we
385 +                                        want to start this
386 +                                        command
387 +                                        The server then
388 +                                        shuts down the
389 +                                        data link to the
390 +                                        client
391 +
392 +             <---------- [OK|ERROR]     Returns OK is the
393 +                                        server is ready to
394 +                                        proceed, or ERROR
395 +                                        if the data link
396 +                                        was not open in the
397 +                                        first place
398 +
399 + <disconnect>
400 + [DISCONNECT] ---------->                Tells the server the
401 +                                        client wants to
402 +                                        close the control
403 +                                        link
404 +                                      
405 +             <---------- [OK]           The last word from
406 +                                        the server, it will
407 +                                        disappear after
408 +                                        this, and close the
409 +                                        data link if
410 +                                        required
411 + ------------------------------------------------------------
412 +
413 + v1.1 - Protocol identifier: "PROTOCOL 1.1" (without quotes)
414 +       Supported commands:
415 +            SETHOSTLIST
416 +
417 + Host         (direction) Server         Comment
418 + ------------------------------------------------------------
419 + <command #4> (indicates to the server which hosts the client
420 +              wants data from)
421 + [SETHOSTLIST]---------->                Tell the server we
422 +                                        want to start this
423 +                                        command
424 +            
425 +             <---------- [OK|ERROR]     The server will
426 +                                        return an ERROR if
427 +                                        the data link is
428 +                                        open, as a host list
429 +                                        must ONLY be set
430 +                                        if the data link is
431 +                                        closed
432 +                                        If the server is
433 +                                        ok to proceed with
434 +                                        the command it says
435 +                                        [OK]
436 +
437 + [{hostlist}] ---------->                This is a semi-colon
438 +                                        seperated list of
439 +                                        FQDN hostnames that
440 +                                        the client wishes to
441 +                                        recieve data from
442 +                                        eg,
443 +        raptor.ukc.ac.uk;killigrew.ukc.ac.uk;chalk.ukc.ac.uk
444 +                                      
445 +                                        If the list is sent
446 +                                        blank (or if no list
447 +                                        is set at all) then
448 +                                        data from ALL hosts
449 +                                        will be sent to the
450 +                                        client (this is the
451 +                                        default if no
452 +                                        SETHOSTLIST is not
453 +                                        run by the client
454 +                                      
455 +             <---------- [OK]           Indicates the server
456 +                                        is ok to proceed and
457 +                                        the host list has
458 +                                        been accepted
459 + ------------------------------------------------------------
460 +
461   Client Data Protocol
462   --------------------
463 + Once the data link has been opened by the control link, the
464 + server will send XML formatted data packets separated by the
465 + \n (newline) character.  For information on the format of
466 + this data see the XML via UDP specification document at:
467  
468 < <TODO>
468 > http://www.i-scream.org.uk/cgi-bin/docs.cgi?doc=specification/xml_via_udp.txt
469  
470   About
471   -----

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines