more explanatory README

diff --git a/org.glite.lb.client/doc/README-notify b/org.glite.lb.client/doc/README-notify
index c7feb9e..481070a 100644 (file)
--- a/org.glite.lb.client/doc/README-notify
+++ b/org.glite.lb.client/doc/README-notify
@@ -1,72 +1,53 @@
 LB notifications
 ----------------
 
-LB infrastructure enables its users to be notified when something interesting happens on a bookkeeping server.
+LB infrastructure enables its users to be notified when something interesting happens on a LB server (typically job status change). It enables the user not to poll LB server periodically to find out whatever he/she is interesting in but confortable wait and let the server itself inform you. If user wants to receive the notifications, he/she must first register to the LB notification infarastructure.
 
-User registers to infrastructure via client API (notification.h) or he/she can use example program glite-lb-notify (see bellow). He/she  must specify a condition under which the notification is sent. The condition(s) is(are) stored in edg_wll_QueryRec data structure. Currently one or more JOBID's are required in it and only a single occurence of a specific attribute is allowed among ANDed conditions.
+User registers via some notification client. (program that uses LB client API to handle notifications). He/she  must specify a condition under which the notification is sent. For example - job XY reaches status DONE. Currently, one or more JOBID's are required in the condition and only a single occurence of a specific attribute is allowed among ANDed conditions. The condition is then delivered to LB server where it is stored. At the same time, server generates an unique notification ID for such registration and returns it to the user.
 
-The request for notification is then delivered to a bookkeeping server. Whenever a new event arrives to the bookkeeping server, the notification condition is tested. Always when it is true, the notification is sent to the user. Notifications are incomming until the user cancels notification registration on the server. 
+The registration exists only for limited amount of time. The validity is returned by LB server together with notification ID when registering. During this period user can attach to server and receive notifications, change conditions which triger notification, prolong validity of the registration, or remove the registration from LB server. For all such operation you have to supply the notification ID.
 
-For a notification deliveriy, a special deamon, notification interlogger is used. It stores registrations in files until they are delivered. 
 
+While the registration is valid, user is able repeatable connect to LB server from different places in the net and continue receiving notifications associated with given notification ID. Notifications generated during the time you are not receiving them are stored and waiting when you reconnect. When you reconnect from another place (another IP or PORT), you will receive all not delivered notifications and continue receiving new ones.
 
 
-Notification example
---------------------
-
-In next steps, you will be instucted how to register for a notification and how to triger this registration on the bookkeeping server in order to receive registration. Our example program 'glite-lb-notify' is used for this purpose. It uses mentioned client API calls to manipulate with registrations. 
-
-
-1) Set up LB environment
-
-       a) Download, compile and install LB module from SCM CVS
-       b) Install it from RPMs
-
-       See instructions at section 'Installation & Configuration'
-       from EGEE JRA1 web site. It was located at (Jan 2005) :
+How does it work?
+-----------------
 
-       http://egee-jra1-wm.mi.infn.it/egee-jra1-wm/lb_install.shtml 
+The request for notification is delivered to LB server. The notification condition specified in the request is stored in LB database and whenever a new event arrives to the LB server, all notification conditions are tested. Always when some of them is true, corresponding notification is sent.
 
+For a notification delivery, a special deamon, a notification interlogger is used. It stores notifications in files and periodically tries to deliver them to the adress of the last connection of notification client. If the user changes the place (IP or PORT) where the client listens, LB server instuct the notification deamon to change delivery destination of all pending notifications. 
 
-2) Get globus proxy certificate
-       ./grid-proxy-init -key PATH_TO_YOUR_KEY -cert PATH_TO_YOUR_CERT
 
 
-3) Start LB deamons
-
-       Substitute KEY with location server private key, CERT with location 
-       of server certificate, and CERTS_DIR directory containing CA 
-       certificates. 
-
-       ./glite-lb-logd -k KEY -c CERT  -C CERTS_DIR -d -v
-
-       ./glite-lb-interlogd -k KEY -c CERT -C CERTS_DIR -b -d -v
-
-       ./glite-lb-bkserverd -d -k KEY -c CERT -C CERTS_DIR
+Notification example
+--------------------
 
-       ./glite-lb-notif-interlogd -k KEY -c CERT -C CERTS_DIR -d -v 
+In the next steps, you will be instucted how to register for a notification and how to triger this registration on the LB server in order to receive registration. Our example program 'glite-lb-notify' is used as a notification client here. It uses mentioned client API calls to manipulate with registrations. 
 
 
-4) Register a job
+1) Register a job
        export EDG_WL_LOG_DESTINATION=HOSTNAME:9002 
        ./glite-lb-job_reg -m HOSTNAME:9000 -s UserInterface
 
        -> returns JOBID - used in the next steps
+       This creates a new job with status submitted.
 
 
-5) Register notification
+2) Register notification
        export EDG_WL_NOTIF_SERVER=HOSTNAME:9000
        ./glite-lb-notify test JOBID
 
 
-6) Change status of your job
+3) Change status of your job
        export EDG_WL_LOG_DESTINATION=HOSTNAME:9002
        ./glite-lb-running.sh -j JOBID
 
 
-7) Watch incomming notifications
+4) Watch incomming notifications. 
+       You should receive several notification, each correspondig 
+       with job status change.
 
 
-Warning: Try to destroy all your registrations when you finish, otherwise the system will still try to deliver you your notifications to nonexistent destinations (ports which nobody listens at).
 
-TIP: If you are stucked, try to clean up notif-interlogger's cache files. They are by default stored at /tmp/notif_events*, or wherever you set by -f option. 
+When you let notification client running several minutes without any incomming notification, it will finish and remove your registration from the server automatically.