Last TODO removed, Operator CHANGED, timeout clarification.

diff --git a/org.glite.lb.doc/src/notification_api.tex b/org.glite.lb.doc/src/notification_api.tex
index 97cb3bb..cb2f851 100644 (file)
--- a/org.glite.lb.doc/src/notification_api.tex
+++ b/org.glite.lb.doc/src/notification_api.tex
@@ -63,24 +63,24 @@ funcions.
   notification the same encoding of conditions as for the \LB
   query/response API is used (sec.~\ref{s:queryrec}). 
 
-  In version 1.x
-  there is a restriction that at least one particular JobId must be
-  defined. In \LB 2.0 you cat make a registration based on other
-  attributes without referencing a particular JobId (you can select
-  owner, VO, network server).
-  \TODO{JDL flags?} 
-
- \item \emph {Refresh of a notification} When a new notification is
+  \marginpar{\LB 2.0 only}%
+  In version 1.x there is a restriction that at least one particular
+  JobId must be defined. In \LB 2.0 you can make a registration based
+  on other attributes without referencing a particular JobId (you can
+  select owner, VO, network server).  It is also a feature of \LB 2.0
+  only, that you can use attributes derived from JDL (VO).
+
+ \item \emph {Refresh of a notification}. When a new notification is
   created using \verb'edg_wll_NotifNew' call, the notification
   validity parameter is intended to set the refresh period, not the
   lifetime of the notification itself. The owner of notification must
   periodically call \verb'edg_wll_NotifRefresh' to ensure validity of
-  the notification.
+  the notification. See also next sections.
 
  \item It is possible to \emph{change existing notification} (its conditions) by
   \verb'edg_wll_NotifChange' call.
 
- \item If user does not want to receive notifications any more,
+ \item If the user does not want to receive notifications anymore,
   \verb'edg_wll_NotifDrop' call \emph{removes the registration} for
   notifications from \LB server.
 \end{itemize}
@@ -88,10 +88,11 @@ funcions.
 \subsection{Receive data}
 To receive data from a notificaton the API provides
 \verb'edg_wll_NotifReceive' call. It returns first incoming
-notification if at least one is available or waits a specified timeout. You can
-also set the timeout to zero if you want to poll.
+notification if at least one is available or waits for a new one. The
+maximal waiting time is limited to a specified timeout. You can also set the
+timeout to zero if you want to poll.
 
-If the user wants to start receiving the notifications from different
+If the user wants to move the client receiving the notifications to a different
 machine than where the registration was done, it is possible. The
 client must use the \verb'edg_wll_NotifBind' call to inform the
 notification infrastructure (interlogger) about its location change.
@@ -133,6 +134,49 @@ the whole set of registrations. Will receive a first notification from
 any of registations.
 
 \subsubsection{Operator CHANGED}
+\marginpar{\LB 2.0 only}%
+The notification events are generated by LB server based on primary
+events send by grid components. Each of the primary events (called LB
+events) generates one notification event to be possibly sent to the
+client but not each LB event for example changes the job state. You
+can use notification conditions to filter only the notification
+events you want to receive, for example $job status = done$. If you
+want to receive all job status changes you need to setup a condition
+on job status attribute using special unary operator
+\verb'CHANGED'. Otherwise (without any condition) you will receive
+more events that you want -- even events where job state was not
+changed. Operator \verb'CHANGED' is available only in \LB 2.0.
+
+\subsubsection{Returned attributes}
+\marginpar{\LB 2.0 only}%
+Each LB notification contains a structure describing job state
+including job's JDL. For optimization purposes the API user can set
+the JDL flag in \verb'edg_wll_NotifNew' flags parameter to prevent
+sending of unnecessary JDL data with each notification.
+
+\subsubsection{Timeouts}
+A user of the notification API should distinguish between various timeouts:
+\begin{itemize}
+\item \emph{Registration validity timeout.} Each registration is
+soft-state entity which must be refreshed in a given timeout. If there
+is no refresh received by the LB server in validity timeout period the
+registration is dropped. On the other hand for that timeout all events
+are queued in the LB infrastructure for the case of client's temporary
+unavailability.
+
+The registration validity timeout can be set by the user when creating
+a new registration but only to a reasonably short time period. The
+validity of a registration is driven by the refresh process not the
+timeout itself. For a exaple of registration management via the
+refresh calls please see the \verb'glite-lb-notify' source code as
+mentioned above.
+
+\item \emph{Receive call timeout.} The timeout used in the
+\verb'edg_wll_NotifReceive' call is inteded just to control the
+receiving loop. It is the maximum time the API can spend in the call
+before returning the control to user code.
+
+\end{itemize}
 
 \subsection{Registering and receiving notification example}