- * Updates display data objects by issuing the following pazpar2 commands: \r
- * 'show', 'stat', 'termlist' and 'bytarget'.\r
- * \r
- * If there is an outstanding change to the search command, a search\r
- * will be issued before the updates are performed. \r
- * \r
- * Returns a count of the remaining active clients from the most recent search.\r
- * \r
- * After refreshing the data from pazpar2 the UI components displaying those \r
- * data should be re-rendered.\r
+ * Updates display data objects by simultaneously issuing the following pazpar2 commands: \r
+ * 'show', 'stat', 'termlist' and 'bytarget'. \r
+ * <p>\r
+ * If there are outstanding changes to the search command, a search\r
+ * will be issued before the updates are performed. Outstanding changes could come \r
+ * from the UI changing a search parameter and not executing search before starting \r
+ * the update cycle - OR - it could come from the user clicking the browsers back/forward\r
+ * buttons. \r
+ * </p>\r
+ * <p>\r
+ * This method is invoked from the composite 'pz2watch', which uses Ajax\r
+ * to keep invoking this method until it returns '0' (for zero active clients).\r
+ * </p>\r
+ * <p>\r
+ * UI components that display data from show, stat, termlist or bytarget, \r
+ * should be re-rendered after each update. \r
+ * </p>\r
+ * Example of invocation in UI:\r
+ * <pre>\r
+ * <pz2utils:pz2watch id="pz2watch"\r
+ * renderWhileActiveclients="myshowui mystatui mytermsui" /< \r
+ * \r
+ * <h:form>\r
+ * <h:inputText id="query" value="#{pzreq.search.query}" size="50"/> \r
+ * <h:commandButton id="button" value="Search"> \r
+ * <f:ajax execute="query" render="${pz2.watchActiveclients}"/>\r
+ * </h:commandButton>\r
+ * </h:form>\r
+ * </pre>\r
+ * The expression pz2.watchActiveClients will invoke the method repeatedly, and the\r
+ * UI sections myshowui, mystatui, and mytermsui will be rendered on each poll. \r