--- /dev/null
+<html>\r
+ <body>\r
+ Overview\r
+ </body>\r
+</html>
\ No newline at end of file
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
import com.indexdata.mkjsf.pazpar2.commands.sp.ServiceProxyCommands;\r
import com.indexdata.mkjsf.utils.Utils;\r
\r
+/**\r
+ * Pazpar2Commands holds references to all Pazpar2 commands. \r
+ * <p>\r
+ * The Pazpar2Commands object itself is exposed to the UI as 'pzreq'. \r
+ * </p>\r
+ * <p>\r
+ * When the UI request a command it will be retrieved from the current state\r
+ * through the state manager, so that the command can trigger a mutation of \r
+ * the state if the user/UI modifies its parameters. \r
+ * </p>\r
+ * Examples:\r
+ * <ul>\r
+ * <li>pzreq.show - will retrieve the show command for editing or execution\r
+ * <li>pzreq.sp.auth - will retrieve the Service Proxy extension command 'auth'\r
+ * </ul>\r
+ * \r
+ * @author Niels Erik\r
+ *\r
+ */\r
@SessionScoped @Named\r
public class Pazpar2Commands implements Serializable {\r
\r
public Pazpar2Commands() {\r
logger.info("Initializing Pazpar2Commands [" + Utils.objectId(this) + "]"); \r
}\r
- \r
- // public void setService(Pz2Service service) {\r
- // this.pz2 = service;\r
- // logger.info("Post construct Pazpar2Command: Service is " + pz2); \r
- // }\r
- \r
+ \r
+ /**\r
+ * \r
+ * @return init command from current state\r
+ */\r
public InitCommand getInit() {\r
return (InitCommand) (Pz2Service.get().getStateMgr().getCommand(INIT)); \r
}\r
\r
+ /** \r
+ * \r
+ * @return ping command from current state \r
+ */\r
public PingCommand getPing() {\r
return (PingCommand) (Pz2Service.get().getStateMgr().getCommand(PING));\r
}\r
\r
+ /**\r
+ * \r
+ * @return settings command from current state\r
+ */\r
public SettingsCommand getSettings() {\r
return (SettingsCommand) (Pz2Service.get().getStateMgr().getCommand(SETTINGS));\r
}\r
\r
+ /**\r
+ * \r
+ * @return search command from current state\r
+ */\r
public SearchCommand getSearch() {\r
return (SearchCommand) (Pz2Service.get().getStateMgr().getCommand(SEARCH));\r
}\r
\r
+ /**\r
+ * \r
+ * @return stat command from current state\r
+ */\r
public StatCommand getStat() {\r
return (StatCommand) (Pz2Service.get().getStateMgr().getCommand(STAT));\r
}\r
\r
+ /**\r
+ * \r
+ * @return show command from current state\r
+ */\r
public ShowCommand getShow() {\r
return (ShowCommand) (Pz2Service.get().getStateMgr().getCommand(SHOW));\r
}\r
\r
+ /**\r
+ * \r
+ * @return record command from current state\r
+ */\r
public RecordCommand getRecord() {\r
return (RecordCommand) (Pz2Service.get().getStateMgr().getCommand(RECORD));\r
}\r
\r
+ /**\r
+ * \r
+ * @return termlist command from current state\r
+ */\r
public TermlistCommand getTermlist() {\r
return (TermlistCommand) (Pz2Service.get().getStateMgr().getCommand(TERMLIST));\r
}\r
\r
+ /**\r
+ * \r
+ * @return bytarget command from current state\r
+ */\r
public BytargetCommand getBytarget() {\r
return (BytargetCommand) (Pz2Service.get().getStateMgr().getCommand(BYTARGET));\r
}\r
\r
+ /**\r
+ * Generically retrieves any command\r
+ * \r
+ * @param name name of command to retrieve\r
+ * @return command of the given type\r
+ */\r
public Pazpar2Command getCommand(String name) { \r
return Pz2Service.get().getStateMgr().getCommand(name);\r
}\r
\r
+ /**\r
+ * Gets the object holding references to Service Proxy-only commands.\r
+ * @return\r
+ */\r
public ServiceProxyCommands getSp() {\r
if (sp == null) {\r
sp = new ServiceProxyCommands(Pz2Service.get().getStateMgr());\r
import com.indexdata.mkjsf.pazpar2.data.ResponseParser;\r
import com.indexdata.mkjsf.pazpar2.data.sp.SpResponseDataObject;\r
\r
+/**\r
+ * Authenticates a user against a Pazpar2 Service Proxy\r
+ * \r
+ * @author Niels Erik\r
+ *\r
+ */\r
public class AuthCommand extends Pazpar2Command implements ServiceProxyCommand {\r
\r
private static final long serialVersionUID = 5487611235664162578L;\r
import com.indexdata.mkjsf.pazpar2.commands.Pazpar2Command;\r
import com.indexdata.mkjsf.pazpar2.data.sp.CategoriesResponse;\r
\r
+/**\r
+ * Retrieves target categories available to the current Service Proxy user.\r
+ * <p>\r
+ * Target categories can be used to limit a search to resources tagged with the given \r
+ * category. The following request in a Faces page would obtain categories for displaying, say, a select list:\r
+ * <p>\r
+ * pzreq.sp.categories.run().targetCategories \r
+ * <p>\r
+ * This would get the Service Proxy extension commands, pick the categories command, execute it, and retrieve\r
+ * a list of TargetCategory objects from the returned response data object. \r
+ * </p>\r
+ * @author Niels Erik\r
+ *\r
+ */\r
public class CategoriesCommand extends Pazpar2Command implements ServiceProxyCommand {\r
\r
private static final long serialVersionUID = 5023993689780291641L;\r
import com.indexdata.mkjsf.pazpar2.data.ResponseParser;\r
import com.indexdata.mkjsf.pazpar2.data.sp.SpResponseDataObject;\r
\r
+/**\r
+ * Service Proxy extensions to the init command - specifically \r
+ * support for POSTing to the Service Proxy an init doc containing Pazpar2 \r
+ * definitions and settings. \r
+ * \r
+ * @author Niels Erik\r
+ *\r
+ */\r
public class InitCommandSp implements Serializable, ServiceProxyCommand {\r
\r
private static final long serialVersionUID = -6609045941782375651L;\r
import com.indexdata.mkjsf.utils.FileUpload;\r
import com.indexdata.mkjsf.utils.Utils;\r
\r
+/**\r
+ * Helper class for file upload of an Service Proxy init doc.\r
+ * \r
+ * @author Niels Erik\r
+ *\r
+ */\r
@Named\r
@SessionScoped\r
public class InitDocUpload extends FileUpload {\r
import com.indexdata.mkjsf.pazpar2.commands.CommandParameter;\r
import com.indexdata.mkjsf.pazpar2.commands.RecordCommand;\r
\r
+/**\r
+ * Service Proxy extensions to the record command. \r
+ * \r
+ * @author Niels Erik\r
+ *\r
+ */\r
public class RecordCommandSp implements Serializable, ServiceProxyCommand {\r
\r
private static final long serialVersionUID = -3901864271733337221L;\r
import com.indexdata.mkjsf.pazpar2.state.StateManager;\r
import com.indexdata.mkjsf.utils.Utils;\r
\r
+/**\r
+ * ServiceProxyCommands holds references to all commands that are \r
+ * Service Proxy-only, that is, not supported by straight Pazpar2.\r
+ * \r
+ * @author Niels Erik\r
+ *\r
+ */\r
public class ServiceProxyCommands implements Serializable {\r
\r
public static final String AUTH = "auth";\r
--- /dev/null
+/**\r
+ * Overall control and execution of search logic. \r
+ * <p>\r
+ * Classes in this package selects a service type and controls and performs \r
+ * the actual execution of commands against the selected service, eventually producing \r
+ * ClientCommandResponses for further processing elsewhere. \r
+ * </p> \r
+ */\r
+package com.indexdata.mkjsf.pazpar2;
\ No newline at end of file
projects / mkjsf-moved-to-github.git / commitdiff