Javadoc

[mkjsf-moved-to-github.git] / src / main / java / com / indexdata / mkjsf / pazpar2 / commands / Expression.java

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