From: Niels Erik G. Nielsen Date: Thu, 6 Jun 2013 01:30:52 +0000 (-0400) Subject: Javadoc X-Git-Tag: v0.0.7~59 X-Git-Url: http://sru.miketaylor.org.uk/cgi-bin?a=commitdiff_plain;h=7df6b1590eb285bca094652950a23edc3da95f70;p=mkjsf-moved-to-github.git Javadoc --- diff --git a/overview.html b/overview.html new file mode 100644 index 0000000..17f74dd --- /dev/null +++ b/overview.html @@ -0,0 +1,5 @@ + + + Overview + + \ No newline at end of file diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/Pz2Service.java b/src/main/java/com/indexdata/mkjsf/pazpar2/Pz2Service.java index 55c4f25..734d177 100644 --- a/src/main/java/com/indexdata/mkjsf/pazpar2/Pz2Service.java +++ b/src/main/java/com/indexdata/mkjsf/pazpar2/Pz2Service.java @@ -36,6 +36,21 @@ import com.indexdata.mkjsf.pazpar2.state.StateListener; import com.indexdata.mkjsf.pazpar2.state.StateManager; import com.indexdata.mkjsf.utils.Utils; +/** + * Pz2Service is the main controller of the search logic, used for selecting the service + * type (which can be done by configuration and/or run-time), selecting which search client + * to use, and performing high-level control of request cycles and state management. + *

+ * Command and response beans are also obtained through Pz2Service - although it is + * transparent to the UI that they are retrieved through this object. + *

+ *

+ * Pz2Service is exposed to the UI as 'pz2'. However, if the service is pre-configured, + * the Faces pages might never need to reference 'pz2' explicitly. Indirectly they UI will, + * though, if the polling mechanism in the tag <pz2utils:pz2watch> is used. + * + * + **/ @Named("pz2") @SessionScoped public class Pz2Service implements StateListener, Configurable, Serializable { @@ -131,6 +146,16 @@ public class Pz2Service implements StateListener, Configurable, Serializable { return stateMgr; } + /** + * Configures the selected search client using the selected configuration reader. + * + * The configuration reader is select deploy-time - by configuration in the application's beans.xml. + * + * @param client search client to use + * @param configReader the selected configuration mechanism + * @throws MissingConfigurationContextException if this object is injected before there is a Faces context + * for example in a Servlet filter. + */ public void configureClient(SearchClient client, ConfigurationReader configReader) throws MissingConfigurationContextException { logger.debug(Utils.objectId(this) + " will configure search client for the session"); try { @@ -153,18 +178,39 @@ public class Pz2Service implements StateListener, Configurable, Serializable { /** - * Updates display data objects by issuing the following pazpar2 commands: - * 'show', 'stat', 'termlist' and 'bytarget'. - * - * If there is an outstanding change to the search command, a search - * will be issued before the updates are performed. - * - * Returns a count of the remaining active clients from the most recent search. - * - * After refreshing the data from pazpar2 the UI components displaying those - * data should be re-rendered. + * Updates display data objects by simultaneously issuing the following pazpar2 commands: + * 'show', 'stat', 'termlist' and 'bytarget'. + *

+ * If there are outstanding changes to the search command, a search + * will be issued before the updates are performed. Outstanding changes could come + * from the UI changing a search parameter and not executing search before starting + * the update cycle - OR - it could come from the user clicking the browsers back/forward + * buttons. + *

+ *

+ * This method is invoked from the composite 'pz2watch', which uses Ajax + * to keep invoking this method until it returns '0' (for zero active clients). + *

+ *

+ * UI components that display data from show, stat, termlist or bytarget, + * should be re-rendered after each update. + *

+ * Example of invocation in UI: + * 
+   *    <pz2utils:pz2watch id="pz2watch"
+   *       renderWhileActiveclients="myshowui mystatui mytermsui" /< 
+   *       
+   *    <h:form>
+   *     <h:inputText id="query" value="#{pzreq.search.query}" size="50"/>                            
+   *      <h:commandButton id="button" value="Search">              
+   *       <f:ajax execute="query" render="${pz2.watchActiveclients}"/>
+   *      </h:commandButton>
+   *     </h:form>
+   *
+ * The expression pz2.watchActiveClients will invoke the method repeatedly, and the + * UI sections myshowui, mystatui, and mytermsui will be rendered on each poll. * - * @return count of activeclients + * @return a count of the remaining active clients from the most recent search. */ public String update () { logger.debug("Updating show,stat,termlist,bytarget from pazpar2"); @@ -183,9 +229,11 @@ public class Pz2Service implements StateListener, Configurable, Serializable { } /** - * Refreshes the data objects listed in 'commands' from pazpar2 + * Simultaneously refreshes the data objects listed in 'commands' from pazpar2, potentially running a + * search or a record command first if any of these two commands have outstanding parameter changes. + * + * @param commands comma separated list of Pazpar2 commands to execute * - * @param commands * @return Number of activeclients at the time of the 'show' command, * or 'new' if search was just initiated. */ @@ -254,6 +302,10 @@ public class Pz2Service implements StateListener, Configurable, Serializable { * etc) this method checks if a search must be executed * before those updates are performed. * + * It will consequently also run a search if the UI updates a + * search parameter without actually explicitly executing the search + * before setting of the polling. + * * @see {@link com.indexdata.mkjsf.pazpar2.state.StateManager#setCurrentStateKey} * @param commands */ @@ -298,13 +350,12 @@ public class Pz2Service implements StateListener, Configurable, Serializable { } else { pzreq.getRecord().setId(recId); pzreq.getRecord().run(); - // doCommand("record"); return pzresp.getRecord().getActiveClients(); } } /** - * Resolves whether the backend has a record with the given recid in memory + * Resolves whether the back-end has a record with the given recid in memory * * @return true if the bean currently holds the record with recid */ diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Pazpar2Commands.java b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Pazpar2Commands.java index 67213e3..c9dc4c0 100644 --- a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Pazpar2Commands.java +++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Pazpar2Commands.java @@ -11,6 +11,25 @@ import com.indexdata.mkjsf.pazpar2.Pz2Service; import com.indexdata.mkjsf.pazpar2.commands.sp.ServiceProxyCommands; import com.indexdata.mkjsf.utils.Utils; +/** + * Pazpar2Commands holds references to all Pazpar2 commands. + *

+ * The Pazpar2Commands object itself is exposed to the UI as 'pzreq'. + *

+ *

+ * When the UI request a command it will be retrieved from the current state + * through the state manager, so that the command can trigger a mutation of + * the state if the user/UI modifies its parameters. + *

+ * Examples: + * + * + * @author Niels Erik + * + */ @SessionScoped @Named public class Pazpar2Commands implements Serializable { @@ -31,52 +50,93 @@ public class Pazpar2Commands implements Serializable { public Pazpar2Commands() { logger.info("Initializing Pazpar2Commands [" + Utils.objectId(this) + "]"); } - - // public void setService(Pz2Service service) { - // this.pz2 = service; - // logger.info("Post construct Pazpar2Command: Service is " + pz2); - // } - + + /** + * + * @return init command from current state + */ public InitCommand getInit() { return (InitCommand) (Pz2Service.get().getStateMgr().getCommand(INIT)); } + /** + * + * @return ping command from current state + */ public PingCommand getPing() { return (PingCommand) (Pz2Service.get().getStateMgr().getCommand(PING)); } + /** + * + * @return settings command from current state + */ public SettingsCommand getSettings() { return (SettingsCommand) (Pz2Service.get().getStateMgr().getCommand(SETTINGS)); } + /** + * + * @return search command from current state + */ public SearchCommand getSearch() { return (SearchCommand) (Pz2Service.get().getStateMgr().getCommand(SEARCH)); } + /** + * + * @return stat command from current state + */ public StatCommand getStat() { return (StatCommand) (Pz2Service.get().getStateMgr().getCommand(STAT)); } + /** + * + * @return show command from current state + */ public ShowCommand getShow() { return (ShowCommand) (Pz2Service.get().getStateMgr().getCommand(SHOW)); } + /** + * + * @return record command from current state + */ public RecordCommand getRecord() { return (RecordCommand) (Pz2Service.get().getStateMgr().getCommand(RECORD)); } + /** + * + * @return termlist command from current state + */ public TermlistCommand getTermlist() { return (TermlistCommand) (Pz2Service.get().getStateMgr().getCommand(TERMLIST)); } + /** + * + * @return bytarget command from current state + */ public BytargetCommand getBytarget() { return (BytargetCommand) (Pz2Service.get().getStateMgr().getCommand(BYTARGET)); } + /** + * Generically retrieves any command + * + * @param name name of command to retrieve + * @return command of the given type + */ public Pazpar2Command getCommand(String name) { return Pz2Service.get().getStateMgr().getCommand(name); } + /** + * Gets the object holding references to Service Proxy-only commands. + * @return + */ public ServiceProxyCommands getSp() { if (sp == null) { sp = new ServiceProxyCommands(Pz2Service.get().getStateMgr()); diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/AuthCommand.java b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/AuthCommand.java index 5013271..3167720 100644 --- a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/AuthCommand.java +++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/AuthCommand.java @@ -9,6 +9,12 @@ import com.indexdata.mkjsf.pazpar2.commands.Pazpar2Command; import com.indexdata.mkjsf.pazpar2.data.ResponseParser; import com.indexdata.mkjsf.pazpar2.data.sp.SpResponseDataObject; +/** + * Authenticates a user against a Pazpar2 Service Proxy + * + * @author Niels Erik + * + */ public class AuthCommand extends Pazpar2Command implements ServiceProxyCommand { private static final long serialVersionUID = 5487611235664162578L; diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/CategoriesCommand.java b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/CategoriesCommand.java index bccd65c..b3794ec 100644 --- a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/CategoriesCommand.java +++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/CategoriesCommand.java @@ -6,6 +6,20 @@ import com.indexdata.mkjsf.pazpar2.Pz2Service; import com.indexdata.mkjsf.pazpar2.commands.Pazpar2Command; import com.indexdata.mkjsf.pazpar2.data.sp.CategoriesResponse; +/** + * Retrieves target categories available to the current Service Proxy user. + *

+ * Target categories can be used to limit a search to resources tagged with the given + * category. The following request in a Faces page would obtain categories for displaying, say, a select list: + *

+ * pzreq.sp.categories.run().targetCategories + *

+ * This would get the Service Proxy extension commands, pick the categories command, execute it, and retrieve + * a list of TargetCategory objects from the returned response data object. + *

+ * @author Niels Erik + * + */ public class CategoriesCommand extends Pazpar2Command implements ServiceProxyCommand { private static final long serialVersionUID = 5023993689780291641L; diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/InitCommandSp.java b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/InitCommandSp.java index 629c07c..dba12b0 100644 --- a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/InitCommandSp.java +++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/InitCommandSp.java @@ -15,6 +15,14 @@ import com.indexdata.mkjsf.pazpar2.data.ResponseDataObject; import com.indexdata.mkjsf.pazpar2.data.ResponseParser; import com.indexdata.mkjsf.pazpar2.data.sp.SpResponseDataObject; +/** + * Service Proxy extensions to the init command - specifically + * support for POSTing to the Service Proxy an init doc containing Pazpar2 + * definitions and settings. + * + * @author Niels Erik + * + */ public class InitCommandSp implements Serializable, ServiceProxyCommand { private static final long serialVersionUID = -6609045941782375651L; diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/InitDocUpload.java b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/InitDocUpload.java index 1d0b90f..1d3d228 100644 --- a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/InitDocUpload.java +++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/InitDocUpload.java @@ -11,6 +11,12 @@ import org.apache.myfaces.custom.fileupload.UploadedFile; import com.indexdata.mkjsf.utils.FileUpload; import com.indexdata.mkjsf.utils.Utils; +/** + * Helper class for file upload of an Service Proxy init doc. + * + * @author Niels Erik + * + */ @Named @SessionScoped public class InitDocUpload extends FileUpload { diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/RecordCommandSp.java b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/RecordCommandSp.java index 0662df1..1d7cfc8 100644 --- a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/RecordCommandSp.java +++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/RecordCommandSp.java @@ -5,6 +5,12 @@ import java.io.Serializable; import com.indexdata.mkjsf.pazpar2.commands.CommandParameter; import com.indexdata.mkjsf.pazpar2.commands.RecordCommand; +/** + * Service Proxy extensions to the record command. + * + * @author Niels Erik + * + */ public class RecordCommandSp implements Serializable, ServiceProxyCommand { private static final long serialVersionUID = -3901864271733337221L; diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/ServiceProxyCommands.java b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/ServiceProxyCommands.java index 8c4fefa..8c34260 100644 --- a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/ServiceProxyCommands.java +++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/ServiceProxyCommands.java @@ -7,6 +7,13 @@ import org.apache.log4j.Logger; import com.indexdata.mkjsf.pazpar2.state.StateManager; import com.indexdata.mkjsf.utils.Utils; +/** + * ServiceProxyCommands holds references to all commands that are + * Service Proxy-only, that is, not supported by straight Pazpar2. + * + * @author Niels Erik + * + */ public class ServiceProxyCommands implements Serializable { public static final String AUTH = "auth"; diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/package-info.java b/src/main/java/com/indexdata/mkjsf/pazpar2/package-info.java new file mode 100644 index 0000000..640b810 --- /dev/null +++ b/src/main/java/com/indexdata/mkjsf/pazpar2/package-info.java @@ -0,0 +1,9 @@ +/** + * Overall control and execution of search logic. + *

+ * Classes in this package selects a service type and controls and performs + * the actual execution of commands against the selected service, eventually producing + * ClientCommandResponses for further processing elsewhere. + *

+ */ +package com.indexdata.mkjsf.pazpar2; \ No newline at end of file