Javadoc

diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/BytargetCommand.java b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/BytargetCommand.java
index 89a5bbd..daea58a 100644 (file)
--- a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/BytargetCommand.java
+++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/BytargetCommand.java
@@ -2,6 +2,12 @@ package com.indexdata.mkjsf.pazpar2.commands;
 \r
 import com.indexdata.mkjsf.pazpar2.commands.sp.ServiceProxyCommand;\r
 \r
+/**\r
+ * Represents a Pazpar2 'bytarget' command\r
+ * \r
+ * @author Niels Erik\r
+ *\r
+ */\r
 public class BytargetCommand extends Pazpar2Command implements ServiceProxyCommand {\r
 \r
   private static final long serialVersionUID = 9070458716105294392L;\r

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 f14e836..eaff692 100644 (file)
--- a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/CommandParameter.java
+++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/CommandParameter.java
@@ -10,6 +10,18 @@ import java.util.List;
 \r
 import org.apache.log4j.Logger;\r
 \r
+/**\r
+ * Represents a Pazpar2 command parameter with a name, an operator, \r
+ * a simple value and/or one or more complex values (expressions).\r
+ * <p>Examples</p>\r
+ * <ul>\r
+ *  <li>{name}{=}{value}</li>\r
+ *  <li>{name}{=}{value} AND {expr1=value1} AND {expr2=value2}</li>\r
+ *  <li>{name}{=}{expr1~value1},{expr2~value2}</li> \r
+ * </ul> \r
+ * @author Niels Erik\r
+ *\r
+ */\r
 public class CommandParameter implements Serializable {\r
 \r
   private static Logger logger = Logger.getLogger(CommandParameter.class);\r
@@ -26,6 +38,14 @@ public class CommandParameter implements Serializable {
     this.name = name;\r
   }\r
   \r
+  /**\r
+   * Instantiates a parameter with a simple value and one or more expressions\r
+   * \r
+   * @param name\r
+   * @param operator\r
+   * @param value\r
+   * @param expressions\r
+   */\r
   public CommandParameter (String name, String operator, String value, Expression... expressions) {\r
     logger.trace("Instantiating command parameter " + name + " with value [" + value + "] and expressions: [" + expressions + "]");\r
     this.name = name;\r
@@ -36,6 +56,12 @@ public class CommandParameter implements Serializable {
     }\r
   }\r
   \r
+  /**\r
+   * Instantiates a parameter with one or more expressions\r
+   * @param name\r
+   * @param operator\r
+   * @param expressions\r
+   */\r
   public CommandParameter (String name, String operator, Expression... expressions) {\r
     logger.trace("Instantiating command parameter " + name + " with expressions: [" + expressions + "]");\r
     this.name = name;\r
@@ -46,6 +72,12 @@ public class CommandParameter implements Serializable {
   }\r
 \r
 \r
+  /**\r
+   * Instantiates a parameter with a simple value\r
+   * @param name\r
+   * @param operator\r
+   * @param value\r
+   */\r
   public CommandParameter (String name, String operator, String value) {\r
     if (!nologparams.contains(name)) logger.trace("Instantiating command parameter '" + name + "' with String: [" + value + "]");    \r
     this.name = name;\r
@@ -53,6 +85,12 @@ public class CommandParameter implements Serializable {
     this.value = value;    \r
   }\r
   \r
+  /**\r
+   * Instantiates a parameter with a numeric value\r
+   * @param name\r
+   * @param operator\r
+   * @param value\r
+   */\r
   public CommandParameter (String name, String operator, int value) {\r
     logger.trace("Instantiating command parameter '" + name + "' with int: [" + value + "]");\r
     this.name = name;\r
@@ -60,15 +98,34 @@ public class CommandParameter implements Serializable {
     this.value = value+"";    \r
   }\r
 \r
-  \r
+  /**\r
+   * Returns the name (left of operator) of this parameter\r
+   * \r
+   * @return name (left of operator) of this parameter\r
+   */\r
   public String getName () {\r
     return name;\r
   }\r
   \r
+  /**\r
+   * Returns a list of all current expressions\r
+   * \r
+   * @return a list of all current expressions\r
+   */\r
   public List<Expression> getExpressions () {\r
     return expressions;\r
   }\r
-  \r
+\r
+  /**\r
+   * Returns expressions selected by their left-hand keys - as in 'expressionField=value'.\r
+   * <p>\r
+   * If the parameter has expressions expr1=x,expr2=y,expr3=z,expr1=u then invoking this method \r
+   * with {"expr1","expr3"} would return expr1=x,expr3=z,expr1=u but not expr2=y.   \r
+   * </p>\r
+   * @param expressionFields The expression types to return\r
+   * @return a list of expressions with the given keys to the left of the operator\r
+   * \r
+   */\r
   public List<Expression> getExpressions(String... expressionFields) {\r
     List<String> requestedFields = Arrays.asList(expressionFields);\r
     List<Expression> exprs = new ArrayList<Expression>();\r
@@ -80,11 +137,21 @@ public class CommandParameter implements Serializable {
     return exprs;\r
   }\r
   \r
+  /**\r
+   * Adds an expression to the end of the list of current expressions (if any)\r
+   * \r
+   * @param expression to add\r
+   */\r
   public void addExpression(Expression expression) {\r
     logger.debug("Adding expression [" + expression + "] to '" + name + "'");\r
     this.expressions.add(expression);\r
   }\r
   \r
+  /**\r
+   * Removes a single expression identified by all its characteristics\r
+   * \r
+   * @param expression to remove\r
+   */\r
   public void removeExpression(Expression expression) {\r
     for (Expression expr : expressions) {\r
       if (expr.toString().equals(expression.toString())) {\r
@@ -94,6 +161,15 @@ public class CommandParameter implements Serializable {
     }    \r
   }\r
   \r
+  /**\r
+   * Removes all expressions that appear after the provided expression and that \r
+   * have the given keys to the left of their operators - as in 'expressionField=value'.\r
+   * <p>\r
+   * This method is intended for bread crumb-like UI controls\r
+   * </p>\r
+   * @param expression The expression to use a starting point for removal (not inclusive)\r
+   * @param expressionFields The expression fields to remove\r
+   */\r
   public void removeExpressionsAfter (Expression expression, String... expressionFields) {\r
     List<String> exprFieldsToRemove = Arrays.asList(expressionFields);\r
     int fromIdx = 0;    \r
@@ -114,6 +190,16 @@ public class CommandParameter implements Serializable {
     }\r
   }\r
   \r
+  /**\r
+   * Removes expressions selected by their left-of-operator fields/keys - as in 'expressionField=value'.\r
+   * <p>\r
+   * If the parameter has expressions expr1=x,expr2=y,expr3=z,expr1=u then invoking this method \r
+   * with {"expr1","expr3"} would remove expr1=x,expr3=z and expr1=u but leave expr2=y.   \r
+   * </p>\r
+   * @param expressionFields The expression types (by field) to remove\r
+   * @return a list of expressions with the given left-of-operator keys\r
+   * \r
+   */\r
   public void removeExpressions (String... expressionFields) {\r
     List<String> fieldsToRemove = Arrays.asList(expressionFields);\r
     Iterator<Expression> i = expressions.iterator();\r
@@ -125,19 +211,41 @@ public class CommandParameter implements Serializable {
        }\r
     }\r
   }\r
-  \r
+\r
+  /**\r
+   *   \r
+   * @return true if an operator was defined for this parameter yet\r
+   */\r
   public boolean hasOperator() {\r
     return operator != null;\r
   }\r
   \r
+  /**\r
+   * Returns true if this parameter has a simple value\r
+   * \r
+   * @return true if this parameter has a simple value\r
+   */\r
   public boolean hasValue() {\r
     return value != null && value.length()>0;\r
   }\r
   \r
+  /**\r
+   * Returns true if this parameter has expressions (complex values)\r
+   * \r
+   * @return true if this parameter has expressions (complex values)\r
+   */\r
   public boolean hasExpressions() {\r
     return expressions.size()>0;\r
   }\r
   \r
+  /**\r
+   * Returns true if this parameter has expressions of the given type,\r
+   * that is, expressions where the left-of-operator key equals 'expressionField'\r
+   * \r
+   * @param expressionField the type of expression to look for\r
+   * @return true if this parameter has expressions of the given type,\r
+   *  that is, expressions where the left-of-operator key equals 'expressionField'\r
+   */\r
   public boolean hasExpressions(String expressionField) {    \r
     for (Expression expr : expressions) {\r
       if (expr.getField().equals(expressionField)) {\r
@@ -147,6 +255,11 @@ public class CommandParameter implements Serializable {
     return false;    \r
   }\r
   \r
+  /**\r
+   * Returns a URL encoded string of this parameter with name, operator, simple value and/or expressions\r
+   * \r
+   * @return URL encoded string of this parameter with name, operator, simple value and/or expressions\r
+   */\r
   public String getEncodedQueryString () {\r
     try {\r
       return name + operator + URLEncoder.encode(getValueWithExpressions(),"UTF-8");\r
@@ -156,10 +269,20 @@ public class CommandParameter implements Serializable {
     }\r
   }\r
     \r
+  /**\r
+   * Returns the simple parameter value or null if no simple value was set for this parameter\r
+   * \r
+   * @return the simple parameter value, null if no simple value was set for this parameter \r
+   */\r
   public String getSimpleValue() {    \r
     return value; \r
   }\r
   \r
+  /**\r
+   * Returns the simple parameter value and/or any expressions, separated by 'AND'\r
+   * \r
+   * @return the simple parameter value and/or any expressions separated by 'AND'\r
+   */\r
   public String getValueWithExpressions () {\r
     StringBuilder completeValue = new StringBuilder((value==null ? "" : value));\r
     boolean first=true;\r
@@ -190,6 +313,12 @@ public class CommandParameter implements Serializable {
     return getValueWithExpressions();\r
   }\r
   \r
+  /**\r
+   * Clones the CommandParameter\r
+   * \r
+   * @return a deep, detached clone of this command parameter, for copying \r
+   * a parameter to a new state.  \r
+   */\r
   public CommandParameter copy() {\r
     logger.trace("Copying parameter '"+ name + "' for modification");\r
     CommandParameter newParam = new CommandParameter(name);\r

diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Expression.java b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Expression.java
index f636f68..67cc3d4 100644 (file)
--- a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Expression.java
+++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Expression.java
@@ -4,6 +4,22 @@ import java.io.Serializable;
 \r
 import org.apache.log4j.Logger;\r
 \r
+/**\r
+ * Represents a complex command parameter value, in form of an expression with \r
+ * an equality operator\r
+ * <p>\r
+ * An expression consist of a left-of-operator field or key, an equality operator (= or ~), \r
+ * a right-of-operator value, and optionally a label describing the value for UI display.\r
+ * </p> \r
+ * Examples:\r
+ * <ul>\r
+ *  <li>pz:id=1234 "My Target"</li>\r
+ *  <li>category~libcatalog "Library Catalogs"</li>\r
+ *  <li>author="Steinbeck, John"</li>\r
+ * </ul>\r
+ * @author Niels Erik\r
+ *\r
+ */\r
 public class Expression implements Serializable {\r
   \r
   private static final long serialVersionUID = -751704027842027769L;\r
@@ -13,13 +29,31 @@ public class Expression implements Serializable {
   String rightEntity;\r
   String label;  \r
   \r
-  public Expression (String leftEntity, String operator, String rightEntity, String label) {\r
-    this.leftEntity = leftEntity;\r
+  /**\r
+   * Instantiates an expression with a label\r
+   * \r
+   * @param leftEntity left-of-operator field name (or 'key')\r
+   * @param operator an equality operator\r
+   * @param rightEntity right-of-operator value\r
+   * @param label to be used for display, for instance in a UI control that adds or removes the expression\r
+   *  from a command parameter\r
+   */\r
+  public Expression (String field, String operator, String value, String label) {\r
+    this.leftEntity = field;\r
     this.operator = operator;\r
-    this.rightEntity = rightEntity;    \r
+    this.rightEntity = value;    \r
     this.label = label;\r
   }\r
   \r
+  /**\r
+   * Instantiates an expression by parsing the provided expression string, which must be\r
+   * on the form {name}({=}or{~}){value}.\r
+   * <p>\r
+   * Currently only '=' and '~' are recognized as operators\r
+   * </p>\r
+   * \r
+   * @param expressionString\r
+   */\r
   public Expression (String expressionString) {\r
     String[] parts = expressionString.split("[=~]");\r
     this.leftEntity = parts[0];\r
@@ -28,6 +62,11 @@ public class Expression implements Serializable {
     this.label=rightEntity;\r
   }\r
   \r
+  /** \r
+   * Clones the expression\r
+   * \r
+   * @return a clone of this expression\r
+   */\r
   public Expression copy() {\r
     logger.trace("Copying " + this.toString());\r
     return new Expression(leftEntity, operator, rightEntity, label);\r
@@ -37,18 +76,39 @@ public class Expression implements Serializable {
     return leftEntity + operator + rightEntity;\r
   }\r
   \r
+  /**\r
+   * Returns the label describing the value of the expression or,\r
+   * if no label was provided, the value itself.\r
+   * \r
+   * @return label or right-of-operator value if no label provided\r
+   */\r
   public String getLabel() {\r
     return label;\r
   }\r
   \r
+  /**\r
+   * Returns the left-of-operator field (or name or key).\r
+   * \r
+   * @return entity left of operator\r
+   */\r
   public String getField () {\r
     return leftEntity;\r
   }\r
   \r
+  /**\r
+   * Returns the operator \r
+   * \r
+   * @return the operator of the expression\r
+   */\r
   public String getOperator() {\r
     return operator;\r
   }\r
   \r
+  /**\r
+   * Returns the right-of-operator value of the expression\r
+   * \r
+   * @return entity right of operator\r
+   */\r
   public String getValue() {\r
     return rightEntity;\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 99b330e..a4fa51f 100644 (file)
--- a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Pazpar2Command.java
+++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Pazpar2Command.java
@@ -334,10 +334,10 @@ public abstract class Pazpar2Command implements Serializable  {
   public abstract ServiceProxyCommand getSp();\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
+   * Here implementing commands publish whether they only \r
+   * apply to the Service Proxy or can be executed \r
+   * against straight Pazpar2 as well. This is convenient for a \r
+   * UI that switches between service types either \r
    * deployment time or run time.\r
    *   \r
    * @return false if the command applies to straight Pazpar2\r