ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/i-scream/projects/cms/documentation/specification/protocols.txt
Revision: 1.5
Committed: Sun Jan 28 20:29:32 2001 UTC (23 years, 3 months ago) by ajm
Content type: text/plain
Branch: MAIN
Changes since 1.4: +15 -5 lines
Log Message:
added definition of the format of time since epoch...

File Contents

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