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 |