Javadoc, and fixes some issues found along the way

diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/CommandParameter.java b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/CommandParameter.java
index d08cde1..f14e836 100644 (file)
--- a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/CommandParameter.java
+++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/CommandParameter.java
@@ -161,9 +161,15 @@ public class CommandParameter implements Serializable {
   }\r
   \r
   public String getValueWithExpressions () {\r
-    StringBuilder completeValue = new StringBuilder((value==null ? "" : value));    \r
+    StringBuilder completeValue = new StringBuilder((value==null ? "" : value));\r
+    boolean first=true;\r
     for (Expression expr : expressions) {      \r
-      completeValue.append(" and " + expr.toString());\r
+      if (value == null && first) {\r
+        first = false;\r
+        completeValue.append(expr.toString());\r
+      } else {\r
+        completeValue.append(" AND " + expr.toString());\r
+      }\r
     }\r
     return completeValue.toString();    \r
   }  \r

diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Pazpar2Command.java b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Pazpar2Command.java
index 7c0ec74..99b330e 100644 (file)
--- a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Pazpar2Command.java
+++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Pazpar2Command.java
@@ -16,6 +16,21 @@ import com.indexdata.mkjsf.pazpar2.data.ResponseDataObject;
 import com.indexdata.mkjsf.pazpar2.data.ResponseParser;\r
 import com.indexdata.mkjsf.pazpar2.data.Responses;\r
 \r
+/**\r
+ * Represents a generic Pazpar2 or Service Proxy command with all its current parameters, and has\r
+ * methods for executing the command against the currently selected Pazpar2 service</p>\r
+ * <p>Being an abstract class it only has generic methods for getting and setting parameters. \r
+ * Implementing classes are supposed to create named getters and setters for convenient access\r
+ * to parameters from the UI.</p> \r
+ * <p>Parameters can be set with or without notifying the state manager.<p>\r
+ * \r
+ * <p><i>Note: Internally the application has to be able to set parameters without state changes \r
+ * - for instance to avoid eternal feedback when copying parameter from one state to the next. A \r
+ * setting from the UI should spawn a new search state however.</i></p>   \r
+ * \r
+ * @author Niels Erik\r
+ *\r
+ */\r
 public abstract class Pazpar2Command implements Serializable  {\r
   \r
   private static Logger logger = Logger.getLogger(Pazpar2Command.class);\r
@@ -34,17 +49,42 @@ public abstract class Pazpar2Command implements Serializable  {
     this.name = name;    \r
   }\r
       \r
+  /**\r
+   * Commands must implement this method to provide an completely detached, deep clone of \r
+   * themselves.\r
+   * \r
+   * The clone is needed by the state manager to transfer commands with current setting \r
+   * from one state to the next.\r
+   * \r
+   * Whenever a non-standard attribute is added to a command class, the copy method must \r
+   * be updated to ensure that the new attribute is brought over as well. \r
+   *   \r
+   * @return a Pazpar2 command of the given type\r
+   */\r
   public abstract Pazpar2Command copy ();\r
           \r
   public String getCommandName() {\r
     return name;\r
   }\r
   \r
+  /**\r
+   * Executes the command with the currently selected parameters against \r
+   * the currently selected Pazpar2 service\r
+   * \r
+   * @return Response data object based on the Pazpar2 service response. \r
+   */\r
   public ResponseDataObject run() {    \r
     return run(Pz2Service.get().getSearchClient(),\r
                Pz2Service.get().getPzresp());\r
   }\r
   \r
+  /**\r
+   * Executes the commands with the currently selected parameters, while adding\r
+   * the parameters provided\r
+   * @param parameters A list of parameters on the form [key=value]\r
+   * \r
+   * @return Response data object based on the Pazpar2 service response\r
+   */\r
   public ResponseDataObject runWith(String... parameters) {\r
     for (String parameter : parameters) {\r
       StringTokenizer tokenizer = new StringTokenizer(parameter,"=");\r
@@ -57,9 +97,10 @@ public abstract class Pazpar2Command implements Serializable  {
   }\r
   \r
   /**\r
-   * For running the command in a thread. Client and Responses must be \r
-   * provided because at this point the CDI bean cannot be retrieved \r
-   * from within a thread.\r
+   * Executes the command in a thread.  \r
+   * \r
+   * Note: Client and Responses must be provided because at this point \r
+   * CDI beans cannot be retrieved from within a thread.\r
    * \r
    * @param client\r
    * @param pzresp\r
@@ -75,7 +116,13 @@ public abstract class Pazpar2Command implements Serializable  {
     return responseObject;    \r
   }\r
   \r
-    \r
+   \r
+  /**\r
+   * Sets a parameter on this command and notifies the state manager\r
+   * about the change\r
+   * \r
+   * @param parameter \r
+   */\r
   public void setParameter (CommandParameter parameter) {\r
     Pazpar2Command copy = this.copy();\r
     logger.trace(name + " command: setting parameter [" + parameter.getName() + "=" + parameter.getValueWithExpressions() + "]");\r
@@ -83,6 +130,12 @@ public abstract class Pazpar2Command implements Serializable  {
     checkInState(copy);\r
   }\r
   \r
+  /**\r
+   * Sets multiple parameters on the command and notifies the state\r
+   * manager -- once -- about the change\r
+   * \r
+   * @param params \r
+   */\r
   public void setParameters (CommandParameter... params) {\r
     Pazpar2Command copy = this.copy();\r
     for (CommandParameter param : params) {\r
@@ -92,39 +145,86 @@ public abstract class Pazpar2Command implements Serializable  {
     checkInState(copy);\r
   }\r
   \r
+  /**\r
+   * Sets multiple parameters on this command without notifying the state manager. \r
+   * Typically used when one parameter setting should automatically trigger\r
+   * other parameters to be reset to defaults etc. Intended to avoid \r
+   * useless proliferation of states  \r
+   * \r
+   * @param params\r
+   */\r
   public void setParametersInState (CommandParameter... params) {    \r
     for (CommandParameter param : params) {\r
       logger.trace(name + " command: setting parameter [" + param.getName() + "=" + param.getValueWithExpressions() + "] silently");\r
       parameters.put(param.getName(),param);\r
     }    \r
   }\r
-    \r
+  \r
+  /**\r
+   * Sets a parameter on this command without notifying the state manager. \r
+   * Typically used when one parameter setting should automatically trigger\r
+   * other parameters to be reset to defaults etc. Intended to avoid \r
+   * useless proliferation of states  \r
+   * \r
+   * @param parameter\r
+   */    \r
   public void setParameterInState (CommandParameter parameter) {\r
     logger.trace(name + " command: setting parameter [" + parameter.getName() + "=" + parameter.getValueWithExpressions() + "] silently");\r
     parameters.put(parameter.getName(),parameter);    \r
   }\r
   \r
   \r
+  /**\r
+   * Retrieves a command parameter by parameter name\r
+   * \r
+   * @param name of the parameter\r
+   * @return CommandParameter\r
+   */\r
   public CommandParameter getParameter (String name) {\r
     return parameters.get(name);\r
   }\r
   \r
+  /**\r
+   * Removes a parameter completely and notifies the state manager\r
+   * about the change\r
+   * \r
+   * @param name of the parameter to remove\r
+   */\r
   public void removeParameter (String name) {\r
     Pazpar2Command copy = this.copy();\r
     copy.parameters.remove(name);\r
     checkInState(copy);\r
   }\r
   \r
+  /**\r
+   * Removes multiple parameters completely and notifies the state manager\r
+   * -- once -- about the change\r
+   * \r
+   * @param name of the parameter to remove\r
+   */  \r
   public void removeParameters() {\r
     Pazpar2Command copy = this.copy();\r
     copy.parameters = new HashMap<String,CommandParameter>();\r
     checkInState(copy);\r
   }\r
   \r
+  \r
+  /**\r
+   * Removes all parameters without notifying the state manager. For instance\r
+   * used in case of change of Pazpar2 service or renewed login to a service.\r
+   *  \r
+   */\r
   public void removeParametersInState() {\r
     parameters = new HashMap<String,CommandParameter>();    \r
   }\r
   \r
+  /**\r
+   * Adds an expression to an ordered list of expressions on a given parameter\r
+   * and notifies the state manager of the change\r
+   * \r
+   * @param parameterName name of the parameter to add the expression to\r
+   * @param expression\r
+   */\r
   public void addExpression(String parameterName, Expression expression) {\r
     Pazpar2Command copy = this.copy();\r
     copy.getParameter(parameterName).addExpression(expression);\r
@@ -201,9 +301,11 @@ public abstract class Pazpar2Command implements Serializable  {
     return getParameter(parameterName)==null ? "" : getParameter(parameterName).getValueWithExpressions();    \r
   }\r
 \r
+  /*\r
   public String getUrlEncodedParameterValue(String parameterName) {\r
     return getParameter(parameterName).getEncodedQueryString();\r
   }\r
+  */\r
   \r
   public void setSession (String sessionId) {\r
     setParameter(new CommandParameter("session","=",sessionId));\r
@@ -213,15 +315,32 @@ public abstract class Pazpar2Command implements Serializable  {
     return getParameterValue("session");\r
   } \r
   \r
-  private void checkInState(Pazpar2Command command) {\r
+  /**\r
+   * Notifies the state manager that this command changed a parameter\r
+   * \r
+   * @param command\r
+   */\r
+  protected void checkInState(Pazpar2Command command) {\r
     Pz2Service.get().getStateMgr().checkIn(command);\r
   }\r
-  \r
-  public String navigateTo (String target) {\r
-    return target;\r
-  }\r
-  \r
+    \r
+  /**\r
+   * Implementing classes must provide their Service Proxy \r
+   * extension command if any extension parameters exists, \r
+   * or -- just to be polite -- 'this' if there is no\r
+   * Service Proxy extension to the given command.\r
+   * @return\r
+   */\r
   public abstract ServiceProxyCommand getSp();\r
-   \r
+     \r
+  /**\r
+   * Implementing commands publishes whether they only \r
+   * apply to the Service Proxy - or can be executed \r
+   * against straight Pazpar2 as well. Convenient for a \r
+   * UI that switches between service types - whether \r
+   * deployment time or run time.\r
+   *   \r
+   * @return false if the command applies to straight Pazpar2\r
+   */\r
   public abstract boolean spOnly();  \r
 }\r

diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/QueryParameter.java b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/QueryParameter.java
new file mode 100644 (file)
index 0000000..68a49d0
--- /dev/null
+++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/QueryParameter.java
@@ -0,0 +1,59 @@
+package com.indexdata.mkjsf.pazpar2.commands;\r
+\r
+public class QueryParameter extends CommandParameter {\r
+\r
+  private static final long serialVersionUID = -3649052232241100927L;\r
+  private String booleanOperator = "AND";\r
+\r
+  public QueryParameter(String name) {\r
+    super(name);\r
+  }\r
+\r
+  public QueryParameter(String name, String operator, String value,\r
+      Expression... expressions) {\r
+    super(name, operator, value, expressions);\r
+  }\r
+\r
+  public QueryParameter(String name, String operator, Expression... expressions) {\r
+    super(name, operator, expressions);\r
+  }\r
+\r
+  public QueryParameter(String name, String operator, String value) {\r
+    super(name, operator, value);\r
+  }\r
+\r
+  public QueryParameter(String name, String operator, int value) {\r
+    super(name, operator, value);\r
+  }\r
+  \r
+  public void setBooleanOperator (String operator) {\r
+    this.booleanOperator = operator;\r
+  }\r
+  \r
+  public String getValueWithExpressions () {\r
+    StringBuilder completeValue = new StringBuilder((value==null ? "" : value));\r
+    boolean first = true;\r
+    for (Expression expr : expressions) {\r
+      if (value == null && first) {\r
+        first = false;\r
+        completeValue.append(expr.toString());\r
+      } else {\r
+        completeValue.append(" "+booleanOperator+" " + expr.toString());\r
+      }\r
+    }\r
+    return completeValue.toString();    \r
+  }  \r
+  \r
+  public QueryParameter copy() {    \r
+    QueryParameter newParam = new QueryParameter(name);\r
+    newParam.value = this.value;\r
+    newParam.operator = this.operator;\r
+    newParam.booleanOperator = this.booleanOperator;\r
+    for (Expression expr : expressions) {\r
+      newParam.addExpression(expr.copy());      \r
+    }\r
+    return newParam;\r
+  }\r
+\r
+\r
+}\r

diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/SearchCommand.java b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/SearchCommand.java
index 1285b2a..e36b239 100644 (file)
--- a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/SearchCommand.java
+++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/SearchCommand.java
@@ -33,10 +33,20 @@ public class SearchCommand extends Pazpar2Command implements ServiceProxyCommand
   }\r
     \r
   public void setQuery(String query) {    \r
-    setParameter(new CommandParameter("query","=",query));\r
+    setParameter(new QueryParameter("query","=",query));\r
+  }\r
+  \r
+  public void setBooleanOperatorForQuery(String operator) {\r
+    Pazpar2Command copy = this.copy();\r
+    ((QueryParameter) getParameter("query")).setBooleanOperator(operator);\r
+    checkInState(copy);\r
   }\r
   \r
   public String getQuery () {    \r
+    return getParameter("query") == null ? null  : getParameter("query").getSimpleValue();\r
+  }\r
+  \r
+  public String getExtendedQuery () {    \r
     return getParameter("query") == null ? null  : getParameter("query").getValueWithExpressions();\r
   }\r
   \r
@@ -109,7 +119,7 @@ public class SearchCommand extends Pazpar2Command implements ServiceProxyCommand
     if (getParameter("filter") == null) {\r
       setFilter(field + operator + value);\r
     } else {\r
-      getParameter("filter").addExpression(new Expression(field,operator,value,(label != null ? label : value)));\r
+      addExpression("filter",new Expression(field,operator,value,(label != null ? label : value)));\r
     }\r
   }\r
   \r
@@ -255,8 +265,8 @@ public class SearchCommand extends Pazpar2Command implements ServiceProxyCommand
    * @param term  i.e. 'Dickens, Charles'\r
    */\r
   public void setFacet(String facetKey, String term) {\r
-    if (term != null && term.length()>0) {         \r
-      getParameter("query").addExpression(new Expression(facetKey,"=",term,null));            \r
+    if (term != null && term.length()>0) { \r
+      addExpression("query", new Expression(facetKey,"=",term,null));                  \r
     }            \r
   }\r
   \r
@@ -288,7 +298,7 @@ public class SearchCommand extends Pazpar2Command implements ServiceProxyCommand
    */\r
   public void removeFacet(String facetKey, String term) {\r
     if (getParameter("query") != null) {\r
-      getParameter("query").removeExpression(new Expression(facetKey,"=",term,null));\r
+      removeExpression("query",new Expression(facetKey,"=",term,null));\r
     }\r
   }\r
       \r

diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/package-info.java b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/package-info.java
new file mode 100644 (file)
index 0000000..347e81e
--- /dev/null
+++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/package-info.java
@@ -0,0 +1,34 @@
+/**\r
+ * \r
+ * Each Pazpar2 command is represented by a class with methods for \r
+ * setting parameters and ultimately running the command against \r
+ * the selected Pazpar2 service. \r
+ * <p>\r
+ * The UI can access the command objects through the bean Pazpar2Commands, \r
+ * which is exposed to the UI under the name 'pzreq'.\r
+ * </p>\r
+ * <p>\r
+ * For commands that has Service Proxy extension parameters, the UI \r
+ * can access the extension parameters through the getSp() method\r
+ * on the command.\r
+ * </p>\r
+ * <p>\r
+ * The UI can access Service Proxy-only commands through the getSp()\r
+ * method on the pzreq bean.\r
+ * </p>\r
+ * Examples\r
+ * <ul>\r
+ *  <li>pzreq.search.query references getter and setter for the \r
+ *          query parameter of the search command.</li>\r
+ * \r
+ *  <li>pzreq.search.run() executes the search command with current\r
+ *          parameters</li>\r
+ *                      \r
+ *  <li>pzreq.record.sp.recordquery references a Service Proxy-only \r
+ *          parameter to the record command</li> \r
+ *         \r
+ *  <li>pzreq.sp.auth.run() executes a Service Proxy-only command</li> \r
+ * </ul>          \r
+ *          \r
+ */\r
+package com.indexdata.mkjsf.pazpar2.commands;
\ No newline at end of file

diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/package-info.java b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/package-info.java
new file mode 100644 (file)
index 0000000..750d4df
--- /dev/null
+++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/package-info.java
@@ -0,0 +1,6 @@
+/**\r
+ * Each Service Proxy-only command and each Pazpar2 command with Service Proxy-only parameters\r
+ * is represented by a class with methods for setting parameters and ultimately running the\r
+ * command against the selected Service Proxy.\r
+ */\r
+package com.indexdata.mkjsf.pazpar2.commands.sp;
\ No newline at end of file