import com.indexdata.mkjsf.pazpar2.state.StateManager;\r
import com.indexdata.mkjsf.utils.Utils;\r
\r
+/** \r
+ * Pz2Service is the main controller of the search logic, used for selecting the service \r
+ * type (which can be done by configuration and/or run-time), selecting which search client \r
+ * to use, and performing high-level control of request cycles and state management. \r
+ * <p>\r
+ * Command and response beans are also obtained through Pz2Service - although it is \r
+ * transparent to the UI that they are retrieved through this object.\r
+ * </p>\r
+ * <p>\r
+ * Pz2Service is exposed to the UI as 'pz2'. However, if the service is pre-configured, \r
+ * the Faces pages might never need to reference 'pz2' explicitly. Indirectly they UI will, \r
+ * though, if the polling mechanism in the tag <pz2utils:pz2watch> is used.\r
+ * \r
+ * \r
+ **/ \r
@Named("pz2") @SessionScoped\r
public class Pz2Service implements StateListener, Configurable, Serializable {\r
\r
return stateMgr;\r
}\r
\r
+ /**\r
+ * Configures the selected search client using the selected configuration reader.\r
+ * \r
+ * The configuration reader is select deploy-time - by configuration in the application's beans.xml.\r
+ * \r
+ * @param client search client to use\r
+ * @param configReader the selected configuration mechanism\r
+ * @throws MissingConfigurationContextException if this object is injected before there is a Faces context\r
+ * for example in a Servlet filter.\r
+ */\r
public void configureClient(SearchClient client, ConfigurationReader configReader) throws MissingConfigurationContextException {\r
logger.debug(Utils.objectId(this) + " will configure search client for the session");\r
try {\r
\r
\r
/**\r
- * 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
* \r
- * @return count of activeclients \r
+ * @return a count of the remaining active clients from the most recent search. \r
*/ \r
public String update () {\r
logger.debug("Updating show,stat,termlist,bytarget from pazpar2");\r
}\r
\r
/**\r
- * Refreshes the data objects listed in 'commands' from pazpar2\r
+ * Simultaneously refreshes the data objects listed in 'commands' from pazpar2, potentially running a\r
+ * search or a record command first if any of these two commands have outstanding parameter changes.\r
+ * \r
+ * @param commands comma separated list of Pazpar2 commands to execute\r
* \r
- * @param commands\r
* @return Number of activeclients at the time of the 'show' command,\r
* or 'new' if search was just initiated.\r
*/\r
* etc) this method checks if a search must be executed\r
* before those updates are performed.\r
* \r
+ * It will consequently also run a search if the UI updates a\r
+ * search parameter without actually explicitly executing the search \r
+ * before setting of the polling.\r
+ * \r
* @see {@link com.indexdata.mkjsf.pazpar2.state.StateManager#setCurrentStateKey} \r
* @param commands\r
*/\r
} else {\r
pzreq.getRecord().setId(recId);\r
pzreq.getRecord().run();\r
- // doCommand("record");\r
return pzresp.getRecord().getActiveClients();\r
}\r
}\r
\r
/**\r
- * Resolves whether the backend has a record with the given recid in memory \r
+ * Resolves whether the back-end has a record with the given recid in memory \r
* \r
* @return true if the bean currently holds the record with recid\r
*/ \r
projects / mkjsf-moved-to-github.git / blobdiff