From: Niels Erik G. Nielsen <nielserik@indexdata.com>
Date: Wed, 5 Jun 2013 21:50:59 +0000 (-0400)
Subject: Javadoc, and fixes some issues found along the way
X-Git-Tag: v0.0.7~60
X-Git-Url: http://sru.miketaylor.org.uk/cgi-bin?a=commitdiff_plain;h=464c86e1706170a0be7be81d239d8c16fad78ec4;p=mkjsf-moved-to-github.git

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
--- 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 {
   }
   
   public String getValueWithExpressions () {
-    StringBuilder completeValue = new StringBuilder((value==null ? "" : value));    
+    StringBuilder completeValue = new StringBuilder((value==null ? "" : value));
+    boolean first=true;
     for (Expression expr : expressions) {      
-      completeValue.append(" and " + expr.toString());
+      if (value == null && first) {
+        first = false;
+        completeValue.append(expr.toString());
+      } else {
+        completeValue.append(" AND " + expr.toString());
+      }
     }
     return completeValue.toString();    
   }  
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
--- 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;
 import com.indexdata.mkjsf.pazpar2.data.Responses;
 
+/**
+ * Represents a generic Pazpar2 or Service Proxy command with all its current parameters, and has
+ * methods for executing the command against the currently selected Pazpar2 service</p>
+ * <p>Being an abstract class it only has generic methods for getting and setting parameters. 
+ * Implementing classes are supposed to create named getters and setters for convenient access
+ * to parameters from the UI.</p> 
+ * <p>Parameters can be set with or without notifying the state manager.<p>
+ * 
+ * <p><i>Note: Internally the application has to be able to set parameters without state changes 
+ * - for instance to avoid eternal feedback when copying parameter from one state to the next. A 
+ * setting from the UI should spawn a new search state however.</i></p>   
+ * 
+ * @author Niels Erik
+ *
+ */
 public abstract class Pazpar2Command implements Serializable  {
   
   private static Logger logger = Logger.getLogger(Pazpar2Command.class);
@@ -34,17 +49,42 @@ public abstract class Pazpar2Command implements Serializable  {
     this.name = name;    
   }
       
+  /**
+   * Commands must implement this method to provide an completely detached, deep clone of 
+   * themselves.
+   * 
+   * The clone is needed by the state manager to transfer commands with current setting 
+   * from one state to the next.
+   * 
+   * Whenever a non-standard attribute is added to a command class, the copy method must 
+   * be updated to ensure that the new attribute is brought over as well. 
+   *   
+   * @return a Pazpar2 command of the given type
+   */
   public abstract Pazpar2Command copy ();
           
   public String getCommandName() {
     return name;
   }
   
+  /**
+   * Executes the command with the currently selected parameters against 
+   * the currently selected Pazpar2 service
+   * 
+   * @return Response data object based on the Pazpar2 service response. 
+   */
   public ResponseDataObject run() {    
     return run(Pz2Service.get().getSearchClient(),
                Pz2Service.get().getPzresp());
   }
   
+  /**
+   * Executes the commands with the currently selected parameters, while adding
+   * the parameters provided
+   * @param parameters A list of parameters on the form [key=value]
+   * 
+   * @return Response data object based on the Pazpar2 service response
+   */
   public ResponseDataObject runWith(String... parameters) {
     for (String parameter : parameters) {
       StringTokenizer tokenizer = new StringTokenizer(parameter,"=");
@@ -57,9 +97,10 @@ public abstract class Pazpar2Command implements Serializable  {
   }
   
   /**
-   * For running the command in a thread. Client and Responses must be 
-   * provided because at this point the CDI bean cannot be retrieved 
-   * from within a thread.
+   * Executes the command in a thread.  
+   * 
+   * Note: Client and Responses must be provided because at this point 
+   * CDI beans cannot be retrieved from within a thread.
    * 
    * @param client
    * @param pzresp
@@ -75,7 +116,13 @@ public abstract class Pazpar2Command implements Serializable  {
     return responseObject;    
   }
   
-    
+   
+  /**
+   * Sets a parameter on this command and notifies the state manager
+   * about the change
+   * 
+   * @param parameter 
+   */
   public void setParameter (CommandParameter parameter) {
     Pazpar2Command copy = this.copy();
     logger.trace(name + " command: setting parameter [" + parameter.getName() + "=" + parameter.getValueWithExpressions() + "]");
@@ -83,6 +130,12 @@ public abstract class Pazpar2Command implements Serializable  {
     checkInState(copy);
   }
   
+  /**
+   * Sets multiple parameters on the command and notifies the state
+   * manager -- once -- about the change
+   * 
+   * @param params 
+   */
   public void setParameters (CommandParameter... params) {
     Pazpar2Command copy = this.copy();
     for (CommandParameter param : params) {
@@ -92,39 +145,86 @@ public abstract class Pazpar2Command implements Serializable  {
     checkInState(copy);
   }
   
+  /**
+   * Sets multiple parameters on this command without notifying the state manager. 
+   * Typically used when one parameter setting should automatically trigger
+   * other parameters to be reset to defaults etc. Intended to avoid 
+   * useless proliferation of states  
+   * 
+   * @param params
+   */
   public void setParametersInState (CommandParameter... params) {    
     for (CommandParameter param : params) {
       logger.trace(name + " command: setting parameter [" + param.getName() + "=" + param.getValueWithExpressions() + "] silently");
       parameters.put(param.getName(),param);
     }    
   }
-    
+  
+  /**
+   * Sets a parameter on this command without notifying the state manager. 
+   * Typically used when one parameter setting should automatically trigger
+   * other parameters to be reset to defaults etc. Intended to avoid 
+   * useless proliferation of states  
+   * 
+   * @param parameter
+   */    
   public void setParameterInState (CommandParameter parameter) {
     logger.trace(name + " command: setting parameter [" + parameter.getName() + "=" + parameter.getValueWithExpressions() + "] silently");
     parameters.put(parameter.getName(),parameter);    
   }
   
   
+  /**
+   * Retrieves a command parameter by parameter name
+   * 
+   * @param name of the parameter
+   * @return CommandParameter
+   */
   public CommandParameter getParameter (String name) {
     return parameters.get(name);
   }
   
+  /**
+   * Removes a parameter completely and notifies the state manager
+   * about the change
+   * 
+   * @param name of the parameter to remove
+   */
   public void removeParameter (String name) {
     Pazpar2Command copy = this.copy();
     copy.parameters.remove(name);
     checkInState(copy);
   }
   
+  /**
+   * Removes multiple parameters completely and notifies the state manager
+   * -- once -- about the change
+   * 
+   * @param name of the parameter to remove
+   */  
   public void removeParameters() {
     Pazpar2Command copy = this.copy();
     copy.parameters = new HashMap<String,CommandParameter>();
     checkInState(copy);
   }
   
+  
+  /**
+   * Removes all parameters without notifying the state manager. For instance
+   * used in case of change of Pazpar2 service or renewed login to a service.
+   *  
+   */
   public void removeParametersInState() {
     parameters = new HashMap<String,CommandParameter>();    
   }
   
+  /**
+   * Adds an expression to an ordered list of expressions on a given parameter
+   * and notifies the state manager of the change
+   * 
+   * @param parameterName name of the parameter to add the expression to
+   * @param expression
+   */
   public void addExpression(String parameterName, Expression expression) {
     Pazpar2Command copy = this.copy();
     copy.getParameter(parameterName).addExpression(expression);
@@ -201,9 +301,11 @@ public abstract class Pazpar2Command implements Serializable  {
     return getParameter(parameterName)==null ? "" : getParameter(parameterName).getValueWithExpressions();    
   }
 
+  /*
   public String getUrlEncodedParameterValue(String parameterName) {
     return getParameter(parameterName).getEncodedQueryString();
   }
+  */
   
   public void setSession (String sessionId) {
     setParameter(new CommandParameter("session","=",sessionId));
@@ -213,15 +315,32 @@ public abstract class Pazpar2Command implements Serializable  {
     return getParameterValue("session");
   } 
   
-  private void checkInState(Pazpar2Command command) {
+  /**
+   * Notifies the state manager that this command changed a parameter
+   * 
+   * @param command
+   */
+  protected void checkInState(Pazpar2Command command) {
     Pz2Service.get().getStateMgr().checkIn(command);
   }
-  
-  public String navigateTo (String target) {
-    return target;
-  }
-  
+    
+  /**
+   * Implementing classes must provide their Service Proxy 
+   * extension command if any extension parameters exists, 
+   * or -- just to be polite -- 'this' if there is no
+   * Service Proxy extension to the given command.
+   * @return
+   */
   public abstract ServiceProxyCommand getSp();
-   
+     
+  /**
+   * Implementing commands publishes whether they only 
+   * apply to the Service Proxy - or can be executed 
+   * against straight Pazpar2 as well. Convenient for a 
+   * UI that switches between service types - whether 
+   * deployment time or run time.
+   *   
+   * @return false if the command applies to straight Pazpar2
+   */
   public abstract boolean spOnly();  
 }
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
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;
+
+public class QueryParameter extends CommandParameter {
+
+  private static final long serialVersionUID = -3649052232241100927L;
+  private String booleanOperator = "AND";
+
+  public QueryParameter(String name) {
+    super(name);
+  }
+
+  public QueryParameter(String name, String operator, String value,
+      Expression... expressions) {
+    super(name, operator, value, expressions);
+  }
+
+  public QueryParameter(String name, String operator, Expression... expressions) {
+    super(name, operator, expressions);
+  }
+
+  public QueryParameter(String name, String operator, String value) {
+    super(name, operator, value);
+  }
+
+  public QueryParameter(String name, String operator, int value) {
+    super(name, operator, value);
+  }
+  
+  public void setBooleanOperator (String operator) {
+    this.booleanOperator = operator;
+  }
+  
+  public String getValueWithExpressions () {
+    StringBuilder completeValue = new StringBuilder((value==null ? "" : value));
+    boolean first = true;
+    for (Expression expr : expressions) {
+      if (value == null && first) {
+        first = false;
+        completeValue.append(expr.toString());
+      } else {
+        completeValue.append(" "+booleanOperator+" " + expr.toString());
+      }
+    }
+    return completeValue.toString();    
+  }  
+  
+  public QueryParameter copy() {    
+    QueryParameter newParam = new QueryParameter(name);
+    newParam.value = this.value;
+    newParam.operator = this.operator;
+    newParam.booleanOperator = this.booleanOperator;
+    for (Expression expr : expressions) {
+      newParam.addExpression(expr.copy());      
+    }
+    return newParam;
+  }
+
+
+}
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
--- 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
   }
     
   public void setQuery(String query) {    
-    setParameter(new CommandParameter("query","=",query));
+    setParameter(new QueryParameter("query","=",query));
+  }
+  
+  public void setBooleanOperatorForQuery(String operator) {
+    Pazpar2Command copy = this.copy();
+    ((QueryParameter) getParameter("query")).setBooleanOperator(operator);
+    checkInState(copy);
   }
   
   public String getQuery () {    
+    return getParameter("query") == null ? null  : getParameter("query").getSimpleValue();
+  }
+  
+  public String getExtendedQuery () {    
     return getParameter("query") == null ? null  : getParameter("query").getValueWithExpressions();
   }
   
@@ -109,7 +119,7 @@ public class SearchCommand extends Pazpar2Command implements ServiceProxyCommand
     if (getParameter("filter") == null) {
       setFilter(field + operator + value);
     } else {
-      getParameter("filter").addExpression(new Expression(field,operator,value,(label != null ? label : value)));
+      addExpression("filter",new Expression(field,operator,value,(label != null ? label : value)));
     }
   }
   
@@ -255,8 +265,8 @@ public class SearchCommand extends Pazpar2Command implements ServiceProxyCommand
    * @param term  i.e. 'Dickens, Charles'
    */
   public void setFacet(String facetKey, String term) {
-    if (term != null && term.length()>0) {         
-      getParameter("query").addExpression(new Expression(facetKey,"=",term,null));            
+    if (term != null && term.length()>0) { 
+      addExpression("query", new Expression(facetKey,"=",term,null));                  
     }            
   }
   
@@ -288,7 +298,7 @@ public class SearchCommand extends Pazpar2Command implements ServiceProxyCommand
    */
   public void removeFacet(String facetKey, String term) {
     if (getParameter("query") != null) {
-      getParameter("query").removeExpression(new Expression(facetKey,"=",term,null));
+      removeExpression("query",new Expression(facetKey,"=",term,null));
     }
   }
       
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
index 0000000..347e81e
--- /dev/null
+++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/package-info.java
@@ -0,0 +1,34 @@
+/**
+ * 
+ * Each Pazpar2 command is represented by a class with methods for 
+ * setting parameters and ultimately running the command against 
+ * the selected Pazpar2 service. 
+ * <p>
+ * The UI can access the command objects through the bean Pazpar2Commands, 
+ * which is exposed to the UI under the name 'pzreq'.
+ * </p>
+ * <p>
+ * For commands that has Service Proxy extension parameters, the UI 
+ * can access the extension parameters through the getSp() method
+ * on the command.
+ * </p>
+ * <p>
+ * The UI can access Service Proxy-only commands through the getSp()
+ * method on the pzreq bean.
+ * </p>
+ * Examples
+ * <ul>
+ *  <li>pzreq.search.query references getter and setter for the 
+ *          query parameter of the search command.</li>
+ * 
+ *  <li>pzreq.search.run() executes the search command with current
+ *          parameters</li>
+ *                      
+ *  <li>pzreq.record.sp.recordquery references a Service Proxy-only 
+ *          parameter to the record command</li> 
+ *         
+ *  <li>pzreq.sp.auth.run() executes a Service Proxy-only command</li> 
+ * </ul>          
+ *          
+ */
+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
index 0000000..750d4df
--- /dev/null
+++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/sp/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * Each Service Proxy-only command and each Pazpar2 command with Service Proxy-only parameters
+ * is represented by a class with methods for setting parameters and ultimately running the
+ * command against the selected Service Proxy.
+ */
+package com.indexdata.mkjsf.pazpar2.commands.sp;
\ No newline at end of file