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 <code>pz2</code>. However, if the service is pre-configured, \r
+ * the Faces pages might never need to reference <code>pz2</code> explicitly. Indirectly they will, \r
+ * though, if the polling mechanism in the tag <code><pz2utils:pz2watch></code> is used.\r
+ * \r
+ * \r
+ * <h3>Configuration</h3>\r
+ *\r
+ * Configuration name: service\r
+ * \r
+ * <p>When configuring the client using the Mk2Config scheme, this is the prefix to\r
+ * use in the .properties file. When using web.xml context parameters for configuration\r
+ * the configuration name has no effect.</p> \r
+ * \r
+ * <p>Pz2Service will acknowledge following configuration parameters:\r
+ * \r
+ * <ul>\r
+ * <li>(service.)TYPE</li> \r
+ * </ul> \r
+ * \r
+ * Possible values for service TYPE are: PZ2, SP, TBD. "TBD", meaning "to-be-decided runtime", is the default.\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
+ * 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
- * 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
- * \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, a 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
try {\r
if (commands.equals("search")) {\r
pzreq.getSearch().run();\r
+ pzresp.getSearch().setIsNew(false);\r
return "new";\r
} else if (commands.equals("record")) {\r
pzreq.getRecord().run();\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
if (stateMgr.hasPendingStateChange("search") && hasQuery()) { \r
logger.info("Triggered search: Found pending search change [" + pzreq.getCommand("search").toString() + "], doing search before updating " + commands); \r
pzreq.getSearch().run();\r
+ pzresp.getSearch().setIsNew(false);\r
} \r
if (stateMgr.hasPendingStateChange("record") && ! commands.equals("record")) { \r
logger.debug("Found pending record ID change. Doing record before updating " + commands);\r
}\r
}\r
\r
+ /**\r
+ * Used by the state manager to notify Pz2Service about state changes\r
+ */\r
@Override\r
public void stateUpdated(String commandName) {\r
logger.debug("State change reported for [" + commandName + "]");\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
return pager;\r
}\r
\r
+ /**\r
+ * Sets the URL of the Service Proxy to use for requests\r
+ * \r
+ * @param url\r
+ */\r
public void setServiceProxyUrl(String url) {\r
searchClient = spClient;\r
setServiceType(SERVICE_TYPE_SP);\r
setServiceUrl(url);\r
}\r
\r
+ /**\r
+ * Returns the Service Proxy URL currently defined for servicing requests\r
+ * \r
+ */\r
public String getServiceProxyUrl () {\r
if (isServiceProxyService()) {\r
return spClient.getServiceUrl();\r
return "";\r
}\r
}\r
- \r
+\r
+ /**\r
+ * Sets the URL of the Pazpar2 to use for requests\r
+ * \r
+ * @param url\r
+ */\r
public void setPazpar2Url(String url) {\r
searchClient = pz2Client;\r
setServiceType(SERVICE_TYPE_PZ2);\r
setServiceUrl(url);\r
}\r
\r
+ /**\r
+ * Returns the Pazpar2 URL currently defined for servicing requests\r
+ * \r
+ */ \r
public String getPazpar2Url() {\r
if (isPazpar2Service()) {\r
return pz2Client.getServiceUrl();\r
}\r
}\r
\r
+ /**\r
+ * Sets the URL to be used by the currently selected search client \r
+ * when running requests. \r
+ * \r
+ * @param url\r
+ */\r
public void setServiceUrl(String url) {\r
if (url!=null && searchClient != null && !url.equals(searchClient.getServiceUrl())) {\r
pzreq.getRecord().removeParametersInState();\r
} \r
}\r
\r
+ /**\r
+ * Gets the currently selected URL used for executing requests. \r
+ * @return\r
+ */\r
public String getServiceUrl() {\r
return (searchClient!=null ? searchClient.getServiceUrl() : "");\r
}\r
projects / mkjsf-moved-to-github.git / blobdiff